Durchführungsstatus im Tagescron automatisch abschliessen

docs/modules/market_management/processes/main/market_management.occurrence_status_completion.md

@@ -0,0 +1,111 @@
+# market_management.occurrence_status_completion
+Stand: 2026-09-19
+Status: Verbindliche Prozess-Spezifikation
+
+## 1. Zweck
+
+Setzt aktive Durchführungen am täglichen Cron-Lauf automatisch auf
+`completed`, sobald der Kalendertag nach ihrem letzten Durchführungstag erreicht
+ist. Abgesagte Durchführungen werden nicht verändert.
+
+## 2. Prozess-Einbettung
+
+Täglicher synchroner Cron-Teilprozess des zentralen System-Cron-Entrypoints.
+Die fachliche Statusänderung gehört zum owning Modul `market_management`.
+
+## 3. Input
+
+- aktuelles Datum in der Zeitzone `Europe/Zurich`
+- keine vorbereiteten Fachdaten; der Prozess liest seine Daten selbst aus der
+  Datenbank
+
+## 4. Exakter Prozessablauf
+
+1. Einen technischen Lauf in `public.process_runs` mit dem aktuellen Datum
+   starten.
+2. Aus `market_occurrence` und `market_occurrence_day` aktive Durchführungen
+   mit mindestens einem Tag bestimmen.
+3. Durchführungen ausschliessen, deren Status `cancelled` oder bereits
+   `completed` ist.
+4. Für jede verbleibende Durchführung den letzten Durchführungstag bestimmen.
+5. Wenn dieser Tag vor dem aktuellen Datum liegt, den Status atomar auf
+   `completed` setzen.
+6. Den technischen Lauf mit Anzahl und IDs der geänderten Durchführungen
+   abschliessen.
+
+Gelesen werden `market_occurrence` und `market_occurrence_day`. Geschrieben
+werden `market_occurrence.status`, `market_occurrence.updated_at` und der
+technische Lauf in `public.process_runs`.
+
+## 5. Batch, Betriebsmodell und Einbettung
+
+Ein täglicher synchroner Cron-Lauf; ein SQL-Update verarbeitet den vollständigen
+aktuellen Scope atomar. Die bestehende Cron-Sperre verhindert parallele Läufe.
+
+## 6. Output
+
+Ein kompakter Laufstatus mit aktuellem Datum, Anzahl und IDs der auf
+`completed` gesetzten Durchführungen sowie der technischen Lauf-ID.
+
+## 7. Erfolgskriterien
+
+- Eine Durchführung wird am Tag nach ihrem letzten Durchführungstag auf
+  `completed` gesetzt.
+- Abgesagte und bereits abgeschlossene Durchführungen bleiben unverändert.
+- Durchführungen ohne Durchführungstag werden nicht verändert.
+- Wiederholte Cron-Läufe sind idempotent.
+- `public.process_runs` enthält einen abgeschlossenen technischen Lauf.
+
+## 8. Fehlerschranke
+
+Ein technischer Fehler bricht den Lauf ab, rollt die fachliche Transaktion
+zurück und markiert `process_runs` als `failed`.
+
+## 9. Fachliche Betriebsregel
+
+Die Prüfung erfolgt einmal täglich über den bestehenden Cron. Die Statusänderung
+ist unabhängig von GUI-Aufrufen und OTC-Bestellungen.
+
+## 10. Sub-Prozess-Referenzen
+
+Keine zusätzlichen Sub-Prozesse.
+
+## 11. End-to-End Sub-Prozess-Kette
+
+System-Cron → Statusabschlussprozess → `market_occurrence` und
+`public.process_runs`.
+
+## 12. Sub-Prozess-Wiederverwendung
+
+Der bestehende System-Cron-Entrypoint und die bestehende Cron-Sperre werden
+wiederverwendet. Ein zusätzlicher Scheduler wird nicht eingeführt.
+
+## 13. Step-Liste
+
+- Lauf starten
+- eligible Durchführungen bestimmen und abschliessen
+- Laufstatus persistieren
+
+## 14. Parallelisierung
+
+Keine Parallelisierung; der deterministische SQL-Batch läuft synchron und
+atomar.
+
+## 15. Output-Payload
+
+```json
+{
+  "status": "done",
+  "as_of_date": "YYYY-MM-DD",
+  "completed_count": 0,
+  "completed_occurrence_ids": [],
+  "technical_run_id": 0
+}
+```
+
+## 16. Done-Kriterien
+
+- Der tägliche Cron ruft den Prozess genau einmal auf.
+- Die Statusregel ist serverseitig implementiert.
+- Der Prozess schreibt `process_runs` vollständig.
+- Wiederholte Läufe erzeugen keine erneuten Statusänderungen.