Projektwissen/docs/wissen/fallstricke.md

Fallstricke und Erkenntnisse

Gemeinsames Gedächtnis: Dinge, die man nicht aus dem Code ablesen kann und die schon einmal Zeit gekostet haben. Kurz, konkret, mit Datum und Quelle. Neue Einträge oben in der passenden Rubrik. Veraltetes löschen, nicht auskommentieren.

BPMN und PICTURE (Skill sn-bpmn, md_to_bpmn.py)

• Echte Daten brechen, was die Beispiele nicht zeigen. Der Stresstest mit 23 Diagrammen aus PICTURE ist strukturell sauber (keine Kante durch ein Element). Er zeigt aber: Gateway-Fragen über 80 Zeichen werden geschnitten, 31 Datenobjekte in einer Reihe machen das Diagramm über 11 000 breit, und ein unbeschriftetes Gateway lässt sich keiner Lane zuordnen (TG: wird zum Namen). Exportformat, Abbildungsregeln und alle Befunde: picture_import.md. (28.09.2026)

• PICTURE-Exporte enthalten interne Kopfdaten. Mandant, Mandanten-URL, Arbeitsbereich und REST-URLs in jeder Verknüpfung, dazu in Anmerkungen gelegentlich Raumnummern und Standorte. Exporte gehören nach referenz/, nie nach docs/; beim Rückwandeln nur Namen übernehmen, Anmerkungen vor dem Ablegen durchsehen. (28.09.2026)

• Vorwärtskanten kennen die übrigen Elemente nur im Notfall. orthogonal_points() rechnet rein geometrisch zwischen zwei Anschlusspunkten. Das reicht, solange das Layout regelmäßig ist. Eine Querverbindung zwischen Geschwisterzweigen schiebt aber eine Aufgabe eine Ebene tiefer in eine Zwischenspalte. Deshalb prüft build_bpmn() jeden Standardweg gegen alle fremden Elemente und sucht nur bei einer Kreuzung mit umweg_points() einen Weg über freie Linien (Lückenmitten, 15 neben jedem Element; erst ein, dann zwei Zwischenknicke; kürzester gewinnt). So bleiben saubere Kanten byte-gleich. Der Belastungstest aus #12 ist jetzt ein dauerhafter Test (test_belastung_keine_kante_durch_ein_element_und_rechtwinklig, 126 Fälle). (#22, 25.09.2026)

• Auch das Aufgaben-Ende einer Gateway-Kante braucht ein gerades Stück. Das Gateway-Ende bekommt einen festen Anschlusspunkt (N/O/S/W), das Aufgaben-Ende die Layout-Seite (mit Lanes O/W, ohne Lanes N/S). Liegen beide auf verschiedenen Achsen, lief die Kante früher direkt an der Aufgabenkante entlang. Jetzt bekommt die Aufgabe einen Stub (RECHTECK_STUB = 20) senkrecht zu ihrer Seite, danach geht es wie zwischen zwei Rauten von Stub zu Stub. Geprüft mit test_kanten_setzen_an_aufgaben_rechtwinklig_an über alle Beispiele. Im Belastungstest aus #12 sind 378 schräge Anschlüsse verschwunden. Dafür laufen in 4 künstlichen Fällen mit Querverbindung zwischen Zweigen Kanten durch eine Aufgabe, in 2 anderen nicht mehr (Art von #22). (#23, 25.09.2026)

• PICTURE übernimmt Beschriftungspositionen und Kästchengrößen aus der Datei. Ohne BPMNLabel setzt es die Gateway-Beschriftung auf 180° (unter die Raute), wo der südliche Pfad und dessen Beschriftung sie schneiden. Im PICTURE-Editor steht sie auf 45°. Der Konverter setzt die Position deshalb selbst: 45°, sonst 45° rechts vom Ost-Stub, 315°, 135°, 225° – die erste Stelle, die keine Kante, Kantenbeschriftung oder kein Element schneidet. Dafür werden die Gateway-Beschriftungen nach allen Kanten gesetzt. Zu kleine Anmerkungs-Kästchen vergrößert PICTURE beim Import, dann überlappen sie Nachbarn und Lane-Grenzen. Deshalb richtet sich die Höhe nach dem Text (text_zeilen(), grobe Schätzung 7 je Zeichen), und die Anmerkungen stehen rechts neben dem Pool. GATEWAY_LABEL_BREITE = 90 hängt an AUSWEICHABSTAND (#8): Bei 100 ragte die Beschriftung über die Ausweichachse bei x + 130. Pool-Name über dem Namen der ersten Lane: nur in der Vorschau beobachtet, in PICTURE kein Problem. (PICTURE 2026.4.1, #14, 25.09.2026)

• Nachrichtenflüsse enden senkrecht unter ihrem Start, nicht an einem verteilten Punkt. Der externe Pool ist ein breites Rechteck, jeder Punkt an seiner Oberkante ist ein gültiger Anschluss. Die frühere Verteilung der Anschlusspunkte über die Pool-Oberkante erzeugte schräge Linien quer durch das Diagramm. Steht unter dem Schritt ein Element, geht der Fluss über einen Gang: mit Lanes 20 neben dem Gang der Rücksprungkanten und mit längerem Stub (30 statt 20), damit sich beide nicht überdecken; ohne Lanes rechts neben allen Elementen, dafür wird der Pool breiter. Belastungstest mit 342 Varianten: vorher 182 Fälle mit Kreuzung, jetzt keiner. (#13, 25.09.2026)

• Rücksprungkanten brauchen je Layout eine eigene Führung. Mit Lanes stehen die Elemente in festen Spalten (linksbündig, 190 auseinander). Der Rückweg läuft senkrecht nur in den Gängen zwischen den Spalten und waagrecht in einem Kanalband, das am Boden der letzten Lane nach der Platzierung angehängt wird. So bleiben die Elemente, wo sie sind, und die Kante bleibt im eigenen Pool. Ohne Lanes gibt es keine festen Spalten, parallele Zweige stehen versetzt zur Mitte. Der Kanal liegt deshalb seitlich an allen Elementen zwischen Quelle und Ziel vorbei. Steht ein Nachbar in derselben Zeile im Weg, geht die Kante unten hinaus bzw. oben hinein. Geprüft mit allen 126 Rücksprung-Varianten zweier Testmodelle, mit und ohne Lanes. (#12, 25.09.2026)

• Vorschau und PICTURE können sich unterscheiden, auch ohne Fehler im Modell. Beispiel XOR-Gateway: PICTURE zeichnet das „X“ nach eigenen Regeln, auch ohne isMarkerVisible. Die Vorschau (bpmn-js) hält sich an das Attribut und zeigte ohne es leere Rauten. Seit #15 setzt der Konverter das Attribut, beide zeigen das X. Wirkt etwas nur in der Vorschau falsch, erst in PICTURE gegenprüfen, bevor der Konverter geändert wird. (PICTURE 2026.4.1, #15, 25.09.2026)

• Gateway → Gateway mit Ziel „hinter“ dem Start-Stub braucht einen seitlichen Umweg. Liegt der Stub des Start-Gateways schon jenseits des Ziel-Anschlusspunkts (z. B. Südpunkt unten, Ziel höher mit Nordpunkt), läuft das letzte gerade Stück durch die Ziel-Raute. orthogonal_points() weicht dann über _ausweichachse() aus. Die Achse liegt im Gang direkt vor der Ziel-Spalte (Abstand 85 zur Mitte), nicht in der Mitte zwischen Quelle und Ziel: Liegen die beiden zwei Spalten auseinander, steht dort eine Aufgabe (im Referenzmodell S43). (#8, 25.09.2026)

• Bekannte Layoutfehler je Kreuzung als xfail, nie je Modell. Stünde ein ganzes Modell auf xfail, bliebe jede neue Kreuzung darin unsichtbar, solange der alte Fehler besteht. Deshalb prüft test_keine_unbekannte_kante_fuehrt_durch_ein_element alle Kanten gegen alle Elemente und meldet alle Funde außer den Paaren in BEKANNTE_KREUZUNGEN. Jedes dieser Paare hat einen eigenen strikten xfail-Test. Anlass: Die alte Gateway-Prüfung brach beim ersten Fund ab; bei #8 stand nur S12→S13 im Issue, tatsächlich waren es sieben Kreuzungen. (#16, 25.09.2026)

• Zusammenführende Gateways brauchen eine Beschriftung mit Zuständigkeit, sonst landen sie in der Lane „Nicht zugeordnet“ (split_lane() braucht Text nach dem Doppelpunkt). In BPMN bleiben Zusammenführungen üblicherweise unbeschriftet – ein Fall für eine spätere Konverteränderung. (23.09.2026, Referenzmodell)

• Das bpmn.io-Wasserzeichen ist Lizenzauflage. bpmn-js steht unter MIT, verlangt aber, dass das Wasserzeichen unten rechts sichtbar bleibt und nicht überdeckt wird. In werkzeuge/vorschau/vorschau.html deshalb nichts in die untere rechte Ecke der Zeichenfläche legen. (bpmn-js LICENSE, 23.09.2026)

• Diagramme nie roh in ein <script> schreiben. Eine Beschriftung mit </script> würde den Skriptblock beenden. scripts/vorschau.py maskiert jedes < im Diagramm als \u003c; die Bibliothek selbst wird nicht verändert, sondern nur auf <script/</script geprüft. (23.09.2026)

• Jede Änderung an der Ausgabe von md_to_bpmn.py macht die abgelegten .bpmn rot. Der Test in tests/test_pruefe_prozesse.py vergleicht jede .bpmn der Prozessbibliothek und in beispiele/ byte-genau mit der Umwandlung ihrer .md. Nach einer Konverteränderung python scripts/pruefe_prozesse.py --erzeugen ausführen; die neuen .bpmn der Beispiele gehören in den Pull Request, die der Bibliothek in einen eigenen Pull Request dort (ADR 0004). Das setzt voraus, dass der Konverter deterministisch bleibt: keine Zufalls-IDs, keine Zeitstempel, keine Reihenfolge aus set-Iteration. (ADR 0003, 23.09.2026; ADR 0004, 25.09.2026)

• Zusätzliche Zeilen in einer Arbeitsschritt-.md nur ganz oben oder mit #. parse_markdown() bricht nach dem ersten Schritt bei jeder unbekannten Zeile ab; davor überspringt es Zeilen, die nicht wie Schlüssel: Wert aussehen. Deshalb steht der Einlese-Vermerk (<!-- eingelesen: … -->) als erste Zeile. (23.09.2026, scripts/einlesen.py)

• Path.read_text() macht aus CRLF stillschweigend LF. Wer eine Datei liest und mit Zusatz zurückschreibt, stellt so Windows-Dateien unbemerkt um. scripts/einlesen.py liest deshalb als Bytes. (23.09.2026, Test)

• Metadaten gehören nicht als Kopfzeile in die Arbeitsschritt-.md. parse_markdown() liest eine Zeile wie Verantwortliche Stelle: … als Schritt mit ID Verantwortliche und Typ Stelle und bricht ab. Status und Stand stehen deshalb im Steckbrief README.md des Prozessordners. (23.09.2026)

• Zuständigkeit gilt auch für Gateways und Ereignisse. Ohne Rolle:-Präfix landen sie in der Lane „Nicht zugeordnet“. Ein ? stört nur vor dem Doppelpunkt: Sachbearbeitung: Antrag vollständig? funktioniert. (23.09.2026, beim Erstellen der Beispiele)

• Ein Gateway hat in PICTURE nur vier feste Anschlusspunkte (N/O/S/W auf der Rautenkontur), keinen variablen Rand wie ein Rechteck. Eine Kante, die diesen Punkt verlässt bzw. dort ankommt, darf sich danach nicht direkt zur Ziel-/Quellkoordinate drehen, wenn diese auf der anderen Achse liegt – sonst läuft der rechtwinklige Streckenzug quer durchs Innere der Raute zurück, statt außen herumzugehen (orthogonal_points() in md_to_bpmn.py, behoben BPMN-Skill 21.09.2026). Ursache: die feste Anschlusspunkt-Zuteilung (assign_gateway_sides(), Präferenzreihenfolge S/O/W/N bzw. N/W/O/S) kennt die tatsächliche Lage des anderen Endes nicht. Die Kante muss beim Verlassen/Ankommen an einer Raute zuerst ein Stück auf der sicheren Stub-Achse bleiben (die einzige garantiert freie Koordinate außerhalb der Kontur), bevor sie zur anderen Achse abbiegt – sonst reicht ein einfacher Bounding-Box-Test nicht, um den Fehler zu erkennen (ein Punkt auf der Rautenkontur liegt immer innerhalb der Bounding-Box). Prüfen mit echter Diamant-Geometrie (Manhattan-Abstand zum Mittelpunkt, skaliert auf die Halbachsen, < 1 heißt innen), nicht mit der Bounding-Box – siehe test_kante_fuehrt_nicht_durchs_innere_eines_gateways in test_md_to_bpmn.py.

Text und Sprache

• Deutscher Text ohne Umlaute/ß ist ein eigenständiges Muster, kein Einzelfall. KI-generierter Text weicht gern auf ASCII aus (gueltig statt gültig, ueber statt über) – in AG_QGIS über alle Plugins verteilt gefunden (Plugin_SN_Basis #42), im BPMN-Skill in Elementnamen und Docstrings. Neuen deutschen Text (Beschriftungen im Modell, Kommentare, Docstrings) immer mit echten Umlauten/ß schreiben. Vor dem Commit python scripts/pruefe_umlaute.py laufen lassen – findet das Muster in .py-Dateien (String-Inhalte und Kommentare mit Leerzeichen). Die Wortstammliste ist bewusst konservativ; Ersatz fürs Lesen ist sie nicht. Arbeitsschritt-.md prüft das Skript nicht. (AG_QGIS 09/2026)

Umgebung und Werkzeuge

• Relative Verweise in eingebetteten Stylesheets gehen in der Einzeldatei verloren. Die CSS der Bootstrap Icons lädt ihre Schrift über url("fonts/bootstrap-icons.woff2?…"). Beim direkten Öffnen von vorschau.html klappt das, in der von scripts/vorschau.py erzeugten Einzeldatei nicht. Deshalb setzt _schriften_einbetten() die woff2-Schrift als data:-URI ein und lässt den woff-Rückfall weg. Ein Test verlangt, dass jede url(...) der erzeugten Seite data: oder ein Fragment (#…, SVG-Verweise aus bpmn-js) ist. (#27, 25.09.2026)

• Öffentliche Organisation heißt nicht öffentliches Repo. In Gitea haben Organisation und Repo getrennte Sichtbarkeit. AG_Prozesse war öffentlich, Projektwissen privat: Die Weboberfläche zeigte es angemeldeten Personen normal, die API ohne Anmeldung lieferte 404. scripts/gitea.py liest bewusst ohne Token und braucht deshalb ein öffentliches Repo; es prüft das jetzt vor jeder Abfrage. Prüfen ohne Anmeldung: curl -s -o /dev/null -w "%{http_code}" https://entwicklung.flurneuordnung-sachsen.de/api/v1/repos/AG_Prozesse/Projektwissen muss 200 liefern. (23.09.2026)

• Gitea ordnet Commits über die E-Mail-Adresse zu. Stimmt user.email nicht mit einer im Gitea-Konto hinterlegten Adresse überein, erscheinen die Commits ohne Zuordnung zum Benutzer. Es gilt die dienstliche Adresse, die im Gitea-Konto hinterlegt ist. Wer den Rechner auch privat nutzt, setzt sie je Repository mit git config --local statt global. Nachträglich nur durch Umschreiben der Historie korrigierbar. (AG_QGIS 04.09.2026)

• pytest ist die einzige Abhängigkeit außerhalb der Standardbibliothek. Die Tests des Konverters brauchen es; md_to_bpmn.py selbst läuft ohne. (23.09.2026)

• .vscode/ gehört nicht ins Repository. Einstellungen mit Pfaden eines einzelnen Arbeitsplatzes gehören in die Benutzereinstellungen, siehe docs/leitfaden/04_werkzeuge_einrichten.md. (AG_QGIS 04.09.2026)

Zusammenarbeit

• Tool-Gedächtnis ist lokal. Die Claude-Auto-Memory sieht niemand sonst. Geteiltes Wissen nur in diesem Ordner.
• Issues sind teils Diskussionen, nicht Aufträge (Label Diskussion). Vor der Umsetzung Konsens im Issue abwarten oder im PR als Annahme kennzeichnen.
• Quelldokumente enthalten oft Interna. Word/PDF-Prozessbeschreibungen nur lokal unter referenz/ ablegen (nicht versioniert). Vor dem Committen eines Arbeitsschritt-Entwurfs prüfen, dass keine Namen, Aktenzeichen oder Verfahrensdaten darin stehen. (23.09.2026)