QGIS-Plugin VLN Karten: Verfahrens-Layer der Karten-API laden und hochladen

Lädt Verfahrensgebiet, Plan 41, Karte alter Stand (KAS) und Wertermittlung (WE) je VKZ vollständig aus KARTE_OBJEKT (Listen-Endpunkt mit Paging) und schreibt sie per PUT zurück. Einmaliger Login (mail/password -> userauth), API-Key persistiert in QSettings; Verfahrens-Auswahl in der Toolbar wird je QGIS-Projekt gemerkt. Gemischte Geometrietypen werden beim Laden in Punkte-/Linien-/Flächen-Layer gesplittet und beim Hochladen wieder vereint. Qt5/Qt6-kompatibel (QGIS 3.22+ und QGIS 4). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-12 13:31:44 +02:00
parent b222b33de7
commit 091ef281b0
8 changed files with 1075 additions and 1 deletions
@@ -1,2 +1,145 @@
-# API_Karte_QGISDemo
+# VLN Karten — QGIS-Plugin für die Karten-API des VLN Managers

+QGIS-Plugin, das die Karten-Layer des [VLN Managers](https://www.vlnsachsen.de)
+direkt in QGIS bearbeitbar macht. Es liest und schreibt dieselben
+Datenbank-Daten (`KARTE_OBJEKT`), die auch das Web-GIS
+(karte.flurneuordnung-sachsen.de) über die `/maps/*`-Endpunkte nutzt.
+
+## Funktionen
+
+- **Einmaliger Login** mit dem VLN-Manager-Konto (E-Mail/Passwort).
+  Der zurückgelieferte API-Key wird in den QGIS-Einstellungen gespeichert
+  und bei jedem QGIS-Start automatisch wiederverwendet; erst bei
+  HTTP 401/403 erscheint der Anmeldedialog erneut.
+- **Verfahrens-Auswahl in der Toolbar** — alle Teilnehmergemeinschaften
+  aus `GET /tgen` als „VKZ — Name“. Die Auswahl wird in der Projektdatei
+  gespeichert und beim Öffnen des Projekts wiederhergestellt.
+- **Vier Layer je Verfahren laden:**
+
+  | Button | API-Layer | DB-Art |
+  |---|---|---|
+  | Verfahrensgebiet | `umringe` | `UMRING` |
+  | Plan 41 (Wege- und Gewässerplan) | `p41` | `P41` |
+  | Karte alter Stand | `kas` | `KAS` |
+  | Wertermittlung | `we` | `WE` |
+
+  Geladen wird **vollständig** über den Listen-Endpunkt mit
+  limit/offset-Paging — auch bei mehr als 2000 Objekten.
+- **Gemischte Geometrietypen:** Die API liefert Punkte, Linien und
+  Flächen in einer FeatureCollection. Beim Laden wird nach
+  Geometrie-Familie in bis zu drei Memory-Layer gesplittet
+  (Single-Typen werden zu Multi-Typen befördert); bei nur einem Typ
+  entsteht ein einzelner Layer.
+- **Hochladen:** „Aktiven Layer hochladen“ vereint alle Teil-Layer
+  desselben Datensatzes (Punkte + Linien + Flächen derselben VKZ) wieder
+  zu einer FeatureCollection und schreibt sie per `PUT` zurück.
+  Vorher: Commit offener Bearbeitungssitzungen und Sicherheitsabfrage
+  mit Auflistung der beteiligten Layer.
+- **Schutz vor Duplikaten:** Erneutes Laden eines bereits geladenen
+  Datensatzes ersetzt die vorhandenen Layer nach Rückfrage, statt sie zu
+  stapeln. Liefert der Server 0 Objekte, wird das deutlich gemeldet und
+  ein leerer Layer zum Digitalisieren angelegt.
+
+## Voraussetzungen
+
+- QGIS **3.22 oder neuer**, einschließlich **QGIS 4** (Qt6/PyQt6 —
+  der Code verwendet durchgehend scoped Enums und `exec()`).
+- Ein VLN-Manager-Konto mit Zugriff auf die Karten-API.
+
+## Installation
+
+Repository klonen und den Plugin-Ordner in das QGIS-Profil verlinken
+(alternativ kopieren), dann QGIS neu starten:
+
+```bash
+git clone https://entwicklung.flurneuordnung-sachsen.de/VLN_SN/API_Karte_QGISDemo.git
+cd API_Karte_QGISDemo
+
+# macOS, QGIS 4 (bei QGIS 3: "QGIS4" durch "QGIS3" ersetzen):
+ln -s "$PWD/vln_karten" \
+  ~/Library/Application\ Support/QGIS/QGIS4/profiles/default/python/plugins/vln_karten
+
+# Linux:
+#   ~/.local/share/QGIS/QGIS4/profiles/default/python/plugins/
+# Windows:
+#   %APPDATA%\QGIS\QGIS4\profiles\default\python\plugins\
+```
+
+Anschließend in QGIS unter *Erweiterungen → Erweiterungen verwalten*
+„VLN Karten“ aktivieren (experimentelle Erweiterungen zulassen).
+
+## Bedienung
+
+1. **Anmelden …** in der Toolbar „VLN Karten“ (auch unter
+   *Web → VLN Karten*): E-Mail und Passwort des VLN-Manager-Kontos.
+   Das Passwort wird nicht gespeichert, nur der API-Key.
+2. **Verfahren wählen** in der Auswahlliste.
+3. **Layer laden**, in QGIS normal editieren (Memory-Layer,
+   EPSG:25833), **hochladen**.
+
+> ⚠️ Der `PUT` der API ersetzt den kompletten Layer-Bestand der
+> jeweiligen VKZ (versionierter Snapshot in `KARTE_SPEICHERSTAND`).
+> Deshalb lädt das Plugin immer alle Teil-Layer gemeinsam hoch — nur
+> einen Teil zu senden, würde die übrigen Geometrietypen serverseitig
+> löschen.
+
+## API-Vertrag
+
+Basis-URL: `https://api.flurneuordnung-sachsen.de/v2`
+(fest hinterlegt als `DEFAULT_BASE_URL` in
+[vln_karten/api_client.py](vln_karten/api_client.py))
+
+```
+POST /person/login
+  Body:     {"mail": "...", "password": "..."}
+  Antwort:  {"data": {"userauth": "<url_token>", "id": ...}}
+  userauth = API-Key, danach Header "X-API-Key: <userauth>"
+
+GET  /tgen                              Verfahren/TGs (Auth nötig)
+
+GET  /maps/<layer>?vkz=&limit=&offset=  Layer lesen (kas/we: Auth nötig)
+  Antwort:  GeoJSON FeatureCollection in EPSG:25833 (ETRS89/UTM33)
+
+PUT  /maps/<layer>/{vkz}                Layer schreiben (Auth nötig)
+  Body:     GeoJSON (ersetzt den Layer dieser VKZ, neuer Snapshot)
+  Antwort:  {"data": {"vkz","layer","art","speicher_id"}, "status":"ok"}
+
+Fehlerformat: RFC 7807 (application/problem+json)
+```
+
+Ein weiterer Layer der API (`st` = Servicetermin) wäre ein zusätzlicher
+Eintrag im `DATASETS`-Dict in [vln_karten/plugin.py](vln_karten/plugin.py).
+
+## Aufbau
+
+| Datei | Zweck |
+|---|---|
+| [vln_karten/plugin.py](vln_karten/plugin.py) | Toolbar, Aktionen, Verfahrens-Auswahl, `DATASETS`-Registry |
+| [vln_karten/api_client.py](vln_karten/api_client.py) | HTTP-Client (Login, Paging-Loader, PUT) über `QgsBlockingNetworkRequest` |
+| [vln_karten/layer_manager.py](vln_karten/layer_manager.py) | GeoJSON ↔ Memory-Layer, Geometrie-Splitting, Layer-Zusammenführung |
+| [vln_karten/login_dialog.py](vln_karten/login_dialog.py) | Anmeldedialog |
+| [vln_karten/metadata.txt](vln_karten/metadata.txt) | QGIS-Plugin-Metadaten |
+
+## Technische Hinweise
+
+- **CRS:** Die API liefert und erwartet Koordinaten in **EPSG:25833**
+  (abweichend von RFC 7946). Import/Export laufen ohne
+  WGS84-Transformation (`GEOJSON_CRS` in `layer_manager.py`).
+- **Geometrien** gehen beim Hochladen als Multi-Typen an die API
+  (`ST_GeomFromGeoJSON` akzeptiert beides). Features ohne Geometrie
+  landen in einem Tabellen-Layer „ohne Geometrie“.
+- **API-Key-Ablage:** unverschlüsselt in den QGIS-Einstellungen
+  (QSettings, Gruppe `vln_karten`). Wer das härten will, verlagert ihn
+  in den QGIS-Authentifizierungsmanager (`QgsApplication.authManager()`).
+- **Requests** laufen synchron (blockierend) — für sehr große
+  Datensätze wäre `QgsNetworkAccessManager` mit Tasks der nächste Schritt.
+- Die gewählte VKZ liegt in der Projektdatei (`writeEntry`-Scope
+  `vln_karten`) — verschiedene Projekte können verschiedene Verfahren
+  vorausgewählt haben.
+
+## Entwicklung
+
+Für schnelles Iterieren empfiehlt sich das Plugin **Plugin Reloader**
+aus dem offiziellen QGIS-Repository — Codeänderungen wirken dann ohne
+QGIS-Neustart. Der Plugin-Ordner kann dafür per Symlink direkt aus dem
+Git-Arbeitsverzeichnis eingebunden bleiben (siehe Installation).