Update CITATION.cff

fix: hesláře osob se po aktualizaci tiše vyprázdní (#68 )
Digiarchiv v4.1.0 (Solr 10, json.nl=arrarr) vrací položky facet jako dvojice ["hodnota", počet] místo objektů {"name": ...}. fetch_set četl r["name"], spadl na TypeError a hesláře vedoucích a nálezců se uložily prázdné. - _facet_name() přijímá oba formáty facet (starý i nový). - Selhání setu vrací prázdný seznam i při přerušeném stránkování, ať se neuloží jen část hesláře. - download_heslare() ponechá u selhaného nebo prázdného setu předchozí hodnoty z heslar.csv a vrátí seznam selhaných setů. - Dialog při částečném selhání zobrazí varování místo „Hotovo“. - Verze 2.1.3 + changelog. Ověřeno proti produkčnímu API: vedoucí 2497, nálezci 426, ostatní hesláře beze změny; simulované selhání ponechá předchozí hodnoty. Refs #67, #66 Připraveno s pomocí AI (Claude).
2026-10-11 13:27:33 +02:00 · 2026-10-01 15:34:52 +02:00 · 2026-10-01 15:33:41 +02:00 · 2026-09-02 17:16:34 +02:00 · 2026-09-02 10:16:36 +02:00 · 2026-09-02 09:38:50 +02:00
23 changed files with 20729 additions and 14429 deletions
@@ -0,0 +1,35 @@
+<!--
+Děkujeme za příspěvek! Vyplň prosím sekce níže.
+Nepotřebné body můžeš smazat. Komentáře (<!-- ... -->) se v PR nezobrazují.
+-->
+
+## Souhrn
+
+<!-- Stručně co a proč. 1–3 věty. -->
+
+## Změny
+
+<!-- Co se konkrétně mění, ideálně po souborech / oblastech. -->
+-
+
+## Testování
+
+<!-- Jak ověřit, že to funguje (kroky v QGIS, scénáře). -->
+-
+
+## Zapojení AI
+
+<!-- Byla u změny použita AI? Jak? Např. "text navržen AI, ručně zkontrolováno
+     a upraveno". Smaž, pokud AI použita nebyla. -->
+-
+
+## Kontrolní seznam
+- [ ] Změny jsou v souladu se stylem projektu (viz `AGENTS.md`)
+- [ ] Při změně funkcí povýšena verze v `amcr_viewer/metadata.txt` a doplněn `changelog`
+- [ ] Otestováno v QGIS (min. podporovaná verze 3.44)
+- [ ] PR míří do správné cílové větve
+- [ ] Větev odpovídá konvenci (`feat/ fix/ docs/ chore/<téma>`, AI `agents/<jméno>/<téma>`)
+
+## Související issue
+
+<!-- Např. "Closes #123". Smaž, pokud se neváže k issue. -->
@@ -0,0 +1,171 @@
+name: Code Quality
+
+# Pouští při každém PR tytéž kontroly, které se dosud dělaly ručně:
+#
+#  * co spouští plugins.qgis.org při uploadu (bandit, detect-secrets,
+#    flake8, analýza souborů) – https://plugins.qgis.org/docs/security-scanning
+#  * oficiální kontrolu kompatibility s Qt6 (pyqgis4-checker)
+#  * skutečné načtení pluginu v QGIS 3.44 (Qt5) i v QGIS 4 (Qt6)
+#  * sestavení ZIPu, který si recenzent stáhne a nainstaluje přímo z PR
+#
+# CodeQL a GitGuardian běží zvlášť, nastavené na úrovni organizace –
+# tady se schválně neduplikují.
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  # Verze se drží napevno, aby se výsledek nezměnil sám od sebe. Výchozí
+  # sada pravidel ruffu se mezi verzemi mění; povýšení je vědomý krok.
+  BANDIT: bandit==1.9.4
+  DETECT_SECRETS: detect-secrets==1.5.0
+  FLAKE8: flake8==7.3.0
+  RUFF: ruff==0.16.5
+
+jobs:
+  # --------------------------------------------------------------------
+  # 1. Statické kontroly – běží první, protože trvají desítky sekund
+  # --------------------------------------------------------------------
+  lint:
+    name: Lint a bezpečnost
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+
+      - name: Install tools
+        run: pip install "$BANDIT" "$DETECT_SECRETS" "$FLAKE8" "$RUFF"
+
+      # Hygiena repozitáře: BOM, přímé importy z PyQt5/PyQt6, spustitelná
+      # práva a podezřelé typy souborů. Padá jako první, protože BOM
+      # zneviditelní soubor pro kontrolu níž.
+      - name: Source hygiene
+        run: python3 tests/check_sources.py
+
+      # Blokující kontrola na plugins.qgis.org
+      - name: Bandit
+        run: bandit -r amcr_viewer/
+
+      # Blokující kontrola na plugins.qgis.org.
+      # --all-files je podstatné: bez něj detect-secrets prohledá jen
+      # soubory sledované gitem a nesledovaný soubor tiše přeskočí.
+      - name: detect-secrets
+        run: |
+          detect-secrets scan --all-files amcr_viewer/ > vysledek.json
+          python3 -c "
+          import json, sys
+          nalezy = json.load(open('vysledek.json'))['results']
+          if nalezy:
+              print(json.dumps(nalezy, indent=2))
+              sys.exit(1)
+          print('detect-secrets: bez nálezů')
+          "
+
+      # Na plugins.qgis.org je informativní, tady blokuje – konfigurace
+      # v amcr_viewer/.flake8 je stejná pro obě místa.
+      - name: Flake8
+        run: flake8 --config amcr_viewer/.flake8 amcr_viewer/
+
+      # Nad rámec plugins.qgis.org; konfigurace v pyproject.toml
+      - name: Ruff
+        run: ruff check .
+
+  # --------------------------------------------------------------------
+  # 2. Kompatibilita s Qt6 – oficiální skript z QGISu
+  # --------------------------------------------------------------------
+  qt6:
+    name: Kompatibilita s Qt6
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      # Pozor: skript končí kódem 0 i když něco najde, výsledek je jen
+      # v logu. Prázdný log (samotná hlavička) znamená čisto.
+      - name: pyqgis4-checker
+        run: |
+          docker run --rm --user "$(id -u):$(id -g)" \
+            --workdir /workspace/ -v "$PWD:/workspace/" \
+            ghcr.io/qgis/pyqgis4-checker:main-ubuntu \
+            pyqt5_to_pyqt6.py --dry_run --logfile /workspace/pyqt6_checker.log .
+          echo "--- pyqt6_checker.log ---"
+          cat pyqt6_checker.log
+          nalezu=$(grep -v '=== dry_run mode | Start Logs ===' pyqt6_checker.log | wc -l)
+          if [ "$nalezu" -ne 0 ]; then
+            echo "::error::pyqgis4-checker nahlásil nálezy, viz log výše"
+            exit 1
+          fi
+
+  # --------------------------------------------------------------------
+  # 3. Načtení pluginu ve skutečném QGIS, v obou podporovaných verzích
+  # --------------------------------------------------------------------
+  qgis:
+    name: Smoke test (QGIS ${{ matrix.qgis }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # ltr = 3.44 na Qt5, stable = 4.x na Qt6. Tagy se posouvají
+        # schválně: chceme vědět, že plugin drží krok s aktuálním QGISem.
+        qgis: [ltr, stable]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Smoke test
+        run: |
+          docker run --rm -v "$PWD:/work:ro" -w /work \
+            --user "$(id -u):$(id -g)" -e HOME=/tmp \
+            "qgis/qgis:${{ matrix.qgis }}" python3 tests/smoke_test.py
+
+  # --------------------------------------------------------------------
+  # 4. ZIP k instalaci – stejný postup jako v release_plugin.yml
+  # --------------------------------------------------------------------
+  package:
+    name: Balíček pluginu
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Zip plugin
+        run: zip -r amcr_viewer.zip amcr_viewer -x "*.git*"
+
+      # Kontrola obsahu ZIPu. Config soubory pro scanner musí být uvnitř
+      # vedle metadata.txt, jinak je plugins.qgis.org nenajde – a některé
+      # nástroje skryté soubory tiše vynechávají.
+      - name: Verify archive contents
+        run: |
+          unzip -l amcr_viewer.zip
+          for soubor in amcr_viewer/metadata.txt amcr_viewer/__init__.py \
+                        amcr_viewer/.flake8; do
+            unzip -l amcr_viewer.zip | grep -qF " $soubor" \
+              || { echo "::error::v ZIPu chybí $soubor"; exit 1; }
+          done
+          if unzip -l amcr_viewer.zip | grep -qE '\.git'; then
+            echo "::error::v ZIPu jsou git soubory"
+            exit 1
+          fi
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: amcr_viewer-plugin
+          path: amcr_viewer.zip
+          if-no-files-found: error
@@ -1,17 +1,28 @@
 name: Release QGIS Plugin

+# Spouští se na push tagu, ne na publikaci releasu. Organizace má zapnuté
+# immutable releases: k už publikovanému releasu nelze nic přiložit, příloha
+# tedy musí vzniknout dřív, než se release zveřejní. Workflow proto založí
+# koncept releasu i se ZIPem; text se dopisuje a publikuje ručně.
+#
+# Pozor: workflow se čte z commitu, na který tag ukazuje. Tag musí být
+# založen až na commitu, který tento soubor obsahuje.
 on:
-  release:
-    types: [published]
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write

 jobs:
  build-and-release:
    runs-on: ubuntu-latest
-    
+
    steps:
-      # 1. Stáhne kód z repozitáře
+      # 1. Stáhne kód z tagu, který běh spustil
      - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3

      # 2. Vytvoří ZIP (předpokládá, že kód je ve složce 'amcr_viewer')
      - name: Zip Plugin
@@ -20,11 +31,14 @@ jobs:
          # -r = rekurzivně, -x = ignorovat skryté git soubory
          zip -r amcr_viewer.zip amcr_viewer -x "*.git*"

-      # 3. Nahraje ZIP k Releasu
-      - name: Upload Release Asset
-        uses: softprops/action-gh-release@v1
-        if: startsWith(github.ref, 'refs/tags/')
+      # 3. Založí koncept releasu i s přílohou
+      #    Tagy s pomlčkou (v2.0.0-alpha.1) se označí jako pre-release.
+      - name: Create draft release with asset
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
        with:
          files: amcr_viewer.zip
+          draft: true
+          name: AMCR Viewer ${{ github.ref_name }}
+          prerelease: ${{ contains(github.ref_name, '-') }}
        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -210,3 +210,5 @@ __marimo__/

 README_files/
 README.html
+amcr_viewer.zip
+pyrefly.toml
@@ -0,0 +1,232 @@
+# AGENTS.md
+
+Pokyny pro AI agenty i lidské přispěvatele pracující v tomto repozitáři.
+Tento soubor je jediný zdroj pravdy; `CLAUDE.md` na něj pouze odkazuje.
+
+## O projektu
+
+**AMČR Viewer** je plugin do QGIS pro stahování a vizualizaci dat z Digitálního
+archivu Archeologické mapy ČR (AMČR / AIS CR) – akce (*Fieldwork events*),
+lokality (*Sites*) a jejich komponenty. Podporuje anonymní i přihlášený přístup
+přes AMČR účet.
+
+Zdroj dat: https://digiarchiv.aiscr.cz/ · Nápověda: https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html
+
+## Zařazení v ekosystému AIS CR
+
+Tento repozitář je jedním ze **sourozeneckých repozitářů** ekosystému AIS CR.
+Centrální governance a AI konfigurace spravuje hub **`aiscr-management`**; konvence
+v tomto souboru jsou s tímto vzorem sladěné a zjednodušené pro potřeby jednoho
+QGIS pluginu. Těžkou mašinerii hubu (složka `.agents/`, OpenSpec, sync skripty,
+multi-assistant generování) tento repozitář **záměrně nepřebírá**. Při širších
+otázkách governance má přednost vzor z `aiscr-management`.
+
+## Struktura repozitáře
+
+```
+amcr_viewer/            # vlastní kód pluginu (toto se balí do releasu)
+  amcr_viewer.py        # vstupní bod pluginu, integrace do QGIS
+  amcr_dialog.py        # dialogy a UI (filtry, přihlášení)
+  amcr_tools.py         # stahování dat z API, sestavení vrstev a atributů
+  amcr_codelists.py     # hesláře / číselníky (codelists)
+  codelists/heslar.csv  # lokální kopie číselníků
+  metadata.txt          # metadata pluginu + verze + changelog
+  i18n/                 # překlady (.ts)
+  *.png                 # ikony
+.github/workflows/      # CI – release pluginu
+README.md               # uživatelská dokumentace (anglicky)
+```
+
+## Konvence
+
+### Jazyk
+- **Kód a identifikátory:** anglicky. Atributová pole vrstev musí být ASCII
+  kompatibilní (bez diakritiky) – viz historie změn v `metadata.txt`.
+- **README a uživatelská dokumentace:** anglicky.
+- **Commity, PR a komentáře v issue:** česky.
+
+### Commity
+- Styl odpovídá historii: česky, věcně, popisně; jeden commit = jedna logická
+  změna.
+- První řádek stručně a výstižně (ideálně v imperativu); podrobnosti do těla.
+- Pokud je commit připraven s pomocí AI, uveď to v těle commitu nebo v popisu PR.
+
+### Větve
+Konvence názvů je sladěná s hubem `aiscr-management`:
+
+- **lidé:** `feat/<téma>` (nová funkce), `fix/<téma>` (oprava), `docs/<téma>`
+  (dokumentace), `chore/<téma>` (údržba).
+- **AI agenti:** `agents/<jméno-agenta>/<téma>` (např. `agents/claude/oprava-pian`).
+
+Další pravidla:
+
+- Cílová větev pro nový vývoj je aktuální `version/v2.x.y` (ne přímo do
+  výchozí větve bez PR).
+- **Nikdy** nepushuj přímo do chráněných větví; vždy přes Pull Request.
+- Standardizační / nefunkční změny drž v samostatné větvi, ať se nemíchají do
+  feature PR.
+
+### Pravidla pro AI agenty (git)
+- AI ve výchozím stavu zůstává u **lokální práce na aktuální větvi**.
+- Bez **výslovného pokynu** uživatele AI nestageuje (`git add`), necommituje,
+  nepushuje ani samo nepřepíná/nezakládá větev pro vzdálené doručení.
+- Při výslovném požadavku na push/PR použij větev `agents/<jméno-agenta>/<téma>`;
+  pokud aktuální větev tomuto vzoru neodpovídá, vyžádej si nejdřív potvrzení.
+- Vytvoření větve, stage, commit, push ani draft PR AI běžně nenabízí; zmiňuj je
+  jen tehdy, když jsou pro splnění úkolu opravdu nutné.
+
+### QGIS specifika
+- Minimální podporovaná verze QGIS je **3.44** (`qgisMinimumVersion` v
+  `metadata.txt`); kód nesmí spoléhat na novější API.
+- Vrstvy a atributy se sestavují přes `QgsField` / QGIS API v `amcr_tools.py`.
+  Při přidání atributu je potřeba doplnit ho konzistentně na všech místech:
+  definice pole (`QgsField`), naplnění hodnoty z dokumentu, překlad hlavičky
+  sloupce a export atributů.
+
+### Kompatibilita s Qt6 / QGIS 4
+
+Plugin cílí na QGIS 3.44 i na QGIS 4 (`qgisMaximumVersion=4.99.0`), tedy na
+Qt5 i Qt6 zároveň. **Tohle se drží rigorózně** – ne až před releasem, ale při
+každé změně kódu. Chování obou větví se liší tiše: pod Qt5 projde i to, co
+QGIS 4 odmítne, takže lokální „funguje mi to“ nic nedokazuje.
+
+Závazná pravidla:
+
+- **Nikdy neimportuj přímo z `PyQt5` ani z `PyQt6`.** Vždy přes shim
+  `qgis.PyQt.*`. Ten mimo jiné pod Qt6 přetahuje `QAction`, `QActionGroup`
+  a `QShortcut` z `QtGui`, takže import z `qgis.PyQt.QtWidgets` je správně.
+- **Enumy vždy plně kvalifikované (scoped).** `Qgis.MessageLevel.Info`, ne
+  `Qgis.Info`; `QgsTask.Flag.CanCancel`, ne `QgsTask.CanCancel`;
+  `QgsWkbTypes.GeometryType.PointGeometry`, ne `QgsWkbTypes.PointGeometry`.
+  Totéž pro Qt: `Qt.CheckState.Checked`, `QDialogButtonBox.StandardButton.Ok`.
+  Zkrácené tvary sice v QGIS 4.2 zatím fungují, ale oficiální kontrola je
+  hlásí a do budoucna mizí.
+- **Zdrojové `.py` soubory ukládej bez BOM.** Kontrolní skript čte soubor
+  jako UTF-8 bez `utf-8-sig` a na BOM spadne s
+  `SyntaxError: invalid non-printable character U+FEFF`, takže se takový
+  soubor **vůbec nezkontroluje**. (`codelists/heslar.csv` BOM mít smí, tam je
+  kvůli Excelu.)
+- Nepoužívej API zrušená v Qt6: `exec_()`, `QRegExp`, `QDesktopWidget`,
+  `QApplication.desktop()`, `Qt.MidButton`, `QFontMetrics.width()`,
+  `setResizeMode`, atributy `AA_EnableHighDpiScaling` / `AA_UseHighDpiPixmaps`.
+- `supportsQt6=True` v `metadata.txt` **nepatří** – bylo zrušeno; o zařazení
+  mezi „QGIS 4 Ready“ rozhoduje rozsah `qgisMinimumVersion` až
+  `qgisMaximumVersion`.
+
+Ověření před PR, který mění Python kód:
+
+```sh
+# oficiální kontrola, kterou pouští i plugins.qgis.org (pyqgis4-checker)
+docker run --rm --pull always --user $(id -u):$(id -g) \
+  --workdir /workspace/ -v "$(pwd):/workspace/" \
+  ghcr.io/qgis/pyqgis4-checker:main-ubuntu \
+  pyqt5_to_pyqt6.py --dry_run --logfile /workspace/pyqt6_checker.log .
+```
+
+Prázdný log = čisté. Kontrola je na plugins.qgis.org informativní
+(neblokuje schválení), ale nález znamená, že plugin v QGIS 4 dříve nebo
+později přestane fungovat.
+
+Když je po ruce QGIS 4 (např. flatpak `org.qgis.qgis`), ověř navíc, že se
+plugin pod Qt6 opravdu načte:
+
+```sh
+flatpak run --command=sh org.qgis.qgis -c \
+  'PYTHONPATH=/app/share/qgis/python python3 -c "import qgis.core"'
+```
+
+## Verzování a release
+
+- Verze pluginu žije v **`amcr_viewer/metadata.txt`** (`version=`).
+- **Při každé změně chování / nové funkci** povyš verzi a doplň položku do
+  `changelog=` v `metadata.txt` (formát `vX.Y.Z (RRRR-MM-DD)` + odrážky).
+- Datum v changelogu ber z **deterministického zdroje**, ne z paměti, např.
+  `python -c "import datetime; print(datetime.date.today().isoformat())"`.
+- Release se spouští **pushnutím tagu `vX.Y.Z`**, ne publikací releasu
+  v UI. Workflow `.github/workflows/release_plugin.yml` zabalí složku
+  `amcr_viewer/` do `amcr_viewer.zip` a založí **koncept** releasu i s touto
+  přílohou; text se dopíše a release zveřejní ručně. Do ZIPu se nesmí dostat
+  `.git*` soubory.
+- Organizace má zapnuté **immutable releases** – k publikovanému releasu už
+  nelze nic přiložit. Proto příloha vzniká na konceptu, ještě před
+  zveřejněním; workflow spouštěný na `release: published` by vždy selhal.
+- Workflow se čte z commitu, na který **tag ukazuje**. Tag proto zakládej až
+  na commitu, který obsahuje aktuální podobu workflow – jinak se nespustí nic.
+
+## Pull requesty
+
+- Používej PR šablonu (`.github/pull_request_template.md`): Souhrn / Změny /
+  Testování / Kontrolní seznam.
+- PR musí mířit do správné `version/v2.x.y` větve.
+- Před požádáním o review projdi kontrolní seznam v šabloně (zejména bump verze
+  v `metadata.txt`, pokud měníš chování).
+- V popisu PR uveď **podíl AI** (např. „text navržen AI, ručně zkontrolováno")
+  a odkaz na související issue, pokud existuje.
+
+## Bezpečnost a soukromí
+
+- Do promptů, příkladů ani commitů **nevkládej** ostrá produkční data, plné
+  log dumpy ani reálné osobní údaje (PII).
+- **Rediguj** secrets, tokeny, API klíče a hesla z čehokoli, co posíláš AI;
+  nikdy je necommituj do repozitáře (ani přihlašovací údaje k AMČR účtu).
+- Pro interní infrastrukturu (URL, hostname, prostředí) používej placeholdery,
+  pokud konkrétní hodnota není nutná a povolená.
+
+## Lokální ověření
+
+Plugin se testuje načtením do QGIS (Plugins → Manage and Install Plugins →
+Install from ZIP, nebo nasazením složky `amcr_viewer/` do adresáře pluginů
+QGIS). **Ruční test v QGIS nic nenahrazuje** – automatické kontroly ověřují,
+že se plugin načte a že projde kontrolami kvality, ne že dělá správnou věc.
+
+### Automatické kontroly
+
+Workflow `.github/workflows/code_quality.yml` pouští při každém PR do `main`
+tohle:
+
+| job | co dělá |
+|---|---|
+| **Lint a bezpečnost** | `check_sources.py`, bandit, detect-secrets, flake8, ruff |
+| **Kompatibilita s Qt6** | `pyqgis4-checker` v dockeru |
+| **Smoke test** | `smoke_test.py` v `qgis/qgis:ltr` i `qgis/qgis:stable` |
+| **Balíček pluginu** | sestaví ZIP, ověří obsah, přiloží jako artefakt |
+
+Smoke test běží v obou podporovaných řadách: `ltr` je QGIS 3.44 na Qt5,
+`stable` je QGIS 4.x na Qt6.
+
+Artefakt z posledního jobu se dá stáhnout ze stránky běhu a rovnou
+nainstalovat přes *Install from ZIP* – recenzent nemusí nic balit ručně.
+
+Totéž lokálně:
+
+```sh
+pip install bandit detect-secrets flake8 ruff
+
+python3 tests/check_sources.py
+bandit -r amcr_viewer/
+detect-secrets scan --all-files amcr_viewer/
+flake8 --config amcr_viewer/.flake8 amcr_viewer/
+ruff check .
+
+# smoke test v obou verzích QGIS (docker, bez instalace čehokoli)
+for tag in ltr stable; do
+  docker run --rm -v "$PWD:/work:ro" -w /work \
+    --user "$(id -u):$(id -g)" -e HOME=/tmp \
+    "qgis/qgis:$tag" python3 tests/smoke_test.py
+done
+```
+
+Na co si dát pozor:
+
+- **`pyqgis4-checker` končí kódem 0, i když něco najde** – výsledek je jen
+  v logu. Workflow proto kontroluje, že log obsahuje jen hlavičku.
+- **`detect-secrets` bez `--all-files` prohledá jen soubory sledované
+  gitem** a o nesledovaném souboru mlčí. Vypadá to jako čistý výsledek.
+- **Konfigurace lintů je rozdělená schválně.** `amcr_viewer/.flake8` leží
+  vedle `metadata.txt`, protože scanner na plugins.qgis.org hledá config
+  soubory jen v kořeni balíčku uvnitř ZIPu; díky tomu platí stejná pravidla
+  v CI, lokálně i při uploadu. Konfigurace ruffu je naopak v kořenovém
+  `pyproject.toml` – ruff se do balíčku pluginu nedistribuuje.
+  Viz https://plugins.qgis.org/docs/security-scanning/config-files
+- **Verze nástrojů jsou v workflow napevno.** Výchozí sada pravidel ruffu se
+  mezi verzemi mění, takže bez pinu by CI začalo padat samo od sebe.
@@ -20,11 +20,10 @@ identifiers:
    value: 10.5281/zenodo.18609813
 repository-code: 'https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer'
 abstract: >-
-  This QGIS plugin is intended for downloading the data
-  (Fieldwork events data only, at the time) from the
-  Digiarchive of the Archaeological Map of the Czech
-  Republic (AMCR). As of now, only publicly accessible data
-  can be downloaded.
+  This plugin is intended for downloading the data
+  (Fieldwork events, Sites, and their Components) from
+  the Digital archive of the Archaeological Map of the
+  Czech Republic (https://digiarchiv.aiscr.cz/).
 license: GPL-3.0
-version: '1.0.1'
-date-released: '2026-02-11'
+version: '2.1.3'
+date-released: '2026-10-01'
@@ -0,0 +1 @@
+@AGENTS.md
@@ -1,123 +1,433 @@
-# AMCR Viewer: QGIS Plugin Documentation
+# AMČR Viewer — QGIS plugin

 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![QGIS 3.44 – 4.x](https://img.shields.io/badge/QGIS-3.44%20%E2%80%93%204.x-589632.svg)](https://qgis.org/)
+[![Code quality](https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/actions/workflows/code_quality.yml/badge.svg)](https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/actions/workflows/code_quality.yml)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18609813.svg)](https://doi.org/10.5281/zenodo.18609813)

-**Platform:** QGIS 3.4.x
+**AMČR Viewer** queries the Digital Archive of the Archaeological Map of the
+Czech Republic (AMČR) and turns the result into ordinary QGIS vector layers.
+It removes the manual export/import round trip: you filter the archive from
+inside QGIS and the matching records arrive as point, line and polygon layers
+with a full attribute table.

-**Module Type:** Data Acquisition & Visualization
-
-**Source Data:** Archaeological Map of the Czech Republic (AIS CR)
+| | |
+| --- | --- |
+| **Source data** | [Digital Archive AMČR](https://digiarchiv.aiscr.cz/) (AIS CR) |
+| **Supported QGIS** | 3.44.0 – 4.99.0 (Qt 5 and Qt 6) |
+| **Output** | temporary `memory` layers, S-JTSK / **EPSG:5514** |
+| **Access** | anonymous by default; optional login for non-public records |
+| **UI language** | Czech |
+| **Licence** | GPL-3.0 |

 ---

-## 1. Overview
+## 1. What it can download

-**AMCR Viewer** is a QGIS plugin designed to facilitate direct access to the Digital Archive of the Archaeological Map of the Czech Republic (AMČR). It allows researchers to **query, retrieve, and visualize *Fieldwork events* and *Sites* data (metadata and geometry) directly within the GIS environment**, eliminating the need to manually export data from the web interface. Both *Fieldwork events* and *Sites* layers may be accompanied by a *Components* layer with additional information. **Only publicly accessible data are supported at the time** (accessibility = anonymous).
+The plugin covers three AMČR record types. Each has its own menu entry, its
+own set of filters and its own attribute table.

+| Entity | Menu entry | What it is |
+| --- | --- | --- |
+| **Fieldwork events** (`akce`) | *Stáhnout data akcí* | Records of archaeological finds and observations tied to a place, a responsible body and a time of execution. |
+| **Sites** (`lokalita`) | *Stáhnout data lokalit* | Records tied to a site, its characteristic archaeological manifestation and presumed function. |
+| **Individual finds** (`samostatny_nalez`) | *Stáhnout data samostatných nálezů* | Records of individual movable finds reported through **AMČR-PAS**, the portal for amateur collaborators. |

-### Key Features
+Fieldwork events and Sites can additionally carry **component** data (period
+and activity area) directly in the attribute table. Individual finds have no
+components — period and dating are attributes of the find itself.

-* **Spatial Querying:** Option to filter records based on the current map canvas extent (Bounding Box).
-* **Advanced Attribute Filtering:** Supports multi-criteria filtering using controlled vocabularies.
-* **Dynamic Geometry Retrieval:** Automatically downloads and categorizes spatial data into Point, Line, and Polygon layers.
-* **Semantic Interoperability:** Automatically translates internal system codes into human-readable labels using the AIS CR API.
+### Key features
+
+* **Spatial querying** — restrict the query to the current map canvas extent.
+* **Multi-criteria attribute filtering** driven by AMČR controlled
+  vocabularies (*hesláře*), with a searchable multi-select picker per filter.
+* **Date range filtering** for fieldwork start/end and for the date of finding.
+* **Automatic geometry retrieval**, split into Point, Line and Polygon layers
+  and reprojected to S-JTSK.
+* **Human-readable labels** — internal codes (`HES-xxxxxx`) are translated via
+  the AIS CR translation dictionary.
+* **Authenticated access** — an AMČR account unlocks non-public records;
+  credentials are stored encrypted in the QGIS Authentication Manager.

 ---

-## 2. Installation Guide
+## 2. Installation

-**Install the plugin from QGIS plugin repository.**  
+### From the QGIS plugin repository (recommended)

-**OR**  
+*Plugins → Manage and Install Plugins… → search for* **AMČR Viewer** *→
+Install*.

-*1. Obtain the [plugin distribution package](https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/releases) (ZIP archive containing the `amcr_viewer` directory).*  
-*2. Launch QGIS.*  
-*3. Navigate to Plugins → Manage and Install Plugins...*  
-*4. Select the Install from ZIP tab.*  
-*5. Locate the source ZIP file and click Install Plugin.*  
-*6. Upon successful installation, the AMCR download button (load AMCR data) will appear in the interface.*  
+### From a ZIP archive (older versions, or a build from source)
+
+1. Download a [release package](https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/releases)
+   (a ZIP containing the `amcr_viewer` directory).
+2. In QGIS go to *Plugins → Manage and Install Plugins… → Install from ZIP*.
+3. Select the archive and click *Install Plugin*.
+
+Every successful CI run also publishes a ready-to-install `amcr_viewer.zip`
+as a build artifact, which is handy for testing a branch before release.
+
+After installation the **AMČR Viewer** button appears in the toolbar as a
+dropdown.
+
+### Requirements
+
+The plugin needs the **`requests`** library. It ships with the QGIS installers
+for Windows and macOS. On Linux distribution packages it may have to be
+installed separately (e.g. `python3-requests`).

 ---

-## 3. User Manual
+## 3. User manual

-### 3.1 Data Retrieval
+### 3.1 Toolbar and menu

-To initiate a search query, click either the **Stáhnout data akcí** or the **Stáhnout data lokalit** icon from the dropdown menu. The filter dialog provides the following options. Shown options vary based on the choosed tool.
+The toolbar button is a dropdown; the default action is *Stáhnout data akcí*.

-* **Spatial Filter:** *Checkbox "Limit search to current map extent":* If checked, the query is restricted to the geographical area currently visible in the QGIS canvas. If unchecked, the query searches the entire database (use with caution regarding data volume).
-* It is possible to view only those Fieldwork events with positive outcome, if "Positive findings only" is checked. Only *PIANs* marked as (or rather *PIANs* belonging to Documentation units marked as) "Type of evidence" = "positive" are rendered.
+| Menu entry | Action |
+| --- | --- |
+| *Stáhnout data akcí* | Opens the filter dialog for Fieldwork events. |
+| *Stáhnout data samostatných nálezů* | Opens the filter dialog for Individual finds. |
+| *Stáhnout data lokalit* | Opens the filter dialog for Sites. |
+| *Přihlásit se* | Opens the login dialog (see 3.2). |
+| *Nápověda AMČR Help* | Opens the online documentation in a browser. |

+### 3.2 Authentication (optional)

-* **Attribute Filters:**
-  * The dialog utilizes "Picker" widgets for controlled vocabularies (common: Region, District, Cadastral area, Period, Activity Area, *PIAN* accuracy; *events* related: Organisation, Researcher, Event type; *sites* related: Site type and class, Level of confidence, State of preservation).
-  * Click **Select...** to open a searchable selection window. Multiple values can be selected simultaneously (Logic: OR).
+By default the plugin sees only publicly accessible records. Logging in with
+an AMČR account extends the result set to everything the account is allowed
+to see.

+* The credentials are **verified against the API before they are stored** —
+  a wrong password never reaches the Authentication Manager. If the server is
+  unreachable, the plugin offers to store them unverified.
+* They are then saved encrypted in the **QGIS Authentication Manager** (DPAPI
+  on Windows, Keychain on macOS, encrypted SQLite on Linux). QGIS will ask for
+  its master password.
+* Stored credentials are reused across QGIS sessions. If the session cookie
+  expires mid-download, the plugin re-authenticates automatically and repeats
+  the request.
+* Reopening the login dialog lets you change the e-mail (leave the password
+  blank to keep the stored one) or remove the credentials entirely
+  (*Odebrat uložené přihlašovací údaje*).

-* **Fieldwork Manager (Dynamic List):**
-  * Due to the dynamic nature of the persons database, the list of Fieldwork Managers is retrieved from the AIS CR servers and needs to be updated the first time (and subsequently, if there is need).
-  * To refresh the list from the server, click the **Refresh (🔄)** button next to the selection field. This downloads the latest list of researchers from the API.
+### 3.3 The filter dialog

-* **Components:** The *components* data are downloaded as well upon checking the corresponding check box. This enriches the main (*Events* and *Sites*) layers with additional information (period and activity area).
+Filters of different categories are combined with **AND**; multiple values
+inside one filter are combined with **OR**. A filter left empty means "no
+restriction". Click *Vybrat…* to open a searchable, checkable list.

-* If no filter is used, all accessible Fieldwork events/PIANs are returned (although the number of Fieldwork events to be loaded is capped at 20000 records; it is advisable to set at least one filter).  
+#### Availability per entity

-For a more in-depth tutorial refer to the [AMČR Documentation](https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html) (only in Czech).
+| Filter (Czech UI label) | Events | Sites | Ind. finds | API parameter |
+| --- | :---: | :---: | :---: | --- |
+| Omezit vyhledávání rozsahem okna | ✓ | ✓ | ✓ | `loc_rpt` |
+| Pouze pozitivní zjištění | ✓ | — | — | `posevidence` |
+| Pouze projektové akce | ✓ | — | — | `proj_akce` |
+| Kraj | ✓ | ✓ | ✓ | `f_kraj` |
+| Okres | ✓ | ✓ | ✓ | `f_okres` |
+| Katastr | ✓ | ✓ | ✓ | `f_katastr` |
+| Přístupnost | ✓ | ✓ | ✓ | `pristupnost` |
+| PIAN – přesnost | ✓ | ✓ | — | `f_pian_presnost` |
+| Organizace | ✓ | — | ✓ | `f_organizace` |
+| Vedoucí výzkumu | ✓ | — | — | `f_vedouci` |
+| Typ výzkumu | ✓ | — | — | `f_typ_vyzkumu` |
+| Datum — *Zahájení* / *Ukončení* | ✓ | — | — | `akce_datum_zahajeni`, `akce_datum_ukonceni` |
+| Lokalita – typ | — | ✓ | — | `f_typ_lokality` |
+| Lokalita – druh | — | ✓ | — | `f_druh_lokality` |
+| Lokalita – jistota určení | — | ✓ | — | `f_jistota` |
+| Lokalita - stav dochování | — | ✓ | — | `f_lokalita_zachovalost` |
+| Období | ✓ | ✓ | ✓ | `f_obdobi` |
+| Kategorie nálezu | — | — | ✓ | `f_kategorie` |
+| Druh nálezu | — | — | ✓ | `f_druh_nalezu` |
+| Specifikace nálezu | — | — | ✓ | `f_specifikace` |
+| Okolnosti nálezu | — | — | ✓ | `f_nalezove_okolnosti` |
+| Nálezce | — | — | ✓ | `f_nalezce` |
+| Datum nálezu | — | — | ✓ | `samostatny_nalez_datum_nalezu` |
+| Areál | ✓ | ✓ | — | `f_areal` |
+| Načíst komponenty | ✓ | ✓ | — | — |

+#### Spatial restriction

+*Omezit vyhledávání rozsahem okna* is **checked by default**. The canvas
+extent is transformed from the project CRS to WGS-84 and sent as a bounding
+box. Unchecking it queries the whole database — do so with an attribute
+filter in place, otherwise you will hit the record cap (see 4.5).

-### 3.2 Layer Structure & Attributes
+#### PIAN accuracy has a non-empty default

-Upon successful retrieval, the plugin generates four temporary memory layers:
+> ⚠ *PIAN – přesnost* is the one filter that is **pre-selected**. For
+> Fieldwork events and Sites the dialog starts with *odchylka jednotky metrů*,
+> *odchylka desítky metrů* and *odchylka stovky metrů* checked, so an
+> otherwise untouched dialog already sends `f_pian_presnost`. Records
+> localised only to a cadastral territory are excluded until you open the
+> picker and add that level yourself.

-1. **AMCR Plochy (Polygons)**
-2. **AMČR Linie (Lines)**
-3. **AMČR Body (Points)**
-4. **AMČR Komponenty (*Components*/no geometry)**
+#### Date ranges

-The Attribute Table includes standardized fields with important metadata. The components layer has no geometry on its own and depend solely on a relation with the other three layers.
+Each date block has a *from* and a *to* picker; an empty picker shows
+*neomezeno* and means an open bound. The API rejects a one-sided range, so the
+plugin substitutes a sentinel (`0001-01-01` / `9999-12-31`) for the empty
+side. A block with **both** pickers empty adds no filter at all.
+
+A reversed range (start later than end) is refused when you confirm the
+dialog — such a query would come back empty and would be indistinguishable
+from a genuinely empty result.
+
+#### Codelists (hesláře)
+
+The controlled vocabularies behind the pickers are cached in
+`amcr_viewer/codelists/heslar.csv` and ship with the plugin. Click
+**Aktualizovat hesláře 🔄** to rebuild the file from the live APIs; it runs as
+a background QGIS task with a progress bar and takes a few minutes.
+
+Most codelists come from the AMČR **OAI-PMH** endpoint. Two are built from
+Digiarchiv **search facets** instead, because they are lists of people rather
+than a published vocabulary: *Vedoucí výzkumu* (`f_vedouci`, faceted over
+fieldwork events) and *Nálezce* (`f_nalezce`, faceted over individual finds).
+
+#### Components
+
+Check **Načíst komponenty** (Events and Sites only) to bring the period and
+activity area of each component into the output layer.
+
+> ⚠ With components loaded, spatial features are **duplicated** — one feature
+> per component. Areas and feature counts computed on such a layer are
+> misleading.
+
+Note that *Období* and *Areál* also act as component filters even when the
+box is unchecked: a documentation unit whose components match nothing is
+dropped from the result.
+
+### 3.4 Output layers
+
+Up to three temporary `memory` layers are created per download, in **S-JTSK
+(EPSG:5514)**:
+
+* `AMCR_Akce_Body` / `_Linie` / `_Polygony`
+* `AMCR_Lokalita_Body` / `_Linie` / `_Polygony`
+* `AMCR_Samostatný_nález_Body` / `_Linie` / `_Polygony`
+
+A layer is only created if the query actually returned that geometry type.
+All layers of one download share the same attribute schema. Field names are
+ASCII; the human-readable names visible in the attribute table are QGIS field
+aliases.
+
+> Memory layers are **not persistent** — export them (GeoPackage, Shapefile,
+> …) before closing the project.
+
+Geometry is taken from the record's S-JTSK WKT when present; otherwise the
+WGS-84 fallback is reprojected. Invalid geometries are repaired rather than
+dropped.
+
+The tables below group the fields by meaning. In the layer they appear in the
+order *common → entity-specific → `pristupnost` → component fields*.
+
+#### Common fields
+
+| Field | Alias | Description |
+| --- | --- | --- |
+| `pian` | PIAN | Spatial unit (PIAN) identifier. *Events and Sites only.* |
+| `presnost` | Přesnost | Spatial accuracy \[units / tens / hundreds of metres / defined by cadastre\]. *Events and Sites only.* |
+| `pian_typ` | PIAN – typ | \[point / line / polygon\]. *Events and Sites only.* |
+| `dj` | Dokumentační jednotka | Documentation unit identifier. *Events and Sites only.* |
+| `typ_dj` | Typ dokumentační jednotky | \[trench / event part / whole event / cadastral territory\]. *Events and Sites only.* |
+| `akce` / `lokalita` / `samostatny_nalez` | Akce / Lokalita / Samostatný nález | Record identifier. |
+| `definicni_body` | Definiční bod(y) (WGS-84) | Feature centroid(s) in WGS-84. |
+| `odkaz_do_digiarchivu` | Odkaz do Digitálního archivu AMČR | Permalink to the record. |
+| `okres` | Okres | District. |
+| `katastr` | Katastr | Main cadastral area. |
+| `dalsi_katastry` | Další katastry | Other cadastral areas. *Always empty for individual finds.* |
+| `pristupnost` | Přístupnost | Record accessibility \[A/B/C/D\]. |
+
+#### Fieldwork event fields
+
+| Field | Alias | Description |
+| --- | --- | --- |
+| `akce_lokalizace` | Akce – lokalizace | Verbal description of the location. |
+| `vedouci` | Vedoucí akce | Main fieldwork manager. |
+| `organizace` | Organizace | Organisation conducting the research. |
+| `specifikace_data` | Specifikace data | \[exact date / exact years / sometime in years\]. |
+| `zahajeni` | Datum zahájeni | Start date. |
+| `ukonceni` | Datum ukončení | End date. |
+| `hlavni_typ` | Hlavní typ | Primary research method. |
+| `vedlejsi_typ` | Vedlejší typ | Secondary research methods. |
+| `zjisteni` | Zjištění | Whether the **documentation unit** is positive or negative evidence \[Pozitivní / Negativní\]. |
+| `nahrazuje_NZ` | Akce – nahrazuje NZ | Replaces a fieldwork report \[Ano / Ne\]. |
+| `projekt` | Projekt | Identifier of the related project, if any. |
+
+#### Site fields
+
+| Field | Alias | Description |
+| --- | --- | --- |
+| `nazev_lokality` | Název lokality | Site name. |
+| `popis_lokality` | Popis lokality | Site description. |
+| `typ_lokality` | Typ lokality | Site classification by definition method. |
+| `druh_lokality` | Druh lokality | Site classification by the nature of the field relics. |
+| `zachovalost` | Zachovalost | State of preservation. |
+
+#### Individual find fields
+
+| Field | Alias | Description |
+| --- | --- | --- |
+| `projekt` | Projekt | Identifier of the related project. |
+| `nalezce` | Nálezce | Finder. |
+| `datum` | Datum nálezu | Date of finding. |
+| `okolnosti` | Nálezové okolnosti | Finding context. |
+| `hloubka_cm` | Hloubka (cm) | Depth below surface. |
+| `lokalizace` | Lokalizace | Verbal description of the find spot. |
+| `obdobi` | Období | Period. |
+| `presna_datace` | Přesná datace | Precise dating, if known. |
+| `nalez` | Nález | Find class. |
+| `material` | Materiál | Find specification / material. |
+| `pocet` | Počet předmětů | Number of objects. |
+| `poznamka` | Poznámka/bližší popis | Note or closer description. |
+| `pred_org` | Předáno organizaci | Organisation the find was handed over to. |
+| `evidencni` | Evidenční číslo | Reference number. |
+
+#### Component fields (only with *Načíst komponenty*)
+
+| Field | Alias | Description |
+| --- | --- | --- |
+| `komponenta` | Komponenta | Component identifier. |
+| `komponenta_areal` | Areál | Activity area \[settlement / burial area / field / …\]. |
+| `komponenta_obdobi` | Období | Period \[Neolithic / High Middle Ages–Modern Period / …\]. |
+
+### 3.5 When a query returns nothing
+
+Progress and errors are written to the QGIS *Messages* panel, tab **AMČR**
+(login goes to **AMČR login**). The log contains the **exact request URL**,
+so a suspicious query can be replayed in a browser instead of being
+reconstructed from the code. Distinct messages tell apart an empty result, an
+API error, a network failure and a result without any geometry.
+
+Only one download can run at a time; starting a second one while the first is
+still running is refused with a message.
+
+For a step-by-step tutorial see the
+[AMČR documentation](https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html)
+(Czech only).

 ---

-## 4. Technical Architecture
+## 4. Technical notes

-The plugin is developed in **Python 3** using the **PyQt5** framework for the GUI and the **Requests** library for HTTP communication.
+The plugin is plain **Python 3** with **`requests`** for HTTP. The GUI is
+built through the **`qgis.PyQt`** compatibility layer rather than importing
+`PyQt5`/`PyQt6` directly, which is what lets a single source tree run on both
+QGIS 3.44 (Qt 5) and QGIS 4 (Qt 6). Every enum is referenced in its scoped
+form (`Qt.CheckState.Checked`, …), as required by Qt 6.

-### 4.1 File Structure
+### 4.1 Repository layout

-* `amcr_viewer.py`: Entry point; handles GUI integration and initialization.
-* `amcr_dialog.py`: Manages the UI logic, including the custom `FilterableSelectionDialog` for handling large vocabularies.
-* `amcr_tools.py`: Core logic module. Handles API requests, pagination, data parsing, and vector layer generation.
-* `amcr_codelists.py`: Manages local caching of controlled vocabularies (`codelists/*.csv`).
+```
+amcr_viewer/            the plugin package (this is what gets zipped)
+  __init__.py           classFactory() entry point for QGIS
+  amcr_viewer.py        toolbar/menu integration, login flow, dispatch
+  amcr_dialog.py        AmcrFilterDialog, FilterableSelectionDialog,
+                        LoginDialog, UpdateCodelistsTask
+  amcr_tools.py         API access, pagination, parsing, layer building
+  amcr_codelists.py     codelist download and CSV cache
+  codelists/heslar.csv  cached controlled vocabularies
+  i18n/                 Qt translation files
+  *.png                 toolbar and menu icons
+  resources.py          generated by pyrcc, currently unused
+  metadata.txt          plugin metadata and changelog
+  .flake8               lint config, read by the plugins.qgis.org scanner
+tests/
+  check_sources.py      source hygiene checks (no QGIS needed)
+  smoke_test.py         loads the plugin in a real, headless QGIS
+.github/workflows/      CI (code quality, release packaging)
+pyproject.toml          ruff configuration
+AGENTS.md               contributor and AI-agent guidelines
+```

-### 4.2 Data Flow & API Integration
+### 4.2 API endpoints

-The plugin interacts with three primary endpoints of the AIS CR infrastructure:
+| Purpose | Endpoint | Notes |
+| --- | --- | --- |
+| Login | `POST https://digiarchiv.aiscr.cz/api/user/login` | Returns a session cookie. Errors arrive with HTTP 200 and an `error` key. |
+| Search | `GET https://digiarchiv.aiscr.cz/api/search/query` | `entity=akce\|lokalita\|samostatny_nalez\|pian`, `mapa=true`, paginated. |
+| Translations | `GET https://digiarchiv.aiscr.cz/api/assets/i18n/cs.json` | Code → Czech label; cached in memory for the session. |
+| Codelists | `GET https://api.aiscr.cz/2.2/oai` | OAI-PMH `ListRecords`, with resumption tokens. |

-1. **Search API (Solr):**
-* Endpoint: `https://digiarchiv.aiscr.cz/api/search/query`
-* Method: `GET`
-* Parameters: `entity=akce`, `rows/page` (pagination).
-* Logic: The plugin implements a `while True` loop to handle pagination, processing data in batches of 500 records to ensure stability.
+### 4.3 Processing pipeline

+1. **Metadata** are paged in batches of **500** records, deduplicated by
+   `ident_cely`, until the reported `numFound` is reached or the cap is hit.
+2. Records **without geometry are skipped**; the rest are expanded into
+   documentation units and — if requested — into components.
+3. **Geometries** (PIAN) are fetched separately in batches of **200**
+   identifiers, to stay under URL length limits.
+4. Features are built, reprojected to EPSG:5514, sorted by geometry type and
+   added to the project in a single batch per layer.

-2. **Translation API:**
-* Endpoint: `https://digiarchiv.aiscr.cz/api/assets/i18n/cs.json`
-* Function: Retrieves the mapping between system codes (e.g., `HES-xxxx`) and Czech labels. This dictionary is cached in memory during the session.
+### 4.4 Data persistence

+* **Codelists** — `amcr_viewer/codelists/heslar.csv`, rewritten only when the
+  user asks for an update.
+* **Credentials** — QGIS Authentication Manager; the config ID is kept in
+  `QSettings` under `amcr_viewer/auth_config_id`.
+* **Layers** — `memory` only, lost when QGIS closes.

-### 4.3 Data Persistence
+### 4.5 Limits

-* **Vocabularies:** Static vocabularies (e.g., Periods, Regions) are stored in `codelists/heslar.csv`.
-* **Dynamic Data:** The list of researchers is downloaded on-demand and cached in `codelists/vedouci.csv`.
-* **Layers:** Output layers are created as `memory` layers. They are non-persistent and will be lost if QGIS is closed without saving.
+* **20 000 records** per query (safety cap; QGIS would otherwise freeze).
+* **500** records per metadata request, **200** identifiers per geometry
+  request.
+* With components loaded, one output feature equals one component, so a
+  single PIAN can appear several times in the layer.

-### 4.4 Constraints
+---

-* **Record Limit:** A safety cap of 20,000 records is enforced.
-* **Batch Processing:** Geometry fetching is batched (50 IDs per request) to comply with URL length limitations and server load balancing.
+## 5. Development
+
+Contributor rules, branch naming and the manual QGIS test checklist live in
+[`AGENTS.md`](./AGENTS.md).
+
+Every pull request runs
+[`.github/workflows/code_quality.yml`](.github/workflows/code_quality.yml),
+which mirrors what plugins.qgis.org checks on upload and adds what it does
+not:
+
+| Job | What it does |
+| --- | --- |
+| **Lint a bezpečnost** | `tests/check_sources.py`, bandit, detect-secrets, flake8, ruff |
+| **Kompatibilita s Qt6** | `pyqgis4-checker` in dry-run mode |
+| **Smoke test** | loads the plugin in headless QGIS — both `ltr` (Qt 5) and `stable` (Qt 6) |
+| **Balíček pluginu** | builds `amcr_viewer.zip`, asserts its contents, uploads it as an artifact |
+
+Reproducing them locally:
+
+```bash
+python3 tests/check_sources.py
+ruff check .
+flake8 --config amcr_viewer/.flake8 amcr_viewer/
+bandit -r amcr_viewer/
+docker run --rm -v "$PWD:/work:ro" -w /work --user "$(id -u):$(id -g)" \
+  -e HOME=/tmp qgis/qgis:stable python3 tests/smoke_test.py
+```
+
+---

 ## 6. Links and resources

-* [AMCR/Digiarchive Documentation](https://amcr-help.aiscr.cz/) (only in Czech).
-* [AMCR Viewer tutorial](https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html) (only in Czech).
+* [AMČR / Digiarchiv documentation](https://amcr-help.aiscr.cz/) (Czech only)
+* [AMČR Viewer tutorial](https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html)
+  (Czech only)
+* [AMČR-PAS](https://amcr-info.aiscr.cz/amcr-pas/) — the amateur collaborator
+  portal behind the Individual finds records
+* [Import/Export. Pluginy propojující QGIS s AMČR \[poster\]](https://zenodo.org/records/20504909)
+  (Czech only; describes v1.3.2)
+
+## Citing
+
+Cite the plugin using [`CITATION.cff`](./CITATION.cff) or the concept DOI
+[10.5281/zenodo.18609813](https://doi.org/10.5281/zenodo.18609813), which
+always resolves to the latest release.
+
+## Licence
+
+GPL-3.0 — see [`LICENSE`](./LICENSE).
@@ -0,0 +1,12 @@
+# Konfigurace flake8 pro plugin AMČR Viewer.
+#
+# Soubor leží vedle metadata.txt schválně: scanner na plugins.qgis.org
+# hledá .flake8 pouze v kořeni balíčku uvnitř ZIPu, takže stejná pravidla
+# platí v CI, lokálně i při uploadu.
+# https://plugins.qgis.org/docs/security-scanning/config-files
+[flake8]
+# resources.py je vygenerovaný výstup pyrcc ("All changes made in this
+# file will be lost"), není nikde importovaný a zdrojový .qrc v repu není.
+# Ručně se neformátuje.
+per-file-ignores =
+    *resources.py: E302,E305,E501
@@ -31,6 +31,5 @@ def classFactory(iface):  # pylint: disable=invalid-name
    :param iface: A QGIS interface instance.
    :type iface: QgsInterface
    """
-    #
    from .amcr_viewer import AmcrViewer
    return AmcrViewer(iface)
@@ -1,178 +1,397 @@
-# -*- coding: utf-8 -*-
-import os
+# -*- coding: utf-8 -*-
 import csv
-import codecs
-import requests
-import json
+import os
+import time
+import xml.etree.ElementTree as ET  # nosec

-# Cesta k adresáři pluginu
+import requests
+from qgis.core import Qgis, QgsMessageLog
+
+# Define paths for the plugin and its codelists directory
 PLUGIN_DIR = os.path.dirname(__file__)
 CODELISTS_DIR = os.path.join(PLUGIN_DIR, 'codelists')
+BASE_URL_AMCR = "https://api.aiscr.cz/2.2/oai"
+BASE_URL_DA = "https://digiarchiv.aiscr.cz/api/search/query"
+OUTPUT_FILE = os.path.join(CODELISTS_DIR, 'heslar.csv')
+
+slovnicek = {
+    'obdobi': (BASE_URL_AMCR, 'heslo:obdobi'),
+    'typ_akce': (BASE_URL_AMCR, 'heslo:akce_typ'),
+    'areal': (BASE_URL_AMCR, 'heslo:areal'),
+    'kraj': (BASE_URL_AMCR, 'ruian_kraj'),
+    'organizace': (BASE_URL_AMCR, 'organizace'),
+    'okres': (BASE_URL_AMCR, 'ruian_okres'),
+    'katastr': (BASE_URL_AMCR, 'ruian_katastr'),
+    'pian_presnost': (BASE_URL_AMCR, 'heslo:pian_presnost'),
+    'typ_lokality': (BASE_URL_AMCR, 'heslo:lokalita_typ'),
+    'druh_lokality': (BASE_URL_AMCR, 'heslo:lokalita_druh'),
+    'jistota': (BASE_URL_AMCR, 'heslo:jistota_urceni'),
+    'lokalita_zachovalost': (BASE_URL_AMCR, 'heslo:stav_dochovani'),
+    'pristupnost': (BASE_URL_AMCR, 'heslo:pristupnost'),
+    'nalez_kategorie': (BASE_URL_AMCR, 'heslo:predmet_druh_kat'),
+    'druh_nalezu': (BASE_URL_AMCR, 'heslo:predmet_druh'),
+    'specifikace': (BASE_URL_AMCR, 'heslo:predmet_specifikace'),
+    'nalezove_okolnosti': (BASE_URL_AMCR, 'heslo:nalezove_okolnosti'),
+    'vedouci': (BASE_URL_DA, 'f_vedouci'),
+    'nalezce': (BASE_URL_DA, 'f_nalezce'),
+}
+
+NS = {
+    'oai': 'http://www.openarchives.org/OAI/2.0/',
+    'dc': 'http://purl.org/dc/elements/1.1/',
+    'oai_dc': 'http://www.openarchives.org/OAI/2.0/oai_dc/'
+}
+

 def ensure_codelists_dir():
+    """Creates the codelists directory if it does not exist."""
    if not os.path.exists(CODELISTS_DIR):
        os.makedirs(CODELISTS_DIR)

-# --- 1. NAČÍTÁNÍ DAT ---

-def load_csv_data(filename):
-    """Obecná funkce pro načtení CSV souboru do slovníku"""
-    data = {}
+def parse_codelist_file(filename, target_dict=None):
+    """
+    Reads a CSV codelist file and populates
+    the target dictionary grouped by categories.
+    """
+    if target_dict is None:
+        target_dict = {}
+
    path = os.path.join(CODELISTS_DIR, filename)
+
+    # Return early if the file doesn't exist to avoid missing file errors
    if not os.path.exists(path):
-        return data
+        return target_dict

    try:
-        with codecs.open(path, 'r', 'utf-8') as f:
+        # Open the file using standard UTF-8 encoding
+        with open(path, encoding='utf-8') as f:
            reader = csv.reader(f, delimiter=';')
-            # Zkusíme přeskočit hlavičku, pokud tam je
-            first_row = next(reader, None)
-            
-            # Pokud soubor není prázdný, zpracujeme ho
-            if first_row:
-                # Pokud první řádek vypadá jako data (neobsahuje slovo "Název"), vrátíme ho do hry
-                # Ale my budeme generovat soubory s hlavičkou, takže OK.
-                pass 

+            # Skip the CSV header row
+            next(reader, None)
+
+            # Iterate through rows and extract label, code, and category
            for row in reader:
                if len(row) >= 3:
                    label = row[0].strip()
                    code = row[1].strip()
-                    category = row[2].strip()
-                    
-                    # Tady můžeme filtrovat podle kategorie, 
-                    # nebo prostě vrátit všechno jako {label: code}
-                    # Pro jednoduchost vracíme {label: code}
-                    clean_code = code if code else None
-                    data[label] = clean_code
+                    cat = row[2].strip()
+                    clean = code if code else None
+
+                    # Initialize a new dictionary for a category if encountered
+                    # for the first time
+                    if cat not in target_dict:
+                        target_dict[cat] = {}
+
+                    # Assign the extracted code to the corresponding label
+                    # within the category
+                    target_dict[cat][label] = clean
+
    except Exception as e:
-        print(f"AMČR Chyba čtení {filename}: {e}")
-        
-    return data
+        QgsMessageLog.logMessage(
+            f"AMČR Codelist Read Error for {filename}: {e}",
+            "AMČR", Qgis.MessageLevel.Critical)
+
+    return target_dict
+

 def load_all_data():
-    """
-    Načte statický heslář I dynamický heslář vedoucích.
-    Vrací slovník slovníků.
-    """
+    """Loads the codelist during plugin startup."""
    ensure_codelists_dir()
-    
-    # 1. Načteme hlavní statický heslář
-    # Musíme ho rozparsovat podle kategorií, tak jak to bylo předtím
-    categorized_data = {
-        'obdobi': {}, 'typ_akce': {}, 'areal': {}, 
-        'kraj': {}, 'organizace': {}, 'okres': {}, 'katastr': {},
-        'vedouci': {}, 'pian_presnost': {}, 'typ_lokality': {}, 'druh_lokality': {},
-        'jistota': {}, 'lokalita_zachovalost': {}
-    }
-    
-    # Funkce pro roztřídění načteného slovníku (tohle je trochu redundance, ale pro zachování logiky)
-    def parse_file(filename):
-        path = os.path.join(CODELISTS_DIR, filename)
-        if not os.path.exists(path): return
-        
-        try:
-            with codecs.open(path, 'r', 'utf-8') as f:
-                reader = csv.reader(f, delimiter=';')
-                next(reader, None) # Skip header
-                for row in reader:
-                    if len(row) >= 3:
-                        label = row[0].strip()
-                        code = row[1].strip()
-                        cat = row[2].strip()
-                        clean = code if code else None
-                        
-                        if cat in categorized_data:
-                            categorized_data[cat][label] = clean
-        except: pass
-
-    # Načteme soubory
-    parse_file('heslar.csv') # Statické
-    parse_file('vedouci.csv') # Dynamické (pokud existuje)
-    
+    categorized_data = {k: {} for k in slovnicek}
+    parse_codelist_file('heslar.csv', categorized_data)
    return categorized_data

-# --- 2. AKTUALIZACE DAT (DOWNLOAD) ---

-def download_vedouci():
+def _facet_name(item):
    """
-    Stáhne seznam vedoucích z API (pomocí onlyFacets) a uloží do codelists/vedouci.csv.
+    Returns the value of one facet item from the Digiarchive API.
+
+    Digiarchive v4.1.0 (Solr 10, json.nl=arrarr) returns facet items as
+    ["value", count] pairs; older versions returned {"name": "value", ...}
+    objects. Both shapes are accepted so the plugin works against either.
+    """
+    if isinstance(item, dict):
+        return item.get("name")
+    if isinstance(item, (list, tuple)) and item:
+        return item[0]
+    return None
+
+
+def fetch_set(base_url, internal_name, api_set, task=None):
+    dataset = []
+    params_amcr = {
+        "verb": "ListRecords",
+        "metadataPrefix": "oai_dc",
+        "set": api_set
+    }
+    params_da = {
+        "entity": "samostatny_nalez" if internal_name == "nalezce" else "akce",
+        "rows": 0,
+        "noFacets": "false",
+        "onlyFacets": "true"
+    }
+
+    while True:
+        # Check for cancellation at each iteration
+        if task and task.isCanceled():
+            return None
+
+        try:
+            if "digiarchiv" not in base_url:
+                response = requests.get(
+                    base_url, params=params_amcr, timeout=30
+                )
+                response.raise_for_status()
+                root = ET.fromstring(response.content)  # nosec
+
+                records = root.findall('.//oai:record', NS)
+                for rec in records:
+                    metadata = rec.find('.//oai_dc:dc', NS)
+                    if metadata is not None:
+                        # Code (identifier)
+                        identifier_el = metadata.find('dc:identifier', NS)
+                        kod = (
+                            identifier_el.text
+                            if identifier_el is not None
+                            else ""
+                        )
+
+                        # Title – filter out system labels "AMČR - ..."
+                        titles = metadata.findall('dc:title', NS)
+                        nazev = ""
+                        for t in titles:
+                            if (
+                                t.text
+                                and not t.text.startswith("AMČR -")
+                                and not t.text.startswith(" AMČR -")
+                            ):
+                                nazev = t.text
+                                break
+                        # If no title passed the filter, fall back
+                        # to the first available one
+                        if not nazev and titles:
+                            nazev = titles[0].text
+
+                        specialni_pripady = ['okres', 'katastr']
+
+                        if internal_name in specialni_pripady:
+                            kod = nazev
+
+                        if internal_name == 'pristupnost':
+                            kod = next(
+                                (
+                                    t.text for t in titles
+                                    if t.text
+                                    and len(t.text) == 1
+                                    and t.text.isalpha()
+                                ),
+                                None
+                            )
+                            # Skip records without a valid one-letter code –
+                            # a None code would end up in the CSV and later
+                            # in the API filter as the string "None"
+                            if not kod:
+                                continue
+
+                        dataset.append({
+                            'Název': nazev,
+                            'Kód': kod,
+                            'Kategorie': internal_name
+                        })
+
+                # Pagination
+                token = root.find('.//oai:resumptionToken', NS)
+                if token is not None and token.text:
+                    params_amcr = {
+                        "verb": "ListRecords",
+                        "resumptionToken": token.text
+                    }
+                    time.sleep(0.5)
+                else:
+                    break
+
+            else:
+                response = requests.get(base_url, params=params_da, timeout=30)
+                response.raise_for_status()
+                data_json = response.json()
+
+                records = data_json['facet_counts']['facet_fields'][api_set]
+
+                for r in records:
+
+                    nazev = _facet_name(r)
+                    if not nazev:
+                        continue
+
+                    dataset.append({
+                            'Název': nazev,
+                            'Kód': nazev,
+                            'Kategorie': internal_name
+                        })
+
+                break
+
+        except Exception as e:
+            # A partial set (e.g. pagination interrupted halfway) would
+            # silently drop codes – report the whole set as failed instead
+            # and let the caller keep the previous values
+            QgsMessageLog.logMessage(
+                f"Chyba u setu {api_set}: {e}",
+                "AMČR", Qgis.MessageLevel.Warning)
+            return []
+
+    return dataset
+
+
+def _read_existing_rows():
+    """
+    Returns the rows of the current heslar.csv grouped by category, so a set
+    that fails to download can keep its previous values.
+    """
+    rows = {}
+    if not os.path.exists(OUTPUT_FILE):
+        return rows
+    try:
+        with open(OUTPUT_FILE, encoding='utf-8-sig', newline='') as f:
+            for row in csv.DictReader(f, delimiter=';'):
+                cat = (row.get('Kategorie') or '').strip()
+                if cat:
+                    rows.setdefault(cat, []).append(row)
+    except Exception as e:
+        QgsMessageLog.logMessage(
+            f"Nelze načíst stávající hesláře: {e}",
+            "AMČR", Qgis.MessageLevel.Warning)
+    return rows
+
+
+def download_heslare(task=None, failed=None):
+    """
+    Fetches the codelists from the AMČR API and saves it to a CSV file.
+
+    A set that fails or comes back empty keeps its rows from the current
+    heslar.csv instead of being wiped; its name is appended to ``failed``
+    (if given) so the caller can warn the user.
    """
    ensure_codelists_dir()
-    
-    # Tvá URL + pojistka, abychom dostali všechny záznamy (limit -1)
-    url = "https://digiarchiv.aiscr.cz/api/search/query?entity=akce&sort=datestamp%20desc&page=0&onlyFacets=True&rows=0"
-    
-    try:
-        r = requests.get(url, timeout=20) # Raději delší timeout pro velký seznam
-        r.raise_for_status()
-        data = r.json()
-        
-        # Cesta k datům dle tvého JSONu:
-        # {"facet_counts": { "f_vedouci": [ {"name": "Novák", ...}, ... ] }}
-        vedouci_list = data.get('facet_counts', {}).get('f_vedouci', [])
-        
-        if not vedouci_list:
-             # Zkusíme ještě alternativní cestu, kdyby API vrátilo standardní Solr strukturu
-             # (facet_counts -> facet_fields -> f_vedouci)
-             vedouci_list = data.get('facet_counts', {}).get('facet_fields', {}).get('f_vedouci', [])
+    existing = _read_existing_rows()
+    all_data = []
+    total_sets = len(slovnicek)
+# index, (interni, api_nazev)
+    for index, (key, value) in enumerate(slovnicek.items()):

-        csv_path = os.path.join(CODELISTS_DIR, 'vedouci.csv')
-        
-        count = 0
-        with codecs.open(csv_path, 'w', 'utf-8') as f:
-            writer = csv.writer(f, delimiter=';')
-            writer.writerow(['Název', 'Kód', 'Kategorie'])
-            
-            # NOVÁ LOGIKA PARSOVÁNÍ
-            for item in vedouci_list:
-                name = None
-                
-                # Varianta A: Položka je slovník {"name": "Jan Novák", "value": 10}
-                if isinstance(item, dict):
-                    name = item.get('name')
-                
-                # Varianta B: Položka je jen string (kdyby se API vrátilo k plochému seznamu)
-                elif isinstance(item, str):
-                    name = item
-                
-                # Pokud máme jméno a není to číslo (count), zapíšeme
-                if name and not str(name).isdigit():
-                    writer.writerow([name, name, 'vedouci'])
-                    count += 1
-                
-        return True, f"Staženo {count} jmen."
-        
-    except Exception as e:
-        return False, str(e)
+        base_url = value[0]
+        interni = key
+        api_nazev = value[1]

-# --- GLOBAL DATA ---
-# Toto se načte při startu QGISu
-_DATA = load_all_data()
+        # Check if the user cancelled the task via the QGIS taskbar
+        if task and task.isCanceled():
+            return False

-OBDOBI = _DATA['obdobi']
-TYP_AKCE = _DATA['typ_akce']
-AREAL = _DATA['areal']
-KRAJE = _DATA['kraj']
-ORGANIZACE = _DATA['organizace']
-OKRESY = _DATA['okres']
-KATASTRY = _DATA['katastr']
-VEDOUCI = _DATA['vedouci']
-PIAN_PRESNOST = _DATA['pian_presnost']
-TYP_LOKALITY = _DATA['typ_lokality']
-DRUH_LOKALITY = _DATA['druh_lokality']
-JISTOTA = _DATA['jistota']
-LOKALITA_ZACHOVALOST = _DATA['lokalita_zachovalost']
+        QgsMessageLog.logMessage(
+            f"Zpracovávám kategorii: {interni}...",
+            "AMČR", Qgis.MessageLevel.Info)

-def refresh_vedouci_cache():
-    """
-    Znovu načte soubor vedouci.csv a aktualizuje globální proměnnou VEDOUCI.
-    Použijeme 'update', aby se zachovala reference na objekt (pokud ho dialog už používá).
-    """
-    temp_data = load_all_data()
-    new_vedouci = temp_data['vedouci']
-    
-    # Vyčistíme a naplníme existující slovník (in-place update)
+        # Pass the task correctly to the updated fetch function
+        data = fetch_set(base_url, interni, api_nazev, task=task)
+
+        if data is None:
+            return False  # Cancelled mid-download
+
+        if not data:
+            # Never replace a working codelist with nothing – an API change
+            # would otherwise silently empty the filter in the dialog
+            old = existing.get(interni, [])
+            QgsMessageLog.logMessage(
+                f"Heslář '{interni}' se nepodařilo stáhnout, "
+                f"ponechávám předchozí hodnoty ({len(old)} položek).",
+                "AMČR", Qgis.MessageLevel.Warning)
+            if failed is not None:
+                failed.append(interni)
+            data = old
+
+        all_data.extend(data)
+
+        # Report progress (0-100)
+        if task:
+            progress = (index + 1) / total_sets * 100
+            task.setProgress(progress)
+
+    # Save to CSV
+    with open(OUTPUT_FILE, 'w', newline='', encoding='utf-8-sig') as f:
+        fieldnames = ['Název', 'Kód', 'Kategorie']
+        writer = csv.DictWriter(f, fieldnames=fieldnames, delimiter=';',
+                                extrasaction='ignore')
+        writer.writeheader()
+        writer.writerows(all_data)
+
+    return True
+
+
+def refresh_globals():
+    """Reloads data from files into the global variables."""
+    data = load_all_data()
+
+    OBDOBI.clear()
+    OBDOBI.update(data.get('obdobi', {}))
+    TYP_AKCE.clear()
+    TYP_AKCE.update(data.get('typ_akce', {}))
+    AREAL.clear()
+    AREAL.update(data.get('areal', {}))
+    KRAJE.clear()
+    KRAJE.update(data.get('kraj', {}))
+    ORGANIZACE.clear()
+    ORGANIZACE.update(data.get('organizace', {}))
+    OKRESY.clear()
+    OKRESY.update(data.get('okres', {}))
+    KATASTRY.clear()
+    KATASTRY.update(data.get('katastr', {}))
    VEDOUCI.clear()
-    VEDOUCI.update(new_vedouci)
-    return len(VEDOUCI)
+    VEDOUCI.update(data.get('vedouci', {}))
+    PIAN_PRESNOST.clear()
+    PIAN_PRESNOST.update(data.get('pian_presnost', {}))
+    TYP_LOKALITY.clear()
+    TYP_LOKALITY.update(data.get('typ_lokality', {}))
+    DRUH_LOKALITY.clear()
+    DRUH_LOKALITY.update(data.get('druh_lokality', {}))
+    JISTOTA.clear()
+    JISTOTA.update(data.get('jistota', {}))
+    LOKALITA_ZACHOVALOST.clear()
+    LOKALITA_ZACHOVALOST.update(data.get('lokalita_zachovalost', {}))
+    PRISTUPNOST.clear()
+    PRISTUPNOST.update(data.get('pristupnost', {}))
+    NALEZ_KATEGORIE.clear()
+    NALEZ_KATEGORIE.update(data.get('nalez_kategorie', {}))
+    DRUH_NALEZU.clear()
+    DRUH_NALEZU.update(data.get('druh_nalezu', {}))
+    SPECIFIKACE.clear()
+    SPECIFIKACE.update(data.get('specifikace', {}))
+    NALEZOVE_OKOLNOSTI.clear()
+    NALEZOVE_OKOLNOSTI.update(data.get('nalezove_okolnosti', {}))
+    NALEZCE.clear()
+    NALEZCE.update(data.get('nalezce', {}))
+
+
+# Initialize empty dicts that will be populated immediately below
+OBDOBI = {}
+TYP_AKCE = {}
+AREAL = {}
+KRAJE = {}
+ORGANIZACE = {}
+OKRESY = {}
+KATASTRY = {}
+VEDOUCI = {}
+PIAN_PRESNOST = {}
+TYP_LOKALITY = {}
+DRUH_LOKALITY = {}
+JISTOTA = {}
+LOKALITA_ZACHOVALOST = {}
+PRISTUPNOST = {}
+NALEZ_KATEGORIE = {}
+DRUH_NALEZU = {}
+SPECIFIKACE = {}
+NALEZOVE_OKOLNOSTI = {}
+NALEZCE = {}
+
+refresh_globals()
@@ -1,39 +1,64 @@
 # -*- coding: utf-8 -*-
-from qgis.PyQt.QtCore import QSettings, QTranslator, QCoreApplication
-from qgis.PyQt.QtGui import QIcon
-from qgis.PyQt.QtWidgets import QMenu, QAction, QToolButton
-
-from .amcr_tools import load_amcr_data
-from .amcr_dialog import AmcrFilterDialog
-from .resources import *
 import os.path

+from qgis.core import Qgis
+from qgis.PyQt.QtCore import QCoreApplication, QSettings, QTranslator, QUrl
+from qgis.PyQt.QtGui import QDesktopServices, QIcon
+from qgis.PyQt.QtWidgets import QAction, QDialog, QMenu, QToolButton
+
+from .amcr_dialog import AmcrFilterDialog, LoginDialog
+from .amcr_tools import load_amcr_data, login_to_api
+
+
 class AmcrViewer:
-    
+    """
+    Main plugin class that manages the GUI elements, menu entries,
+    and coordinates the flow between user input and data processing.
+    """
+
    def __init__(self, iface):
+        """
+        Constructor initializes the connection to QGIS interface and sets up
+        internationalization (i18n).
+        """
        self.iface = iface
        self.plugin_dir = os.path.dirname(__file__)
-        locale = QSettings().value('locale/userLocale')[0:2]
+
+        # Determine the user's locale to load appropriate translation files.
+        # The setting may be missing (None) on a fresh QGIS install.
+        locale = str(QSettings().value('locale/userLocale') or 'en')[0:2]
        locale_path = os.path.join(
            self.plugin_dir,
            'i18n',
-            'AmcrViewer_{}.qm'.format(locale))
+            f'AmcrViewer_{locale}.qm'
+        )

+        # Install the translator if a translation file
+        # for the current locale exists
        if os.path.exists(locale_path):
            self.translator = QTranslator()
            self.translator.load(locale_path)
            QCoreApplication.installTranslator(self.translator)

+        # Initialize internal state
        self.actions = []
-        self.menu = self.tr(u'&AMČR Viewer')
+        self.menu = self.tr('&AMČR Viewer')
        self.first_start = None

    def tr(self, message):
+        """
+        Helper method for translating strings within
+        the AmcrViewer context.
+        """
        return QCoreApplication.translate('AmcrViewer', message)

    def add_action(self, icon_path, text, callback, enabled_flag=True,
                   add_to_menu=True, add_to_toolbar=True, status_tip=None,
                   whats_this=None, parent=None):
+        """
+        Helper method to create QActions and automatically register them
+        into the QGIS Menu and Toolbar.
+        """
        icon = QIcon(icon_path)
        action = QAction(icon, text, parent)
        action.triggered.connect(callback)
@@ -45,29 +70,40 @@ class AmcrViewer:
        if whats_this is not None:
            action.setWhatsThis(whats_this)

+        # Standard QGIS API for adding icons and menu items
        if add_to_toolbar:
            self.iface.addToolBarIcon(action)

        if add_to_menu:
            self.iface.addPluginToMenu(self.menu, action)

-        self.actions.append(action)
+        # Store only actions that are directly attached
+        # to the QGIS UI for later cleanup
+        if add_to_toolbar or add_to_menu:
+            self.actions.append(action)
+
        return action

    def initGui(self):
-       
-        import os
-        plugin_dir = os.path.dirname(__file__)
-        icon_akce_path = os.path.join(plugin_dir, 'akce.png')
-        icon_lokality_path = os.path.join(plugin_dir, 'lokality.png')
+        """
+        Called when the plugin is loaded. Creates the menu structure,
+        sub-actions, and the dropdown tool button in the toolbar.
+        """
+        # Define paths for action-specific icons
+        icon_akce_path = os.path.join(self.plugin_dir, 'akce.png')
+        icon_pas_path = os.path.join(self.plugin_dir, 'sn.png')
+        icon_lokality_path = os.path.join(self.plugin_dir, 'lokality.png')
+        icon_amcr_help_path = os.path.join(self.plugin_dir, 'amcr-help.png')

-        # 1. Vytvoření společného menu
+        # 1. Create a container menu for the plugin
        self.plugin_menu = QMenu()

-        # 2. Vytvoření akcí (bez automatického přidání do lišty a menu)
+        # 2. Create sub-actions (Download Projects / Download Sites)
+        # add_to_menu/toolbar is False because these go into our
+        # custom dropdown menu
        self.action_download_akce = self.add_action(
            icon_path=icon_akce_path,
-            text=self.tr(u'Stáhnout data akcí | AMČR Viewer'),
+            text=self.tr('Stáhnout data akcí | AMČR Viewer'),
            callback=lambda checked=False: self.run_download('akce'),
            parent=self.iface.mainWindow(),
            add_to_menu=False,
@@ -75,51 +111,137 @@ class AmcrViewer:
        )
        self.plugin_menu.addAction(self.action_download_akce)

+        self.action_download_pas = self.add_action(
+            icon_path=icon_pas_path,
+            text=self.tr('Stáhnout data samostatných nálezů | AMČR Viewer'),
+            callback=lambda checked=False: self.run_download(
+                'samostatny_nalez'),
+            parent=self.iface.mainWindow(),
+            add_to_menu=False,
+            add_to_toolbar=False
+        )
+        self.plugin_menu.addAction(self.action_download_pas)
+
        self.action_download_lokality = self.add_action(
            icon_path=icon_lokality_path,
-            text=self.tr(u'Stáhnout data lokalit | AMČR Viewer'),
-            callback=lambda checked=False: self.run_download('lokalita'), 
+            text=self.tr('Stáhnout data lokalit | AMČR Viewer'),
+            callback=lambda checked=False: self.run_download('lokalita'),
            parent=self.iface.mainWindow(),
            add_to_menu=False,
            add_to_toolbar=False
        )
        self.plugin_menu.addAction(self.action_download_lokality)

-        # 3. Přidání rozbalovacího menu do hlavního menu QGIS
+        self.action_login_dialog = self.add_action(
+            icon_path=icon_pas_path,
+            text=self.tr('Přihlásit se | AMČR Viewer'),
+            callback=lambda checked=False: self.login(),
+            parent=self.iface.mainWindow(),
+            add_to_menu=False,
+            add_to_toolbar=False
+        )
+        self.plugin_menu.addAction(self.action_login_dialog)
+
+        self.action_amcr_help = self.add_action(
+            icon_path=icon_amcr_help_path,
+            text=self.tr('Nápověda AMČR Help | AMČR Viewer'),
+            callback=lambda checked=False: self.open_help(),
+            parent=self.iface.mainWindow(),
+            add_to_menu=False,
+            add_to_toolbar=False
+        )
+        self.plugin_menu.addAction(self.action_amcr_help)
+
+        # 3. Create the main project action and attach the menu to it
        main_icon = QIcon(icon_akce_path)
-        self.main_action = QAction(main_icon, 'AMČR Viewer', self.iface.mainWindow())
+        self.main_action = QAction(
+            main_icon,
+            'AMČR Viewer',
+            self.iface.mainWindow()
+        )
        self.main_action.setMenu(self.plugin_menu)
        self.iface.addPluginToMenu(self.menu, self.main_action)

-        # 4. Přidání rozevíracího tlačítka do nástrojové lišty (Toolbar)
+        # 4. Create and configure a QToolButton for the QGIS Toolbar
+        # This button acts as a dropdown menu button (MenuButtonPopup)
        self.tool_button = QToolButton()
        self.tool_button.setMenu(self.plugin_menu)
        self.tool_button.setDefaultAction(self.action_download_akce)
-        self.tool_button.setPopupMode(QToolButton.MenuButtonPopup)
-        
-        # Vložení vytvořeného tlačítka do QGIS rozhraní
-        self.iface.addToolBarWidget(self.tool_button)
-        
+        self.tool_button.setPopupMode(
+            QToolButton.ToolButtonPopupMode.MenuButtonPopup
+        )
+
+        # Add the widget directly to the toolbar
+        # and store the reference for cleanup
+        self.toolbar_action = self.iface.addToolBarWidget(self.tool_button)
+
        self.first_start = True

    def unload(self):
+        """
+        Called when the plugin is disabled or removed.
+        Ensures all GUI elements are removed from QGIS to avoid ghost icons.
+        """
+        # 1. Remove the custom entry from the main 'Plugins' menu
+        if hasattr(self, 'main_action'):
+            self.iface.removePluginMenu(self.menu, self.main_action)
+
+        # 2. Remove the custom QToolButton from the toolbar
+        if hasattr(self, 'toolbar_action'):
+            self.iface.removeToolBarIcon(self.toolbar_action)
+
+        # 3. Clean up any remaining actions registered in self.actions
        for action in self.actions:
-            self.iface.removePluginMenu(self.tr(u'&AMČR Viewer'), action)
+            self.iface.removePluginMenu(self.menu, action)
            self.iface.removeToolBarIcon(action)
-        
+        self.actions.clear()
+
+        # 4. Reset map tools if currently active
        if hasattr(self, 'tool'):
            self.iface.mapCanvas().unsetMapTool(self.tool)

    # --- Data downloading ---
    def run_download(self, typ_dat):
-        
+        """
+        Triggered by menu/toolbar actions. Opens the filter dialog and
+        hands off the parameters to the data loader.
+        """
+        # Open the specific filter dialog (Projects vs Sites)
        dlg = AmcrFilterDialog(typ_dat)
-        result = dlg.exec_()
-        
-        if result == 1:
+        result = dlg.exec()
+
+        # If user confirmed the dialog (OK button),
+        # gather filters and load data
+        if result == QDialog.DialogCode.Accepted:
            filters = dlg.get_filters()
            bbox = dlg.get_bbox()
            komponenty = dlg.get_komponenty()
-            
+
+            # Access the map canvas and start
+            # the fetch/render process from amcr_tools
            canvas = self.iface.mapCanvas()
            load_amcr_data(canvas, bbox, filters, typ_dat, komponenty)
+
+    def login(self):
+        dlg = LoginDialog(parent=self.iface.mainWindow())
+        result = dlg.exec()
+        if result == QDialog.DialogCode.Accepted:
+            username, password = LoginDialog.get_credentials()
+            session = login_to_api(username, password)
+            if session:
+                self.iface.messageBar().pushMessage(
+                    "AMČR",
+                    "Přihlášení proběhlo úspěšně.",
+                    level=Qgis.MessageLevel.Success
+                )
+            else:
+                self.iface.messageBar().pushMessage(
+                    "AMČR",
+                    "Přihlášení se nezdařilo – viz záložka AMČR login "
+                    "v panelu Zprávy.",
+                    level=Qgis.MessageLevel.Critical
+                )
+
+    def open_help(self):
+        help_url = "https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html"
+        QDesktopServices.openUrl(QUrl(help_url))
@@ -5,13 +5,14 @@

 [general]
 name=AMČR Viewer
-qgisMinimumVersion=3.4
+qgisMinimumVersion=3.44.0
+qgisMaximumVersion=4.99.0
 description=Viewing and downloading the AMČR data.
-version=1.2.0-rc.1
+version=2.1.3
 author=David Spáčil
 email=spacil@arub.cz

-about=This plugin is intended for downloading the data (Fieldwork events, Sites and their Components) from the Digiarchive of the Archaeological Map of the Czech Republic (https://digiarchiv.aiscr.cz/). As of now, only publicly accessible data can be downloaded.
+about=This plugin is intended for downloading the data (Fieldwork events, Sites, and their Components) from the Digital archive of the Archaeological Map of the Czech Republic (https://digiarchiv.aiscr.cz/).

 tracker=https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/issues
 repository=https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer
@@ -21,14 +22,47 @@ repository=https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer

 hasProcessingProvider=no
 # Uncomment the following line and add your changelog:
-# changelog=
+changelog=
+  Plný seznam změn v češtině je dostupný zde: https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/releases/tag/v2.1.1
+  v2.1.3 (2026-10-01)
+   * Fixed empty person codelists (excavation leaders, finders) after updating codelists against Digiarchive v4.1.0
+   * A codelist that fails to download keeps its previous values and the user is warned
+  v2.1.2 (2026-09-01)
+   * Qt6 compatibility
+   * Code clean-up
+  v2.1.1 (2026-09-01)
+   * Added download of Individual finds (PAS), including a dedicated menu entry
+   * Added filtering by date
+   * Added filtering of project fieldwork events and a Project column in the attribute table
+   * Codelists are now built from the Digiarchiv API as well, not only from OAI-PMH; persons come from its facets by role (finder, fieldwork leader)
+   * Updated the bundled codelist file
+   * Filter dialog is now scrollable
+   * Empty API results are now diagnosable from the Messages panel: the query URL and API errors are logged
+   * Code clean-up
+  v2.0.2 (2026-06-13)
+   * Plugin-wide fixes and optimalizations (details https://github.com/ARUP-CAS/aiscr-qgis-amcr-viewer/pull/49)
+  v2.0.1 (2026-06-10)
+   * Fixed QGIS minimum version
+  v2.0.0 (2026-06-05)
+   * Added warning regarding the feature duplication when loading components to the dialog 
+   * Added Help button to the plugin menu
+   * Code clean-up
+  v2.0.0-alpha.4 (2026-06-03)
+   * Backend filtering of the results based on the component-related filters improvement (plugin not only loads the results from API, it filters them further)
+  v2.0.0-alpha.2–3 (2026-05-19)
+   * Security vulnerabilities fix
+  v2.0.0-alpha.1 (2026-05-19):
+   * Attribute fields renamed to be ASCII compliant
+   * Codelist update; codelist can be recompiled from AMČR API
+   * Base element changed from Documentation Unit to Component if user asks for components to simplify result filtering
+   * Plugin now supports logging with an AMČR account and enables the downloading of Events and Sites available to the roles Researcher and higher 

 # Tags are comma separated with spaces allowed
-tags=python,AMCR,AIS CR,archaeology,PIAN,AMČR
+tags=python,AMCR,AIS CR,archaeology,PIAN,AMČR,archeologie

 homepage=https://amcr-help.aiscr.cz/digiarchiv/qgis-viewer.html
 category=Vector
-icon=download.png
+icon=akce.png
 # experimental flag
 experimental=False

@@ -40,9 +74,6 @@ deprecated=False
 # Check the documentation for more information.
 # plugin_dependencies=

-# Category of the plugin: Raster, Vector, Database or Web
-# category=
-
 # If the plugin can run on QGIS Server.
 server=False

@@ -6,7 +6,7 @@
 #
 # WARNING! All changes made in this file will be lost!

-from PyQt5 import QtCore
+from qgis.PyQt import QtCore

 qt_resource_data = b"\
 \x00\x00\x04\x0a\
@@ -0,0 +1,44 @@
+# Konfigurace lintů pro tento repozitář.
+#
+# Plugin se nedistribuuje jako Python balíček (do QGISu jde ZIP složky
+# amcr_viewer/), takže tenhle soubor nic nebalí ani neinstaluje – slouží
+# jen k tomu, aby ruff choval stejně v CI, lokálně i za rok. Bez explicitní
+# konfigurace se výchozí sada pravidel mezi verzemi ruffu mění.
+#
+# Konfigurace flake8 je záměrně jinde: v amcr_viewer/.flake8, protože ji
+# musí najít i scanner na plugins.qgis.org.
+
+[tool.ruff]
+line-length = 79
+# QGIS 3.44 běží na Pythonu 3.9 a novějším
+target-version = "py39"
+# Generovaný výstup pyrcc, "All changes made in this file will be lost"
+extend-exclude = ["amcr_viewer/resources.py"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle – chyby
+    "W",    # pycodestyle – varování
+    "F",    # pyflakes
+    "I",    # pořadí importů
+    "UP",   # zastaralé konstrukce
+    "B",    # bugbear
+    "C4",   # comprehensions
+    "SIM",  # zjednodušení
+    "RET",  # návratové hodnoty
+    "BLE",  # holé except
+]
+ignore = [
+    # Hlavička "# -*- coding: utf-8 -*-" je konvence šablony Plugin
+    # Builderu a drží se v celém projektu jednotně.
+    "UP009",
+    # "except Exception" je v pluginu záměr: výjimka nesmí propadnout do
+    # QGISu, chyba se uživateli ukáže v liště zpráv.
+    "BLE001",
+    # Obě dotčená místa mají ke každé větvi vysvětlující komentář,
+    # sloučením do jednoho výrazu by se čitelnost zhoršila.
+    "SIM103",
+    # contextlib.suppress() by kvůli jednomu místu přidal import a odsunul
+    # komentář, který vysvětluje, proč tam ta výjimka je.
+    "SIM105",
+]
@@ -9,7 +9,7 @@
   id="svg1"
   xml:space="preserve"
   sodipodi:docname="icon.svg"
-   inkscape:version="1.4.3 (0d15f75, 2025-12-25)"
+   inkscape:version="1.4.4 (dcaf3e7d9e, 2026-05-05)"
   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
   xmlns="http://www.w3.org/2000/svg"
@@ -24,12 +24,12 @@
     inkscape:deskcolor="#d1d1d1"
     inkscape:document-units="mm"
     inkscape:zoom="22.627417"
-     inkscape:cx="6.8059028"
-     inkscape:cy="14.606174"
+     inkscape:cx="0.57452426"
+     inkscape:cy="15.556349"
     inkscape:window-width="1920"
-     inkscape:window-height="1009"
-     inkscape:window-x="1912"
-     inkscape:window-y="-8"
+     inkscape:window-height="1131"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
     inkscape:window-maximized="1"
     inkscape:current-layer="layer1" /><defs
     id="defs1"><clipPath
@@ -96,4 +96,20 @@
       d="M 3.3486328 2.4970052 L 3.3486328 3.8323242 L 2.7424683 3.8323242 L 4.2085286 5.738151 L 5.674589 3.8323242 L 5.0684245 3.8323242 L 5.0684245 2.4970052 L 3.3486328 2.4970052 z "
       inkscape:export-filename="path32.png"
       inkscape:export-xdpi="3000"
-       inkscape:export-ydpi="3000" /></g></svg>
+       inkscape:export-ydpi="3000" /><rect
+       style="opacity:1;fill:#85140e;fill-opacity:1;stroke:none;stroke-width:0.414999;stroke-linecap:butt;stroke-linejoin:round;stroke-dasharray:none;paint-order:stroke fill markers"
+       id="rect1"
+       width="1.672105"
+       height="1.2511554"
+       x="-4.501821"
+       y="4.2814822" /><text
+       xml:space="preserve"
+       style="font-size:0.705556px;font-family:'Open Sans';-inkscape-font-specification:'Open Sans';text-align:start;writing-mode:lr-tb;direction:ltr;text-anchor:start;opacity:1;fill:#85140e;fill-opacity:1;stroke:none;stroke-width:0.414999;stroke-linecap:butt;stroke-linejoin:round;stroke-dasharray:none;paint-order:stroke fill markers"
+       x="-2.6360023"
+       y="5.1136947"
+       id="text1"><tspan
+         sodipodi:role="line"
+         id="tspan1"
+         style="font-size:0.705556px;fill:#85140e;fill-opacity:1;stroke-width:0.415"
+         x="-2.6360023"
+         y="5.1136947">lokality</tspan></text></g></svg>
@@ -0,0 +1,85 @@
+# -*- coding: utf-8 -*-
+"""
+Repository hygiene rules that need no QGIS and therefore run first.
+
+Each rule guards a mistake that has already happened here at least once,
+or one the plugins.qgis.org file analysis reports:
+
+* a UTF-8 BOM makes the official pyqgis4-checker skip the file entirely,
+  so a broken file looks clean – it is silent, which is what makes it bad
+* a direct PyQt5/PyQt6 import breaks the other Qt version
+* an executable or hidden file in the package is reported on upload
+
+Run it from the repository root:
+
+    python3 tests/check_sources.py
+"""
+
+import os
+import re
+import stat
+import sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+BALICEK = os.path.join(ROOT, "amcr_viewer")
+
+# Files that belong in the plugin package even though the upload scanner
+# would otherwise call them hidden
+POVOLENE_SKRYTE = {".flake8", ".bandit", ".secrets.baseline"}
+
+# Extensions that have no business inside a plugin package
+PODEZRELE = {".exe", ".dll", ".so", ".dylib", ".sh", ".bat", ".cmd",
+             ".pyc", ".pyd", ".jar", ".bin"}
+
+PRIMY_IMPORT = re.compile(r"^\s*(?:from|import)\s+PyQt[56]\b", re.MULTILINE)
+
+nalezy = []
+
+
+def zdrojaky():
+    for adresar, _, soubory in os.walk(BALICEK):
+        for soubor in sorted(soubory):
+            if soubor.endswith(".py"):
+                yield os.path.join(adresar, soubor)
+
+
+def vsechny_soubory():
+    for adresar, _, soubory in os.walk(BALICEK):
+        for soubor in sorted(soubory):
+            yield os.path.join(adresar, soubor)
+
+
+def zkratka(cesta):
+    return os.path.relpath(cesta, ROOT)
+
+
+for cesta in zdrojaky():
+    with open(cesta, "rb") as f:
+        zacatek = f.read(3)
+    if zacatek == b"\xef\xbb\xbf":
+        nalezy.append(f"{zkratka(cesta)}: UTF-8 BOM na začátku souboru")
+
+    with open(cesta, encoding="utf-8-sig") as f:
+        text = f.read()
+    for shoda in PRIMY_IMPORT.finditer(text):
+        radek = text[:shoda.start()].count("\n") + 1
+        nalezy.append(f"{zkratka(cesta)}:{radek}: přímý import z PyQt5/PyQt6, "
+                      f"použij shim qgis.PyQt")
+
+for cesta in vsechny_soubory():
+    jmeno = os.path.basename(cesta)
+    rezim = os.stat(cesta).st_mode
+    if rezim & (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH):
+        nalezy.append(f"{zkratka(cesta)}: spustitelná práva "
+                      f"({stat.filemode(rezim)})")
+    if jmeno.startswith(".") and jmeno not in POVOLENE_SKRYTE:
+        nalezy.append(f"{zkratka(cesta)}: skrytý soubor v balíčku pluginu")
+    if os.path.splitext(jmeno)[1].lower() in PODEZRELE:
+        nalezy.append(f"{zkratka(cesta)}: podezřelý typ souboru")
+
+if nalezy:
+    print("Nálezy:")
+    for nalez in nalezy:
+        print(f"  {nalez}")
+    sys.exit(1)
+print("Kontrola zdrojáků: bez nálezů")
@@ -0,0 +1,130 @@
+# -*- coding: utf-8 -*-
+"""
+Smoke test: loads the plugin inside a real QGIS and exercises the parts
+that differ between Qt5 and Qt6.
+
+It is deliberately offline – no request ever leaves the machine, so the
+test says nothing about the AMCR API, only about the plugin loading and
+its widgets being constructible.
+
+Run it from the repository root:
+
+    python3 tests/smoke_test.py
+
+QGIS must be importable (inside the qgis/qgis Docker image it already is).
+The exit code is 0 when everything passed, 1 otherwise.
+"""
+
+import os
+import sys
+import traceback
+
+# Offscreen, otherwise the dialogs need an X server
+os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, ROOT)
+
+selhani = []
+
+
+def zkouska(nazev, funkce):
+    """Runs one check and keeps going even when it raises."""
+    try:
+        detail = funkce()
+    except Exception:
+        selhani.append(nazev)
+        print(f"  FAIL  {nazev}")
+        print(traceback.format_exc().rstrip())
+    else:
+        print(f"  OK    {nazev}" + (f" – {detail}" if detail else ""))
+
+
+from qgis.core import (  # noqa: E402
+    Qgis,
+    QgsApplication,
+    QgsTask,
+    QgsWkbTypes,
+)
+from qgis.PyQt import QtCore  # noqa: E402
+from qgis.PyQt.QtCore import QDate  # noqa: E402
+
+print(f"QGIS {Qgis.QGIS_VERSION.split('-')[0]} | Qt {QtCore.QT_VERSION_STR} "
+      f"| PyQt {QtCore.PYQT_VERSION_STR}")
+
+QgsApplication.setPrefixPath(os.environ.get("QGIS_PREFIX_PATH", "/usr"), True)
+qgs = QgsApplication([], True)
+qgs.initQgis()
+
+import amcr_viewer.amcr_codelists  # noqa: E402,F401
+import amcr_viewer.amcr_dialog as dialog  # noqa: E402
+import amcr_viewer.amcr_tools  # noqa: E402,F401
+import amcr_viewer.amcr_viewer  # noqa: E402,F401
+
+print("  OK    import všech modulů pluginu")
+
+
+def enumy():
+    """
+    The scoped enum forms must exist. Unscoped aliases still resolve in
+    QGIS 4.2, so a plain import proves nothing – these are read explicitly.
+    """
+    return (f"QgsTask.Flag.CanCancel={int(QgsTask.Flag.CanCancel)}, "
+            f"PointGeometry={int(QgsWkbTypes.GeometryType.PointGeometry)}, "
+            f"MessageLevel.Info={int(Qgis.MessageLevel.Info)}")
+
+
+def uloha():
+    ukol = dialog.UpdateCodelistsTask("smoke")
+    assert ukol.canCancel() is True
+    return "canCancel=True"
+
+
+def dialogy():
+    # A modal warning would block the offscreen run forever
+    dialog.QMessageBox.warning = staticmethod(lambda *a, **k: None)
+    popis = []
+    for typ in ("akce", "lokalita", "samostatny_nalez"):
+        okno = dialog.AmcrFilterDialog(typ)
+        okno.show()
+        QgsApplication.processEvents()
+        popis.append(f"{typ}: {len(okno.date_ranges)} rozmezí")
+        okno.close()
+    return ", ".join(popis)
+
+
+def filtr_datumu():
+    """
+    A half-filled range must be completed with the sentinel. The API
+    rejects a one-sided range, so this is the part worth guarding.
+
+    The expected value is written out on purpose – comparing against
+    dialog.DATE_OPEN_TO would only prove the module agrees with itself.
+    """
+    okno = dialog.AmcrFilterDialog("samostatny_nalez")
+    pole, _, od, _do = okno.date_ranges[0]
+    od.setDate(QDate(2016, 1, 1))
+    hodnota = okno.get_filters()[pole]
+    assert hodnota == "2016-01-01,9999-12-31", hodnota
+
+    # A range left completely empty must add no filter at all
+    prazdne = dialog.AmcrFilterDialog("samostatny_nalez")
+    pole_prazdne = prazdne.date_ranges[0][0]
+    assert pole_prazdne not in prazdne.get_filters()
+    prazdne.close()
+
+    okno.close()
+    return hodnota
+
+
+zkouska("scoped enumy", enumy)
+zkouska("UpdateCodelistsTask", uloha)
+zkouska("filtrační dialogy", dialogy)
+zkouska("filtr podle data", filtr_datumu)
+
+qgs.exitQgis()
+
+if selhani:
+    print(f"\nNEPROŠLO: {', '.join(selhani)}")
+    sys.exit(1)
+print("\nVše prošlo")