Projektwissen/docs/analyse/01_projektanalyse.md

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

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.