DanielandClaude Opus 5.5
31131cc5c3
- ADR 0004 ersetzt ADR 0003: Die Prozessmodelle liegen im Repository AG_Prozesse/Prozessbibliothek, geklont nach Prozessbibliothek/ (neuer Eintrag in workspace.toml, .gitignore). prozesse/ ist entfernt; das Ablageformat (Ordner je Prozess, drei Dateien, Status) bleibt. - pruefe_prozesse.py prüft den Klon (Ort über setup_workspace.repos_root), lässt Punkt-Ordner wie .git aus und erlaubt in der Wurzel nur die Repo-Dateien. Fehlt der Klon, gibt es einen Hinweis statt eines Befunds; pytest warnt dann. - einlesen.py sucht den Bestand in der Bibliothek und nennt Treffer als Prozessbibliothek/<name>/, auch wenn der Klon woanders liegt. - Regeln aus prozesse/README.md nach docs/leitfaden/08_prozessbibliothek.md, inklusive Ablauf bei Konverteränderungen (zwei Pull Requests). - Verweise in AGENTS.md, README, Skills, Leitfäden, Vorlagen, Fallstricken und STATUS nachgezogen. - Tests: python -m pytest -q -> 88 bestanden, 1 xfail (#8), 1 Warnung (Bibliothek noch nicht geklont). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
254 lines
11 KiB
Markdown
254 lines
11 KiB
Markdown
# 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 am Rand des Diagramms herumgeführt.
|
||
|
||
### 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`):
|
||
|
||
- `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.
|