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

@@ -0,0 +1,111 @@
# Phase 08 — Mobile + CLI + Storybook + SDK
**Dauer:** 10+ Wochen (parallelisiert; rein sequenziell ~14-16 Wochen)
**Tasks:** 5 (CLI-Scaffolding + CLI-Ops + Storybook + TypeScript-SDK + Capacitor-Mobile)
**Ziel:** Großer DX-Sprung in mehreren Dimensionen — Developers bekommen einen produktiven CLI für Module/Route/Entity-Scaffolding und Tenant-Migration-Ops, eine Storybook-Instance für visuell-getestete UI-Komponenten, einen typed TypeScript-SDK gegen die öffentliche API und einen nativen Mobile-Wrapper via Capacitor mit Push-Notifications + Biometric-Auth.
## Warum diese Phase nach Phase 06
- **Plugin-System (Phase 06)** definiert das Manifest-/Hook-Format. Das CLI-Scaffolding für Plugin-Templates (`toolctrl add-plugin-template`) referenziert diesen Vertrag direkt — wäre Phase 06 noch offen, müsste der Generator mit Mock-Manifesten arbeiten und nachträglich umgebaut werden.
- **Feature-Flags (#53 aus Phase 05)** werden vom CLI für Feature-Checks (z. B. `toolctrl doctor` reportet aktive Flags pro Tenant) und vom Mobile-Wrapper für Capability-Gating (Push erst aktivieren wenn Flag `mobile.push.enabled` an ist) konsumiert.
- **Sentry-Web-Wiring (Phase 02)** ist Pflicht, damit der Capacitor-Build im nativen Wrapper Crash-Reports und Web-Errors korrekt routet (Sentry-Native-Bridge braucht denselben DSN).
- **Backup-CLI (#46 aus Phase 03)** liefert die Snapshot-Mechanik, auf der `toolctrl migrate-tenant` aufsetzt. Ohne diesen Task müsste die Tenant-Migration ihren eigenen Snapshot-Mechanismus mitbringen — duplizierter Code, doppelte Test-Last.
- **Dep-Updates (Phase 01)** stellen aktuelle React-Router-, Vite- und Storybook-kompatible Versionen sicher, sonst kämpfen wir hier mit Peer-Dependency-Konflikten.
## Was diese Phase nicht blockt
Phase 08 hat **keine harten Downstream-Blocker.** Phase 10 (Compliance + Polish) hängt nicht an dieser Phase. Das bedeutet:
- Wenn ein Team-Mitglied schon Phase-10-Tasks vorbereiten will (z. B. React-Email, Lighthouse-Audit, WCAG-Sweep), kann es das parallel tun.
- Die Mobile-App-Store-Submission ist **Operator-Task** und wird in der Detail-MD nur dokumentarisch beschrieben, nicht vom Agent ausgeführt.
- Storybook ist eine reine DX-Verbesserung; das Produkt funktioniert ohne sie unverändert weiter.
## Task-Reihenfolge
| Reihenfolge | Task-ID | Datei | Parallelisierbar mit |
|---|---|---|---|
| 1 | #62 | `storybook.md` | alle anderen Phase-08-Tasks |
| 2 | #63 | `ts-sdk.md` | alle anderen Phase-08-Tasks |
| 3 | #60 | `cli-scaffolding.md` | #62, #63, #65 (sequenziell zu nichts) |
| 4 | #61 | `cli-ops.md` | #62, #63, #65 (braucht `#46 backup-cli` aus Phase 03) |
| 5 | #65 | `capacitor.md` | #62, #63 (profitiert von #61 für Build-Pipeline, kein Hard-Lock) |
## Dependency-Graph (intern)
```
Phase 01 (Dep-Updates)
Phase 02 (Sentry-Web-Wiring #14)
Phase 03 (#46 Backup-CLI)
Phase 05 (#53 Feature-Flags)
Phase 06 (Plugin-System komplett)
│
┌───────────────┼───────────────┬───────────────┐
▼ ▼ ▼ ▼
#62 storybook #63 ts-sdk #60 cli-scaffolding #65 capacitor
│ │ │ │
│ │ ▼ │
│ │ #61 cli-ops ──────────────►│
│ │ (depends #46) (uses CI/Build
│ │ aus cli-ops)
▼ ▼ ▼ ▼
Phase 10 (Compliance + Polish — unblocked)
```
Vier echte Parallel-Tracks nach Erfüllung der External-Depends:
- **Track A — Storybook (`#62`):** Setup einer aggregierenden Storybook-Instance unter `apps/storybook/`, Stories für ~20 Kern-Komponenten + Theme-Decorator + a11y/interactions-Addons. Vollständig unabhängig.
- **Track B — TS-SDK (`#63`):** `@hey-api/openapi-ts`-Pipeline, Higher-Level-Wrapper (Auth/Retry/Idempotency/Pagination/Webhook-Verify), `@toolctrl/api-client-ts` + `@toolctrl/api-types`. Vollständig unabhängig.
- **Track C — CLI (`#60 → #61`):** Scaffolding-Generatoren zuerst (Module/Route/Entity/Webhook/Plugin-Template), dann Ops-Commands (`doctor`, `migrate-tenant`, `impersonate`). `#61` braucht `#46`.
- **Track D — Mobile (`#65`):** Capacitor-Setup, Native-Projects, Plugins, Web-App-Anpassungen, Push-Backend, CI-Pipeline. Profitiert wenn `#61 cli-ops` bereits einen `toolctrl doctor mobile`-Sub-Command hat, aber kein Hard-Lock.
Empfohlene Parallelisierung mit 4 Agents: Tracks A/B/C/D laufen gleichzeitig nach Phase-06-Abschluss. Track C synchronisiert zwischen den beiden CLI-Tasks.
## Phase Done-Definition
Diese Phase ist `completed` wenn:
- [ ] Alle 5 Tasks `completed` in `PROGRESS.md`
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` global grün
- [ ] CLI-Binary `toolctrl` installiert via `pnpm install -g @toolctrl/cli` oder via `npx @toolctrl/cli`; alle dokumentierten Commands runable
- [ ] CLI-Snapshot-Tests grün: Module/Route/Entity-Generator-Output exakt wie gespeicherte Snapshots
- [ ] `apps/storybook/` startbar mit `pnpm --filter @toolctrl/storybook dev`; Static-Build deployed unter `https://storybook.staging.toolctrl.de`
- [ ] Mindestens 20 Kern-Komponenten haben Stories in CSF-3-Format; alle haben a11y-Checks via @storybook/addon-a11y (0 violations)
- [ ] `packages/api-client-ts/` exportiert generierten Client + Higher-Level-Wrapper; npm-publishable als `@toolctrl/api-client-ts`
- [ ] `packages/api-types/` exportiert nur Types (für reine Type-Konsumenten ohne Runtime-Code)
- [ ] SDK-Integration-Tests gegen lokale API grün; Pagination-Iterator + Webhook-HMAC-Verify + Idempotency-Auto-Gen verifiziert
- [ ] `apps/mobile/` enthält Capacitor 7.x-Setup mit iOS + Android Native-Projects; `npx cap sync` erfolgreich
- [ ] Push-Notification-Backend in `apps/worker` oder `packages/notifications` aktiv: FCM + APNs Provider, DeviceToken-Model, Auto-Fan-Out aus `notifications`-Modul
- [ ] `useCapacitor()`-Hook in `apps/web` detected Native-Wrapper; Auth-Flow nutzt Biometric + Token-Storage statt Browser-Cookie wenn aktiv
- [ ] Splash-Screen + App-Icon aus Brand-Settings generiert für iOS + Android
- [ ] CI-Pipeline (GitHub-Actions oder Codemagic) baut iOS-IPA + Android-APK auf push to `agent/mobile-*`-Branches; TestFlight-Upload + Play-Internal-Track gated über Operator-Approval
- [ ] `.env.example` enthält neue Keys: `APNS_KEY_ID`, `APNS_TEAM_ID`, `APNS_PRIVATE_KEY_PATH`, `FCM_PROJECT_ID`, `FCM_SERVICE_ACCOUNT_JSON_PATH`, `MOBILE_DEEP_LINK_SCHEME`, `STORYBOOK_PUBLIC_URL`, `SDK_API_BASE_URL`
- [ ] Doku-Files vorhanden: `docs/cli/overview.md`, `docs/cli/scaffolding.md`, `docs/cli/ops.md`, `docs/contributing/storybook.md`, `docs/api/typescript-sdk.md`, `docs/mobile/capacitor-setup.md`
- [ ] Staging-Deployment auf `agent/phase-08-final`: Storybook-Static-Site online; SDK-Integration-Tests gegen Staging-API grün; iOS-Build in TestFlight-Internal verfügbar; Android-Build in Play-Internal-Track verfügbar
- [ ] Integration-Test-Flows:
- `toolctrl create-module foo` → generierter Code kompiliert, Tests grün, Sidebar-Eintrag sichtbar
- `toolctrl create-route /bar` → Route registriert, Auto-Update in `apps/web/app/routes.ts` korrekt
- `toolctrl doctor` → erkennt fehlenden Redis-Container, gibt grünes Häkchen bei korrektem Setup
- `toolctrl migrate-tenant <id> --from=staging --to=dev --dry-run` → Output zeigt alle Schritte ohne Schreib-Operationen
- SDK gegen Staging: `npm install @toolctrl/api-client-ts && client.contacts.list({ tenantId })` liefert paginated Result
- Mobile: Login mit Biometric → Push-Token-Registration → Backend triggert Test-Notification → Notification erscheint im iOS-Simulator
- [ ] Tenant-Isolation-Tests: SDK respektiert Tenant-Scope (Cross-Tenant-Read 403); Mobile-Push fan-outet nur an User des Ziel-Tenants
- [ ] `gsd-code-reviewer`-Subagent hat alle Phase-08-Commits reviewed; Findings adressiert
- [ ] Phase-Summary in dieser README.md ergänzt (siehe unten)
## Phase Summary
_(Wird nach Abschluss der Phase vom ausführenden Agent ergänzt.)_
### Lessons Learned
_(Wird nach Abschluss ergänzt — insbesondere: Storybook-vs-Test-Runner-Tradeoffs, Generator-Template-Wartbarkeit, openapi-ts-Custom-Templates-Aufwand, Capacitor-Plugin-Bugs auf iOS/Android, FCM-vs-APNs-Setup-Friktionen, Tenant-Migration-Edge-Cases.)_
## Verweise
- Detail-MD-Template: `../DETAIL-MD-TEMPLATE.md`
- Agent-Workflow: `../AGENT-INSTRUCTIONS.md`
- Execution-Order: `../00-execution-order.md`
- Live-Status: `../PROGRESS.md`
- Vorgänger-Phase: `../06-plugin-system/README.md`, `../07-chatbot/README.md`
- Nachfolger-Phase (nicht geblockt): `../10-compliance-polish/README.md`
- Externe Depends: `../03-scaling-infrastructure/backup-cli.md`, `../05-business-features/feature-flags.md`