Lars/Kairo-Jinkendo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
Kairo-Jinkendo/docs/sprints/Sprint0_AP0_7_Completion_Report_v0.2.md

343 lines
10 KiB
Markdown
Raw Permalink Normal View History

Doku AP0.7: Abschlussbericht v0.2 (final) mit DoD-Matrix und QA-Fix Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-05 08:14:28 +02:00
# AP0.7 – Abschlussbericht Tenant Hardening, Actor Directory & Data Layer Minimum
**Status:** abgeschlossen
**Stand:** 2026-07-05 (final)
**Branch:** `develop` · Dev-Deploy und Tests grün
**Version:** Backend `0.7.0-ap0.7` · Frontend `0.7.0-ap0.7` · Schema `006` (unverändert)
**Wesentliche Commits:** `db06af0` (Implementierung), `02b3b17` (Fix Überblick-Widget Overflow)
---
## 1. Scope und Einordnung
AP0.7 ist ein **Basis-Härtungsauftrag** — keine neuen großen Fachfeatures.
| Teil | Ziel | Status |
|------|------|--------|
| A | Tenant Hardening | ✓ Invarianten dokumentiert, Endpoints geprüft, Tests ergänzt |
| B | Actor Directory | ✓ `GET /api/actors`, ActorSelect mit echter Liste |
| C | Data Layer Minimum | ✓ `backend/data_layer/`, Workspace-Endpoints, Widget-Integration |
| D | Audit-Härtung | ✓ Bewertung — `actor_id`-Spalte bewusst zurückgestellt |
**Keine neue Migration** — Read-Models nutzen Schema `006`.
**Produktfrage beantwortet:** Kairo steht vor weiterem Fachausbau auf einer tenant-sicheren Basis mit Actor Directory und zentraler Read-Schicht.
---
## 2. Definition of Done — Prüfmatrix
### 2.1 AP0.7-Auftrag (Abnahmekriterien)
| Kriterium | Ergebnis | Nachweis |
|-----------|----------|----------|
| Tenant-Invarianten dokumentiert | ✓ | `Kairo_Tenant_Invariants_v0.1.md` |
| Fachliche Endpoints tenant-geprüft | ✓ | Code-Review Initiatives/Actions/Actors |
| Cross-Tenant-Tests | ✓ | `test_ap07.py`, `test_initiatives_actions.py` |
| `GET /api/actors` | ✓ | Router + 14 AP0.7-Tests |
| ActorSelect echte Liste | ✓ | `useActors()` + `/api/actors` |
| Maßnahmen Tenant-Actors zuweisbar | ✓ | Assignment-Tests + UI |
| Data Layer Minimum | ✓ | `backend/data_layer/` |
| Workspace Summary | ✓ | API + `WorkspaceSummaryWidget` |
| Blocked/Active zentral | ✓ | `/api/workspace/actions/*` |
| Actor Workload Basic | ✓ | API (kein UI-Widget) |
| Frontend nutzt Data Layer | ✓ | Widgets ohne Client-Aggregation |
| Keine großen Fachfeatures | ✓ | Read-only Erweiterung |
| AP0.6b UX erhalten | ✓ | Look & Feel unverändert |
| Tests grün | ✓ | pytest + Vitest 9/9 |
| README/Doku | ✓ | README, Tenant-Invarianten, dieser Bericht |
### 2.2 Scope Teil A–D
| Teil | Ergebnis |
|------|----------|
| A — Tenant Hardening | ✓ 10 Invarianten, keine neuen Leaks gefunden |
| B — Actor Directory | ✓ List + Detail, `kairo.actor.read` |
| C — Data Layer | ✓ 5 Read-Funktionen, 5 Workspace-Endpoints |
| D — Audit | ✓ `actor_id`-Spalte zurückgestellt, begründet |
### 2.3 Tests
| Test | Ergebnis | Nachweis |
|------|----------|----------|
| `test_ap07.py` | ✓ 14/14 | Actor, Workspace, Cross-Tenant, Capabilities |
| `test_rights_registry.py` | ✓ | 18 Capabilities |
| Vitest Frontend | ✓ 9/9 | Registry inkl. `workspace_summary` |
| `vite build` | ✓ | Production-Build |
| Manueller UI-Smoke | ✓ | User: Überblick-Overflow gemeldet → Fix verifiziert („ok“) |
### 2.4 Post-QA Bugfix
| Issue | Fix | Status |
|-------|-----|--------|
| Überblick-Widget: Kennzahlen ragen über Kartenrand | `02b3b17` — volle Grid-Breite, 2×2/4-Spalten responsive, `minmax(0,1fr)` | ✓ behoben, User bestätigt |
---
## 3. Umgesetzte Dateien
### Backend (neu)
| Datei | Zweck |
|-------|--------|
| `backend/data_layer/` | Read-Models: actions, initiatives, actors, workspace |
| `backend/routers/actors.py` | Actor Directory API |
| `backend/routers/workspace.py` | Workspace Read API |
| `backend/rights_registrations/workspace_ops.py` | `kairo.actor.read`, `kairo.workspace.read` |
| `backend/tests/test_ap07.py` | 14 AP0.7-Tests |
### Backend (geändert)
| Datei | Änderung |
|-------|----------|
| `backend/services/actors.py` | `list_actors`, `get_actor` |
| `backend/routers/actions.py` | `/me/open` → Data Layer |
| `backend/main.py` | Router actors + workspace |
| `backend/version.py` | `0.7.0-ap0.7` |
### Frontend (neu/geändert)
| Datei | Zweck |
|-------|--------|
| `frontend/src/api/workspace.js` | Workspace API-Client |
| `frontend/src/hooks/useActors.js` | Actor Directory + Fallback |
| `frontend/src/widgets/WorkspaceSummaryWidget.jsx` | Überblick-Karte |
| Widgets, `ActorSelect`, `ActionForm`, `InitiativeDetailPage` | Data Layer + echte Actors |
| `frontend/src/styles/pages.css` | Summary-Metrics (Post-QA-Fix) |
### Doku
| Datei | Zweck |
|-------|--------|
| `docs/architecture/Kairo_Tenant_Invariants_v0.1.md` | Mandanten-Invarianten |
| `README.md` | AP0.7 API, Capabilities, Smoke-Test |
---
## 4. Tenant Hardening
**Ergebnis:** AP0.5-Services waren bereits tenant-sicher (`tenant_id` aus Context, Queries gefiltert, Cross-Tenant → 404).
**AP0.7 ergänzt:** Actor-Directory-Isolation, Workspace-Data-Layer-Tests, verbindliche Invarianten-Doku.
**Gefundene Mandantenrisiken:** Keine neuen Lücken. Actor-Zuweisungen weiter über `_actor_in_tenant()`.
---
## 5. Tenant-Invarianten
10 verbindliche Invarianten in `docs/architecture/Kairo_Tenant_Invariants_v0.1.md`:
1. Fachliche Tabellen mit `tenant_id`
2. `tenant_id` aus TenantContext
3. Queries filtern nach `tenant_id`
4. Fremde IDs → 404
5. Assignments tenant-intern
6. User ≠ Actor
7. Actors tenant-scoped
8. Audit mit `tenant_id`
9. Neue Tabellen: Tenant-Entscheidung
10. Router delegieren an Services/Data Layer
---
## 6. Actor Directory
| Endpoint | Capability | Verhalten |
|----------|------------|-----------|
| `GET /api/actors` | `kairo.actor.read` | Aktive Tenant-Actors; Filter `actor_type`, `q`, `include_inactive` |
| `GET /api/actors/{id}` | `kairo.actor.read` | Detail; Cross-Tenant → 404 |
Response: `{ id, name, actor_type, is_active }` — **ohne** `user_id`.
**Grants `kairo.actor.read`:** Portal Admin/User, Tenant Owner/Admin/Member — für Assignment-UI und Workload für alle operativen Mitglieder.
---
## 7. ActorSelect / Assignment UX
- `useActors()` lädt `/api/actors`
- Mehrfachauswahl, Typ-Labels (Mensch, Agent, …)
- Fallback auf Human Actor bei API-Fehler
- Loading/Error/Empty States
- Agents/Working Groups aus dem Tenant zuweisbar
---
## 8. Data Layer Struktur
```text
backend/data_layer/
actions.py — get_my_open_actions, get_my_blocked_actions
initiatives.py — get_active_initiatives
actors.py — get_actor_workload
workspace.py — get_workspace_summary
```
| Schicht | Verantwortung |
|---------|---------------|
| Router | HTTP, Capability-Gates |
| Data Layer | Read-Aggregation, tenant-scoped |
| Services | Write/CRUD, Audit |
---
## 9. Workspace Summary
`GET /api/workspace/summary`:
```json
{
"open_actions_count": 0,
"blocked_actions_count": 0,
"active_initiatives_count": 0,
"done_actions_recent_count": 0
}
```
- Personal (current actor): open, blocked, done (7 Tage)
- Tenant-weit: aktive/pausierte Vorhaben
Frontend: `WorkspaceSummaryWidget` — volle Grid-Breite, responsive 2×2 / 4 Spalten.
---
## 10. Actor Workload Basic
`GET /api/workspace/actors/workload` — Counts pro Actor (open, blocked, in_progress).
**Nur API** — kein UI-Widget in AP0.7 (bewusst für AP0.8).
---
## 11. Neue/geänderte API-Endpunkte
| Endpoint | Methode | Capability |
|----------|---------|------------|
| `/api/actors` | GET | `kairo.actor.read` |
| `/api/actors/{id}` | GET | `kairo.actor.read` |
| `/api/workspace/summary` | GET | `kairo.workspace.read` |
| `/api/workspace/actions/open` | GET | `kairo.workspace.read` |
| `/api/workspace/actions/blocked` | GET | `kairo.workspace.read` |
| `/api/workspace/initiatives/active` | GET | `kairo.workspace.read` |
| `/api/workspace/actors/workload` | GET | `kairo.workspace.read` |
---
## 12. Capability-Nutzung
| Capability | Neu | Grants |
|------------|-----|--------|
| `kairo.actor.read` | ✓ | Member+ |
| `kairo.workspace.read` | ✓ | Member+ |
Gesamt: **18 Capabilities** (vorher 16). Kein separates `kairo.workspace.metrics.read`.
---
## 13. Audit-Härtung / actor_id-Bewertung
| Frage | Antwort |
|-------|---------|
| `actor_id` als Spalte jetzt? | **Nein** — Migration 007 + Backfill → AP0.8 |
| Reicht `details`? | ✓ für Assignments (`actor_ids`) |
| Risiko | Gering für Sprint 0 |
---
## 14. Frontend-Integration
| Widget | Datenquelle (nach AP0.7) |
|--------|--------------------------|
| WorkspaceSummaryWidget | `/api/workspace/summary` |
| MyOpenActionsWidget | `/api/workspace/actions/open` |
| BlockedActionsWidget | `/api/workspace/actions/blocked` |
| InitiativesWidget | `/api/workspace/initiatives/active?limit=5` |
| ActorSelect | `/api/actors` |
**Keine fachliche KPI-Berechnung in Widgets.**
---
## 15. Übernommene Muster aus Mitai
- Zentrale Data-Layer-Schicht
- Widgets konsumieren vorbereitete Daten
- Trennung Rohdaten / Kennzahlen / UI
---
## 16. Übernommene Muster aus Shinkan
- Tenant-sichere Queries
- Capability Gates
- Cross-Tenant → 404
- Access-Layer-Denken
---
## 17. Bewusst nicht übernommene Muster
- Analytics-Plattform, Forecasting, KI
- Actor-Admin-UI
- `audit_log.actor_id` Migration
- Backend-Widget-Registry
- Actor Workload UI-Widget
---
## 18. Abweichungen von der Spezifikation
| Thema | Abweichung | Begründung |
|-------|------------|------------|
| Actor Workload | nur API | UI in AP0.8 |
| `/api/actions/me/open` | beibehalten | Abwärtskompatibilität |
| `done_actions_recent_count` | 7-Tage-Fenster | pragmatisch via `updated_at` |
---
## 19. Offene Entscheidungen
1. `audit_log.actor_id` — Migration AP0.8?
2. Actor Workload Widget — wann sichtbar?
3. Initiative bearbeiten in UI — PATCH existiert
4. Foundation Audit/Admin-UI — backlog
---
## 20. Empfehlung für AP0.8
1. **Audit/Admin minimal** — Audit-Log lesbar, optional `actor_id`-Spalte
2. **Actor Workload Widget** — kleine Karte im Workspace
3. **Initiative bearbeiten in UI**
4. **Kommentare pro Maßnahme** (optional)
Danach Sprint-1-Fachscope gemäß Product Spec.
---
## Manueller Smoke-Test (Referenz)
1. Login → Workspace → **Überblick** mit 4 Kennzahlen, kein Overflow
2. Offene / blockierte Maßnahmen in separaten Widgets
3. Vorhaben-Detail → Maßnahme anlegen → **mehrere Actors** in ActorSelect
4. Agent zuweisen → speichern → Assignment sichtbar
5. Status blocked → erscheint nur im Blockiert-Widget
6. API: `curl /api/actors`, `/api/workspace/summary` mit Token
---
## Abnahme-Checkliste AP0.7 (final)
| Kriterium | Erfüllt |
|-----------|---------|
| Tenant-Invarianten | ✓ |
| Actor Directory | ✓ |
| Data Layer | ✓ |
| Workspace Summary | ✓ |
| Frontend Integration | ✓ |
| Tests grün | ✓ |
| AP0.6b UX | ✓ |
| Post-QA Überblick-Fix | ✓ |
Reference in New Issue Copy Permalink