Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/08-mobile-cli-storybook-sdk

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