Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

+101
View File
@@ -0,0 +1,101 @@
# Mid-Stream-Änderungen — Rollback-Playbook
**Zweck:** Wenn ein AI-Coding-Agent ein Milestone falsch baut und du es mittendrin korrigieren musst, ohne dass 5 andere Module brechen.
## Grundsatz: atomare Commits pro Slice
Der ToolController committet pro Slice atomar. Eine Slice rückgängig zu machen heißt: einen Commit-Range zu reverten — nicht einen einzelnen File.
## Eskalations-Stufen
### Stufe 1: Kosmetik / UI falsch
**Anzeichen:** Funktion läuft technisch, aber Layout/Wording/Reihenfolge falsch.
**Vorgehen:**
1. NIEMALS direkt im `app/routes/**` korrigieren — Designer baut neu in Subframe
2. Subframe-Update → AI-Agent integriert in `packages/ui-hivegrid/src/adapters/`
3. Visual-Regression-Gate (M016) zeigt Diff
4. Merge
**Risiko:** sehr niedrig. Layer-Trennung schützt.
### Stufe 2: View-Model falsch (Daten-Form)
**Anzeichen:** Funktion zeigt falsche Daten / fehlende Felder / falsche Aggregation.
**Vorgehen:**
1. View-Model in `packages/view-models/src/<domain>/*.vm.ts` korrigieren
2. Zod-Schema mit-aktualisieren
3. Loader-Funktion im `app/routes/**` korrigieren
4. UI-Component in `packages/ui-hivegrid/**` muss NICHT geändert werden (sonst war die Trennung schlecht)
**Risiko:** mittel. Wenn die UI-Component die VM-Form falsch annimmt: neuer Vertrag.
### Stufe 3: Domain-Logik falsch
**Anzeichen:** Daten werden falsch geschrieben, Permissions stimmen nicht, falsche Side-Effects.
**Vorgehen:**
1. `app/domain/**` korrigieren (NICHT UI, NICHT VM)
2. Bei DB-Schema-Änderung: neue Prisma-Migration als FORWARD-MIGRATION (kein Backward-Edit der alten)
3. Bei Permission-Bug: Permission-Wrapper-Test in M004 erweitern
4. Cross-Tenant-Probe-Test (M005) muss grün bleiben
**Risiko:** hoch. Daten könnten bereits in der DB falsch sein.
### Stufe 4: Komplettes Milestone neu
**Anzeichen:** Architektur-Fehler, falscher Layer-Schnitt, Anti-Pattern in der Foundation.
**Vorgehen:**
1. Branch identifizieren — TC arbeitet pro Milestone in einem Branch
2. Branch nicht mergen → revert ist trivial
3. Wenn schon gemergt: `git revert <merge-commit>` als neuer Commit
4. PLAN.md des Milestones aktualisieren (Lessons Learned als Hinweis für Slice-Planung)
5. TC neu starten auf das Milestone
**Risiko:** sehr hoch wenn andere Milestones bereits darauf bauen. Deshalb: vor jedem Milestone PLAN.md prüfen, ob die Abhängigkeiten klar sind.
## Reversibilitäts-Pflichten pro Milestone
Bevor TC ein Milestone als fertig markiert, müssen folgende Rollback-Pfade existieren:
| Artefakt | Rollback-Pfad |
|---|---|
| **Code-Änderungen** | `git revert <slice-commit>` — atomic per Slice |
| **DB-Migration** | Forward-Only-Migration mit dokumentiertem Inverse-SQL als Kommentar im Migration-File |
| **Sidebar-Eintrag** | Eintrag in `sidebar.config.ts` löschen → Sidebar baut sich neu |
| **Routes** | Route-Datei löschen → RR7 verweigert die URL |
| **Permissions** | Permission-Key in `permissions.ts` als deprecated markieren |
| **Feature-Flag** | Flag aus auf `false` → Modul unsichtbar ohne Code-Deploy |
## Notbremse: Feature-Flag
Jedes Modul, das in Produktion landet, kann via Feature-Flag aus M006 ausgeschaltet werden — ohne Deploy. Wenn etwas live brennt:
1. Plattform-Admin → Feature-Flags
2. Flag des betroffenen Moduls auf `false` für betroffenen Mandanten
3. Modul verschwindet aus der Sidebar (siehe sidebar.config.ts `feature_flag` Feld)
4. Bug in Ruhe fixen
5. Flag wieder auf `true`
## Was du als Mensch nicht selbst korrigieren solltest
- **NICHT direkt in `packages/ui-subframe/**`** — das ist Subframe-Output, wird beim nächsten Designer-Update überschrieben
- **NICHT direkt in `packages/ui-hivegrid/src/adapters/**`** — der AI-Agent generiert das aus dem Subframe-Output
- **NICHT in TC-State (`.tc/`)** ohne Backup
## Was du selbst korrigieren KANNST
- `docs/milestones/M*/PLAN.md` — Pflichtenheft-Bezug, Hinweise, Erfolgskriterien anpassen
- `AGENTS.md` und `docs/INTEGRATION-CONTRACTS.md` — Agent-Regeln verschärfen
- `docs/CHANGE-REQUESTS.md` — Change-Request festhalten
## Eskalationspfad
1. Feature-Flag aus (Notbremse)
2. PLAN.md aktualisieren mit klarer Korrektur-Anweisung
3. TC auf das Milestone neu starten oder gezielt eine Slice via `/tc steer` umsteuern
4. Verify-Gates laufen lassen, bis grün
5. Flag wieder an