# ITSM — Technische Architektur

Stand: 2026-07-15 (Rust-Rewrite, Version 1.0). Verbindliche Entscheidungen: siehe `docs/adr/`.

## 1. Überblick

Mandantenfähige ITSM-Plattform (Tickets, Service-Katalog, Wissensdatenbank, CMDB)
als einzelnes Rust-Binary mit PostgreSQL. AES ist ein buchbarer Service im
Katalog (HTTP-Integration, kein Code-Import). Repo-Bearbeitung aus Tickets
läuft über die Gitea-kompatible Forge-Contents-API.

    Browser ──HTTP──► itsm (axum, Port 8090) ──► PostgreSQL 16
                          │
                          ├──► AES-Dashboard (Erreichbarkeits-Check, Katalog)
                          └──► Forge-API (Repo-Edit aus Change-Tickets)

## 2. Modulstruktur (src/)

| Modul | Verantwortung |
|---|---|
| `main.rs` | App-Aufbau, Routing, Retention-Hintergrundtask |
| `config.rs` | ENV-Konfiguration + Startvalidierung |
| `web.rs` | AppState, Middleware (Session, CSRF, Client-IP, Security-Header), Fehlertyp, RBAC-Helfer, PageCtx |
| `db.rs` | Datenzugriff (deadpool/tokio-postgres), alle Queries parametrisiert und tenant-gescoped |
| `security.rs` | Passwort-Hashing/-Verifikation (Argon2id + Werkzeug pbkdf2/scrypt), Token, Policy, SSRF-Guard |
| `itil.rs` | ITIL-Logik: Rollen, Statusmodell, Prioritätsmatrix, Change-Gate (reine Funktionen, unit-getestet) |
| `auth.rs` | Login (Rate-Limit, Rehash-Migration), Logout, Ersteinrichtung |
| `tickets.rs` | Listen/KPIs/Sparklines, Ticket-API, Statuswechsel, Change-Freigabe, Problem/CI-Links, Repo-Edit, Kanban |
| `services.rs` | Service-Katalog, paralleler Erreichbarkeits-Check (30 s Cache) |
| `kb.rs` | Wissensdatenbank inkl. Freigabe-Workflow |
| `cmdb.rs` | Configuration Items + Beziehungen |
| `admin.rs` | Mandanten-Einstellungen, Audit-Ansicht, Benutzerverwaltung |
| `dashboard.rs` | CSI-Kennzahlen (SLA-Erfüllung, MTTR, Verteilungen) |
| `forge.rs` | Forge-Contents-Client (get/update, Sha-Locking) |

Frontend: Askama-Templates (`templates/`), ein statisches CSS + ein JS
(`static/`), kein Framework, kein Inline-JS (CSP).

## 3. Request-Fluss

1. `ctx_middleware` (web.rs): Session-Cookie → SHA-256 → DB-Lookup (`sessions`
   JOIN `users`/`tenants`) → `AuthUser` in Request-Extensions. Client-IP nur
   aus X-Forwarded-For, wenn `ITSM_TRUSTED_PROXY_COUNT > 0`.
2. CSRF: jede zustandsändernde Methode braucht Token aus Session (Formular-
   Feld `_csrf` oder Header `X-CSRF-Token`); Ausnahmen: `/login`, `/setup/new`.
3. Handler: RBAC-Check (`need_auth`/`need_operative`/`need_admin`/
   `need_change_approver`) → Fachlogik → Audit-Log-Eintrag.
4. Antwort: Security-Header (CSP, nosniff, X-Frame-Options DENY, Referrer-
   Policy, HSTS bei `ITSM_HTTPS=1`).

## 4. Datenmodell (PostgreSQL, schema.sql)

Alle fachlichen Tabellen tragen `tenant_id`; jede Query filtert darauf.

- `tenants` — Mandanten inkl. SLA-Defaults + DSGVO-Retention-Fristen
- `users` — global eindeutige E-Mail (Login löst Mandant auf), `role`
  (admin/change_manager/agent/user), `auth_source` ('local', 'ldap' reserviert)
- `tickets` — inkl. ITIL-Feldern: `impact`/`urgency` (Priorität via Matrix),
  `change_typ`/`approval_status`/`approved_by/-_at` (Change Enablement),
  `problem_id`/`known_error` (Problem Mgmt), `first_response_at`/`resolved_at`/
  `closed_at` (SLA-Zeitstempel)
- `ticket_timeline` — Worklog (Status, Kommentare, Repo-Edits: dokumentationspflichtig)
- `ticket_ci_links` — Ticket↔CI (SACM)
- `services`, `kb_articles` (mit `status` Entwurf/Freigegeben),
  `configuration_items` + `ci_relationships`
- `audit_log` — alle sicherheitsrelevanten Aktionen (ISO 27001 A.12.4 / DSGVO Art. 30)
- `login_attempts` — Rate-Limit-Basis (7 Tage aufbewahrt)
- `sessions` — serverseitige Sessions, nur SHA-256-Hash des Cookie-Tokens

Migrationen: idempotenter Block am Ende von `schema.sql`, wird bei jedem
App-Start per `include_str!` ausgeführt (ADR-005).

## 5. RBAC-Matrix

| Aktion | admin | change_manager | agent | user |
|---|---|---|---|---|
| Eigene Tickets (Incident/Service Request) anlegen/sehen | ✓ | ✓ | ✓ | ✓ |
| Alle Tickets sehen/bearbeiten, Status wechseln | ✓ | ✓ | ✓ | – |
| Probleme/Änderungen/Releases/Kanban/CMDB | ✓ | ✓ | ✓ | – |
| KB lesen | alle | alle | alle | nur Freigegeben |
| KB anlegen/bearbeiten | ✓ | ✓ | ✓ | – |
| KB freigeben, Change-Freigabe (CAB) | ✓ | ✓ | – | – |
| Repo-Edit aus Ticket (nur umsetzbarer Change) | ✓ | ✓ | – | – |
| Services anlegen, Administration, Audit-Log | ✓ | – | – | – |

## 6. ITIL-Abbildung (v3-Prozesse / v4-Practices)

- Statusmodell: Offen → In Bearbeitung → Warten → Gelöst → Geschlossen;
  Reopen Gelöst→Offen; Geschlossen final. Übergänge serverseitig erzwungen.
- Priorität = Matrix(Impact × Urgency), 3×3 nach v3 SO 4.2.5.4.
- Change Enablement: Standard (vorautorisiert) / Normal (CAB) / Emergency
  (sofort, nachträgliche ECAB-Freigabe). Umsetzung + Repo-Edit erst wenn
  `itil::change_may_be_implemented`.
- Problem Management: Incident↔Problem-Verknüpfung, Known-Error-Flag.
- SLA: Fristen aus Mandanten-Defaults, Zeitstempel bei Statuswechseln,
  Überfälligkeits- und Restzeit-Berechnung serverseitig.
- Continual Improvement: /dashboard (SLA-Erfüllung 30 T, MTTR, Verteilungen).

## 7. Sicherheitsarchitektur

Siehe ADR-002/003/007/008 und README-Abschnitt "Sicherheit". Kurzfassung:
serverseitige widerrufbare Sessions, CSRF überall, DB-gestütztes Login-Rate-
Limit (E-Mail+IP), Argon2id mit transparenter Migration von Werkzeug-pbkdf2
UND -scrypt (ADR-003!), SSRF-Guard, CSP ohne Inline-JS, Audit-Log.