# 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.