Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -1,101 +1,42 @@
|
||||
# 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.
|
||||
**Zweck:** Ein laufendes Ticket sicher korrigieren, ohne abhängige Tickets oder bereits ausgelieferte Daten zu beschädigen.
|
||||
|
||||
## Grundsatz: atomare Commits pro Slice
|
||||
## Grundsatz
|
||||
|
||||
Der HiveGrid committet pro Slice atomar. Eine Slice rückgängig zu machen heißt: einen Commit-Range zu reverten — nicht einen einzelnen File.
|
||||
- Plane hält Status und Dependencies; die Ticket-Doc hält Scope, DoD, Rollback und Proof.
|
||||
- Änderungen werden an atomaren Checkpoints committed. Ein Rollback erfolgt mit `git revert`, nicht durch Umschreiben veröffentlichter Historie.
|
||||
- Vor Contract-, Schema- oder Scope-Änderungen werden `blocked-by` und `blocks` in beide Richtungen geprüft.
|
||||
|
||||
## Eskalations-Stufen
|
||||
## Eingriffsstufen
|
||||
|
||||
### Stufe 1: Kosmetik / UI falsch
|
||||
### 1. UI/Wording
|
||||
|
||||
**Anzeichen:** Funktion läuft technisch, aber Layout/Wording/Reihenfolge falsch.
|
||||
Interim-UI beziehungsweise Subframe-Adapter korrigieren, Visual-Baseline nachziehen und die stabile VM-/Action-Grenze beibehalten. Keine fachliche Logik in Routes oder UI verschieben.
|
||||
|
||||
**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
|
||||
### 2. View-Model oder Domain-Logik
|
||||
|
||||
**Risiko:** sehr niedrig. Layer-Trennung schützt.
|
||||
Pure VM-Builder, Zod-Schema und fokussierte Tests gemeinsam ändern. Bei Schreiblogik zusätzlich Audit, Activity, Notifications, Permission- und RLS-Kontext prüfen.
|
||||
|
||||
### Stufe 2: View-Model falsch (Daten-Form)
|
||||
### 3. Datenmodell oder öffentlicher Contract
|
||||
|
||||
**Anzeichen:** Funktion zeigt falsche Daten / fehlende Felder / falsche Aggregation.
|
||||
- Neue Forward-only-Migration; angewandte Migrationen nicht umbenennen oder editieren.
|
||||
- Inverse-SQL als Kommentar dokumentieren.
|
||||
- Alle abhängigen Ticket-Docs und Konsumenten im selben Änderungsschnitt nachziehen.
|
||||
- Prisma-Validierung, Migrations-Parität, RLS-Verträge und fokussierte Consumer-Tests ausführen.
|
||||
|
||||
**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)
|
||||
### 4. Ticket-Ansatz verwerfen
|
||||
|
||||
**Risiko:** mittel. Wenn die UI-Component die VM-Form falsch annimmt: neuer Vertrag.
|
||||
Noch nicht gemergte Checkpoints gezielt reverten oder den Branch verwerfen. Bereits gemergte Änderungen ausschließlich über neue Revert-/Fix-Commits korrigieren. Ticket-Doc mit Ursache, Auswirkungen, neuem Plan und aktuellem DoD-Prozentsatz aktualisieren.
|
||||
|
||||
### Stufe 3: Domain-Logik falsch
|
||||
## Notbremse
|
||||
|
||||
**Anzeichen:** Daten werden falsch geschrieben, Permissions stimmen nicht, falsche Side-Effects.
|
||||
Wenn ein ausgeliefertes Modul einen vorhandenen Feature- oder Ingress-Schalter besitzt, ihn kontrolliert deaktivieren und die operative Auswirkung dokumentieren. Kein neuer Schalter außerhalb des Ticket-Scopes und kein Deploy-Bypass.
|
||||
|
||||
**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
|
||||
## Pflichtnachweise vor Push
|
||||
|
||||
**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
|
||||
1. Betroffene Ticket-DoD und Dependencies konsistent.
|
||||
2. Passende fokussierte Tests und `verify:*`-Gates grün.
|
||||
3. `pnpm typecheck`, `pnpm lint` und `pnpm test` gemäß `docs/AGENT-CHECKLIST.md` grün.
|
||||
4. Rollback-Pfad und Forward-only-DB-Vertrag in der Ticket-Doc dokumentiert.
|
||||
5. Plane-Kommentar und Status erst nach dem lokalen Proof aktualisieren.
|
||||
Reference in new issue
Block a user