Kairo-Jinkendo/docs/sprints/Sprint0_AP0_5_Completion_Report_v0.2.md

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