CIRS – Critical Incident Reporting System

Ein schlankes Meldesystem für Vorfälle/Beinaheereignisse mit FastAPI + PostgreSQL im Backend und React + Vite + MUI im Frontend. Enthält Audit-Trail mit Hashkette, Rollen (Reporter/Reviewer/Admin), Kommentare, Zuweisungen, Watcher, Bulk-Aktionen, KPI-Dashboard und (optional) SSO-Hooks.

Inhalt

• Features
• Technik-Stack
• Schnellstart (Docker Compose)
• Logins & Rollen
• Frontend (lokal entwickeln)
• Backend (lokal entwickeln)
• Konfiguration
• Wichtigste Routen
• Audit-Log & Verifikation
• Dashboard
• Troubleshooting
• Lizenz

Features

Meldungen/Incidents

• Anlegen (auch anonym), Anhänge, Kategorien/Schweregrade
• Status-Workflow: draft → submitted → under_review → closed (+ reopened)
• Zuweisung an Bearbeiter, Watcher (Beobachter)
• Kommentare
• Bulk-Aktionen (Status/Assign)
• PDF-Export pro Incident

Audit

• Audit-Tabelle (Aktionen, Nutzer, Zeitpunkt, Details)
• Hashkette pro Eintrag (Veränderung erkennbar)
• Verifikation per /audit/verify

Dashboard

• KPIs: Gesamtmeldungen, offene Meldungen, Ø/Tag
• Zeitbereich 7/30/90/Custom
• Top-Kategorien/Schweregrade
• „Zuletzt aktiv“ Liste
• Click-Through in die gefilterte Incidents-Liste

Rollen & Rechte

• Reporter: melden & eigene Vorgänge einsehen
• Reviewer: zusätzlich Audit-Ansicht, Bulk, SLA-Konfig
• Admin: Benutzerverwaltung (im Backend vorhanden)

SLA (Service Level Agreement - erlaubte Zeitspanne bis zur Aktion)

• Konfiguration in Stunden
• UI zeigt „> SLA“ (überschritten) / „ok“
• Vearbeitung eines Incidents sollte innerhalv dieser Zeit angefangen werden

Technik-Stack

• Frontend: React 18, Vite, MUI (Material UI), React Router
• Backend: FastAPI, SQLAlchemy/SQLModel, Alembic
• DB: PostgreSQL
• Sonstiges: ClamAV (Dateiscans), MkDocs (optional Doku)
• Container: Docker Compose

Quickstart (Docker Compose)

Voraussetzungen: Docker & Docker Compose

# Projektverzeichnis
docker compose up
# oder im Hintergrund:
# docker compose up -d

Frontend: http://localhost:5173/

Backend (API & Swagger): http://localhost:8000/ und http://localhost:8000/docs

PostgreSQL: läuft als Container db

(Optional) Doku: eigener Container, intern erreichbar

Das Backend legt beim Start einen Bootstrap-Admin an (siehe Log).

Logins & Rollen

Standard-Zugang (Dev):

• Benutzername: admin
• Passwort: admin
• Rolle: admin

Nach erfolgreichem Login wirst du zum Dashboard geleitet. Von dort gelangst du in Ereignisse (Incidents) und Audit.

Frontend

Frontend (lokal entwickeln)

Das Frontend läuft bereits im Container (Vite, Port 5173). Falls du außerhalb von Docker entwickeln willst:

cd frontend 
npm i
npm run dev

Wichtige Dateien:

• src/main.jsx – App-Shell, Router, Theme
• src/auth.js – Auth-Context (Provider + Hook)
• src/pages/Dashboard.jsx – KPI-Dashboard
• src/pages/Incidents.jsx – Liste + klassisches Popup (Dialog) für Details/Kommentar/Assign/Watcher
• src/pages/Audit.jsx – Audit-Listen + Incident-Timeline
• src/components/KpiCard.jsx – KPI Karte

Backend

Das Backend läuft im Container auf Port 8000. Lokal (ohne Docker) kannst du so starten:

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# .env setzen (siehe Konfiguration)
# z.B. CRIS_DB_URL=postgresql+psycopg2://cirs:cirs@localhost:5432/cirs

alembic upgrade head
uvicorn app.main:app --reload --port 8000

Swagger/OpenAPI: http://localhost:8000/docs mkDocs: http://localhost:8001

Konfiguration

Frontend

• VITE_API_URL – Basis-URL der API (Default: http://localhost:8000)

Backend (Umgebungsvariablen)

• CRIS_DB_URL – PostgreSQL-URL
• Default: postgresql+psycopg2://cirs:cirs@db:5432/cirs
• CORS-Ursprünge – Im FastAPI-App-Setup konfiguriert (Frontend-Origin freigeben)
• JWT/Secrets – Teil der Auth-Konfiguration (im Projekt enthalten)

Wichtigste Routen Frontend (React Router)

• /dashboard – KPI-Übersicht
• /incidents – Liste, Filter, Bulk; Detail-Popup via Klick
• ?status=open → interpretiert submitted/under_review/reopened
• ?create=1 → Formular „Jetzt melden“ öffnen (wenn vorhanden)
• /audit – Audit-Logs & Timeline (nur Reviewer/Admin)
• /login, /register, /sso-start, /sso-callback

Backend (Auswahl)

• POST /auth/login, GET /auth/me, GET /auth/users
• GET /incidents (Filter, Sortierung, Paging)
• GET /incidents/{id}, POST /incidents (Erstellen)
• POST /incidents/{id}/status?status=closed|under_review|…
• POST /incidents/{id}/assign?user_id=…
• GET/POST /incidents/{id}/comments
• GET/POST/DELETE /incidents/{id}/watchers
• POST /incidents/bulk/status, POST /incidents/bulk/assign
• GET /incidents/{id}/export/pdf
• GET /incidents/stats/summary?days=30 (Dashboard-KPIs)
• GET /config/sla, POST /config/sla?sla_hours=48
• GET /audit (paged), GET /audit/incident/{id} (Timeline), GET /audit/verify
• 403 auf /audit/*? → Dein Nutzer braucht Rolle reviewer oder admin.

Dashboard

• Zeitbereich-Umschalter (7/30/90/Custom)
• KPIs inkl. optionaler Deltas (wenn Backend previous_total/previous_open liefert)
• Top-Kategorien/Schweregrade (einfache Balken)
• „Zuletzt aktiv“ (neueste 5)
• Karten sind klickbar → führen in die passende gefilterte Incidents-Liste