Projektwissen/docs/wissen/picture_import.md

# 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 `<Name>_0.bpmn`, `<Name>_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<n>` 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<n> im Original verknüpft …` |
| „Beschreibung“ eines Elements | Kommentarzeile `# S<n> Beschreibung: …` |
| Anmerkung, Datenobjekt, Datenspeicher, Gruppe | unverbundenes Element; Bezug als Kommentar `# … gehört zu S<n>`, ohne Assoziation mit „(nach Lage geschätzt)“ |
| Ablaufelement ganz ohne Sequenzfluss | `Hinweis` „… im Original ohne Sequenzfluss“ |
| Nicht-Endelement ohne Ausgang (Sackgasse) | ergänzt: `X<n> 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.
   **Bewertung nach dem PICTURE-Import (28.09.2026): kein Konverterfehler**, sondern ein Designfehler der
   Ausgangsmodelle. Dort sind Datenobjekte nicht an Aufgaben gebunden. Gelöst wird das über die
   Arbeitsschritt-Datenbank, in der jedes Dokument einem Arbeitsschritt gehört. Kein Konverter-Issue.
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

- **Erkenntnis aus dem Import (28.09.2026):** Der Konverter ist nicht der Engpass, sondern die Ausgangsdaten. Die
  PICTURE-Modelle haben unbeschriftete Gateways, Sackgassen, lose Elemente und Datenobjekte ohne Bezug. Wer mit
  wenigen Iterationen zu einem brauchbaren Prozess kommen will, braucht deutlich bessere Eingaben und eine
  saubere Interviewmethode, die diese Lücken schon beim Erfassen schließt (Issue #28).
- Befunde 1 und 3 sind Kandidaten für Konverter-Issues, 4 bis 7 für Issues zur Syntax (Vertrag). Befund 2 löst
  die Arbeitsschritt-Datenbank.
- 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).