102 lines
4.2 KiB
Markdown
102 lines
4.2 KiB
Markdown
# 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 HiveGrid 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
|