287 lines
14 KiB
Markdown
287 lines
14 KiB
Markdown
# 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
|