Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/08-mobile-cli-storybook-sdk/VERIFICATION.md
T

290 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Phase 08 — Verification Report (Mobile/CLI/Storybook/SDK)
**Verifier:** Read-only Audit-Agent
**Datum:** 2026-05-16
**Geprüfte Files (6):**
- `README.md`
- `cli-scaffolding.md` (#60)
- `cli-ops.md` (#61)
- `storybook.md` (#62)
- `ts-sdk.md` (#63)
- `capacitor.md` (#65)
**Gesamturteil:** PASS mit kleinen Findings. Phase ist execution-ready. Keine Hard-Blocker. 14 Findings (1 MAJOR, 7 MINOR, 6 NIT/Opportunities).
---
## 1. Template-Konformität (15 Sections)
Template-Reihenfolge: Frontmatter → Problem → Depends on → Blocks → Approach → Implementation Steps → Test Requirements → Acceptance Criteria → Rollback Strategy → Security Notes → Subagent Recommendations → Staging-Deployment-Steps → Deviations from Plan → Progress Log → Lessons Learned.
| Datei | Frontmatter | Problem | Depends | Blocks | Approach | Steps | Tests | Accept | Rollback | Security | Subagents | Staging | Deviations | Progress | Lessons | Pass |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| cli-scaffolding.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | ✓ |
| cli-ops.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | ✓ |
| storybook.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | ✓ |
| ts-sdk.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | ✓ |
| capacitor.md | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | OK | ✓ |
Alle 5 Detail-MDs konform. README.md ist Phase-README (kein Template-Subjekt).
---
## 2. Dependency-Konsistenz
### Mapping gegen `00-execution-order.md`
Execution-Order sagt für Phase 08:
- Phase 01 (Deps), 02 (Sentry Web-Wiring), 05 (Feature-Flags) als External-Depends
- `cli-ops.md` braucht `backup-cli.md` aus Phase 03
- `capacitor.md` braucht Push-Notification-Backend (Web-Push als Vorstufe in `apps/worker`)
| Task | Erwartete Depends | Gesetzte Depends | Status |
|---|---|---|---|
| cli-scaffolding | Phase 01 dep-updates, Phase 05 feature-flags, Phase 06 plugin-system | dep-updates, feature-flags, audit-docs (Phase 06) | ✓ |
| cli-ops | cli-scaffolding, backup-cli (#46), tenant-snapshot (#47), Sentry | cli-scaffolding, backup-cli, tenant-snapshot, sentry-wiring-api-worker, metrics-grafana | ✓ |
| storybook | Phase 01 deps, dead-code | dep-updates, dead-code | ✓ |
| ts-sdk | Phase 01 deps, Sentry, optional feature-flags | dep-updates, sentry-wiring-api-worker, feature-flags | ✓ |
| capacitor | Sentry Web-Wiring, feature-flags, ts-sdk, Push-Backend | sentry-wiring-web, feature-flags, ts-sdk, cli-ops (soft) | ✓ |
### Parallel-Tracks (README-Behauptung vs Detail-MDs)
- README sagt: Tracks A (storybook), B (ts-sdk), C (cli-scaffolding → cli-ops), D (capacitor) parallel
- Capacitor `Depends on` listet `ts-sdk.md` als Hard-Dep — README bezeichnet das als „parallel". **MINOR Finding (F1):** Inkonsistenz. Capacitor kann nicht *gleichzeitig* mit ts-sdk gestartet werden, weil Step 6 (Push-Registration-Frontend) explizit `client.devices.register()` aus dem SDK aufruft. Realistischerweise ist Capacitor sequentiell nach ts-sdk. README sollte das klarstellen oder explizit „kann mit Stub-Client starten, finaler Wire-Up nach ts-sdk fertig" schreiben.
- README sagt: `cli-ops` braucht `#46 backup-cli` → korrekt gesetzt in cli-ops.md
- Capacitor profitiert von `cli-ops` für `toolctrl doctor mobile` → korrekt als Soft-Dep markiert
- Plugin-System (Phase 06) als External-Dep für cli-scaffolding korrekt (Plugin-Template-Generator referenziert Manifest-Format)
### Dep-Graph-Konsistenz: ✓ (mit Finding F1)
---
## 3. Implementation-Steps-Qualität
### CLI-Scaffolding (cli-scaffolding.md)
- **Templates:** Module/Route/Entity/Webhook/Plugin — alle 5 abgedeckt mit konkreten File-Listen ✓
- **AST-Patching:** `ts-morph` explizit genannt (Step 4: `patch-routes.ts`, `patch-sidebar.ts`, `patch-permissions.ts`) ✓
- **Auto-Register:** `routes.ts` + `AppSidebar.tsx` + `seedPermissions.ts` per AST ✓
- **Idempotency:** Pre-Check + alphabetisch sortierte Insertion ✓
- **Tenant-Scope:** Module-Templates injizieren `tenantId`-Scope + `assertTenantHasAccess` ✓
- **Plugin-Output außerhalb Repo:** `--output-dir`-Flag, Hinweis explizit ✓
**NIT (F2):** Step 5 erwähnt `apps/web/app/sidebar/AppSidebar.tsx` als AST-Patch-Ziel, aber gemäß `git status` der aktuellen Working-Copy gibt es `apps/web/app/application/sidebar/AppSidebar.tsx` UND `apps/web/app/components/layouts/sidebars/shadcn/app-sidebar.tsx`. Pfad-Klärung wäre für ausführenden Agent hilfreich (oder Auto-Detect implementieren).
### CLI-Ops (cli-ops.md)
- **Doctor-Probes:** 10 Stück gezählt: `db.connect`, `db.pending-migrations`, `redis.ping`, `env.catalog-drift`, `node.version`, `pnpm.lock-staleness`, `docker.containers`, `build.artifacts`, `sentry.connectivity`, `grafana.reachability` ✓
- **Migrate-Tenant 7-Step:** Pre-Flight → Source-Snapshot → DB-Restore → S3-Copy → Verify → Mark-Migrated → Cleanup ✓
- **Resumable via State-File:** JSON in `.toolctrl/migrations/<id>-<ts>.json` mit Step-Status-Tracking ✓
- **Dry-Run-Mode:** Pro Step Flag, klar getrennt ✓
- **Impersonate:** Hard-Block für Production, 15min-TTL, Audit-Log-Pflicht ✓
- **Backend-Route `api.auth.impersonate`:** Mit-implementiert in Step 10 ✓
**NIT (F3):** `db.pending-migrations`-Probe nutzt `prisma migrate status`. Wenn Probe gegen Remote-DB läuft (`--env=production`) und keine lokale Prisma-Migration-Folder existiert, kann das verwirren. Empfehlung: Probe dokumentieren als „nur sinnvoll im Local-Mode".
### Storybook (storybook.md)
- **Stories-Glob aus 3 UI-Packages:** `packages/{ui,ui-app,ui-subframe,ui-mock}/src/**/*.stories.@(ts|tsx|mdx)` — sogar 4 Packages (ui-mock ist zusätzlich) ✓
- **Theme/Brand/UI-Layer Decorators als Toolbar-Globals:** Explizit Step 2, mit Provider-Wrapping ✓
- **20 Kern-Komponenten:** Liste in Approach (Button bis EmptyState), Stories-Steps verteilt auf 4/5/6 ✓
- **Add-ons:** addon-a11y, addon-interactions, addon-themes, addon-docs, test-runner ✓
- **Visual-Regression:** Lost-Pixel als Default (Step 8), Chromatic als Optional dokumentiert ✓
**MINOR (F4):** README + Acceptance-Criteria erwähnen `packages/ui-mock` als zu aggregierendes Package, aber Approach beschreibt es nur als „ergänzt durch". Stories-Strategie für `ui-mock` bleibt vage — sollen Mock-Komponenten eigene Stories haben oder nur als Fixture-Lieferant dienen? Empfehlung: Klärung in Approach.
### TS-SDK (ts-sdk.md)
- **Hey-API für Generation:** Step 3 `@hey-api/openapi-ts` ✓
- **Higher-Level-Wrapper:** Auth (4 Strategies) + Retry + Idempotency + Pagination + Webhook-Verify alle in eigenen Implementation-Steps (4-9) ✓
- **`@toolctrl/api-types` als Types-Only-Package:** Step 10 ✓
- **Drift-Check in CI:** Step 2 Drift-Check-Script ✓
- **Constant-Time Webhook-Verify:** `crypto.timingSafeEqual` explizit ✓
- **Pagination AsyncIterator:** Cursor + Page + Link-Header alle drei Modi ✓
- **Sentry-Trace-Header-Forwarding:** In Security-Notes erwähnt ✓
**MINOR (F5):** Step 2 ruft `ApiSpecsService.generateSpecs()` „headless" auf, „Import aus apps/web mit Server-Bundle-Workaround oder Aufruf via separates Node-Script". Das ist die einzige unklare Stelle: wie genau wird der Server-Bundle-Konflikt gelöst? Eine konkretere Approach-Skizze (z. B. separater Vite/tsx-Runner mit env-Stub) würde dem Implementation-Agent Recherche-Aufwand sparen.
### Capacitor (capacitor.md)
- **8 Plugins:** Push, Biometric, Preferences, App, Share, Camera, Splash, StatusBar — alle 8 in Tabelle ✓
- **DeviceToken Prisma-Model:** Step 7 mit Schema-Snippet ✓
- **FCM + APNs Provider:** Step 8 `firebase-admin` + `apn`/`@parse/node-apn` ✓
- **Fan-Out via Notification-Dispatcher:** Step 9 erweitert `packages/notifications/src/dispatcher.ts` ✓
- **Splash + Icon Generation aus Brand-Settings:** Step 10 via `@capacitor/assets` ✓
- **Deep-Linking (Universal + App-Links):** Step 11 mit `.well-known/apple-app-site-association` und `assetlinks.json` ✓
- **`useCapacitor()`-Hook SSR-safe:** Step 4 mit lazy-import ✓
- **Biometric-bound Token:** `accessControl: 'biometricAny'` in Step 5 ✓
**MAJOR (F6):** **Fan-Out ist *nicht* über das Outbox-Pattern (Phase 03 `outbox-pattern.md`) sondern direkt aus dem Dispatcher.** Das widerspricht der Skalierungs-Foundation: alle Side-Effects (Email, Webhook, Push) sollten via Outbox laufen, sonst Risiko von Double-Send/Lost-Send wenn der API-Request-Transaktion rollback macht aber Push schon gequeued ist. Empfehlung: Step 9 erweitern um „Push-Job-Enqueue läuft via `outbox`-Event-Emit (Phase 03), nicht direkt via BullMQ-Queue-Push aus Request-Context". Andernfalls Risiko von Inkonsistenzen zwischen DB-State und Push-Notifications.
**MINOR (F7):** Step 6 `client.devices.register()` impliziert dass das SDK eine `.devices`-Resource hat. Diese muss entweder Teil der OpenAPI-Spec sein (also Backend-Route `apps/web/app/routes/api.devices.tsx` o.ä. existiert) — der Plan dafür ist im Backend-Push-Step (7+8) nicht explizit. Add: API-Route `POST /api/devices/register` als eigener Sub-Step in Step 8 oder neuer Step.
---
## 4. Test-Requirements
### Generator-Snapshot + Smoke (cli-scaffolding)
- Snapshot-Tests pro Generator: 5 Generators × Snapshot ✓
- Smoke-Tests: `create module foo --yes` → `pnpm typecheck` grün ✓
- Coverage-Target: ≥ 85 % ✓
### Storybook Visual-Regression
- Lost-Pixel-Baseline ≤ 0.1 % Pixel-Diff ✓
- Test-Runner + A11y-Gate gegen Static-Build ✓
- Composed-Story-Tests via `composeStories` exemplarisch (Button/Dialog/Form-Field) ✓
### SDK-Integration-Tests gegen lokale API
- `src/__integration__/sdk-against-local-api.test.ts` mit Vitest-globalSetup oder testcontainers ✓
- Full E2E: Auth → List → Create → Update → Delete → Verify-Webhook ✓
- Coverage ≥ 90 % Higher-Level-Wrapper ✓
### Capacitor native-iOS/Android-E2E
- iOS-Simulator + Android-Emulator-E2E erwähnt ✓
- Build-Smoke (xcodebuild + assembleDebug) als CI-Pflicht ✓
- E2E-Files in `apps/mobile/e2e/` ✓
**MINOR (F8):** Capacitor-E2E-Test-Stack ist nicht konkret benannt. Playwright + iOS-Simulator ist Quasi-Standard, aber Playwright hat nur experimentellen iOS-Support. WebdriverIO + Appium ist robuster. Empfehlung: Approach um Test-Stack-Wahl konkretisieren (vermutlich Maestro oder Detox sinnvoller als Playwright für native E2E).
**NIT (F9):** Storybook-Test-Requirements erwähnen Story-Coverage-Audit-Script („alle Public-Komponenten aus `packages/ui` müssen mindestens 1 Story haben"), aber das Script selbst ist nicht als Implementation-Step. Wer schreibt das Audit-Script? Empfehlung: als 11. Implementation-Step ergänzen oder dem Tests-Step zuordnen.
---
## 5. Staging-Deployment-Steps
### Storybook deployt als Static-Site
- Coolify-Service-Snippet mit nginx + Traefik-Labels ✓
- Domain `storybook.staging.toolctrl.de` ✓
- Lost-Pixel-Baseline-Generation auf Staging ✓
### Capacitor TestFlight + Play-Internal-Track
- Both Pipelines (Codemagic empfohlen für iOS, GitHub-Actions auch ok) ✓
- TestFlight-Upload via `xcrun altool` oder `transporter` ✓
- Play-Internal via `r0adkll/upload-google-play` ✓
- Operator-Task für Public-Submission klar abgegrenzt ✓
### Push-Backend APNs-Keys + FCM-Credentials
- `.env.example` Keys gelistet: `APNS_KEY_ID`, `APNS_TEAM_ID`, `APNS_PRIVATE_KEY_PATH`, `FCM_PROJECT_ID`, `FCM_SERVICE_ACCOUNT_JSON_PATH` ✓
- Security-Notes: 1Password-Vault als Backup, Auto-Rotation 12 Monate, niemals in Repo ✓
- GitHub-Actions-Secrets + Coolify-Env-Vars als Speicherort ✓
**MINOR (F10):** Storage-Pfad für `APNS_PRIVATE_KEY_PATH` ist als File-Path konfiguriert, aber unklar wo das File auf Production-Server liegen soll. Empfehlung: in Doku konkret machen (z. B. `/var/secrets/apns/AuthKey_XXXXXXXXXX.p8` mit chmod 600 + nur worker-Container-Mount). Ohne diese Spezifizierung ist nicht klar wie Coolify das mountet.
**MINOR (F11):** Staging-Test in cli-ops.md (Step 4 „Test-Tenant-Migration auf Staging real durchführen") setzt voraus dass eine `staging-backup`-DB existiert. Diese ist nirgends provisioniert. Empfehlung: Pre-Req-Note in Staging-Deployment-Steps („setup separate staging-backup Postgres via docker-compose oder Coolify-Service vor Test").
---
## 6. Konsistenz mit User-Wünschen
### Capacitor für Mobile (nicht RN/PWA)
- ✓ Capacitor 7.x explizit, RN/Flutter/PWA in „Warum nicht Alternativen" begründet abgelehnt
### „A: Vollausbau CLI alle 7 Commands"
User-Anfrage zählt 7 Commands. Phase 08 deckt 5 ab:
- `create module`, `create route`, `create entity` (cli-scaffolding #60)
- `add webhook`, `add plugin-template` (cli-scaffolding #60)
- `ops doctor`, `ops migrate-tenant`, `ops impersonate` (cli-ops #61) → 3 weitere = 8 total
Plus aus Phase 03:
- `backup-cli.md` (#46) — Backup-Command
- `tenant-snapshot.md` (#47) — Snapshot-Command
Falls die „7" wörtlich gemeint sind, sind es realistisch 8-10 Commands aufgeteilt auf Phase 03 + Phase 08. **NIT (F12):** README sollte explizit listen, welche Commands wo leben — eine Übersichts-Tabelle in der Phase-08-README mit Verweis auf Phase-03-Backup-Commands wäre hilfreich für Operator-Klarheit.
### „A: Storybook alle 3 UI-Packages"
- ✓ Stories-Glob aus `ui`, `ui-app`, `ui-subframe` (+ `ui-mock` als Bonus)
### „C: Hey-API für TS, kein Vendor-Lock"
- ✓ `@hey-api/openapi-ts` explizit, openapi-generator-cli + Kubb als Alternativen abgelehnt
- ✓ Spec-Generierung läuft lokal aus `ApiSpecsService` (selbst-kontrolliert, kein extern-gehostetes Tool)
- ✓ `@toolctrl/api-types` als separates Types-Only-Package erlaubt Konsumenten ohne SDK-Runtime-Dep
---
## 7. Fehlende Aspekte
### App-Store-Submission-Workflow
- ✓ Capacitor Step 14: `docs/mobile/app-store-submission-runbook.md` + `play-store-submission-runbook.md`
- ✓ Operator-Task klar abgegrenzt (Screenshots, Privacy-Policy, Review-Notes, „Submit for Review")
- **MINOR (F13):** Privacy-Policy-Link ist erwähnt, aber Apple Privacy-Manifest (`PrivacyInfo.xcprivacy`, Pflicht seit Mai 2024 für neue Apps) ist nicht adressiert. Empfehlung: Sub-Step in Step 14 ergänzen oder dedizierten Hinweis in Security-Notes.
### Push-Token-Cleanup bei Logout
- ✓ Security-Notes Step „Token-Lifecycle": Logout revoken, Password-Change revoken, 90d-Cron
- Aber: Implementation-Steps adressieren das nicht explizit. Step 5 (`nativeAuth.ts`) sollte Token-Revoke-API-Call beim Logout enthalten. **NIT (F14):** Step 5 oder ein neuer Step für `client.devices.revoke({ tokenId })` (Backend-Route + Frontend-Trigger) ergänzen, sonst landet das in „Forgotten Detail" beim Implementation-Agent.
### CLI-Auto-Update-Mechanism
- **NICHT adressiert.** Weder cli-scaffolding noch cli-ops haben Update-Notification (z. B. `update-notifier`-Package das beim CLI-Start checkt ob neuere Version auf npm liegt). Für einen npm-published Tool ist das Standard. **Opportunity:** Sub-Step in cli-scaffolding Step 11 ergänzen: „Add `update-notifier` for npm-version-check on CLI-startup".
### Storybook-Production-Hosting
- Staging-Hosting `storybook.staging.toolctrl.de` ist abgedeckt
- Production-Hosting (z. B. `storybook.toolctrl.de` als Public-Dev-Marketing-Asset) nicht erwähnt
- Vermutlich gewollt, dass Storybook nur Staging bleibt — sollte aber explizit in README stehen. **Opportunity:** Ein Satz in Phase-Done-Definition oder Staging-Deployment-Steps: „Production-Storybook-Hosting bewusst out-of-scope".
---
## 8. Cross-Phase-Konsistenz
- ✓ Phase 06 Plugin-Manifest-Format referenziert (cli-scaffolding Step 9 für Plugin-Template-Generator)
- ✓ Phase 05 Feature-Flags referenziert (CLI-Doctor reportet Flags, Mobile-Capability-Gating)
- ✓ Phase 02 Sentry referenziert (Capacitor-Bridge, SDK-Trace-Headers, Doctor-Probe)
- ✓ Phase 03 Backup-CLI als Foundation für migrate-tenant
- ✓ Phase 03 Outbox referenziert — *außer* bei Push-Fan-Out (siehe F6 MAJOR)
---
## 9. Findings-Liste (kompakt)
| # | Schwere | Datei | Beschreibung |
|---|---|---|---|
| F1 | MINOR | README.md | Capacitor als Parallel-Track deklariert, aber hat ts-sdk als Hard-Dep — Inkonsistenz |
| F2 | NIT | cli-scaffolding.md | Sidebar-Pfad `apps/web/app/sidebar/AppSidebar.tsx` existiert in dieser Form nicht (Actual: `application/sidebar/...` + `components/layouts/sidebars/shadcn/...`); Auto-Detect oder Pfad-Klärung |
| F3 | NIT | cli-ops.md | `db.pending-migrations`-Probe Verhalten gegen Remote-DB klären |
| F4 | MINOR | storybook.md | `packages/ui-mock` Rolle in Story-Aggregation unklar |
| F5 | MINOR | ts-sdk.md | `ApiSpecsService`-headless-Call-Approach unklar (Server-Bundle-Workaround) |
| F6 | **MAJOR** | capacitor.md | Push-Fan-Out direkt aus Dispatcher statt via Outbox-Pattern — Konsistenz-Risiko bei Transaction-Rollback |
| F7 | MINOR | capacitor.md | Backend-Route `POST /api/devices/register` als Implementation-Step nicht explizit |
| F8 | MINOR | capacitor.md | Native-E2E-Test-Stack nicht benannt (Playwright iOS ist experimentell) |
| F9 | NIT | storybook.md | Story-Coverage-Audit-Script nicht als Implementation-Step |
| F10 | MINOR | capacitor.md | `APNS_PRIVATE_KEY_PATH`-Mount auf Production-Server nicht spezifiziert |
| F11 | MINOR | cli-ops.md | `staging-backup`-DB für Migrate-Tenant-Real-Test nicht provisioniert |
| F12 | NIT | README.md | „7 Commands"-Übersicht (Phase 03 + Phase 08) fehlt als zusammenhängende Tabelle |
| F13 | MINOR | capacitor.md | Apple Privacy-Manifest (`PrivacyInfo.xcprivacy`) nicht adressiert |
| F14 | NIT | capacitor.md | Push-Token-Revoke bei Logout als Implementation-Step nicht explizit |
Plus 2 Opportunities (nicht in Tabelle):
- CLI-Auto-Update-Mechanism (`update-notifier`) fehlt
- Storybook-Production-Hosting explizit als out-of-scope deklarieren
---
## 10. Gesamtbewertung
**Phase 08 ist execution-ready.** Die Detail-MDs sind durchgehend hoch-qualitativ, klar strukturiert, mit konkreten Implementation-Steps und vollständigen Acceptance-Criteria. Template-Konformität ist 100 %. Dependencies sind sauber gemappt (mit kleiner Diskrepanz F1).
**Empfohlene Pre-Execution-Aktionen (in Reihenfolge):**
1. **F6 zwingend fixen** vor capacitor.md Start: Push-Fan-Out auf Outbox-Pattern umstellen oder explizit dokumentieren warum Direkt-Enqueue OK ist
2. F1, F5, F7, F8, F10 als „nice-to-clarify" vor Start des jeweiligen Tracks adressieren
3. F2 spätestens bei cli-scaffolding-Implementation-Step 5 (sonst falscher Pfad-Patch)
4. F13 spätestens vor TestFlight-Upload (Apple Review rejected sonst)
Der Rest (Nits + Opportunities) kann während Execution adressiert werden.
**Sign-off:** PASS (mit MAJOR-Finding F6 als Hard-Recommendation für Fix vor Capacitor-Start).