AP0.2: Auth, Tenant, Actor Foundation mit Sessions, TenantContext und Tests.
Deploy Development / deploy (push) Successful in 38s
Test Suite / pytest-backend (push) Failing after 7s
Test Suite / k6 /api/health Baseline (push) Has been skipped
Test Suite / playwright-smoke (push) Has been skipped
Test Suite / lint-backend (push) Successful in 2s
Test Suite / compose-smoke (push) Has been skipped

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
LarsandCursor committed 2026-07-04 20:09:54 +02:00
1 parent b5efdbbc2e
commit 564008be13
25 files changed
+1340 -3

No files matched your search

@@ -0,0 +1,121 @@
# AP0.1 – Abschlussbericht Projektgrundlage
**Status:** abgeschlossen
**Stand:** 2026-07-04
**Branch:** `develop` (`b5efdbb`) · Prod-Stand identisch (`main` `7b96bab`)
---
## Umgesetzt
| Anforderung (AP0.1) | Umsetzung |
|---------------------|-----------|
| Backend-Skeleton + FastAPI | `backend/main.py`, `backend/Dockerfile` |
| Health Endpoint `GET /api/health` | Liefert `status`, `app`, `db` (+ `version`, `schema`) |
| PostgreSQL-Anbindung | `backend/db.py`, Compose-Services |
| Docker Compose lokal | `docker-compose.dev-env.yml`, `docker-compose.yml` |
| Migrationsverzeichnis | `backend/migrations/` |
| Migration Runner + `schema_migrations` | `backend/run_migrations.py` |
| Erste Migration `001_init_core.sql` | `kairo_app_meta` (Schema-Phase AP0.1) |
| Testbasis | `backend/tests/` (pytest) |
| Frontend optional minimal | React/Vite-SPA + nginx-Proxy (`frontend/`) |
| Verzeichnisse `infra/`, `scripts/`, `tests/` | vorhanden |
| README „Local Development“ | `README.md` § Local Development |
| Kein Sprint-1-Fachscope | Keine Tenant/User/Actor-Logik, nur Meta-Tabelle |
**Zusätzlich (über AP0.1-Minimum, bewusst Sprint-0-Infrastruktur):**
- Gitea Actions: `deploy-dev.yml`, `deploy-prod.yml`, `test.yml`
- CI: pytest im Container, compose-smoke (PR), k6-Baseline, Playwright smoke
- Deployment-Doku: `docs/DEPLOYMENT.md`
- Dev/Prod auf Raspberry Pi (Ports 8097/3097 bzw. 8004/3004)
---
## Tests
### Unit / Integration (pytest)
| Test | Datei | Status |
|------|-------|--------|
| App importierbar | `test_health.py::test_app_importable` | ✓ |
| Health Endpoint | `test_health.py::test_health_endpoint` | ✓ |
| Runner findet Migrationen | `test_migrations.py::test_migration_runner_finds_migrations` | ✓ |
| Runner trägt Migration ein + idempotent | `test_migrations.py::test_migration_runner_is_idempotent` | ✓ |
| Core-Tabelle existiert | `test_migrations.py::test_core_table_exists` | ✓ |
### CI (Self-hosted Runner, Dev)
| Job | Status (2026-07-04) |
|-----|---------------------|
| pytest-backend | ✓ |
| k6 /api/health Baseline | ✓ (nach K6_CI-Anpassung) |
| playwright-smoke | ✓ |
| lint-backend | ✓ |
| compose-smoke | ✓ (PR, isolierte CI-Ports) |
### Prod
| Schritt | Status |
|---------|--------|
| Deploy Production (manueller Merge `develop` → `main`) | ✓ |
| Test Suite Prod-Trigger | Fix auf `develop` (`b5efdbb`): Push auf `main` startet Tests |
---
## Lokaler Start
```bash
git checkout develop
docker compose -f docker-compose.dev-env.yml up --build
curl http://localhost:8097/api/health
curl http://localhost:3097/api/health
docker compose -f docker-compose.dev-env.yml exec backend pip install -r requirements-dev.txt
docker compose -f docker-compose.dev-env.yml exec backend python -m pytest tests -ra -vv
```
Migrationen laufen beim Backend-Start automatisch (`run_migrations.main()` in `main.py`, überspringbar via `SKIP_DB_MIGRATE=1` für Tests).
---
## Offene Fragen
1. **Reverse Proxy** — Domains `kairo.jinkendo.de` / `dev.kairo.jinkendo.de` noch nicht eingerichtet; CI und Deploy nutzen localhost (bewusst ausreichend für AP0.1).
2. **Prod `.env`** — Muss auf dem Pi unter `/home/lars/docker/kairo/.env` mit sicherem `DB_PASSWORD` liegen (Deploy klont Repo, erzeugt `.env` nicht).
3. **README „Startzustand“** — Abschnitt oben in `README.md` beschreibt noch „kein Anwendungscode“; AP0.1-Tabelle unten ist aktuell — Kosmetik-Update empfohlen.
4. **`workflow_run`-Trigger** — In Gitea/act unzuverlässig; Prod-Tests hängen an Push `main` (Fix `b5efdbb`). Merge/Deploy bleibt manuell durch Product Owner.
---
## Abweichungen von der Spezifikation
| Spezifikation | Ist | Bewertung |
|---------------|-----|-----------|
| Health nur `status`, `app`, `db` | zusätzlich `version`, `schema` | Erweiterung, abwärtskompatibel |
| `db: "ok"` | auch `"error"` bei DB-Ausfall, dann `status: "degraded"` | sinnvoller Betriebszustand |
| Frontend optional | minimal umgesetzt (Health-Anzeige + nginx `/api`-Proxy) | im Scope |
| Offene Entscheidungen dokumentiert | in diesem Bericht + `docs/DEPLOYMENT.md`, kein separates ADR für AP0.1 | ausreichend für Abschluss |
Keine fachliche Sprint-1-Logik vorgezogen.
---
## Empfehlung für AP0.2
**Nächster Auftrag:** AP0.2 – Tenant, User, Actor (`Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md` § AP0.2)
Vorgehen:
1. Migration `002_tenant_user_actor.sql` — Tabellen laut Foundation, weiterhin ohne Vorhaben/Projekt-Domäne.
2. Seed für lokalen Admin-User (Dev only).
3. pytest für Migration + minimale Repository/Model-Schicht.
4. Health/version bei Schema-Bump (`DB_SCHEMA_VERSION` → `002`).
5. README-Startzustand bereinigen; optional Reverse Proxy parallel (nicht blockierend).
AP0.1 nicht erneut anfassen, außer README-Kosmetik oder Proxy-Wunsch.
---
*Erstellt im Rahmen Sprint 0 – AP0.1 Akzeptanz.*
@@ -0,0 +1,154 @@
# AP0.2 – Abschlussbericht Auth, Identity, Tenant & Actor Foundation
**Status:** abgeschlossen (Implementierung)
**Stand:** 2026-07-04
**Branch:** `develop` (noch nicht auf `main` gemergt)
---
## 1. Umgesetzte Dateien
| Datei | Zweck |
|-------|--------|
| `backend/migrations/002_auth_identity_tenant_actor.sql` | Schema User, Session, Tenant, Membership, Actor, Audit |
| `backend/auth.py` | bcrypt, Sessions, login/logout, `require_auth`, `require_portal_admin` |
| `backend/tenant_context.py` | `TenantContext`, `get_tenant_context`, `require_tenant_context` |
| `backend/bootstrap.py` | Env-basierter Admin/Tenant/ Actor-Seed |
| `backend/services/audit.py` | Audit-Log für Auth-Aktionen |
| `backend/services/actors.py` | Actor-Erzeugung + Human-Lookup |
| `backend/routers/auth.py` | Login/Logout |
| `backend/routers/me.py` | `/api/me`, `/api/me/context`, Tenant-Wechsel |
| `backend/main.py` | Router, Bootstrap nach Migrationen |
| `backend/tests/conftest.py` | DB-Fixtures |
| `backend/tests/factories.py` | Testdaten |
| `backend/tests/test_auth.py` | Login, Logout, Session, Context |
| `backend/tests/test_tenant_actor.py` | Actor-Typen, Rollen-Trennung |
| `backend/version.py` | `0.2.0-ap0.2`, Schema `002` |
| `docker-compose.dev-env.yml`, `docker-compose.yml` | Bootstrap/Session-Env |
| `.env.example`, `README.md` | Doku |
---
## 2. Neue Migrationen
- **`002_auth_identity_tenant_actor.sql`**
- `users` — E-Mail, bcrypt-Hash, `portal_role` (`user` \| `admin`)
- `sessions` — Token, `user_id`, `active_tenant_id`, Ablauf
- `tenants` — Slug, Name, aktiv
- `tenant_memberships` — `tenant_role` (`owner` \| `admin` \| `member`)
- `actors` — `human`, `agent`, `working_group`, `external_system`
- `audit_log` — Auth-Ereignisse
---
## 3. Neue Endpoints
| Endpoint | Methode | Auth |
|----------|---------|------|
| `/api/auth/login` | POST | — |
| `/api/auth/logout` | POST | `X-Auth-Token` |
| `/api/me` | GET | `X-Auth-Token` |
| `/api/me/context` | GET | `X-Auth-Token` |
| `/api/me/context/required` | GET | `X-Auth-Token` + aktiver Tenant |
| `/api/me/tenant` | POST | `X-Auth-Token` |
OpenAPI: `/api/docs` (Dev)
---
## 4. Auth-Fluss
```
POST /api/auth/login { email, password }
→ bcrypt verify
→ INSERT sessions (opaque token, expires_at, active_tenant_id = erste Membership)
→ audit: auth.login
→ Response: { token, expires_at, user }
Request mit Header X-Auth-Token
→ get_session(token) JOIN users
→ require_auth → session dict (user_id aus DB, nie aus Client-Header)
POST /api/auth/logout
→ DELETE session
→ audit: auth.logout
```
---
## 5. TenantContext-Auflösung
```
require_auth → session (user_id, active_tenant_id, portal_role, …)
→ tenant_memberships + tenants prüfen (nur aktive)
→ human actor: actors WHERE tenant_id + user_id + type=human
→ TenantContext(
portal_role, # Plattform
tenant_role, # Mandant
tenant_id/slug/name,
actor_id/type
)
```
Tenant-Wechsel: `POST /api/me/tenant` aktualisiert `sessions.active_tenant_id` nur bei gültiger Membership.
---
## 6. Tests und Testergebnis
| Testdatei | Abdeckung |
|-----------|-----------|
| `test_auth.py` | Login, Logout, Session ungültig, `/api/me`, Context, Tenant-Wechsel verweigert |
| `test_tenant_actor.py` | Human↔User, Agent/WG/External ohne User, Portal- vs. Tenant-Rolle |
| `test_migrations.py` | Migration 002 erkannt + idempotent |
Lokal ausführen (Backend-Container):
```bash
docker compose -f docker-compose.dev-env.yml exec backend pip install -r requirements-dev.txt
docker compose -f docker-compose.dev-env.yml exec backend python -m pytest tests -ra -vv
```
*(In dieser Session kein Docker lokal — Verifikation über CI nach Push auf `develop`.)*
---
## 7. Abweichungen von den Designprinzipien
| Prinzip | Abweichung | Begründung |
|---------|------------|------------|
| Mitai `profiles` | Kairo nutzt `users` | Klarere Trennung User ≠ Actor; kein Multi-Profil-Legacy |
| Legacy SHA256-Upgrade | nur bcrypt | Grüne Wiese AP0.2 |
| `require_auth_flexible` (Query-Token) | nicht implementiert | Nicht AP0.2-Scope; SSE/Download später |
| Account-Lifecycle-Gates | fehlen | AP0.3+ |
| Capabilities in TenantContext | leer / nicht modelliert | Bewusst Nicht-Scope |
Eingehalten: Server-Sessions, `X-Auth-Token`, `Depends(require_auth)` separat, user_id aus Session, Portal- vs. Tenant-Rolle getrennt, TenantContext als eigene Schicht.
---
## 8. Offene Entscheidungen
1. **Passwort-Policy / Rate-Limiting** für Login — noch nicht implementiert.
2. **Session-Invalidierung** bei Passwort-Reset (Feature kommt später).
3. **Tenant-Erstellung via API** — aktuell nur Bootstrap/DB; Admin-API in späterem AP.
4. **Frontend Auth-UI** — AP0.2 backend-only; SPA-Anbindung folgt.
5. **Prod-Bootstrap** — `KAIRO_BOOTSTRAP_*` in Prod `.env` setzen oder einmalig manuell seeden.
---
## 9. Empfehlung für AP0.3
Laut Foundation-Dokument ursprünglich „Capabilities & Rights Registry“ — der User-Auftrag kombinierte Auth+Tenant bereits in AP0.2.
**AP0.3 Vorschlag:**
- Capability/Rights Registry (DB + Sync)
- `require_capability()` Dependency
- TenantContext um `capabilities: list[str]` erweitern
- Keine Feature-Limits / Billing
- Optional: Frontend Login-Form + Token-Speicherung
---
*Erstellt im Rahmen Sprint 0 – AP0.2.*