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

+286
View File
@@ -0,0 +1,286 @@
# ToolController-Briefing für HiveGrid 2.0
**Adressat:** ToolController + alle AI-Coding-Agents (Sub-Agents von TC), die an HiveGrid arbeiten.
**Stand:** 2026-05-10
**Verbindlichkeit:** dieses Dokument plus die hier referenzierten Pfade definieren das Vorgehen vollständig.
---
## 0. Was du baust
HiveGrid 2.0 ist eine Multi-Tenant-SaaS-Plattform für SHK-Handwerksbetriebe. Erstkunde: Geerkens. EU-Stack komplett (kein US-Anbieter). Repository-Wurzel: `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud`.
176 Milestones in `docs/milestones/M001/` bis `docs/milestones/M176/`. Jedes Verzeichnis enthält genau eine Datei `PLAN.md`. Diese sind deine Arbeits-Aufträge.
## 0.1 Die Boilerplate IST deine Codebase — nicht „eine Vorlage"
Das Repo `HiveGrid-Cloud/` enthält die EU-sterilisierte ToolCTRL-Boilerplate als Fundament. Das ist **dein Code**, du editierst, erweiterst und löschst ihn. Du klonst nichts, du importierst nichts „von außen", du baust **nicht** parallel ein neues Projekt.
Konkret heißt das:
- `apps/web/`, `apps/api/`, `apps/worker/`, `packages/db/`, `packages/mail/`, `packages/queue/`, `packages/ui/`, `prisma/`, `package.json` mit pnpm-Workspace, Tailwind 4, shadcn/Radix, BullMQ, MailerSend → das ist deine Arbeitsbasis. Du nutzt sie.
- Du erweiterst, was fehlt: neue `packages/view-models/`, `packages/ui-hivegrid/`, `packages/ui-subframe/` (Phase 1 leer), neue Routes unter `app/routes/...`, neue Module unter `app/domain/...`, neue Prisma-Modelle in `prisma/schema/...`
- Du löschst, was nicht zu HiveGrid gehört (Affiliate/Marketing/CMS-Reste aus dem ToolCTRL-Boilerplate, falls noch vorhanden)
- Du baust **in** dieser Codebase, nicht **neben** ihr
## 0.2 Pre-Flight-Check beim Start (jedes Mal)
Bevor du das erste Milestone planst, verifiziere die Vorbedingungen:
1. `package.json` im Repo-Root existiert mit pnpm-Workspace-Konfig — wenn nein: STOP, melde „Boilerplate-Inhalt fehlt im Repo"
2. `apps/`, `packages/`, `prisma/` existieren — wenn nein: STOP
3. `pnpm install && pnpm typecheck && pnpm test` läuft grün — wenn nein: STOP, melde welche Tests rot sind
4. Kein US-Provider im Code: `grep -rE "@ai-sdk/openai|@ai-sdk/anthropic|remix-auth-google|from \"openai\"" --include="*.ts" --include="*.tsx" --include="*.json" .` ist leer — wenn nein: STOP, EU-Sterilisation nicht abgeschlossen
5. `docs/PROGRESS-TRACKER.md` existiert — wenn nein: STOP
Erst nach 5/5 grün beginnst du mit dem ersten Milestone.
---
## 1. Wo du alles findest
| Was | Wo |
|---|---|
| **Verbindliches Pflichtenheft v1.1** | `_bmad-output/pflichtenheft/` |
| → Vision + Anti-Liste | `_bmad-output/pflichtenheft/02-vision.md` |
| → 20 Architektur-Bauprinzipien | `_bmad-output/pflichtenheft/03-architektur.md` |
| → 7 Modul-Blöcke mit Detail-Pflichten | `_bmad-output/pflichtenheft/blocks/block1.md` … `block7.md` |
| → Anhang (Geparktes, Noah-Anmerkungen N1-N19) | `_bmad-output/pflichtenheft/99-anhang.md` |
| **Master-Milestone-Index** | `docs/milestones/README.md` |
| **Pflichtenheft → Milestone Coverage-Map** | `docs/milestones/PFLICHTENHEFT-COVERAGE.md` |
| **Per-Milestone-Plan** (176 Stück) | `docs/milestones/M???-<slug>/PLAN.md` |
| **Live-Progress-Tracker** (du updatest ihn) | `docs/PROGRESS-TRACKER.md` |
| **Agent-Regeln + Definition of Done** | `AGENTS.md` (Repo-Root) |
| **Integration-Contracts** (Sidebar, Routes, Wiring) | `docs/INTEGRATION-CONTRACTS.md` |
| **Mid-Stream-Korrektur-Playbook** | `docs/MID-STREAM-CHANGES.md` |
| **Change-Request-Workflow** | `docs/CHANGE-REQUESTS.md` (entsteht in M176) |
---
## 2. Wie du ein Milestone planst (Pflicht-Reihenfolge)
Pro Milestone arbeitest du diese Schritte ab — nicht überspringen:
1. **Lies `docs/milestones/M???-<slug>/PLAN.md` vollständig.** Sie enthält Ziel, Pflichtenheft-Sektionen, Abhängigkeiten, Out-of-Scope, Erfolgskriterium, Hinweise und am Ende die **Definition of Done**.
2. **Lies die referenzierten Pflichtenheft-Sektionen** (`_bmad-output/pflichtenheft/blocks/blockX.md` Sektion Y.Z). Klartext-Hinweise und Edge-Cases stehen dort, nicht in PLAN.md.
3. **Lies `AGENTS.md`.** Verbindliche Regeln für Layer-Trennung, drei Anti-Patterns, EU-Stack, Querschnitt-Wiring, Klartext-Pflicht.
4. **Lies `docs/INTEGRATION-CONTRACTS.md`.** Hier steht, wo dein Modul in Sidebar / Routes / Tab-Bar / Search-Index andockt.
5. **Prüfe Abhängigkeiten:** Sind alle in PLAN.md genannten Vorbedingungs-Milestones abgeschlossen? Wenn nein: STOP und an User melden.
6. **Plane Slices** (TC-Standard, 5–8 pro Milestone):
- Erste Slice ist meist Datenmodell + Migration
- Folge-Slices: Domain-Logik → Loader/Action → View-Model → UI-Component → Sidebar/Routing-Wiring → Tests
- Letzte Slice: Smoke-Test + Hot-Swap-Drill
7. **Plane Tasks pro Slice** (5 Tasks à 30 Min – 2 Std). Pro Task konkrete Files + Verify-Befehle.
8. **Vor Execute:** prüfe gegen die **Definition of Done** in PLAN.md. Sind alle Punkte über die geplanten Slices abgedeckt? Wenn nicht: ergänze Slices.
9. **Execute pro Slice atomar.** Pro Slice ein Commit. Forward-Only-DB-Migrations mit Inverse-SQL als Kommentar.
10. **Nach jeder Slice: Verify-Gate.** Erst nach grünem Verify zur nächsten.
---
## 3. UI-Bauen ohne Subframe (Phase-1-Bootstrap)
**Wichtig:** Der finale UI-Workflow läuft über Subframe (Designer baut → Subframe-Output → AI-Agent integriert via Adapter). **Aber jetzt** baust du UI mit den **vorhandenen Komponenten der Boilerplate** — sauber, austauschbar, testbar.
Ziel: Geerkens-tauglich aussehende UI, die später ohne Logik-Bruch durch Subframe-Output ersetzt werden kann.
### Was du verwenden darfst
| Layer | Quelle |
|---|---|
| Primitives | shadcn/ui + Radix-UI (alle `@radix-ui/*`-Pakete sind in der Boilerplate) |
| Icons | lucide-react |
| Tabellen | bestehende `components/ui/table.*` aus Boilerplate-`packages/ui` |
| Forms | react-hook-form + zod (bereits in Deps) |
| Charts | recharts oder @tremor/react |
| Tipp-Trigger / Suche | kbar |
| Editor | TipTap (für Notizen, Marketing-Editor) |
| Drag-&-Drop | react-beautiful-dnd / xyflow (für Automation-Editor) |
| PDF | @react-pdf/renderer |
| Touch-Signatur | signature_pad |
| Tailwind 4 | bereits konfiguriert |
### Was du NICHT machst
- ❌ KEIN Subframe-MCP-Aufruf für irgendwas in Phase 1.
- ❌ KEIN `packages/ui-subframe`-Inhalt füllen — das Verzeichnis bleibt leer (oder mit Dummy-README), bis der Designer kommt.
- ❌ KEINE Custom-CSS-Stylesheets pro Komponente — Tailwind-Utility-Klassen.
- ❌ KEINE eigenen Component-Libraries erfinden — nur shadcn/Radix-Composites.
### Wie du UI strukturierst
Genau gleich wie es später mit Subframe sein wird — **die Layer-Trennung ist jetzt schon Pflicht**, sonst funktioniert der spätere Hot-Swap nicht:
```
app/routes/<modul>/<route>.tsx → Loader baut View-Model, rendert <Page vm={...} actions={{...}} />
packages/view-models/src/<modul>/*.vm.ts → Pure Funktion (entity, ctx) → VM, mit Zod-Schema
packages/ui-hivegrid/src/pages/<modul>/... → React-Component, baut auf shadcn/Radix mit Tailwind, KEIN Server-Code
packages/ui-hivegrid/src/components/... → Wiederverwendbare Composites (Tabellen, Karten, Modale)
```
Components in `packages/ui-hivegrid/src/pages/<modul>/<Component>.tsx` empfangen IMMER:
- `vm: <ModulVM>` als Prop (das View-Model)
- `actions: { onX: (...) => ... }` als Prop (Callbacks)
KEINE Hooks für Daten-Fetching innerhalb dieser Components. KEINE direkten Server-Imports.
### Warum das den späteren Hot-Swap erlaubt
Wenn der Designer später Subframe-Output liefert, wird der Inhalt von `packages/ui-hivegrid/src/pages/<modul>/<Component>.tsx` durch den Subframe-konformen Adapter ersetzt — die **Schnittstelle** (Props: `vm` + `actions`) bleibt identisch. Routes, View-Models, Domain-Logik werden NICHT angefasst. Der Tausch ist atomar.
Genau deshalb gilt für die Phase-1-Bootstrap-UI:
- Kein direkter `useLoaderData` in Components (auch jetzt nicht!)
- Kein direkter Prisma-Import (auch jetzt nicht!)
- Alle Texte über i18n (M003)
- Alle Aktionen als Callback-Props
- View-Model hat Zod-Schema, das später dem Subframe-Adapter den Vertrag erzwingt
### Visuelles Anspruchsniveau
„Sauber genug zum Testen", nicht „pixel-perfect Designer-Output". Konkret:
- Konsistentes Spacing (Tailwind 4-Standard)
- Hell + Dunkel-Modus respektiert (nutze Tailwind `dark:`)
- DE-Long-Strings testen (47-Zeichen-Buttons dürfen nicht überlaufen)
- Empty-States, Loading, Error mit Klartext (siehe AGENTS.md Punkt E)
- Mobile-Viewport-Test (kein Desktop-Only-Layout)
---
## 4. Pro Milestone — Pflicht-Deliverables (Definition of Done)
Aus jeder PLAN.md am Ende. In Stichpunkten:
**Erreichbarkeit** (siehe INTEGRATION-CONTRACTS.md §1)
- Sidebar-Eintrag in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` mit Permission-Gate
- Route registriert
- Breadcrumb für Detail-Routes
- Mobile-Tab-Bar-Eintrag falls relevant
- Customer-Portal-Sichtbarkeit explizit konfiguriert
**Querschnitt-Wiring**
- Audit (auto via M001 oder manuell)
- Activity-Stream via `logActivity` (M045)
- Notifications via `notify()` (M011)
- Search-Index in `indexed-entities.ts`
- Permission-Filter via `withTenantScope()` + `withPermission()` (M004)
- Feature-Flag-fähig (M006)
**Code-Layer-Disziplin** (PR-Block bei Verstoß)
- Loader baut VM; UI empfängt nur VM + Actions
- Keine Prisma-/Server-Imports in `packages/ui-hivegrid/**`
- Keine Direktimporte aus `packages/ui-subframe` in `app/routes/**` (ist eh leer in Phase 1)
- Alle UI-Texte als i18n-Keys
**Tests**
- Unit-Test für VM-Builder mit Zod-Schema
- Smoke-Test in `e2e/smoke/<modul>.spec.ts`
- Hot-Swap-Drill grün (Smoke-Test gegen `packages/ui-mock` aus M017)
- Visual-Regression-Snapshot (M016)
**Klartext**
- Fehler-Texte aus M002-Catalog
- Empty/Loading/Error mit Klartext + nächster Aktion
- Permission-Denied → 404 statt 403
**Rollback-Pfad**
- Forward-Only-DB-Migration mit Inverse-SQL als Kommentar
- Atomic-Slice-Commits
- Feature-Flag vorhanden zum Abschalten ohne Deploy
**Klick-Pfad zum Prüfen** (steht in PLAN.md unten)
- 4-Schritt-Anleitung, wie der User die Funktion findet und testet
---
## 5. Drei harte Anti-Patterns (sofortiger PR-Block)
1. `@prisma/client` oder `~/db` in `packages/ui-hivegrid/**`
2. Direktimport aus `packages/ui-subframe` in `app/routes/**` (das Paket ist Phase-1 leer, aber der Import-Pfad bleibt verboten)
3. `useLoaderData<typeof loader>()` innerhalb von `packages/ui-hivegrid/**`
Plus: jede Erweiterung, die der Anti-Liste in `_bmad-output/pflichtenheft/02-vision.md` V.3 widerspricht. Vollständige Liste siehe dort.
---
## 6. EU-Stack — nicht verhandelbar
- KEIN `@ai-sdk/anthropic`, `@ai-sdk/openai`, `openai`
- KEIN `remix-auth-google`, KEIN Apple-/Google-/Microsoft-Login (Phase 1)
- JA Mistral primär, Scaleway sekundär, AlephAlpha tertiär
- JA Email+PW + Magic-Link + TOTP-2FA
- Hosting Scaleway (EU), DB in EU, Storage Scaleway-S3 (EU)
Wenn etwas im Boilerplate-Code noch US-Provider referenziert: STOP und an User melden — die Boilerplate sollte EU-sterilisiert sein.
---
## 7. Wenn du nicht weiterkommst
| Situation | Vorgehen |
|---|---|
| Pflichtenheft-Sektion ist mehrdeutig | STOP. Frage formulieren, an User. Kein Auto-Refactor. |
| Abhängigkeits-Milestone fehlt | STOP. An User: „M??? braucht M??? — wann fertig?" |
| Boilerplate hat Bug, der dich blockiert | STOP. Bug an User mit konkretem Pfad + Repro. |
| Anti-Listen-Punkt in PLAN.md gewünscht | STOP. Change-Request via `docs/CHANGE-REQUESTS.md` (M176). |
| Layer-Trennung lässt sich nicht einhalten | STOP. Architektur-Frage, nicht selber lösen. |
---
## 8. Erste konkrete Aufgabe
Beginne mit **M001 (Audit-Log default)**. Lies:
1. `docs/milestones/M001-audit-log-default/PLAN.md`
2. `_bmad-output/pflichtenheft/03-architektur.md` Sektion A.6
3. `AGENTS.md`
4. `docs/INTEGRATION-CONTRACTS.md` (§5 Audit-Wiring, §6 — der Audit-Eintrag selbst gehört zu diesem Milestone)
Plane M001 in Slices, präsentiere den Plan, warte auf User-Bestätigung, dann Execute.
Nach M001 → M002 → ... in der Reihenfolge der Master-Liste, ABER: prüfe in jeder PLAN.md die Abhängigkeiten — manche Milestones lassen sich parallelisieren (siehe `Wird benötigt von`-Felder).
---
## 9. Was du dem User nach jedem Milestone meldest
Kurzer Statusbericht in dieser Form:
```
Milestone: M??? — <Titel>
Status: READY-TO-VERIFY | BLOCKED | NEEDS-USER-INPUT
Slices: X von Y abgeschlossen
Tests: Smoke ✓ / Hot-Swap-Drill ✓ / Visual-Regression: <Anzahl Diffs zu prüfen>
DoD-Score: N/14 erfüllt
Sidebar-Eintrag: <Gruppe> > <Eintrag>
Klick-Pfad zum Prüfen: <wie aus PLAN.md>
PROGRESS-TRACKER aktualisiert: ✓
Offene Punkte (falls relevant): <Liste>
```
---
## 10. Progress-Tracker-Pflicht (`docs/PROGRESS-TRACKER.md`)
Diese Datei ist Live-Übersicht für den User. Du updatest sie **nach jedem Status-Wechsel**:
### Bei Milestone-Start
1. Status in der Master-Tabelle: `⚪ NICHT-GESTARTET` → `🔵 IN-ARBEIT`
2. Detail-Sektion gemäß Vorlage (Abschnitt „Vorlage" in der Tracker-Datei) anlegen — kopiere den Block, fülle Pflichtenheft-Bezug, leere Slice-Liste, leere DoD-Checkboxen ein
3. Klick-Pfad-Block aus PLAN.md übernehmen, mit konkreten User-Typ + Sidebar-Pfad ausfüllen
### Bei Slice-Abschluss
4. In der Detail-Sektion die Slice abhaken mit Commit-Hash
5. DoD-Checkboxen abhaken, sobald die jeweilige Pflicht erfüllt ist
6. DoD-Score in der Master-Tabelle aktualisieren (z.B. `8/14`)
### Bei Milestone-Abschluss (alle DoD-Punkte erfüllt + Tests grün)
7. Status in Master-Tabelle: `🔵 IN-ARBEIT` → `🟡 READY-TO-VERIFY`
8. „Notes vom Agent"-Block in Detail-Sektion ausfüllen (was war nicht offensichtlich, was muss User wissen)
9. STOP. Warte auf User-Sign-Off. Starte KEIN nächstes Milestone.
### Nach User-Sign-Off
10. User trägt selbst `🟢 SIGNED-OFF` + Datum in die Detail-Sektion ein
11. Du übernimmst diesen Status in die Master-Tabelle und beginnst das nächste Milestone
### Konsistenz-Pflicht
- DoD-Score in Master-Tabelle muss zur Detail-Sektion passen
- `🟡 READY-TO-VERIFY` ohne 14/14 DoD = Inkonsistenz → korrigiere sofort
- Mehr als 5 Milestones in `🔵 IN-ARBEIT` parallel → STOP, Fokus-Verlust → an User melden