18 KiB
Phase 08 — Verification Report (Mobile/CLI/Storybook/SDK)
Verifier: Read-only Audit-Agent Datum: 2026-05-16 Geprüfte Files (6):
README.mdcli-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.mdbrauchtbackup-cli.mdaus Phase 03capacitor.mdbraucht Push-Notification-Backend (Web-Push als Vorstufe inapps/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 onlistetts-sdk.mdals 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) explizitclient.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-opsbraucht#46 backup-cli→ korrekt gesetzt in cli-ops.md -
Capacitor profitiert von
cli-opsfürtoolctrl 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-morphexplizit genannt (Step 4:patch-routes.ts,patch-sidebar.ts,patch-permissions.ts) ✓ - Auto-Register:
routes.ts+AppSidebar.tsx+seedPermissions.tsper 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>.jsonmit 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-typesals Types-Only-Package: Step 10 ✓- Drift-Check in CI: Step 2 Drift-Check-Script ✓
- Constant-Time Webhook-Verify:
crypto.timingSafeEqualexplizit ✓ - 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-associationundassetlinks.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 typecheckgrü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
composeStoriesexemplarisch (Button/Dialog/Form-Field) ✓
SDK-Integration-Tests gegen lokale API
src/__integration__/sdk-against-local-api.test.tsmit 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 altoolodertransporter✓ - Play-Internal via
r0adkll/upload-google-play✓ - Operator-Task für Public-Submission klar abgegrenzt ✓
Push-Backend APNs-Keys + FCM-Credentials
.env.exampleKeys 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-Commandtenant-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-mockals Bonus)
„C: Hey-API für TS, kein Vendor-Lock"
- ✓
@hey-api/openapi-tsexplizit, openapi-generator-cli + Kubb als Alternativen abgelehnt - ✓ Spec-Generierung läuft lokal aus
ApiSpecsService(selbst-kontrolliert, kein extern-gehostetes Tool) - ✓
@toolctrl/api-typesals 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ürclient.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: „Addupdate-notifierfor npm-version-check on CLI-startup".
Storybook-Production-Hosting
- Staging-Hosting
storybook.staging.toolctrl.deist abgedeckt - Production-Hosting (z. B.
storybook.toolctrl.deals 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):
- F6 zwingend fixen vor capacitor.md Start: Push-Fan-Out auf Outbox-Pattern umstellen oder explizit dokumentieren warum Direkt-Enqueue OK ist
- F1, F5, F7, F8, F10 als „nice-to-clarify" vor Start des jeweiligen Tracks adressieren
- F2 spätestens bei cli-scaffolding-Implementation-Step 5 (sonst falscher Pfad-Patch)
- 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).