Projektwissen/.agents/skills/sn-bpmn/Anleitung.md

# Markdown → BPMN 2.0 für PICTURE

`md_to_bpmn.py` wandelt eine einfache textuelle Prozessbeschreibung (`.md`)
in eine standardkonforme BPMN-2.0-XML-Datei um, die sich über den
BPMN-Import in PICTURE laden lässt. BPMN 2.0 ist ein offener, seit 2011
stabiler OMG-Standard – das Skript muss dafür kein PICTURE-internes
Schema "lernen" und erzeugt keine PICTURE-spezifischen UUIDs.

## Empfohlener Arbeitsablauf bei unstrukturiertem Ausgangstext

1. Rohtext (Fließtext, Stichpunkte, Sitzungsnotizen o. ä.) bereitstellen.
2. Daraus wird eine strukturierte Arbeitsschritt-`.md` in der unten
   beschriebenen Syntax abgeleitet und zur Prüfung vorgelegt.
3. Fachlich prüfen und in der `.md` direkt anpassen (Reihenfolge,
   Verzweigungen, Verantwortliche, Formulierungen) – dabei gegen
   `Modellierregeln.md` abgleichen.
4. Aus der freigegebenen `.md` die BPMN-2.0-Datei erzeugen und in PICTURE
   importieren.

Schritt 2 erfordert Interpretation von Fließtext und ist kein rein
mechanischer Schritt – die Qualität hängt von der Klarheit der Quelle und
der fachlichen Prüfung in Schritt 3 ab. Die fachlichen BPMN-Modellierregeln
stehen in `Modellierregeln.md`.

## Aufruf

```bash
python .agents/skills/sn-bpmn/md_to_bpmn.py <prozess.md> <ausgabe.bpmn>
```

Beispiel (aus dem Workspace-Root):

```bash
python .agents/skills/sn-bpmn/md_to_bpmn.py entwuerfe/antrag-pruefen.md entwuerfe/antrag-pruefen.bpmn
```

Versionierte Modelle in der Prozessbibliothek werden nicht einzeln, sondern
gesammelt erzeugt: `python scripts/pruefe_prozesse.py --erzeugen` (siehe
`docs/leitfaden/08_prozessbibliothek.md`).

Die erzeugte `.bpmn`-Datei kann anschließend über den BPMN-Import-Dialog
in PICTURE geladen werden.

### Diagramm vorab prüfen, ohne PICTURE

Um zu prüfen, ob `md_to_bpmn.py` selbst korrekt gerechnet hat (Struktur,
Anschlusspunkte, Layout) – unabhängig davon, was ein Import-Werkzeug daraus
macht – eignet sich ein originalgetreuer BPMN-Viewer. Im Repository liegt
einer, offline und ohne Datenübertragung:

```bash
python scripts/vorschau.py entwuerfe/<name>.md     # oder eine .bpmn
```

Ohne Python: `werkzeuge/vorschau/vorschau.html` im Browser öffnen und die
`.bpmn` hineinziehen (Details: `werkzeuge/vorschau/README.md`). Alternativ:

- **`demo.bpmn.io`** – im Browser, kein Install nötig: `.bpmn`-Datei per
  Drag & Drop reinziehen.
- **Camunda Modeler** – kostenlose Desktop-App, gleiche Rendering-Engine
  wie bpmn.io, auch offline.

Beide übernehmen importierte Anschlusspunkte originalgetreu, statt sie neu
zu berechnen.

## Markdown-Syntax

### Kopfzeile (optional, vor dem ersten Schritt)

```
Prozess: <Name des Prozesses>
```

### Schritte

Jeder Schritt ist eine Zeile der Form:

```
<ID> <Typ>: <Beschriftung>
```

- **ID**: ein kurzes, eindeutiges Kürzel ohne Leerzeichen (z. B. `S1`, `3.3`, `A`)
- **Typ** (Groß-/Kleinschreibung egal):

  | Schreibweise im .md                 | Erzeugtes BPMN-Element             |
  |--------------------------------------|-------------------------------------|
  | `Start`                              | Start-Ereignis                     |
  | `Ende` / `End`                       | End-Ereignis                       |
  | `Zwischenereignis` / `Intermediate`  | Zwischen-Ereignis (Catch)          |
  | `Task` / `Aufgabe`                   | Aufgabe (Task)                     |
  | `Manuelle Aufgabe`                   | Manuelle Aufgabe                   |
  | `User Aufgabe`                       | User-Aufgabe                       |
  | `Service Aufgabe`                    | Service-Aufgabe                    |
  | `Script Aufgabe`                     | Script-Aufgabe                     |
  | `Geschäftsregel Aufgabe`             | Geschäftsregel-Aufgabe             |
  | `Sendeaufgabe`                       | Aufgabe (sendend)                  |
  | `Empfangsaufgabe`                    | Aufgabe (empfangend)               |
  | `Teilprozess` / `Subprocess`         | Geschlossener Teilprozess          |
  | `Aufruf`                             | Aufruf-Element (Call Activity)     |
  | `Gateway XOR`                        | Exklusives Gateway (XOR)           |
  | `Gateway OR` / `Gateway ODER`        | Inklusives Gateway (OR)            |
  | `Gateway AND` / `Gateway UND`        | Paralleles Gateway (AND)           |
  | `Gateway Ereignisbasiert`            | Ereignisbasiertes Gateway          |
  | `Hinweis` / `Note`                   | Textuelle Anmerkung (unverbunden)  |
  | `Datenobjekt`                        | Datenobjekt (unverbunden)          |
  | `Datenspeicher`                      | Datenspeicher (unverbunden)        |
  | `Gruppe`                             | Gruppe (unverbunden)               |

  Vollständige Liste inkl. Bedeutung: `Elementkatalog.md`.

### Typisierte Ereignisse

Start-, Zwischen- und Endereignisse können ein zweites Wort für die Art des
Ereignisses bekommen: `<Start|Zwischenereignis|Ende> <Kind>: <Beschriftung>`.
Mögliche `<Kind>`-Wörter: `Nachricht`, `Zeit`, `Eskalation`, `Bedingung`,
`Link`, `Fehler`, `Signal`, `Terminierung`. Details und Einschränkungen (z. B.
`Terminierung` nur als Endereignis, `Link` nur als Zwischenereignis) stehen in
`Elementkatalog.md` und `Modellierregeln.md`.

```
S1 Start Nachricht: Antrag geht ein
S9 Zwischenereignis Zeit: 14 Tage Frist abwarten
S17 Ende Terminierung: Verfahren beendet
```

Ein Zwischenereignis ist standardmäßig empfangend (Catch); mit einem
zusätzlichen dritten Wort `sendend` wird daraus ein auslösendes (Throw-)
Ereignis, z. B. `S2 Zwischenereignis Nachricht sendend: Status melden`.

### Geschlossene Pools und Nachrichtenflüsse

Externe Beteiligte (Bürger, andere Behörden, …), mit denen nur Nachrichten
ausgetauscht werden, vor dem ersten Schritt deklarieren:

```
Extern: Bürger
Extern: Landratsamt
```

Unter einem Schritt erzeugt `~> <Name>` einen ausgehenden, `<~ <Name>` einen
eingehenden Nachrichtenfluss zu einem so deklarierten Beteiligten:

```
S8 Sendeaufgabe: Bescheid versenden
  ~> Bürger
  -> S9
```

Nachrichtenflüsse sind nur zwischen Pools erlaubt (siehe `Modellierregeln.md`)
– das Ziel muss immer ein per `Extern:` deklarierter Name sein, nie eine
Schritt-ID im selben Pool.

### Verzweigungen / Sprünge

Unter einem Schritt können beliebig viele Pfeil-Zeilen stehen:

```
S3 Gateway XOR: Antrag vollständig?
  Ja -> S4
  Nein -> S3a
```

- `<Bezeichnung> -> <Ziel-ID>` – beschriftete Kante (z. B. für Ja/Nein-Zweige)
- `-> <Ziel-ID>` – unbeschriftete Kante (z. B. für parallele AND-Zweige oder
  einfache Weiterleitung)

**Wichtig:** Wenn ein Schritt **keine** Pfeil-Zeile hat, wird automatisch
eine Kante zum **nächsten Schritt in der Datei** erzeugt. Ihr müsst also nur
dort explizite Pfeile setzen, wo der Ablauf von der reinen Lesereihenfolge
abweicht (Verzweigung, Sprung zurück, Zusammenführung).

Rücksprünge (Schleifen, z. B. „Nachforderung" zurück zur Prüfung) werden
automatisch erkannt und an allen Elementen vorbei zurückgeführt: mit Lanes
über einen Kanal am Boden des eigenen Pools, ohne Lanes seitlich am Diagramm.

### Verantwortliche / Swimlanes

Schreibt ihr am Anfang der Beschriftung eines Schritts einen kurzen Namen
gefolgt von einem Doppelpunkt, wird dieser als **Verantwortlicher** erkannt
und daraus automatisch eine Swimlane gemacht:

```
V1 Task: Flurneuordnung: Gewannenkonzept festlegen
O3 Task: ÖbVI: Waldgrenzen verhandeln
O9 Task: LRA: Aufmessung im Ortstermin
```

Aus den drei unterschiedlichen Verantwortlichen entstehen drei Lanes in
einem Pool; Schritte ohne Verantwortlichen-Angabe landen gesammelt in einer
Lane „Nicht zugeordnet". Ohne jede Verantwortlichen-Angabe entsteht wie
bisher ein Diagramm ohne Lanes.

Das ist eine Heuristik: Ein Doppelpunkt weit vorn in einer kurzen
Beschriftung (max. 30 Zeichen, max. 4 Wörter, kein „?") wird als
Verantwortlicher gedeutet. Enthält eine Beschriftung an dieser Stelle
zufällig einen Doppelpunkt, der keine Zuständigkeit meint, entsprechend
umformulieren.

### Vollständige Beispiele

In `beispiele/` neben dieser Datei, reine Syntaxbeispiele (fachlich nicht geprüft):

- Ohne Lanes: `beispiele/beispiel_prozess.md` / `beispiele/beispiel_prozess.bpmn`
- Mit Lanes und externem Beteiligten: `beispiele/beispiel_lanes.md` / `beispiele/beispiel_lanes.bpmn`

Referenzmodell (Test) – ein echter, größerer Prozess, gegen den Änderungen am
Konverter geprüft werden (Byte-Vergleich plus Strukturtests in
`tests/test_referenzmodelle.py`; die Prüfung „keine Kante durch ein Element“
läuft auch über die Syntaxbeispiele):

- `beispiele/referenz_gewannenfestlegung.md` / `.bpmn` – 4 Lanes, externer Pool,
  14 Gateways, verschachtelte Varianten; fachlich nicht abgenommen

Ein Test hält die `.bpmn` der Beispiele aktuell; nach einer Änderung am
Konverter `python scripts/pruefe_prozesse.py --erzeugen` ausführen.

## Einschränkungen der aktuellen Version

- Es wird pro `.md`-Datei **ein** Diagramm (ein Prozess) erzeugt, keine
  mehrstufigen Prozessnetze mit verknüpften Teilprozess-Diagrammen.
- `Teilprozess` (geschlossener Teilprozess) und `Aufruf` (Aufruf-Element)
  werden als Bausteine angelegt, aber **ohne** Inhalt bzw. **ohne**
  Verknüpfung zu einem Ziel-Prozess – Details bzw. Verknüpfung lassen sich
  in PICTURE nach dem Import nachtragen. Der **aufgeklappte** Teilprozess
  (Inhalt inline im selben Diagramm) wird noch nicht unterstützt.
- Wiederholungs-Marker (Schleife, Multi-Instanz sequenziell/parallel) werden
  noch nicht unterstützt; bei Bedarf als `Hinweis` an der betroffenen
  Aktivität dokumentieren.
- Assoziationen (gepunktete Linien) von Datenobjekten/-speichern zu
  Aktivitäten werden nicht automatisch gezeichnet; Datenobjekt/-speicher
  landen unverbunden im Diagramm und werden nach dem Import in PICTURE bei
  Bedarf manuell mit den betroffenen Aktivitäten verbunden.
- Das automatische Layout ist ein einfacher Schichten-Algorithmus
  (ähnlich den meisten BPMN-Auto-Layouts) – bei komplexen Prozessen lohnt
  sich nach dem Import ein manuelles Nachjustieren einzelner Boxen und
  Beschriftungen. Das gilt besonders für geschlossene Pools (externe
  Beteiligte): Sie werden schlicht unterhalb des Hauptpools gestapelt.
- Jede Kante bekommt in der erzeugten `.bpmn`-Datei einen eigenen
  Anschlusspunkt (Modellierregel 4, in `Modellierregeln.md`) statt eines
  gemeinsamen Mittelpunkts. Bei Task/Ereignis/Datenobjekt usw. werden dazu
  mehrere Punkte über die tatsächliche Kontur verteilt (Rechteckkante bzw.
  Kreisbogen). **Ein Gateway bekommt dagegen nur einen der vier festen
  PICTURE-Eckpunkte (0°/90°/180°/270°) je Kante**, nie einen Punkt
  dazwischen auf der Rautenkante – mehr als vier Kanten an einem Gateway
  (eingehend plus ausgehend) können sich damit nicht mehr eindeutig
  darstellen lassen, siehe Modellierregel 4. Wirkt das Ergebnis in einem
  Anzeige-Werkzeug trotzdem so, als würden Verzweigungen an einem Punkt
  zusammenlaufen, zuerst in einem originalgetreuen BPMN-Viewer (z. B.
  `demo.bpmn.io`, siehe unten) prüfen: Ein Viewer, der importierte
  Anschlusspunkte respektiert statt sie neu zu berechnen, zeigt die
  verteilten Punkte korrekt an.
- Der BPMN-Import in PICTURE übernimmt die reine Ablaufstruktur
  zuverlässig; PICTURE-/FIM-spezifische Zusatzfelder (Fallzahl,
  Bearbeitungszeit, RACI usw.) sind kein Teil des BPMN-Standards und
  müssten nach dem Import ergänzt werden.