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