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 doctorreportet aktive Flags pro Tenant) und vom Mobile-Wrapper für Capability-Gating (Push erst aktivieren wenn Flagmobile.push.enabledan 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-tenantaufsetzt. 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 unterapps/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).#61braucht#46. - Track D — Mobile (
#65): Capacitor-Setup, Native-Projects, Plugins, Web-App-Anpassungen, Push-Backend, CI-Pipeline. Profitiert wenn#61 cli-opsbereits einentoolctrl 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
completedinPROGRESS.md pnpm lint,pnpm typecheck,pnpm testglobal grün- CLI-Binary
toolctrlinstalliert viapnpm install -g @toolctrl/clioder vianpx @toolctrl/cli; alle dokumentierten Commands runable - CLI-Snapshot-Tests grün: Module/Route/Entity-Generator-Output exakt wie gespeicherte Snapshots
apps/storybook/startbar mitpnpm --filter @toolctrl/storybook dev; Static-Build deployed unterhttps://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-tspackages/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 syncerfolgreich- Push-Notification-Backend in
apps/workeroderpackages/notificationsaktiv: FCM + APNs Provider, DeviceToken-Model, Auto-Fan-Out ausnotifications-Modul useCapacitor()-Hook inapps/webdetected 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.exampleenthä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 sichtbartoolctrl create-route /bar→ Route registriert, Auto-Update inapps/web/app/routes.tskorrekttoolctrl doctor→ erkennt fehlenden Redis-Container, gibt grünes Häkchen bei korrektem Setuptoolctrl 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