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

18 KiB
Raw Blame History

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).