bump

docs/admin.md

@@ -0,0 +1,121 @@
+# Adminbereich
+
+Der Adminbereich liegt im Frontend unter `/admin` und verwendet dieselbe
+serverseitige Authentifizierung, CSRF-Pruefung und Permission-Logik wie die
+restliche Anwendung. Angular blendet Navigation und Aktionen nur fuer passende
+Permissions ein; verbindlich prueft immer das Backend.
+
+## Permissions
+
+Die administrativen Permissions sind fest in
+`apps/backend/src/roles/permissions.ts` definiert:
+
+- `users.read`: Benutzer anzeigen, suchen und filtern
+- `users.manage`: Benutzer aktivieren, deaktivieren und Rollen zuweisen
+- `roles.read`: Rollen und Permissions anzeigen
+- `roles.manage`: Rollen anlegen, bearbeiten und loeschen
+- `sessions.manage`: Sessions anderer Benutzer anzeigen und beenden
+- `audit.read`: administratives Audit-Log anzeigen
+
+Benutzer haben keine direkten Permissions. Effektive Permissions werden aus
+allen Rollen abgeleitet. Rollen- und Benutzerverwaltung laufen ueber Services;
+Controller greifen nicht direkt auf TypeORM-Repositories zu.
+
+## Systemrollen
+
+Es gibt mindestens die Systemrollen `admin` und `user`.
+
+- `admin` ist geschuetzt, nicht loeschbar und muss administrative Permissions
+  behalten.
+- `user` ist geschuetzt, nicht loeschbar und Standardrolle fuer neue Benutzer.
+- Eigene Rollen koennen angelegt, umbenannt, geloescht und mit bekannten
+  Permissions versehen werden.
+
+Eine Rolle kann nur geloescht werden, wenn sie keinem Benutzer mehr zugewiesen
+ist. Andernfalls antwortet die API mit `ROLE_STILL_ASSIGNED`.
+
+## Letzter aktiver Administrator
+
+Die Anwendung darf nie ohne aktiven Administrator enden. Sicherheitskritische
+Aktionen laufen transaktional und halten einen MySQL-Lock
+`business_app_admin_integrity`:
+
+- Benutzer deaktivieren
+- Rollen eines Benutzers aendern
+- Adminrolle entfernen
+- Adminrolle in ihren Permissions veraendern
+- Rolle loeschen
+
+Wenn eine Aktion den letzten aktiven Administrator entfernen wuerde, antwortet
+die API mit HTTP 409 und `LAST_ACTIVE_ADMIN_REQUIRED`.
+
+## Benutzerstatus und Sessions
+
+Benutzer werden weiterhin ausschliesslich ueber OIDC angelegt. Name und E-Mail
+kommen vom Identity Provider und sind im Adminbereich nicht editierbar.
+
+Beim Deaktivieren wird der Benutzer sofort inaktiv gesetzt und alle aktiven
+Sessions des Benutzers werden widerrufen. Neue OIDC-Logins deaktivierter Benutzer
+werden trotz erfolgreicher IdP-Authentifizierung abgewiesen. Beim erneuten
+Aktivieren darf sich der Benutzer wieder anmelden; alte Sessions werden nicht
+wiederhergestellt.
+
+Admin-Session-Endpunkte geben nur eine sichere, gekuerzte Session-Referenz,
+Zeitpunkte, User-Agent, IP-Annaeherung und Status zurueck. Tokens und rohe
+Session-Secrets werden nie ausgegeben.
+
+## API-Endpunkte
+
+Benutzer:
+
+- `GET /api/admin/users`
+- `GET /api/admin/users/:id`
+- `PATCH /api/admin/users/:id/deactivate`
+- `PATCH /api/admin/users/:id/activate`
+- `POST /api/admin/users/:id/roles/:roleId`
+- `DELETE /api/admin/users/:id/roles/:roleId`
+- `GET /api/admin/users/:id/sessions`
+- `DELETE /api/admin/users/:userId/sessions/:sessionId`
+- `DELETE /api/admin/users/:id/sessions`
+
+Rollen:
+
+- `GET /api/admin/roles`
+- `GET /api/admin/roles/:id`
+- `POST /api/admin/roles`
+- `PUT /api/admin/roles/:id`
+- `DELETE /api/admin/roles/:id`
+
+Audit:
+
+- `GET /api/audit-log`
+
+## Audit-Log
+
+Administrative Aenderungen werden auditierbar protokolliert, darunter:
+
+- `USER_ACTIVATED`
+- `USER_DEACTIVATED`
+- `USER_ROLE_ASSIGNED`
+- `USER_ROLE_REMOVED`
+- `ROLE_CREATED`
+- `ROLE_UPDATED`
+- `ROLE_DELETED`
+- `ROLE_PERMISSIONS_UPDATED`
+- `SESSION_REVOKED`
+- `ALL_USER_SESSIONS_REVOKED`
+
+Gespeichert werden fachliche IDs, Request-ID und minimale Metadaten. Tokens,
+Secrets und vollstaendige Sessiondaten werden nicht geloggt.
+
+## Migration
+
+Die Admin-Erweiterung fuegt `roles.description` hinzu. Vor dem Deployment muss
+die Migration ausgefuehrt werden:
+
+```bash
+npm run migration:run
+```
+
+Der normale App-Start fuehrt Migrationen weiterhin nicht automatisch aus,
+sondern meldet fehlende Migrationen ueber die Readiness-Pruefung.