AndreasTharangandClaude Sonnet 5
ab416fb34c
Erster Stand des Repositories AG_QGIS/Projektwissen (bisher Arbeitstitel "Workspace", ADR 0006). Der lokale Ordner heisst weiter AG_QGIS, weil darin auch die Plugin-Klone liegen. Git verbindlich (ADR 0007), aus dem bisherigen Wiki-Konzept entwickelt: - docs/leitfaden/05_git_arbeitsweise.md mit Kanal-Kette, Branch-Namen und Gitea-Branch-Schutz. - Der Einstiegspunkt eines Fixes richtet sich nach dem Kanal, in dem der Fehler sitzt; ein Fix an testing oder stable ist erst mit der Rueckfuehrung nach unten abgeschlossen. Das fehlte bisher. - Der stabile Kanal heisst stable, nicht main: der Release-Workflow in Repository:hidden/workflows fuehrt git checkout "$CHANNEL" aus, der Branchname muss also dem Kanalnamen entsprechen. Er existiert in keinem Plugin-Repo und ist vom Maintainer anzulegen. - Der Mensch drueckt ab: .claude/settings.json sperrt push, merge, tag. - scripts/hallo.py und /hallo holen den Stand aller Klone, per Fast-Forward wo gefahrlos; nie mergen, stashen oder verwerfen. Ticketzugriff: - scripts/gitea.py liest Issues, Kommentare und PRs ueber die oeffentliche API, ohne Token, nur GET. Schreibendes nur als Entwurf in entwuerfe/. - Skill sn-ticket. Tests (ADR 0009): - docs/leitfaden/06_tests.md: Testebenen, Testpflicht, und wie eine Fachperson beurteilt, ob Tests fachlich sinnvoll sind. - scripts/testkatalog.py erzeugt docs/tests/testkatalog.md per ast-Parsing, ohne Import und ohne QGIS. Befund: nur 100 von 332 Tests haben einen Docstring, sn_basis keinen einzigen von 87. - Vorlage und erste Testkonzept-Seite mit Mermaid. Dabei gefunden und gegen origin geprueft: _ermittle_gebietstyp_aus_fbschl hat keinen Test, obwohl PR #44/#45 genau diese Funktion tolerant gemacht hat. - docs/konzept/07_qgis_tests_plan.md: Stufenplan fuer Tests gegen echtes QGIS. Dabei aufgefallen: QGIS 3.40 ist seit Januar 2026 End of Life, qgis_min steht aber noch darauf. Werkzeuge (ADR 0008): - 04_werkzeuge_einrichten.md nur noch Claude Code als CLI und in VS Code. - .vscode/ entfernt, brauchbare Einstellungen als persoenliche Vorlage. Ausserdem: README als Einstieg neu aufgebaut, Mermaid-Diagramm in schnittstellen.md repariert (unmaskierte Klammern, rendert seither nicht). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
222 lines
14 KiB
Markdown
222 lines
14 KiB
Markdown
# Projektanalyse: Aufbau und Zusammenspiel der Komponenten
|
||
|
||
Momentaufnahme vom 02.09.2026 (alle Repos auf ihrem Default-Branch, siehe `00_gesamtueberblick_2026-09-02.md`).
|
||
Zielgruppe: neue Entwickler und KI-Agenten, die das Gesamtbild brauchen, bevor sie einzelne Dateien öffnen.
|
||
Die lebenden Referenzen dazu sind `../architektur/modulkarte.md` und `../architektur/schnittstellen.md`.
|
||
|
||
## 1. Kurzfassung
|
||
|
||
- Das Vorhaben ist eine **Plugin-Familie** für QGIS: `sn_basis` als Plattform (UI-Rahmen, Wrapper, Prüfer, Datenmodule,
|
||
Druck) und Fachplugins, die sich beim Start in Menü und Toolbar von `sn_basis` einhängen. Produktiv ausgebaut sind
|
||
`sn_verfahrensgebiet` und `sn_plan41`; `sn_widmung` ist ein Gerüst, drei weitere Repos sind Platzhalter.
|
||
- Die Architekturidee ist tragfähig: Wrapper-Schicht mit Mock-Modus, einheitliches Prüfmodell, gemeinsame Tabs,
|
||
klare Registrierung der Fachplugins. Sie ist aber **nur im Code** dokumentiert und an einigen Stellen aufgeweicht
|
||
(Fachlogik in UI-Dateien, Rückwärtsimport, doppelte Variablennamen, zwei Linklisten).
|
||
- Die Codequalität entspricht dem Entstehungsprozess: fachlich fundiert, in KI-erzeugten Fragmenten gewachsen,
|
||
mit sehr großen Dateien (zehn Dateien über 600 Zeilen, Spitze 1 674), verbreiteten `try/except: pass`-Mustern,
|
||
Debug-`print`, auskommentiertem Code und uneinheitlicher Namensgebung.
|
||
- Es gibt **umfangreiche Tests im Mock-Modus** (332 Tests), die ohne QGIS in unter einer Sekunde laufen. Sie sind
|
||
der wichtigste Hebel für KI-gestützte Arbeit, aber derzeit nicht vollständig grün und nicht in CI.
|
||
- Prozessseitig existiert bereits ein funktionierender Kern: Feature-Branches, Pull Requests auf `unstable`,
|
||
Issues mit Labels, dreistufiger Release-Prozess mit Gitea Actions. Es fehlen Test-CI, Abhängigkeitsdeklaration,
|
||
Dokumentation und ein organisationsweiter Versionsstand.
|
||
|
||
## 2. Bestand
|
||
|
||
| Repository | Paket | Rolle | Reife | Python-Dateien / Tests |
|
||
|---|---|---|---|---|
|
||
| `Plugin_SN_Basis` | `sn_basis` | Plattform und Bibliothek | aktiv, unstable | 40 / 13 Testdateien (87 Tests) |
|
||
| `Plugin_SN_Verfahrensgebiet` | `sn_verfahrensgebiet` | Fachplugin Verfahrensgebiet | aktiv, unstable | 17 / 12 (201 Tests) |
|
||
| `Plugin_SN_Plan41` | `sn_plan41` | Fachplugin Plan § 41 | aktiv, unstable | 10 / 5 (44 Tests) |
|
||
| `Plugin_SN_Widmung` | `sn_widmung` | Fachplugin Widmung | Gerüst | 5 / 0 |
|
||
| `Plugin_SN_FLT`, `_Topografie`, `_Template` | – | Platzhalter | leer | 0 |
|
||
| `Plugin_Test_Action` | – | Testplugin für Release | Werkzeug | 1 |
|
||
| `Repository` | – | Plugin-Feeds, Release-Orchestrierung | Werkzeug | – |
|
||
| `Linkliste` | – | Dienstekatalog CSV → XML/JSON/YAML | Daten | – |
|
||
| `Defaults` | – | Beispiel-Verfahrensdaten, ein QML | Daten, unreferenziert | – |
|
||
|
||
Beteiligte laut Git-Historie: Daniel Helbig (LK Meißen, Hauptentwickler der Fachlogik), Michael Otto (LK Mittelsachsen,
|
||
Release-Infrastruktur, Linkliste, seit 08/2026 auch Fachlogik), Erik Sefkow (VLN Sachsen, VLN-API), Issue-Autoren
|
||
`22munzke` und „Kai“ (Copilot-Nutzer, Issue Basis #36). Entwicklungsschub 03–04/2026 (92 Commits in `Plugin_SN_Basis`),
|
||
seitdem gleichmäßig 10–11 Commits pro Monat.
|
||
|
||
Der Ordner `Alternativansatz/` (außerhalb dieses Workspace) enthält einen unabhängigen Prototyp „LNO-Fachschale“;
|
||
seine Bewertung steht in `00_vergleich_alternativansatz_2026-09-02.md`. Kurz: die Idee eines versionierten
|
||
GeoPackage-Datenvertrags ist wertvoll, der Prototyp selbst ist kein Ersatz für die Plugin-Familie.
|
||
|
||
## 3. Architektur zur Laufzeit
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph QGIS["QGIS 3.40 (Qt5) / QGIS 4 (Qt6)"]
|
||
subgraph BASIS["sn_basis – Plattform"]
|
||
NAV["ui: Navigation, DockManager, BaseDockWidget, PrintTab, SettingsTab"]
|
||
MOD["modules: Pruefmanager, pruef_ergebnis, *pruefer, DataGrabber, Datenabruf, LayerLoader, Datenschreiber, print_*"]
|
||
FUN["functions: qt_/qgiscore_/qgisui_/dialog_/message_/variable_wrapper, verfahrensgebiet_manager"]
|
||
NAV --> MOD --> FUN
|
||
end
|
||
VG["sn_verfahrensgebiet"] --> NAV
|
||
VG --> MOD
|
||
VG --> FUN
|
||
P41["sn_plan41"] --> NAV
|
||
P41 --> MOD
|
||
P41 --> FUN
|
||
WID["sn_widmung (Gerüst)"] --> NAV
|
||
MOD -. Lazy-Import Listenauswerter .-> P41
|
||
FUN --> PROJ[("QGIS-Projekt: Variablen sn_*, Layer")]
|
||
end
|
||
VG --> ALKIS["ALKIS-WFS Sachsen"]
|
||
P41 --> LUIS["LUIS/RAPIS ArcGIS REST, WFS"]
|
||
P41 --> VLN["VLN-Karten-API v2"]
|
||
P41 --> GPKG[("Verfahrens-GeoPackage")]
|
||
```
|
||
|
||
### Schichten in `sn_basis`
|
||
|
||
1. **functions/ – Wrapper.** Jede Qt-, QGIS- und OS-Abhängigkeit geht durch ein Wrapper-Modul, das bei fehlendem QGIS
|
||
Mock-Klassen bereitstellt. Das ist die Grundlage dafür, dass Tests und KI-Agenten ohne QGIS arbeiten können, und
|
||
gleichzeitig die Brücke zwischen Qt5 und Qt6. `qgiscore_wrapper.py` (1 122 Zeilen) und `qt_wrapper.py` (796)
|
||
enthalten zusätzlich Fachhelfer (`create_buffer_layer`, `polygon_zu_linie`), die dort nicht hingehören.
|
||
2. **modules/ – Prüfen, Laden, Schreiben, Drucken.** Einheitliches Ergebnisobjekt `pruef_ergebnis` mit Aktionscode;
|
||
`Pruefmanager` entscheidet über Dialoge oder Standardantworten. Die Datenpipeline (`DataGrabber` → `Datenabruf` →
|
||
`LayerLoader` → `Datenschreiber`) ist generisch gedacht, wird aber nur von Plan41 vollständig genutzt.
|
||
Die Druckmodule (2 800 Zeilen) sind der größte zusammenhängende Block.
|
||
3. **ui/ – Rahmen.** Navigation (Menü/Toolbar), DockManager (nur ein Dock sichtbar), BaseDockWidget (Tabs aus
|
||
Klassenattribut), gemeinsame Tabs Druck und Projekteigenschaften.
|
||
|
||
### Fachplugins
|
||
|
||
Beide großen Fachplugins folgen demselben Muster: `main.py` (Registrierung, Services), `ui/dockwidget.py` (Tabs),
|
||
ein großer Arbeits-Tab (`working_tab.py` 873 Zeilen bzw. `tab_a_ui.py` + `tab_a_logic.py` 1 872 Zeilen) und
|
||
Fachfunktionen in `functions/` bzw. `modules/`. Der Verfahrensgebiet-Tab enthält viel Ablaufsteuerung, die eigentlich
|
||
in die Fachfunktionen gehört; Plan41 hat Logik und UI bereits getrennt.
|
||
|
||
## 4. Zusammenspiel im Detail
|
||
|
||
### 4.1 Start und Registrierung
|
||
|
||
QGIS instanziiert alle Plugins; die Ladereihenfolge ist nicht garantiert. `sn_basis.initGui()` baut die Navigation und
|
||
ruft anschließend `initGui()` **aller** Plugins mit Präfix `sn_` nach. Ein Fachplugin registriert in `initGui()` eine
|
||
Action mit Priorität (Verfahrensgebiet 10, Plan41 20, Widmung 30), erzeugt beim Klick sein Dock (`sn_dock_<name>`) und
|
||
übergibt es an `DockManager.show()`. Sequenzdiagramm und Vertrag: `schnittstellen.md` Abschnitt 1–2.
|
||
|
||
Bewertung: funktioniert, ist aber fragil. Die Abhängigkeit von `sn_basis` ist in keiner `metadata.txt` deklariert;
|
||
QGIS kann die Fachplugins ohne Basis aktivieren, und sie scheitern dann still. Mehrfaches `initGui()` erzeugt neue
|
||
Action-Objekte, alte Referenzen bleiben im Fachplugin bis zum nächsten `run()`.
|
||
|
||
### 4.2 Gemeinsamer Zustand
|
||
|
||
Der Zustand lebt in **QGIS-Projektvariablen** mit Präfix `sn_` (Tabelle in `schnittstellen.md` Abschnitt 3) und in
|
||
**Layer-Anzeigenamen**. Beides ist stringbasiert und ohne zentrale Definition. Befund:
|
||
|
||
- 20 verschiedene Schlüssel; die zehn Einstellungsfelder sind in `SettingsLogic.VARIABLEN` gelistet, alle anderen
|
||
verteilt im Code.
|
||
- Zwei Schreibweisen für denselben Zweck (`verfahrensgebiet_layer` / `verfahrensgebietslayer`) und ein doppeltes Präfix
|
||
(`sn_sn_abdeckungslayer`).
|
||
- Layer werden über Namen wie „Verfahrensgebiet“ oder `BROR_LAYER_NAME` gefunden; der `verfahrensgebiet_manager`
|
||
verfolgt den Verfahrensgebiet-Layer über Projektsignale und schreibt seine ID in die Variable.
|
||
|
||
### 4.3 Datenflüsse
|
||
|
||
**Verfahrensgebiet aus ALKIS** (Diagramme im Repo unter `docs/`): Projektvariablen (VKZ/Landkreis) → WFS-Suche
|
||
`BauRaumOderBodenordnungsrecht` → Auswahl → Layer → Gemarkungen (vereinfachter WFS) → Flurstücke je Gemarkung
|
||
(SF-WFS, BBOX-Batches) → Flächenvergleich → Detailprüfung (Grenzpunkte, Knickpunkte). Viele Dialoge, blockierende
|
||
Requests im QGIS-Prozess, manuell gepumpte Fortschrittsdialoge.
|
||
|
||
**Verfahrensgebiet aus Shape/ZIP:** Mehrfachauswahl → Entpacken → `FBSchl`-Klassifikation → Vereinigung je Gebietstyp
|
||
→ Abgleich mit BROR → gleicher weiterer Ablauf.
|
||
|
||
**Plan41-Fachdaten:** `assets/Linkliste.xlsx` → `DataGrabber` (Klassifikation) → `Listenauswerter` (Validierung; lebt in
|
||
`sn_plan41`, wird von `sn_basis` lazy importiert) → `Datenabruf` (WFS/REST/OGR mit Raumfilter) → `LayerLoader`
|
||
(Filter, Stil) → `Datenschreiber` (GeoPackage, Laden, HTML-Protokoll).
|
||
|
||
**Plan41 ↔ VLN-API:** Login → Verfahren → GeoJSON → Memory-Layer je Geometriefamilie → Bearbeitung → Upload als
|
||
eine FeatureCollection (ersetzt Serverbestand).
|
||
|
||
**Druck:** PrintTab (in jedem Fachplugin-Dock eingebettet) → `PrintLogic` (Bereich, Maßstab, Atlas) → `PrintLayout`
|
||
(§ 38/§ 41) bzw. `PrintLayoutBaufreigabe`.
|
||
|
||
### 4.4 Release und Verteilung
|
||
|
||
Tag `v<JJ.M.N>-u|-t|` im Plugin-Repo → Repo-Workflow sendet Payload an `Repository` (Branch `hidden/workflows`) →
|
||
zentraler Workflow baut **den Kanal-Branch**, erzeugt `metadata.txt` aus dem Template, packt das ZIP unter dem in Gitea
|
||
hinterlegten Paketnamen, legt ein Release an und aktualisiert `plugins-<kanal>.xml`. Der Kanal `stable` ist leer und
|
||
hat keinen Branch. Details und Fallstricke: `schnittstellen.md` Abschnitt 9, `fallstricke.md`.
|
||
|
||
### 4.5 Nebenrepositories
|
||
|
||
`Linkliste` erzeugt automatisch drei Formate aus einer CSV, wird aber von keinem Plugin gelesen. `Defaults` wird
|
||
nirgends referenziert. Beide sind Kandidaten für die Konsolidierung (eine Dienstquelle, generierte Laufzeitdatei).
|
||
|
||
## 5. Qualitätsbefund
|
||
|
||
### 5.1 Struktur und Stil
|
||
|
||
| Beobachtung | Beispiele | Auswirkung für KI-gestützte Arbeit |
|
||
|---|---|---|
|
||
| Sehr große Dateien | zehn Dateien > 600 Zeilen (Modulkarte) | teure Kontexte, ungenaue Änderungen; Agenten müssen per `grep` navigieren |
|
||
| Fachlogik in UI-Klassen | `working_tab.py`, `print_tab.py` | schwer testbar, Änderungen streuen |
|
||
| Wrapper enthält Fachhelfer | `qgiscore_wrapper.create_buffer_layer`, `polygon_zu_linie` | Schichtgrenze verwischt |
|
||
| Rückwärtsabhängigkeit | `sn_basis.DataGrabber` → `sn_plan41.Listenauswerter` | Basis ist nicht eigenständig; seit PR #57 nur noch lazy |
|
||
| Stringbasierter Zustand | Projektvariablen, Layernamen | Tippfehler brechen Abläufe still; siehe Doppelnamen |
|
||
| Breite `try/except Exception: pass` | `base_dockwidget`, `dockmanager`, viele Fachfunktionen | Fehler werden verschluckt, Ursachensuche teuer |
|
||
| Debug-Reste | `print()` in `navigation.py`, `main.py`, `tab_a_logic.py`; `TEST ACTION` im Menü | Nutzer sehen Entwicklungsballast |
|
||
| Auskommentierter Code | `Verfahrensgebiet.run()` doppelt (alt/neu) | Unsicherheit, welche Fassung gilt |
|
||
| Uneinheitliche Namen | `schreibe_Daten`, `lade_Layer` neben `create_layer`; deutsche/englische Mischung | Stil je Datei beibehalten (Regel), Vereinheitlichung im Refactoring |
|
||
| Fehlende Typen/Docstrings in Teilen | Widmung, ältere Funktionen | Agenten raten Signaturen |
|
||
| Personenbezogene IDE-Pfade | `.vscode/settings.json` | irritiert neue Entwickler |
|
||
|
||
Das Muster ist typisch für **schrittweise per Chatbot erzeugten Code**: jedes Fragment ist für sich plausibel und
|
||
gut kommentiert, die Gesamtstruktur wurde aber nie gegen ein Zielbild geprüft. Positiv hervorzuheben: die Wrapper-Idee,
|
||
das Prüfmodell, der Mock-Modus und die konsequente deutsche Dokumentation in Docstrings und Changelogs.
|
||
|
||
### 5.2 Tests
|
||
|
||
Ausführung im Mock-Modus mit Python 3.14 am 02.09.2026 (`python scripts/run_tests.py`):
|
||
|
||
| Paket | Gesamt | Grün | Fehlschläge | Fehler | Übersprungen |
|
||
|---|---:|---:|---:|---:|---:|
|
||
| `sn_basis` | 87 | 87 | 0 | 0 | 0 |
|
||
| `sn_plan41` | 44 | 43 | 0 | 1 | 0 |
|
||
| `sn_verfahrensgebiet` | 201 | 157 | 15 | 21 | 8 |
|
||
|
||
Die roten Verfahrensgebiet-Tests betreffen überwiegend `verfahrensgebiet_shape_komplett`, `flurstueck_alkis`,
|
||
`grenzpunkt_alkis`, `gemarkung_alkis` und `working_tab`: Tests erwarten die Einzeldatei-/Einzellayer-Schnittstellen
|
||
vor dem Umbau auf Mehrfachauswahl. Es handelt sich also überwiegend um **veraltete Tests, nicht um Regressionen**;
|
||
das muss aber je Test entschieden werden. Es gibt keine CI, die Tests bei Push/PR ausführt; die vorhandenen Actions
|
||
dienen nur Releases.
|
||
|
||
### 5.3 Dokumentation
|
||
|
||
Fünf README-Dateien sind leer oder zweizeilig. Wertvoll sind die Mermaid-Abläufe in `Plugin_SN_Verfahrensgebiet/docs/`,
|
||
das ERD in `Plugin_SN_Plan41/doc/`, die Changelogs und die Docstrings. Es gibt keine Beschreibung der Gesamtarchitektur,
|
||
der Verträge, der Entwicklungsumgebung oder des Arbeitsablaufs – genau das, was Agenten und neue Entwickler brauchen.
|
||
|
||
### 5.4 Prozess
|
||
|
||
- Branch-Modell `feature/*` → PR → `unstable` → PR → `testing` wird gelebt (57 PRs in Basis).
|
||
- Issues mit `Bug`/`Feature`/`Diskussion`; ein Teil sind Diskussionen ohne Auftragscharakter.
|
||
- Kein Manifest für kompatible Versionsstände; `sn_basis` und Fachplugins werden unabhängig getaggt.
|
||
- Keine Abhängigkeitsdeklaration (`openpyxl`, Basisplugin).
|
||
- Individuelle Werkzeuge: VS Code + Copilot (mit lokalem `/memories`), diverse Chatbots; künftig Claude Code und Codex.
|
||
|
||
## 6. Risiken mit Blick auf die nächste Phase
|
||
|
||
1. **Rote Tests werden zur Gewohnheit.** Ohne Baseline und CI verlieren Tests ihre Aussagekraft, und Agenten „reparieren“
|
||
Tests statt Code. → Baseline festhalten, neue rote Tests verbieten, Rot→Grün als eigene Aufgaben.
|
||
2. **Kontextexplosion.** Zehn Dateien über 600 Zeilen und keine Modulkarte führen dazu, dass jeder Agent das Projekt
|
||
neu erkundet. → Modulkarte, Schnittstellen, Fallstricke als Pflichtlektüre; Regeln zum gezielten Lesen.
|
||
3. **Wissensinseln.** Erkenntnisse liegen in Copilot-Memories, Chat-Verläufen und Köpfen. → Versionierte Wissensbasis.
|
||
4. **Unbeabsichtigte API-Brüche in `sn_basis`.** Jede Änderung trifft drei Fachplugins in drei Repos. → Regel „grep vor
|
||
Änderung“, später Manifest kompatibler Stände.
|
||
5. **Release-Fehler.** Kanal-Branch statt Tag, Template-Fehler, Workspace-Dateien im ZIP. → Skill `sn-release`, Excludes.
|
||
6. **Refactoring zu früh.** Ein Umbau bei roten Tests und ohne dokumentierte Verträge zerstört Wissen. → Reihenfolge:
|
||
Vorbereitung → grüne Basis → Verträge festschreiben → Refactoring in Scheiben.
|
||
|
||
## 7. Konsequenzen für die Vorbereitung
|
||
|
||
Aus der Analyse folgen die Bausteine des Konzepts (`../konzept/02_zusammenarbeit_ki_agenten.md`):
|
||
ein Workspace-Meta-Repository mit kanonischer `AGENTS.md`, Modulkarte und Schnittstellen als Pflichtkontext,
|
||
eine versionierte Wissensbasis als geteiltes Gedächtnis, Skills für wiederkehrende Abläufe, ein werkzeugunabhängiger
|
||
Testlauf mit Baseline und ein leichter, aber verbindlicher Arbeitszyklus über Gitea-Issues und Pull Requests.
|