⚠️ Veraltet (Stand 2026-04-30)

Diese Dokumentation beschreibt das alte System vor dem Process-Engine-Refactor (Phase 4.7). Die zugrundeliegenden Tabellen (cascade_*, concept_instances/bausteine, crisis_scenarios/events/tasks, workflow_*) wurden gedroppt. Die hier dokumentierten Routen und Models existieren so nicht mehr.

Aktuelle Architektur: Process-Engine API — eine Engine, mehrere Apps (flow.*, concept.*, crisis.*).

Diese Datei bleibt als historische Referenz erhalten.

Krisenmanagement — API-Referenz

Alle Endpoints unter /api/platform/v1/. Authentifizierung via JWT Bearer Token.

Szenarien

GET /crisis/scenarios

Alle Szenarien des Tenants.

Query-Parameter:

Parameter	Typ	Beschreibung
approved	string	`"true"` — nur freigegebene Szenarien

Response:

json

{
  "items": [
    {
      "id": "clx...",
      "tenantId": "...",
      "name": "Feueralarm",
      "nameSlug": "feueralarm",
      "severity": "CRITICAL",
      "type": "GENERAL",
      "description": "Brand oder Brandverdacht im Schulgebaeude.",
      "targetResponseMs": 0,
      "version": 1,
      "isActive": true,
      "approvedBy": "@admin:school.prilog.team",
      "approvedAt": "2026-04-03T...",
      "notifyRoles": ["SCHOOL_PRINCIPAL", "SCHOOL_ADMIN"],
      "checklistItems": [...],
      "externalContacts": [...],
      "escalationRules": [...],
      "needsReview": false,
      "daysSinceReview": 12
    }
  ],
  "total": 10
}

GET /crisis/scenarios/:id

Einzelnes Szenario mit allen Details.

POST /crisis/scenarios

Neues Szenario erstellen (unapproved).

Rollen: SCHOOL_ADMIN, SCHOOL_PRINCIPAL

Body:

json

{
  "name": "Neues Szenario",
  "nameSlug": "neues-szenario",
  "severity": "HIGH",
  "type": "GENERAL",
  "targetResponseMs": 300000,
  "notifyRoles": ["SCHOOL_PRINCIPAL"],
  "checklistItems": [
    {
      "id": "item1",
      "order": 1,
      "title": "Erste Aufgabe",
      "assignedRole": "SCHOOL_ADMIN",
      "escalateAfterMs": 300000,
      "isMandatory": true
    }
  ],
  "externalContacts": [],
  "escalationRules": []
}

PUT /crisis/scenarios/:id

Szenario bearbeiten. Erstellt eine neue Version — alte bleibt unveraendert.

Rollen: SCHOOL_ADMIN, SCHOOL_PRINCIPAL

POST /crisis/scenarios/:id/approve

Szenario freigeben. Setzt approvedBy und approvedAt.

Rollen: SCHOOL_ADMIN, SCHOOL_PRINCIPAL

Fehler: 409 ALREADY_APPROVED wenn bereits freigegeben.

Workflow

POST /crisis/activate

Krise aktivieren oder Vorschau anzeigen.

Body:

json

{
  "scenarioId": "clx...",
  "confirm": false,
  "activationNote": "Brand im Erdgeschoss"
}

confirm: false → Vorschau:

json

{
  "scenario": { "id": "...", "name": "Feueralarm", "severity": "CRITICAL", "description": "..." },
  "willNotify": ["SCHOOL_PRINCIPAL", "SCHOOL_ADMIN"],
  "willCreateRoom": "Krise: Feueralarm",
  "checklistCount": 4
}

confirm: true → Aktivierung:

json

{
  "eventId": "clx...",
  "matrixRoomId": "!abc:school.prilog.team",
  "activatedAt": "2026-04-03T10:30:00.000Z",
  "tasksCreated": 4,
  "notifiedUsers": 2
}

Fehler: 409 CRISIS_ALREADY_ACTIVE mit existingEventId.

GET /crisis/active

Alle aktiven Events des Tenants. Fuer Dashboard-Badge und Polling.

GET /crisis/:eventId

Event-Detail inkl. Szenario, Tasks und Report.

POST /crisis/:eventId/deactivate

Krise beenden. Erstellt automatisch einen Nachbericht.

Rollen: SCHOOL_ADMIN, SCHOOL_PRINCIPAL

POST /crisis/:eventId/false-alarm

Fehlalarm markieren.

Body:

json

{
  "note": "Fehlausloesung der Brandmeldeanlage"
}

Fehler: 400 NOTE_REQUIRED wenn note leer.

Aufgaben

GET /crisis/:eventId/tasks

Alle Tasks des Events, sortiert nach Erstellungszeit.

PATCH /crisis/:eventId/tasks/:taskId/status

Task-Status setzen.

Body:

json

{
  "status": "DONE"
}

Erlaubte Werte: OPEN, IN_PROGRESS, DONE

Berichte

GET /crisis/:eventId/report

Nachbericht als JSON.

GET /crisis/:eventId/report/pdf

Nachbericht als PDF-Download.

Response-Header:

Content-Type: application/pdf
Content-Disposition: attachment; filename="krisenbericht-clx12345-2026-04-03.pdf"

GET /crisis/:eventId/audit

Audit-Log des Events.

Rollen: SCHOOL_ADMIN, SCHOOL_PRINCIPAL

GET /crisis/events

Alle Events (aktiv + archiviert) fuer die Archiv-Ansicht. Limit: 50.

Schulreisen

GET /school-trips

Alle Schulreisen. Optional ?status=ACTIVE.

GET /school-trips/:id

Schulreise-Detail. Jeder Zugriff wird im Audit-Log protokolliert.

POST /school-trips

Neue Schulreise anlegen.

Rollen: SCHOOL_ADMIN, SCHOOL_PRINCIPAL

Body:

json

{
  "title": "Klassenfahrt 7a",
  "destination": "Berlin",
  "startDate": "2026-06-15",
  "endDate": "2026-06-19",
  "participants": [
    { "name": "Max Mustermann", "class": "7a", "emergencyContact": "+49 170 1234567" }
  ],
  "companions": [
    { "name": "Frau Mueller", "role": "Klassenleitung", "phone": "+49 170 9876543" }
  ]
}

PUT /school-trips/:id

Schulreise aktualisieren (Teilnehmer, Kontakte, Status, etc.).

POST /school-trips/:id/activate

Status auf ACTIVE setzen (Reise starten).

POST /school-trips/:id/complete

Status auf COMPLETED setzen (Reise beenden).

DELETE /school-trips/:id

Schulreise loeschen (nur bei Status PLANNED oder CANCELLED).

Kinderschutz

Zugriffskontrolle

Alle Kinderschutz-Endpoints erfordern SCHOOL_ADMIN oder SCHOOL_PRINCIPAL. Jeder Zugriff wird im accessLog des Falls protokolliert.

GET /child-protection

Alle Faelle. Optional ?status=OPEN.

GET /child-protection/:id

Fall-Detail. Protokolliert Zugriff im accessLog.

POST /child-protection

Neuen Fall anlegen.

Body:

json

{
  "caseReference": "KS-2026-001",
  "observations": [
    { "date": "2026-04-03T10:00:00Z", "observer": "@lehrer", "text": "Auffaellige Verletzungen..." }
  ]
}

POST /child-protection/:id/observation

Beobachtung hinzufuegen.

Body:

json

{
  "text": "Erneut Verletzungen beobachtet",
  "category": "koerperlich"
}

POST /child-protection/:id/expert

Fachkraft einbeziehen. Setzt Status auf EXPERT_INVOLVED.

Body:

json

{
  "expertUserId": "@fachkraft:school.prilog.team"
}

POST /child-protection/:id/report

Ans Jugendamt melden (Vier-Augen-Prinzip).

Erste Zustimmung:

json

{ "success": false, "message": "Erste Zustimmung erhalten...", "approvalsGiven": 1, "approvalsNeeded": 2 }

Zweite Zustimmung (anderer User):

json

{ "success": true, "message": "Meldung ans Jugendamt dokumentiert." }

Fehler: 403 FOUR_EYES_SAME_PERSON wenn dieselbe Person zweimal bestaetigt.

POST /child-protection/:id/risk-assessment

Gefaehrdungseinschaetzung speichern.

POST /child-protection/:id/close

Fall schliessen mit Begruendung. Setzt retainUntil auf 10 Jahre.

Integrationen

GET /integrations/adapters

Alle registrierten Export-Adapter.

json

{
  "items": [
    { "id": "pdf-a-export", "type": "pdf-a", "name": "PDF/A-Archivexport", "description": "..." },
    { "id": "youth-office-export", "type": "youth-office", "name": "Jugendamt-Meldung", "description": "..." },
    { "id": "police-export", "type": "police", "name": "Polizei-Bericht", "description": "..." },
    { "id": "data-protection-export", "type": "data-protection", "name": "DSGVO-Meldung", "description": "..." }
  ]
}

POST /integrations/export/crisis-report/:eventId

Krisenbericht ueber einen Adapter exportieren.

Body:

json

{
  "adapterType": "pdf-a"
}

Response: PDF-Download oder JSON mit Metadaten.

POST /integrations/export/child-protection/:caseId

Kinderschutzfall exportieren.

Body:

json

{
  "adapterType": "youth-office"
}

n8n Callback-Endpoints

Diese Endpoints werden von n8n-Workflows aufgerufen und sind nicht fuer die direkte Nutzung durch Portal oder Web-Client vorgesehen. Authentifizierung erfolgt via internem Service-Token.

POST /n8n-callback/events/[eventId]/create-tasks

Erstellt Checklisten-Aufgaben fuer ein aktives Event. Wird vom n8n-Workflow nach Krisenaktivierung aufgerufen.

Body:

json

{
  "tasks": [
    {
      "title": "Gebaeude raeumen",
      "assignedRole": "CUSTODIAN",
      "escalateAfterMs": 300000,
      "isMandatory": true,
      "order": 1
    }
  ]
}

POST /n8n-callback/events/[eventId]/create-room

Erstellt einen Matrix-Krisenraum fuer das Event und pinnt die Checkliste an.

Response:

json

{
  "matrixRoomId": "!abc:school.prilog.team"
}

POST /n8n-callback/events/[eventId]/notify-matrix

Postet eine Nachricht in den Krisenraum des Events.

Body:

json

{
  "message": "Aufgabe eskaliert: Gebaeude raeumen (Stufe 2)",
  "type": "escalation"
}

GET /n8n-callback/events/[eventId]/tasks

Gibt alle Tasks des Events zurueck. Wird von n8n zur Eskalationspruefung verwendet.

POST /n8n-callback/tasks/[taskId]/escalate

Eskaliert einen Task auf die naechste Stufe. Setzt Status auf ESCALATED, erstellt Audit-Eintrag und postet im Krisenraum.

Body:

json

{
  "level": 2,
  "message": "Zeitlimit ueberschritten — Schulleitung benachrichtigt"
}

POST /n8n-callback/events/[eventId]/generate-report

Generiert den Nachbericht fuer ein beendetes Event.

Response:

json

{
  "reportId": "clx...",
  "generatedAt": "2026-04-03T12:00:00.000Z"
}

Deprecation: escalationRules

Das Feld escalationRules auf CrisisScenario ist veraltet. Eskalationslogik wird jetzt im verknuepften n8n-Workflow konfiguriert. Das Feld bleibt aus Kompatibilitaetsgruenden erhalten, wird aber nicht mehr vom Backend ausgewertet.

Fehler-Codes

Code	HTTP	Beschreibung
NOT_FOUND	404	Ressource nicht gefunden
INSUFFICIENT_ROLE	403	Keine ausreichende Berechtigung
CRISIS_ALREADY_ACTIVE	409	Fuer dieses Szenario laeuft bereits eine Krise
ALREADY_APPROVED	409	Szenario ist bereits freigegeben
NOTE_REQUIRED	400	Fehlalarm-Begruendung fehlt
REASON_REQUIRED	400	Schliessungs-Begruendung fehlt
INVALID_STATUS	400	Ungueltiger Task-Status
FOUR_EYES_SAME_PERSON	403	Vier-Augen: gleiche Person kann nicht zweimal bestaetigen
CANNOT_DELETE_ACTIVE_TRIP	400	Aktive Schulreisen koennen nicht geloescht werden
UNKNOWN_ADAPTER	400	Adapter-Typ nicht registriert
ADAPTER_NOT_SUPPORTED	400	Adapter unterstuetzt diese Export-Art nicht
EXPORT_FAILED	500	Export-Generierung fehlgeschlagen
PDF_GENERATION_FAILED	500	PDF-Erstellung fehlgeschlagen

Krisenmanagement — API-Referenz ​

Szenarien ​

GET /crisis/scenarios ​

GET /crisis/scenarios/:id ​

POST /crisis/scenarios ​

PUT /crisis/scenarios/:id ​

POST /crisis/scenarios/:id/approve ​

Workflow ​

POST /crisis/activate ​

GET /crisis/active ​

GET /crisis/:eventId ​

POST /crisis/:eventId/deactivate ​

POST /crisis/:eventId/false-alarm ​

Aufgaben ​

GET /crisis/:eventId/tasks ​

PATCH /crisis/:eventId/tasks/:taskId/status ​

Berichte ​

GET /crisis/:eventId/report ​

GET /crisis/:eventId/report/pdf ​

GET /crisis/:eventId/audit ​

GET /crisis/events ​

Schulreisen ​

GET /school-trips ​

GET /school-trips/:id ​

POST /school-trips ​

PUT /school-trips/:id ​

POST /school-trips/:id/activate ​

POST /school-trips/:id/complete ​

DELETE /school-trips/:id ​

Kinderschutz ​

GET /child-protection ​

GET /child-protection/:id ​

POST /child-protection ​

POST /child-protection/:id/observation ​

POST /child-protection/:id/expert ​

POST /child-protection/:id/report ​

POST /child-protection/:id/risk-assessment ​

POST /child-protection/:id/close ​

Integrationen ​

GET /integrations/adapters ​

POST /integrations/export/crisis-report/:eventId ​

POST /integrations/export/child-protection/:caseId ​

n8n Callback-Endpoints ​

POST /n8n-callback/events/[eventId]/create-tasks ​

POST /n8n-callback/events/[eventId]/create-room ​

POST /n8n-callback/events/[eventId]/notify-matrix ​

GET /n8n-callback/events/[eventId]/tasks ​

POST /n8n-callback/tasks/[taskId]/escalate ​

POST /n8n-callback/events/[eventId]/generate-report ​

Fehler-Codes ​

Krisenmanagement — API-Referenz

Szenarien

GET /crisis/scenarios

GET /crisis/scenarios/:id

POST /crisis/scenarios

PUT /crisis/scenarios/:id

POST /crisis/scenarios/:id/approve

Workflow

POST /crisis/activate

GET /crisis/active

GET /crisis/:eventId

POST /crisis/:eventId/deactivate

POST /crisis/:eventId/false-alarm

Aufgaben

GET /crisis/:eventId/tasks

PATCH /crisis/:eventId/tasks/:taskId/status

Berichte

GET /crisis/:eventId/report

GET /crisis/:eventId/report/pdf

GET /crisis/:eventId/audit

GET /crisis/events

Schulreisen

GET /school-trips

GET /school-trips/:id

POST /school-trips

PUT /school-trips/:id

POST /school-trips/:id/activate

POST /school-trips/:id/complete

DELETE /school-trips/:id

Kinderschutz

GET /child-protection

GET /child-protection/:id

POST /child-protection

POST /child-protection/:id/observation

POST /child-protection/:id/expert

POST /child-protection/:id/report

POST /child-protection/:id/risk-assessment

POST /child-protection/:id/close

Integrationen

GET /integrations/adapters

POST /integrations/export/crisis-report/:eventId

POST /integrations/export/child-protection/:caseId

n8n Callback-Endpoints

POST /n8n-callback/events/[eventId]/create-tasks

POST /n8n-callback/events/[eventId]/create-room

POST /n8n-callback/events/[eventId]/notify-matrix

GET /n8n-callback/events/[eventId]/tasks

POST /n8n-callback/tasks/[taskId]/escalate

POST /n8n-callback/events/[eventId]/generate-report

Fehler-Codes