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:
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)
|
||||
Reference in new issue
Block a user