From 1b44bb3d10f769d2f8eca96efc9e2f3fe78a52c5 Mon Sep 17 00:00:00 2001
From: "XPS\\Micro" <Rainer Wieland>
Date: Sat, 31 Jan 2026 07:06:13 +0100
Subject: [PATCH] Update documentation for v0.3.0 (admin features)

- CHANGELOG.md: Add v0.3.0 with admin dashboard, email verification,
  user states, and all new features
- install/README.md: Add SMTP configuration variables
- README.md: Update version to 0.3.0

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/README.md             |  2 +-
 docs/install/README.md     | 14 +++++++++
 docs/versions/CHANGELOG.md | 60 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 75 insertions(+), 1 deletion(-)

diff --git a/docs/README.md b/docs/README.md
index 62af5a3..c0ae87c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -40,5 +40,5 @@ Willkommen zur Dokumentation des Container Spawner Projekts.
 
 ---
 
-**Aktuelle Version**: 0.1.0
+**Aktuelle Version**: 0.3.0
 **Letzte Aktualisierung**: Januar 2026
diff --git a/docs/install/README.md b/docs/install/README.md
index a5276d7..d9b7a71 100644
--- a/docs/install/README.md
+++ b/docs/install/README.md
@@ -169,6 +169,20 @@ docker-compose up -d
 | `JWT_ACCESS_TOKEN_EXPIRES` | `3600` | JWT Token Gueltigkeitsdauer (Sekunden) |
 | `CONTAINER_IDLE_TIMEOUT` | `3600` | Timeout in Sekunden (noch nicht implementiert) |
 
+### Email/SMTP-Variablen (fuer Verifizierung)
+
+| Variable | Standard | Beschreibung |
+|----------|----------|--------------|
+| `SMTP_HOST` | `localhost` | SMTP-Server Hostname |
+| `SMTP_PORT` | `587` | SMTP-Server Port |
+| `SMTP_USER` | `` | SMTP-Benutzername |
+| `SMTP_PASSWORD` | `` | SMTP-Passwort |
+| `SMTP_FROM` | `noreply@localhost` | Absender-Email-Adresse |
+| `SMTP_USE_TLS` | `true` | TLS verwenden (true/false) |
+| `FRONTEND_URL` | `http://localhost:3000` | Frontend-URL fuer Email-Links |
+
+**Hinweis**: Die Email-Konfiguration wird fuer die Email-Verifizierung bei der Registrierung und fuer Passwort-Reset-Emails benoetigt.
+
 ### User-Templates
 
 Es stehen zwei Templates fuer User-Container zur Verfuegung:
diff --git a/docs/versions/CHANGELOG.md b/docs/versions/CHANGELOG.md
index a646d46..28c3a57 100644
--- a/docs/versions/CHANGELOG.md
+++ b/docs/versions/CHANGELOG.md
@@ -19,6 +19,66 @@ Das Format basiert auf [Keep a Changelog](https://keepachangelog.com/de/1.0.0/).
 
 ---
 
+## [0.3.0] - 2026-01-31
+
+### Hinzugefuegt
+- **Admin-Dashboard**: Vollstaendige Benutzerverwaltung fuer Admins
+  - Benutzer sperren/entsperren
+  - Passwoerter zuruecksetzen (sendet Email)
+  - Benutzer-Container loeschen
+  - Benutzer loeschen
+  - Verifizierungs-Emails erneut senden
+- **Email-Verifizierung**: Neue Benutzer muessen Email bestaetigen
+  - Verifizierungs-Email bei Registrierung
+  - OneTimeToken-basierte Verifizierung
+  - verify-success und verify-error Seiten
+- **Erster User wird Admin**: Der erste registrierte Benutzer erhaelt Admin-Rechte
+- **Benutzer-States**: registered → verified → active
+- **Aktivitaetstracking**: `last_used` Feld fuer letzten Container-Zugriff
+- **Farbcodierte Benutzerliste** im Admin-Dashboard:
+  - Gruen: Aktiv, kuerzlich genutzt
+  - Gelb: Warnung (unverifiziert/inaktiv)
+  - Rot: Kritisch (lange unverifiziert/sehr lange inaktiv)
+- **SMTP-Konfiguration**: Email-Versand fuer Verifizierung und Passwort-Reset
+- **Admin-API Endpoints**:
+  - `GET /api/admin/users` - Alle Benutzer auflisten
+  - `POST /api/admin/users/{id}/block` - Benutzer sperren
+  - `POST /api/admin/users/{id}/unblock` - Benutzer entsperren
+  - `POST /api/admin/users/{id}/reset-password` - Passwort zuruecksetzen
+  - `POST /api/admin/users/{id}/resend-verification` - Verifizierungs-Email senden
+  - `DELETE /api/admin/users/{id}/container` - Container loeschen
+  - `DELETE /api/admin/users/{id}` - Benutzer loeschen
+  - `POST /api/admin/users/{id}/takeover` - Container-Zugriff (Dummy, Phase 2)
+- **Neue Backend-Dateien**:
+  - `admin_api.py` - Admin-Blueprint mit Endpoints
+  - `decorators.py` - @admin_required und @verified_required Decorator
+  - `email_service.py` - Email-Versand-Service
+- **Neue Frontend-Seiten**:
+  - `/admin` - Admin-Dashboard
+  - `/verify-success` - Email-Verifizierung erfolgreich
+  - `/verify-error` - Email-Verifizierung fehlgeschlagen
+
+### Geaendert
+- `models.py`: Neue Felder (is_admin, is_blocked, state, last_used, verification_token), UserState Enum, AdminTakeoverSession Model
+- `config.py`: SMTP-Konfiguration, FRONTEND_URL
+- `api.py`: Signup sendet Verifizierungs-Email (kein Auto-Login mehr), Login prueft Blockade und Verifizierung
+- `app.py`: Admin-Blueprint registriert
+- `.env.example`: SMTP-Variablen hinzugefuegt
+- Frontend `api.ts`: Admin-API-Funktionen
+- Frontend `use-auth.tsx`: User-Interface mit is_admin und state
+- Frontend `signup/page.tsx`: Zeigt Verifizierungs-Hinweise nach Registrierung
+- Frontend `login/page.tsx`: Option zum erneuten Senden der Verifizierungs-Email
+- Frontend `dashboard/page.tsx`: Admin-Link fuer Admins
+
+### Sicherheit
+- Blockierte Benutzer koennen sich nicht mehr anmelden
+- Unverifizierte Benutzer koennen sich nicht anmelden
+- Admins koennen sich nicht selbst sperren oder loeschen
+- Admins koennen andere Admins nicht loeschen
+- Verification-Token ist einmalig verwendbar (OneTimeToken)
+
+---
+
 ## [0.2.0] - 2026-01-31
 
 ### Hinzugefuegt