docs: Plan-Modus-Design und ADP AP1.10 (Archetypen, Entity Field System).

Festlegung Vorhaben als Wurzel, Plan-Outline, Modal/DnD, Gate-Graph und Roadmap AP1.9b–AP1.13.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
LarsandCursor committed 2026-07-09 11:13:54 +02:00
1 parent 09feddae4a
commit afb07f70b9
4 files changed
+514 -19

No files matched your search

@@ -0,0 +1,212 @@
# ADP — AP1.10 Initiative-Archetypen & Entity Field System v0.1
**Status:** vorgeschlagen (PO-Freigabe ausstehend)
**Stand:** 2026-07-09
**Autor:** Product/Architektur (PO-Session Planen)
**Bezug:** Vision v0.2, Canonical OM v0.2, `ADP_Recursive_Containers_and_Execution_Granularity_v0.1.md`, `Kairo_Plan_Mode_Design_v0.1.md`
**Auslöser:** Planen braucht beschreibbare Vorhaben/Container; parallele „Unabhängigkeit“ von Objekten erzeugt Navigations- und Daten-Inkonsistenz
---
## Problem
1. **Initiative** hat heute nur `title`, `goal`, `status`, `priority`, `owner_actor_id` — unzureichend für Programm-, Produkt- oder Transformations-Vorhaben (Vision, Zielzustand, Typ-spezifische Attribute).
2. **Dynamische Felder** fehlen zentral; Ad-hoc-JSONB pro Entität würde Retrieval, Indexierung und Agent-Zugriff fragmentieren.
3. **Hierarchie vs. Unabhängigkeit:** Alles operative hängt fachlich an einem Vorhaben, aber UI und Scope suggerierten teils losgelöste Welten — Planen wird unzuverlässig.
4. **Archetypen** (Vorhabentypen) sind nicht modelliert; Vorlagen für Felder und UI können nicht tenant-konfigurierbar werden.
Ohne Entscheidung drohen: hardcodierte Formularfelder, nicht auswertbare Metadaten, erneute Omnibus-CRUD-Seiten.
---
## Betroffene Regeln
| Dokument | Regel |
|----------|--------|
| Vision v0.2 | Initiative = Programm/Vorhaben; Plan vs. Ist getrennt |
| Canonical OM v0.2 | Project optional rekursiv; Action = Arbeitspaket; Gates orthogonal |
| Tenant Invariants | Keine hardcodierte Fachkonfiguration; Mandantenfähigkeit |
| ADP Recursive Containers | `container_kind` = Label; kein eigener Stream-Typ |
| ADP AP1.9 | Modal/Detail für Pflege; keine Inline-CRUD-Wand |
| Principle Gate | Neues OM-Schema nur mit ADP |
---
## PO-Arbeitsentscheidungen (2026-07-09)
| # | Frage | Entscheidung |
|---|--------|--------------|
| D1 | Archetyp nur Initiative oder auch Project? | **Initiative verbindlich**; Project-Templates **Phase 2** (optional `project_archetype_key`) |
| D2 | `goal` vs. `vision` | **`goal`** = Kurzbeschreibung (1–2 Sätze, bestehend); **`vision`** = ausführliches Zielbild (neu, TEXT) |
| D3 | Flache Vorhaben ohne Project? | **Ja** — Actions dürfen direkt unter Initiative hängen (`project_id` NULL); Plan-Baum zeigt Initiative → Actions |
| D4 | Graph-Inhalt | **Phase 1:** Gates + Dependencies; Project→Gate-Zuordnung in Detail/Liste; **Phase 2:** Project-Knoten im Graph optional |
---
## Optionen (Felder & Archetypen)
| Option | Kurz | Pro | Contra |
|--------|------|-----|--------|
| **A** | Nur mehr Spalten auf `initiatives` | Schnell, indexiert | Keine Typ-Vorlagen; kein Wiederverwendungsmodell für Project |
| **B** | Freies JSONB `metadata` pro Tabelle | Flexibel | Schwer auswertbar; kein Schema-Gate |
| **C** | **Zweischichtig: Standardspalten + zentrales EFS** | Index + Typ-Vorlagen + Agent-API | Migration + Registry-Aufwand |
**Empfehlung: Option C**
---
## Entscheidung (Option C)
### 1. Vorhaben als Wurzel (verbindlich)
Jede operative Entität hat **`initiative_id NOT NULL`** (bereits Schema für Action, Project, Backlog, RoadmapItem).
| Konzept | Regel |
|---------|--------|
| „Unabhängigkeit“ | Nur **Querschnitts-Ansichten** (Ausführen, Cockpit), nie orphan-Objekte |
| Deep Links | `/actions/:id` etc. leiten Scope aus Objekt ab |
| Planen | Scope-pflichtig auf mindestens ein Vorhaben |
### 2. Schicht A — Standardfelder (spaltenbasiert, indexiert)
**Migration `015_initiative_archetypes.sql`** (nummeriert, reproduzierbar):
```sql
-- initiatives (Erweiterung)
ALTER TABLE initiatives ADD COLUMN IF NOT EXISTS vision TEXT NOT NULL DEFAULT '';
ALTER TABLE initiatives ADD COLUMN IF NOT EXISTS target_state_summary TEXT NOT NULL DEFAULT '';
ALTER TABLE initiatives ADD COLUMN IF NOT EXISTS archetype_key VARCHAR(64) NOT NULL DEFAULT 'initiative.generic';
CREATE INDEX IF NOT EXISTS idx_initiatives_archetype ON initiatives(tenant_id, archetype_key);
CREATE INDEX IF NOT EXISTS idx_initiatives_status ON initiatives(tenant_id, status);
-- title bereits vorhanden; goal bleibt
```
**Project (optional Phase 1b):** nur `sort_order` Index falls noch fehlt; `archetype_key` deferred.
Standardfelder pro Typ sind **Pflicht für Listen, Filter, Steering, Breadcrumb-Titel** — nie aus EFS für Hot Paths.
### 3. Schicht B — Entity Field System (EFS)
Zentrale Mandanten-Registry (analog Feature/Capability Registry — **keine** Router-DDL):
| Tabelle | Zweck |
|---------|--------|
| `entity_archetypes` | `key`, `entity_type`, `label`, `description`, `is_system` |
| `field_definitions` | `archetype_key`, `field_key`, `field_type`, `label`, `required`, `searchable`, `sort_order`, `validation_json` |
| `field_values` | `tenant_id`, `entity_type`, `entity_id`, `field_key`, typed columns OR `value_json` + `value_text` Denormalisierung für searchable |
**Feldtypen (v1):** `text`, `longtext`, `number`, `boolean`, `date`, `enum`, `actor_ref`, `url`
**API (v1):**
```text
GET /api/entity-archetypes?entity_type=initiative
GET /api/initiatives/{id}/field-definitions — effektive Definition (Archetyp + Tenant-Overrides später)
GET /api/initiatives/{id}/fields — Werte
PATCH /api/initiatives/{id}/fields — partial update, validiert gegen Definition
```
Gleiche Oberfläche später für `project`, `action` — **ein** Service `backend/entity_fields/` (Scope Lock: keine parallele Logik in Routern).
**Retrieval-Strategie:**
| Pfad | Quelle |
|------|--------|
| Listen, Cockpit, Scope-Titel | Spalten Schicht A |
| Detail-Modal, Export, Agent-Kontext | Schicht A + lazy EFS |
| Volltext/Suche auf dynamischen Feldern | nur `searchable=true`; optional GIN auf `value_text` — **nicht** MVP-Blocker |
### 4. Archetypen (Initial-Seed, system)
| `archetype_key` | Label | Zusätzliche Standardfelder | Typische EFS-Felder (Seed) |
|-----------------|-------|----------------------------|----------------------------|
| `initiative.generic` | Allgemeines Vorhaben | vision optional | — |
| `initiative.program` | Programm / Mega-Vorhaben | vision, target_state_summary | stakeholder_map, success_criteria |
| `initiative.product` | Produkt / Release | vision, target_state_summary | release_theme, metrics |
Weitere Archetypen nur via Seed/Admin — **nicht** hardcoded im Frontend.
### 5. Frontend-Konsequenz
- Initiative bearbeiten: **Modal** (Plan-Outline oder `/initiatives` Katalog), rendert Schema aus API
- Keine typ-spezifischen React-Formulare hardcoded — **FieldRenderer** aus Definitionen
- Archetyp-Wahl bei Anlage (Dropdown aus Registry)
---
## Scope Lock
| Verboten bis ADP-Freigabe | Erlaubt |
|---------------------------|---------|
| Ad-hoc JSONB-Spalten auf OM-Tabellen für Fachfelder | AP1.9b Scope-Breadcrumb |
| Hardcodierte Vorhabentyp-Forms im Frontend | AP1.12 Plan-Outline (mit bestehenden Feldern) |
| Mitai/Shinkan Domänenlogik kopieren | Referenz-Pattern für Registry |
| Verboten nach Freigabe | Erlaubt |
|------------------------|---------|
| Felddefinitionen in Routern | `backend/entity_fields/` + nummerierte Migration |
| Dynamische Felder in Steering-Heuristiken ohne ADP-Erweiterung | Standardspalten in Steering |
---
## Implementierungspakete
```text
AP1.10a Migration Standardfelder + archetype_key; API read/write Initiative inkl. vision
AP1.10b EFS Tabellen + Registry-Sync + field_definitions Seed
AP1.10c API fields + Validierung + Initiative Modal (FieldRenderer minimal)
AP1.10d Project sort_order API + Plan-Reorder (siehe Plan Mode Design)
```
**Version-Ziel:** `0.17.0-ap1.10a` … `0.17.x-ap1.10c`
---
## Risiko
| Risiko | Mitigation |
|--------|------------|
| EFS-Overengineering | MVP: 3 System-Archetypen; searchable=false default |
| Performance dynamische Felder | Hot path nur Spalten; EFS lazy |
| Migration bestehender Initiativen | Default `initiative.generic`; leere vision |
| Tenant-Custom-Fields zu früh | Phase 2: Tenant-Overrides auf field_definitions |
---
## Rückbaubarkeit
- Archetyp-Spalte nullable machen / Default behalten
- EFS-Tabellen droppbar ohne OM-Kern zu zerstören
- FieldRenderer isoliert; Fallback auf feste Standardfelder
---
## Auswirkung auf Roadmap
| Paket | Beziehung |
|-------|-----------|
| AP1.9b | Scope-Breadcrumb kontextsensitiv — parallel, kein Blocker |
| AP1.12 | Plan-Outline nutzt 10a Standardfelder; 10c für Modal-Schema |
| AP1.13 | Gate-Graph unabhängig von EFS |
| AP1.5d | Tasks im Plan-Baum nach 12 |
**Nächstes Code nach AP1.9b/c:** AP1.10a (Standardfelder) vor AP1.11/13.
---
## PO-Freigabe
- [ ] Option C (Zweischichtig + EFS) angenommen
- [ ] Archetyp-Seed (generic, program, product) OK
- [ ] D1–D4 Entscheidungen bestätigt
- [ ] `backend/entity_fields/` Scope Lock OK
---
## Referenzen
- `docs/product/Kairo_Plan_Mode_Design_v0.1.md`
- `docs/product/Kairo_PM_Frontend_UI_Concept_v0.1.md`
- `docs/architecture/ADP_Recursive_Containers_and_Execution_Granularity_v0.1.md`
- `docs/reference/design-principles/mitai/REGISTRY_PLUGIN_DESIGN_PRINCIPLES.md` (Pattern, kein Scope)