From 74825291cfeb18bf4d8c4ab20e89a561b74de637 Mon Sep 17 00:00:00 2001 From: daniel Date: Mon, 28 Sep 2026 21:35:37 +0200 Subject: [PATCH] Befunde aus dem Stresstest mit dem PICTURE-Bestand festhalten MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Neues Wissensdokument docs/wissen/picture_import.md: Aufbau eines PICTURE-BPMN-Exports, Abbildung auf die Markdown-Syntax von sn-bpmn und die Befunde aus der Rückwandlung von 23 Diagrammen des AG-Bestands (Konverter, Syntax, Modelle). Kurzeinträge in fallstricke.md, Verweis im Wegweiser docs/README.md. Co-Authored-By: Claude Opus 5.5 --- docs/README.md | 1 + docs/wissen/fallstricke.md | 9 +++ docs/wissen/picture_import.md | 104 ++++++++++++++++++++++++++++++++++ 3 files changed, 114 insertions(+) create mode 100644 docs/wissen/picture_import.md diff --git a/docs/README.md b/docs/README.md index 12a169e..7087340 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,6 +5,7 @@ | `status/STATUS.md` | lebend, kurz | **immer zuerst** – aktueller Stand, Baustellen | | `wissen/fallstricke.md` | lebend | bei Überraschungen; vor Arbeiten am Konverter und am PICTURE-Import | | `wissen/glossar.md` | lebend | Fachbegriffe (Flurbereinigung, BPMN) | +| `wissen/picture_import.md` | lebend | PICTURE-Exporte zurückwandeln: Exportformat, Abbildung auf die Syntax, Befunde des Stresstests | | `wissen/vln_sn.md` | lebend | Vorbilder in der Organisation VLN_SN: HTML-Stil (EA-Bilanz), Workflow-System als Kandidat; Nutzungsbedingungen | | `entscheidungen/` | append-only (ADR) | warum etwas so ist; neue Entscheidung = neue Datei | | `leitfaden/03_arbeitsweise.md` | stabil | Einstieg, Arbeitszyklus, Checklisten | diff --git a/docs/wissen/fallstricke.md b/docs/wissen/fallstricke.md index c7758a0..5700799 100644 --- a/docs/wissen/fallstricke.md +++ b/docs/wissen/fallstricke.md @@ -5,6 +5,15 @@ Kurz, konkret, mit Datum und Quelle. Neue Einträge oben in der passenden Rubrik ## 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 diff --git a/docs/wissen/picture_import.md b/docs/wissen/picture_import.md new file mode 100644 index 0000000..aeb09a0 --- /dev/null +++ b/docs/wissen/picture_import.md @@ -0,0 +1,104 @@ +# PICTURE-Bestand zurückwandeln: Exportformat und Befunde aus dem Stresstest + +Lebendes Dokument. Hält fest, wie ein BPMN-Export aus PICTURE aufgebaut ist, was die Markdown-Syntax von +`sn-bpmn` davon abbilden kann und was der erste Stresstest von `md_to_bpmn.py` an echten Daten gezeigt hat. +Stand: 28.09.2026, Grundlage: 26 Exportdateien des bisherigen AG-Bestands (23 Diagramme mit Inhalt). + +Die Exportdateien sind interne Unterlagen. Sie liegen nur lokal unter `referenz/` und werden nie versioniert. In die +Prozessbibliothek kommen die daraus abgeleiteten `.md` und `.bpmn` mit dem Status `Import`. + +## Aufbau eines PICTURE-Exports + +- **Eine Datei je Diagramm.** Ein Prozess mit Subdiagrammen wird als `_0.bpmn`, `_1.bpmn` … exportiert. + Den Namen des Diagramms trägt `bpmndi:BPMNDiagram/@name`, z. B. „3 Planung“; das Hauptdiagramm heißt immer + „Hauptdiagramm“. `bpmn2:process/@name` ist leer. +- **Exporteur:** `exporter="PICTURE Prozessplattform" exporterVersion="3.0.0"`, Namensraum + `http://www.picture-gmbh.de/bpmn-ext` (Präfix `pic`). Kopfdaten (`pic:metaData`) nennen Mandant, Mandanten-URL + und Arbeitsbereich. Die Kopfdaten sind intern und dürfen nicht übernommen werden. +- **Attribute stecken in `extensionElements/pic:attributes`** als `…Value` mit deutschem `name`: Füllfarbe, + Randfarbe, Textfarbe, Pfeilfarbe, „Wahrscheinlichkeit für diesen Fall“ (an jedem Sequenzfluss), „Beschreibung“ + (HTML in CDATA), „Verknüpfung zum Subdiagramm“, „Verknüpfung zu externem Prozessmodell“, „Wiederholungs-Typ“, + „Verantwortliche Organisationseinheit“, „Zweck“, „Verfahrensart“. +- **Verknüpfungen** nennen Ziel-Name, Art (`Process` bzw. `SubDiagram`), UUID und eine REST-URL des Mandanten. Nur + der Name ist verwertbar. +- **Pools und Lanes sind selten.** Nur 2 von 23 Diagrammen haben einen Pool mit Lanes (Lanes heißen nach + Funktionen: VLN, TG, OFB, Unternehmensträger). Die übrigen haben weder Pool noch Lane, alle Elemente hängen + direkt am Prozess. +- **Anmerkungen hängen fast nie per Assoziation.** 215 Anmerkungen, aber nur 6 Assoziationen: Der Bezug ergibt sich + in PICTURE aus der Lage im Bild. Datenobjekte sind nur vereinzelt über `dataInputAssociation` verbunden. +- **Leere Exporte kommen vor:** Datei mit Prozess, aber ohne ein einziges Element (bei 3.10 und 3.16). + +## Was im Bestand vorkommt + +245 Aufgaben, 107 Teilprozesse (einige aufgeklappt, mit Inhalt), 7 Aufrufaktivitäten, 116 XOR-, 30 AND- und +10 OR-Gateways, 32 Zwischenereignisse (22 Zeit, 6 Bedingung, 2 Nachricht), 216 Datenobjekte, 13 Datenspeicher, +215 Anmerkungen, 11 Gruppen, 6 Schleifen-Marker, 600 Sequenzflüsse, keine Nachrichtenflüsse. + +## Wie zurückgewandelt wurde + +Mit einem Hilfsskript, noch nicht im Repository (Kandidat für ein eigenes Issue, dann mit Tests): + +| PICTURE | Arbeitsschritt-`.md` | +|---|---| +| Ablaufelement mit Sequenzfluss | Schritt `S` mit ausdrücklichen Pfeilen, Reihenfolge Breitensuche ab Start, Gleichstand nach Lage | +| Lane | Präfix `Lane: ` vor der Beschriftung | +| aufgeklappter Teilprozess | geschlossener `Teilprozess` plus `Hinweis` „Inhalt von … (im Original aufgeklappt): …“ | +| Diagramm, das nur aus einem aufgeklappten Teilprozess besteht | dessen Inhalt ist der Prozess | +| Schleifen-Marker | `Hinweis` „… wird wiederholt (Schleife)“ | +| Verknüpfung zum Subdiagramm oder Prozessmodell | Kommentarzeile `# S im Original verknüpft …` | +| „Beschreibung“ eines Elements | Kommentarzeile `# S Beschreibung: …` | +| Anmerkung, Datenobjekt, Datenspeicher, Gruppe | unverbundenes Element; Bezug als Kommentar `# … gehört zu S`, ohne Assoziation mit „(nach Lage geschätzt)“ | +| Ablaufelement ganz ohne Sequenzfluss | `Hinweis` „… im Original ohne Sequenzfluss“ | +| Nicht-Endelement ohne Ausgang (Sackgasse) | ergänzt: `X Ende: (im Original ohne Abschluss)` | + +Kommentarzeilen (`#`) sind wichtig: Sie halten Bezüge fest, die das Diagramm nicht zeigt, und sind später die +Grundlage für eine Arbeitsschritt-Datenbank. + +## Befunde aus dem Stresstest + +Alle 23 `.md` lassen sich umwandeln. Jede Kante der abgebildeten Ebene ist in der `.bpmn` enthalten (Kanten im +Inneren aufgeklappter Teilprozesse fallen weg). Die Strukturprüfungen +aus `tests/test_referenzmodelle.py` finden **keine Kante durch ein Element, keine überlappenden Elemente, keine +schrägen Anschlüsse und keine zu kleinen Anmerkungen** – auch bei 116 Elementen und 58 Kanten. Offen sind: + +### Konverter (`md_to_bpmn.py`) + +1. **Lange Gateway-Beschriftungen werden geschnitten.** 10 Konflikte in 4 Modellen, alle an Gateways mit Fragen + über 80 Zeichen (z. B. „Hat die Wegenetz-Bestandsanalyse Handlungsbedarf ergeben? Bzw. Sollen Wegebaumaßnahmen + ausgeführt werden?“). Keine der fünf festen Positionen ist dann frei; die Beschriftung schneidet eine Kante oder + die Nachbaraufgabe. Die Beispiele haben nur kurze Fragen, deshalb fiel das bisher nicht auf. +2. **Datenobjekte stehen in einer einzigen Reihe oben.** Bei 31 Datenobjekten wird das Diagramm über 11 000 breit, + der Ablauf selbst nur rund 5 800. Ohne Assoziationen stehen sie zudem weit weg von der Aufgabe, zu der sie gehören. +3. **Große Prozesse ohne Lanes werden sehr hoch.** Senkrechtes Layout: U3.10 mit 46 Ablaufelementen ist 6 400 hoch. + PICTURE-Originale sind waagrecht angelegt. + +### Markdown-Syntax (Vertrag, Änderung nur per Issue) + +4. **Ein unbeschriftetes Element lässt sich keiner Lane zuordnen.** `S4 Gateway AND: TG:` ergibt ein Gateway mit + dem Namen „TG:“ in der Lane „Nicht zugeordnet“, weil `split_lane()` einen leeren Rest nicht als Zuständigkeit + gilt. Betrifft jedes unbeschriftete Gateway in einem Modell mit Lanes (3 Fälle im Bestand). +5. **Ein Ablaufelement ohne Ausgang geht nicht.** Fehlt die Pfeilzeile, verbindet der Konverter mit dem nächsten + Schritt. Sackgassen des Originals (z. B. zwei Vergabearten in U3.5) brauchen deshalb ein erfundenes Endereignis. +6. **Unverbundene Ablaufelemente gehen nicht.** Übersichtsdiagramme wie „U3 Organisatorische Verfahrensbetreuung“ + (15 Teilprozesse ohne Fluss, ein Katalog) lassen sich nur als Liste von Hinweisen abbilden. +7. **Nicht abbildbar:** aufgeklappte Teilprozesse, Schleifen- und Multi-Instanz-Marker, Assoziationen, + Verknüpfungen zwischen Diagrammen, Beschreibungen zu einzelnen Elementen, Kopfattribute des Prozesses (Zweck, + Verfahrensart, verantwortliche Organisationseinheit). Die Anleitung nennt das schon als Einschränkung; der Bestand + zeigt, wie häufig es vorkommt: 16 aufgeklappte Teilprozesse, 6 Schleifen, 27 Verknüpfungen. + +### Modelle im Bestand + +8. **Das Top-Level-Diagramm hat ein AND-Gateway mit fünf Kanten** (Split in vier Zweige). PICTURE kann nur vier + Kanten eindeutig anschließen (Modellierregel 4). +9. **Dubletten mit Abweichungen:** „6 Bauakt“ gibt es zweimal (Subdiagramm im Top-Level ohne Lanes, 44 Elemente; + Einzelexport mit Lanes VLN/TG/OFB, 25 Elemente) mit unterschiedlichem Inhalt. „5.2 Durchführung“ liegt im + Subdiagramm „5 Wertermittlung I“ zusätzlich als loses aufgeklapptes Duplikat neben dem Ablauf. +10. **Sackgassen und lose Elemente** (siehe 5 und 6) sind im Original Modellierfehler oder Platzhalter. Sie stehen + im Steckbrief des jeweiligen Modells. + +## Weiter + +- Befunde 1 bis 3 sind Kandidaten für Konverter-Issues, 4 bis 7 für Issues zur Syntax (Vertrag). +- Issue #28 (Qualifizierung der Eingabe) und die geplante Arbeitsschritt-Datenbank können auf die Import-Modelle + zurückgreifen: Die Anmerkungen enthalten viel Fachwissen (Fristen, Rechtsgrundlagen, Werkzeuge, + Dokumente je Schritt). -- 2.54.0