Doku AP0.5: ADP Scope-Verschiebung, MIGRATIONS 006, Abschlussbericht v0.2.
Deploy Development / deploy (push) Successful in 33s
Test Suite / pytest-backend (push) Successful in 29s
Test Suite / lint-backend (push) Successful in 2s
Test Suite / compose-smoke (push) Has been skipped
Test Suite / k6 /api/health Baseline (push) Successful in 18s
Test Suite / playwright-smoke (push) Successful in 12s
Deploy Development / deploy (push) Successful in 33s
Test Suite / pytest-backend (push) Successful in 29s
Test Suite / lint-backend (push) Successful in 2s
Test Suite / compose-smoke (push) Has been skipped
Test Suite / k6 /api/health Baseline (push) Successful in 18s
Test Suite / playwright-smoke (push) Successful in 12s
This commit is contained in:
1 parent
a34a61458e
commit
802c9259dc
3 files changed
+418
-1
No files matched your search
@@ -0,0 +1,316 @@
|
||||
# AP0.5 – Abschlussbericht Minimaler Vorhaben- und Maßnahmen-Slice
|
||||
|
||||
**Status:** abgeschlossen
|
||||
**Stand:** 2026-07-05 (final)
|
||||
**Branch:** `develop` · Dev-Deploy und Test Suite grün · Schema `006`
|
||||
**Version:** `0.5.0-ap0.5`
|
||||
|
||||
**Scope-Entscheidung:** [ADP_AP0_5_Sprint0_Scope_Shift_v0.1.md](../architecture/ADP_AP0_5_Sprint0_Scope_Shift_v0.1.md) — Foundation-AP0.5 (Audit/Admin) → **AP0.6** verschoben.
|
||||
|
||||
---
|
||||
|
||||
## 1. Scope und Einordnung
|
||||
|
||||
AP0.5 liefert den **ersten fachlich nutzbaren Kairo-Slice**: Ein angemeldeter Actor kann innerhalb eines Tenants Vorhaben und Maßnahmen verwalten, Actors zuweisen und offene Maßnahmen abrufen.
|
||||
|
||||
| Anforderung (AP0.5) | Status |
|
||||
|---------------------|--------|
|
||||
| Migration `006` (initiatives, actions, action_assignments) | ✓ |
|
||||
| Tenant-Bezug für alle Objekte | ✓ |
|
||||
| Owner Actor für Initiative | ✓ |
|
||||
| Action gehört zu Initiative | ✓ |
|
||||
| Action → ein oder mehrere Actors (Assignments) | ✓ |
|
||||
| CRUD-Minimum Initiatives | ✓ |
|
||||
| CRUD-Minimum Actions | ✓ |
|
||||
| Endpoint „Meine offenen Maßnahmen“ | ✓ |
|
||||
| Statusmodell minimal | ✓ |
|
||||
| Priority minimal | ✓ |
|
||||
| Capability-Gates (4 neue Capabilities) | ✓ |
|
||||
| Audit bei Create/Update/Statuswechsel | ✓ |
|
||||
| Tests (Isolation, CRUD, Assignment, Status) | ✓ |
|
||||
| README/API-Doku | ✓ |
|
||||
| CI pytest grün | ✓ (55/55 nach Seed-Fix) |
|
||||
|
||||
**Bewusst nicht in AP0.5:** Projects, Milestones, Programs, Reviews, Evidence, Blocker, KI/Prompt-Erweiterung, MCP, automatische Priorisierung, komplexe UI, Workflow Engine, Foundation-AP0.5 (Audit/Admin-UI).
|
||||
|
||||
**Wesentliche Commits:** `afa6815` (Implementierung), `a34a614` (Cleanup-Seed FK-Fix).
|
||||
|
||||
---
|
||||
|
||||
## 2. Definition of Done — Prüfmatrix
|
||||
|
||||
### 2.1 AP0.5-Auftrag (fachlich)
|
||||
|
||||
| Kriterium | Ergebnis | Nachweis |
|
||||
|-----------|----------|----------|
|
||||
| Vorhaben anlegen | ✓ | `POST /api/initiatives`, `test_initiative_crud` |
|
||||
| Maßnahmen erfassen | ✓ | `POST /api/initiatives/{id}/actions` |
|
||||
| Actors zuweisen | ✓ | `PUT /api/actions/{id}/assignments`, `test_action_assignments` |
|
||||
| Status ändern | ✓ | `PATCH`, `test_action_crud_and_status_change` |
|
||||
| Offene Maßnahmen abrufen | ✓ | `GET /api/actions/me/open`, `test_my_open_actions` |
|
||||
| Tenant-Isolation | ✓ | 3 Isolation-Tests |
|
||||
| Tests grün | ✓ | CI Job `pytest-backend` |
|
||||
|
||||
### 2.2 Principle Gate (G-01–G-12)
|
||||
|
||||
| ID | Prinzip | AP0.5 |
|
||||
|----|---------|-------|
|
||||
| G-01 | Tenant-first | ✓ `tenant_id` serverseitig |
|
||||
| G-02 | Actor-first | ✓ Assignments an Actors |
|
||||
| G-03 | TenantContext | ✓ `require_capability` |
|
||||
| G-04 | Auth/Capability/Feature getrennt | ✓ |
|
||||
| G-05 | Rights Registry | ✓ `initiative_ops.py` |
|
||||
| G-10 | Audit | ✓ 9 Audit-Actions |
|
||||
| G-11 | Migration Standard | ✓ `006_*` nummeriert |
|
||||
| G-12 | Fail-Fast Startup | ✓ Migration beim Start |
|
||||
|
||||
### 2.3 Sprint-0 DoD (Foundation §12) — mit ADP
|
||||
|
||||
| Kriterium | Status | Anmerkung |
|
||||
|-----------|--------|-----------|
|
||||
| Migrationen funktionieren | ✓ | 001–006 |
|
||||
| Tenant/User/Actor/Membership | ✓ | AP0.2 |
|
||||
| TenantContext, Capability, Prompt, Audit | ✓ | AP0.2–0.4 |
|
||||
| Tests Kernmodelle | ✓ | inkl. AP0.5 |
|
||||
| README aktuell | ✓ | AP0.5-Abschnitt |
|
||||
| Keine hardcodierten Rechte | ✓ | |
|
||||
| Vorhaben nicht in Sprint 0 | ⚠ | **ADP begründet** — minimaler Slice |
|
||||
| Foundation-AP0.5 Audit/Admin | ✗ | → AP0.6 |
|
||||
|
||||
### 2.4 User Story S0-07 (Audit)
|
||||
|
||||
| Feld (Foundation) | AP0.5 |
|
||||
|-------------------|-------|
|
||||
| Tenant | ✓ `tenant_id` |
|
||||
| Aktion | ✓ `action` |
|
||||
| Zeitpunkt | ✓ `created_at` |
|
||||
| Entity | ✓ in `details` (JSON) |
|
||||
| Actor | ✗ nur `user_id` (bekannt seit AP0.2) |
|
||||
|
||||
---
|
||||
|
||||
## 3. Umgesetzte Dateien
|
||||
|
||||
### 3.1 Migration & Schema
|
||||
|
||||
| Datei | Zweck |
|
||||
|-------|--------|
|
||||
| `backend/migrations/006_initiatives_actions.sql` | initiatives, actions, action_assignments |
|
||||
|
||||
### 3.2 Services
|
||||
|
||||
| Datei | Zweck |
|
||||
|-------|--------|
|
||||
| `backend/services/initiatives.py` | Vorhaben-CRUD, Validierung, Audit |
|
||||
| `backend/services/actions.py` | Maßnahmen-CRUD, Assignments, offene Maßnahmen |
|
||||
|
||||
### 3.3 API & Capabilities
|
||||
|
||||
| Datei | Zweck |
|
||||
|-------|--------|
|
||||
| `backend/routers/initiatives.py` | Initiative-Endpoints + nested Actions |
|
||||
| `backend/routers/actions.py` | Action-Endpoints + `/me/open` |
|
||||
| `backend/rights_registrations/initiative_ops.py` | 4 Capabilities |
|
||||
| `backend/main.py` | Router-Mount |
|
||||
| `backend/version.py` | `0.5.0-ap0.5`, Schema `006` |
|
||||
|
||||
### 3.4 Tests, Seeds, Doku
|
||||
|
||||
| Datei | Zweck |
|
||||
|-------|--------|
|
||||
| `backend/tests/test_initiatives_actions.py` | 11 Tests AP0.5 |
|
||||
| `backend/tests/test_migrations.py` | Migration 006 |
|
||||
| `backend/tests/test_rights_registry.py` | 16 Capabilities |
|
||||
| `backend/seeds/seed_001_cleanup_pytest_artifacts.dev.sql` | Initiatives vor Actor-Löschung (FK-Fix) |
|
||||
| `README.md` | API-Doku AP0.5 |
|
||||
| `docs/MIGRATIONS.md` | Migrationstabelle 001–006 |
|
||||
| `docs/architecture/ADP_AP0_5_Sprint0_Scope_Shift_v0.1.md` | Scope-Entscheidung |
|
||||
| `frontend/src/App.jsx` | Header AP0.5 |
|
||||
|
||||
---
|
||||
|
||||
## 4. Neue Migrationen
|
||||
|
||||
**`006_initiatives_actions.sql`**
|
||||
|
||||
| Tabelle | Spalten (Kern) |
|
||||
|---------|----------------|
|
||||
| `initiatives` | `tenant_id`, `title`, `goal`, `status`, `priority`, `owner_actor_id` |
|
||||
| `actions` | `tenant_id`, `initiative_id`, `title`, `description`, `status`, `priority` |
|
||||
| `action_assignments` | `tenant_id`, `action_id`, `actor_id` — UNIQUE `(action_id, actor_id)` |
|
||||
|
||||
CHECK-Constraints für Status und Priority. `owner_actor_id` → `actors` ON DELETE **RESTRICT**.
|
||||
|
||||
---
|
||||
|
||||
## 5. Datenmodell
|
||||
|
||||
```
|
||||
tenants
|
||||
└── initiatives
|
||||
id, tenant_id, title, goal, status, priority
|
||||
owner_actor_id → actors
|
||||
created_at, updated_at
|
||||
└── actions [ON DELETE CASCADE]
|
||||
id, tenant_id, initiative_id, title, description
|
||||
status, priority
|
||||
└── action_assignments [ON DELETE CASCADE von action]
|
||||
id, tenant_id, action_id, actor_id
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Endpoints
|
||||
|
||||
| Endpoint | Methode | Capability |
|
||||
|----------|---------|------------|
|
||||
| `/api/initiatives` | GET | `kairo.initiative.read` |
|
||||
| `/api/initiatives` | POST | `kairo.initiative.manage` |
|
||||
| `/api/initiatives/{id}` | GET/PATCH/DELETE | read / manage |
|
||||
| `/api/initiatives/{id}/actions` | GET/POST | `kairo.action.read` / manage |
|
||||
| `/api/actions/{id}` | GET/PATCH/DELETE | action.read / manage |
|
||||
| `/api/actions/{id}/assignments` | PUT | `kairo.action.manage` |
|
||||
| `/api/actions/me/open` | GET | `kairo.action.read` |
|
||||
|
||||
`tenant_id` ausschließlich aus `TenantContext` — nie aus Client-Body.
|
||||
|
||||
Details und curl-Beispiele: `README.md`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Statusmodell
|
||||
|
||||
**Initiative:** `active` · `paused` · `completed` · `archived`
|
||||
|
||||
**Action:** `open` · `in_progress` · `blocked` · `done` · `discarded`
|
||||
|
||||
**Priorität:** `low` · `normal` · `high`
|
||||
|
||||
**Offen** (`/api/actions/me/open`): Status ∈ `{open, in_progress, blocked}` und zugewiesen an `ctx.actor_id`. Sortierung: Priority high→low, dann `updated_at DESC`.
|
||||
|
||||
---
|
||||
|
||||
## 8. Assignment-Modell
|
||||
|
||||
- n:m über `action_assignments`
|
||||
- `PUT /api/actions/{id}/assignments` ersetzt die komplette Liste
|
||||
- Beim Create optional `assigned_actor_ids`
|
||||
- Assignee-Actors müssen im gleichen Tenant und aktiv sein
|
||||
- Cross-Tenant-Zuweisung → HTTP 400
|
||||
|
||||
---
|
||||
|
||||
## 9. Capability-Nutzung
|
||||
|
||||
| Capability | Default-Grants |
|
||||
|------------|----------------|
|
||||
| `kairo.initiative.read` | portal user/admin, tenant owner/admin/member |
|
||||
| `kairo.initiative.manage` | portal admin, tenant owner/admin/member |
|
||||
| `kairo.action.read` | portal user/admin, tenant owner/admin/member |
|
||||
| `kairo.action.manage` | portal admin, tenant owner/admin/member |
|
||||
|
||||
Enforcement: `require_capability()` → `require_tenant_context` → Probe/Enforce via `CAPABILITY_ENFORCE`.
|
||||
|
||||
---
|
||||
|
||||
## 10. Tenant-Isolation
|
||||
|
||||
- Alle Queries: `WHERE tenant_id = %s` aus `ctx.tenant_id`
|
||||
- Fremde IDs → **404** (kein Leak)
|
||||
- Cross-Tenant-Actor → **400**
|
||||
- Tests: `test_tenant_isolation_initiatives`, `test_tenant_isolation_actions`, `test_cross_tenant_actor_assignment_rejected`
|
||||
|
||||
---
|
||||
|
||||
## 11. Audit
|
||||
|
||||
| Audit-Action | Trigger |
|
||||
|--------------|---------|
|
||||
| `initiative.created` | POST Initiative |
|
||||
| `initiative.updated` | PATCH Initiative |
|
||||
| `initiative.status_changed` | PATCH mit Statusänderung |
|
||||
| `initiative.deleted` | DELETE Initiative |
|
||||
| `action.created` | POST Action |
|
||||
| `action.updated` | PATCH Action |
|
||||
| `action.status_changed` | PATCH mit Statusänderung |
|
||||
| `action.assigned` | PUT Assignments |
|
||||
| `action.deleted` | DELETE Action |
|
||||
|
||||
Nachweis: `test_audit_on_create_and_status_change`.
|
||||
|
||||
**Lücke (S0-07):** kein `actor_id`-Feld in `audit_log` — nur `user_id`. Offen für AP0.6.
|
||||
|
||||
---
|
||||
|
||||
## 12. Tests & CI
|
||||
|
||||
### 12.1 Testabdeckung AP0.5
|
||||
|
||||
| Test | Abdeckung |
|
||||
|------|-----------|
|
||||
| `test_initiative_crud` | Create, List, Get, Update, Delete |
|
||||
| `test_action_crud_and_status_change` | Lifecycle + Status |
|
||||
| `test_action_assignments` | Multi-Actor |
|
||||
| `test_my_open_actions` | Filter offen/erledigt/nicht zugewiesen |
|
||||
| `test_tenant_isolation_*` | Cross-Tenant 404 |
|
||||
| `test_cross_tenant_actor_assignment_rejected` | FK-Logik |
|
||||
| `test_audit_on_create_and_status_change` | Audit-Log |
|
||||
| `test_member_has_initiative_capabilities` | Grants |
|
||||
| `test_unauthenticated_rejected` | Auth-Gate |
|
||||
| `test_invalid_status_rejected` | Pydantic |
|
||||
|
||||
### 12.2 CI-Nachweis
|
||||
|
||||
| Lauf | Ergebnis |
|
||||
|------|----------|
|
||||
| Erster Push `afa6815` | 53 passed, **2 failed** (Cleanup-Seed FK) |
|
||||
| Fix `a34a614` | **55 passed**, 0 failed |
|
||||
|
||||
Fehlerursache: `initiatives.owner_actor_id` RESTRICT verhinderte Actor-Löschung im pytest-Cleanup. Fix: Initiatives vor Actors in `seed_001_cleanup_pytest_artifacts.dev.sql` löschen.
|
||||
|
||||
---
|
||||
|
||||
## 13. Abweichungen von Foundation / Designprinzipien
|
||||
|
||||
| Thema | Abweichung | Begründung / ADP |
|
||||
|-------|------------|------------------|
|
||||
| AP-Nummerierung | AP0.5 ≠ Foundation-AP0.5 | ADP Scope-Verschiebung |
|
||||
| Vorhaben in Sprint 0 | minimaler Slice | ADP Option B |
|
||||
| Audit Actor-Feld | nur `user_id` | AP0.2-Schema, AP0.6 |
|
||||
| GUI | keine Vorhaben-UI | bewusst minimal |
|
||||
| Feature Registry | keine initiative-Features | Capabilities reichen |
|
||||
|
||||
**Eingehalten:** Tenant/Actor/Capability-Trennung; keine hardcodierten Rechte; nummerierte Migration; kein Mitai/Shinkan-Domänencode.
|
||||
|
||||
---
|
||||
|
||||
## 14. Bewusst nicht übernommen
|
||||
|
||||
- Projects, Milestones, Programs, Reviews, Evidence, Blocker
|
||||
- KI/Prompt-Erweiterung, MCP, Workflow Engine
|
||||
- Automatische Priorisierung
|
||||
- Foundation-AP0.5: Admin-Routen, Admin-Seite, granulares Registry-Audit
|
||||
- GUI für Vorhaben/Maßnahmen (Swagger/API)
|
||||
|
||||
---
|
||||
|
||||
## 15. Empfehlung AP0.6
|
||||
|
||||
**Foundation-AP0.5 nachziehen (Audit & Admin):**
|
||||
|
||||
- Granulares Audit (optional `actor_id` in `audit_log`)
|
||||
- Minimale Admin-Routen oder Admin-Seite
|
||||
- Entitlements-/Registry-Prüfbarkeit in GUI
|
||||
|
||||
**Alternativ fachlich:** Kommentare pro Maßnahme (`action_comments`) — siehe v0.1 §11.
|
||||
|
||||
---
|
||||
|
||||
## Referenzen
|
||||
|
||||
- Auftrag: AP0.5 Minimaler Vorhaben- und Maßnahmen-Slice (Cursor)
|
||||
- ADP: `docs/architecture/ADP_AP0_5_Sprint0_Scope_Shift_v0.1.md`
|
||||
- Foundation: `docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md` § AP0.5, §12, §13
|
||||
- Principle Gate: `docs/architecture/Kairo_Sprint0_Principle_Gate_v0.1.md`
|
||||
- Vorgänger: `docs/sprints/Sprint0_AP0_4_Completion_Report_v0.2.md`
|
||||
- v0.1: `docs/sprints/Sprint0_AP0_5_Completion_Report_v0.1.md`
|
||||
Reference in new issue
Block a user