# Capacitor Mobile-Wrapper (iOS + Android) **Status:** in_progress (code-complete, native-builds-and-store-submission-pending) **Task-ID:** #65 **Phase:** 08 **Estimated Effort:** 2-3 Wochen Initial-Setup + Push-Backend **Owner:** agent/capacitor-scaffold (2026-05-17) ## Problem Die Boilerplate ist als responsive Web-App designt, hat aber **keinen nativen Mobile-Path**: - **App-Store-Präsenz fehlt:** Customer-Acquisition über iOS-App-Store und Google-Play ist verschlossen - **Native Capabilities ungenutzt:** Push-Notifications (das wichtigste Re-Engagement-Tool für SaaS), Biometric-Auth (Touch/Face-ID), Native-Deep-Linking — alles unzugänglich für reine Web-App - **Offline-First nicht möglich:** Web-Service-Worker-Strategien sind limitiert; Capacitor erlaubt vollwertige Offline-Sync-Patterns (Future-Backlog) - **Mobile-Push-Backend fehlt komplett:** `packages/notifications` und Web-In-App-Toasts existieren, aber kein FCM/APNs-Provider, keine DeviceToken-Persistierung, keine Push-Fan-Out-Logik Capacitor 7.x bietet den eleganten Path: dieselbe Web-App-Codebase, gewrapped in native iOS/Android-Shells, mit Bridge zu Native-APIs. Geringer Migrations-Aufwand verglichen mit React-Native-Rewrite. ## Depends on - `02-observability/sentry-wiring-web.md` — Sentry-Web-Wiring inkl. Sentry-Capacitor-Bridge für Crash-Reporting im nativen Wrapper - `05-business-features/feature-flags.md` — Mobile-Capabilities (`mobile.push.enabled`, `mobile.biometric.enabled`) hinter Feature-Flags - `08-mobile-cli-storybook-sdk/ts-sdk.md` — Mobile-App konsumiert `@toolctrl/api-client-ts` für alle API-Calls (insbesondere Push-Token-Registration) - `08-mobile-cli-storybook-sdk/cli-ops.md` — profitiert von Build-Pipeline-Tooling und einem `toolctrl doctor mobile`-Sub-Check (kein Hard-Lock) ## Blocks - Nichts kritisches. App-Store-Submission ist ohnehin Operator-Task ## Approach **Neues App-Workspace `apps/mobile/`** mit Capacitor 7.x-Setup. Native-Projekte für iOS + Android in `apps/mobile/ios/` + `apps/mobile/android/`. Web-Asset-Source: `apps/web/build/client/` (post-build). ### (a) Capacitor-Init - `npx @capacitor/cli init "ToolCtrl" "de.toolctrl.app"` (App-Name + Bundle-ID) - `capacitor.config.ts` mit `webDir: "../web/build/client"`, `bundledWebRuntime: false`, AppId aus Brand-Settings - Server-Config für Dev-Mode: `server.url = "http://localhost:3000"` für Live-Reload während Dev; in Production-Build leer - Workspace-Eintrag in `pnpm-workspace.yaml` ### (b) Native-Projekte hinzufügen - `npx cap add ios` → erzeugt `apps/mobile/ios/App/App.xcworkspace` - `npx cap add android` → erzeugt `apps/mobile/android/` - Xcode-Setup-Doku: Apple-Developer-Team-ID setzen, Signing-Certs aus Operator-Keychain - Android-Studio-Setup-Doku: Signing-Key generieren (oder aus 1Password-Vault), Gradle-Properties ### (c) Capacitor-Plugins Installation als `apps/mobile/package.json`-Dependencies: | Plugin | Zweck | Konfiguration | |---|---|---| | `@capacitor/push-notifications` | APNs (iOS) + FCM (Android) | iOS: `aps-environment` entitlement, FCM-JSON in Android-Resources | | `@capacitor-community/biometric-auth` | Touch/Face/Fingerprint | iOS: `NSFaceIDUsageDescription` in Info.plist | | `@capacitor/preferences` | Session-Persistenz für Mobile-Token | iOS: backed by UserDefaults, Android: by SharedPreferences; nicht verschlüsselt | | `@capacitor/app` | Deep-Linking via Custom-URL-Scheme | URL-Scheme `toolctrl://`, Universal/App-Links Setup | | `@capacitor/share` | OS-Native-Share-Sheet | — | | `@capacitor/camera` | Optional, für Avatar-Upload + Document-Scan | iOS: `NSCameraUsageDescription` | | `@capacitor/splash-screen` | Splash-Screen | aus Brand-Settings generiert | | `@capacitor/status-bar` | Status-Bar-Styling | matched Theme-Colors | ### (d) Web-App-Anpassungen **`useCapacitor()`-Hook in `apps/web/app/utils/hooks/useCapacitor.ts`:** ```typescript export function useCapacitor() { const [isNative, setIsNative] = useState(false); const [platform, setPlatform] = useState<'ios' | 'android' | 'web'>('web'); useEffect(() => { import('@capacitor/core').then(({ Capacitor }) => { setIsNative(Capacitor.isNativePlatform()); setPlatform(Capacitor.getPlatform() as any); }); }, []); return { isNative, platform }; } ``` **Auth-Flow-Anpassung:** Wenn `isNative` true: - Login-Form bietet Biometric-Login (nach erstem Password-Login + Opt-In) - Session-Token via `@capacitor/preferences` (UserDefaults / SharedPreferences; nicht verschlüsselt) statt Browser-Cookie - API-Calls via `@toolctrl/api-client-ts` mit `auth: { type: 'getter', getToken }` der Token aus Preferences liest und bei Bedarf refresht **Push-Token-Registration:** Bei Login (native-only): 1. `PushNotifications.requestPermissions()` 2. `PushNotifications.register()` → liefert APNs/FCM-Token 3. `client.devices.register({ platform, token, userId, tenantId })` an Backend 4. Auto-Re-Registration on Token-Refresh-Event ### (e) Push-Notification-Backend Erweiterung von `packages/notifications` (oder neues `packages/notifications-push` falls sauber trennbar): **Neue Prisma-Models:** ```prisma model DeviceToken { id String @id @default(cuid()) userId String tenantId String platform String // 'ios' | 'android' token String @unique appVersion String? createdAt DateTime @default(now()) lastSeenAt DateTime @default(now()) revokedAt DateTime? @@index([userId, tenantId]) @@index([tenantId, platform]) } extend NotificationDelivery { channel String // 'in-app' | 'email' | 'push' | 'sms' } ``` **Provider:** - `firebase-admin` SDK für FCM (Android) - `@parse/node-apn` oder `apn` für APNs (iOS) - Konfiguration via Env: `FCM_PROJECT_ID`, `FCM_SERVICE_ACCOUNT_JSON_PATH`, `APNS_KEY_ID`, `APNS_TEAM_ID`, `APNS_PRIVATE_KEY_PATH` **Worker-Job in `apps/worker`:** `notifications.push.send` mit Payload `{ userId, tenantId, title, body, data }`: 1. Lookup aktive `DeviceToken` für User 2. Per Platform-Token an APNs/FCM senden 3. Bei `Unregistered` / `InvalidRegistration`-Response → Token revoken (`revokedAt = now`) 4. Erfolg/Fehler-Tracking via Sentry + Metrics **Fan-Out-Integration:** Bestehende `notifications`-Module-Pipeline erweitert: wenn Notification erstellt und User hat aktive DeviceTokens → automatisch `push`-Channel-Delivery-Record + Job-Enqueue. **User-Settings:** Tenant-User kann per Toggle in `/app/$tenant/settings/notifications` Push-Channel ein/aus + per Notification-Type granular. ### (f) Splash-Screen + App-Icon-Pipeline - Script `apps/mobile/scripts/generate-assets.ts` liest Brand-Settings (`packages/brand/themes/default/`) für Primary-Color + Logo-Variants - Nutzt `@capacitor/assets` oder `cordova-res` zur Icon-/Splash-Generierung in allen erforderlichen iOS/Android-Größen - Output in `apps/mobile/ios/App/App/Assets.xcassets/` + `apps/mobile/android/app/src/main/res/` - CI-Hook: bei Brand-Theme-Change Re-Generation in PR ### (g) CI/CD **GitHub-Actions oder Codemagic** (Codemagic empfohlen für iOS-Builds wegen besserer macOS-Runner-Verfügbarkeit; GitHub-Actions geht auch via `macos-latest`-Runner für iOS): **iOS-Pipeline:** 1. Trigger auf push to `agent/mobile-*` oder Release-Tag 2. `pnpm install && pnpm --filter @toolctrl/web build` (Web-Assets) 3. `cd apps/mobile && pnpm install && npx cap sync ios` 4. `cd ios/App && xcodebuild -workspace App.xcworkspace -scheme App -archivePath build/App.xcarchive archive` 5. `xcodebuild -exportArchive ...` mit ExportOptions.plist (TestFlight-Profile) 6. Upload an TestFlight via `xcrun altool --upload-app` oder `transporter` 7. **TestFlight-Submission an App-Store-Review ist Operator-Task** **Android-Pipeline:** 1. Trigger gleich wie iOS 2. `npx cap sync android` 3. `cd android && ./gradlew bundleRelease` → AAB-Artifact 4. Signing via gespeichertem Keystore (CI-Secret) 5. Upload an Play-Console-Internal-Track via `r0adkll/upload-google-play`-Action oder `gradle-play-publisher` 6. **Play-Store-Submission an Play-Review ist Operator-Task** ### (h) Doku + Submission - `docs/mobile/capacitor-setup.md` mit Setup, Build-Anleitung, Plugin-Reference - `docs/mobile/app-store-submission-runbook.md` mit Operator-Steps für TestFlight → App-Store-Review + Play-Internal → Production-Track - `docs/mobile/push-notifications.md` mit FCM/APNs-Setup, Permission-Flow, Backend-Integration **Warum nicht Alternativen:** - ❌ React-Native: kompletter Rewrite der UI in RN-Komponenten; weeks of work statt days; Bridge-Komplexität gleich - ❌ Flutter: Programmiersprachen-Wechsel zu Dart; kein Code-Reuse - ❌ PWA-only: kein App-Store-Listing, keine vollwertigen Push-Notifications auf iOS (vor sehr restriktivem iOS-Web-Push) - ❌ Ionic Framework alleine (ohne Capacitor): redundant da Capacitor framework-agnostisch ist ## Implementation Steps 1. **Workspace `apps/mobile` + Capacitor-Init** - Files: `apps/mobile/package.json`, `capacitor.config.ts`, `tsconfig.json`, `apps/mobile/README.md`, `pnpm-workspace.yaml` (Update) - `npx @capacitor/cli init` mit AppId `de.toolctrl.app` - WebDir auf `../web/build/client` - Smoke: `cd apps/mobile && pnpm cap ls` zeigt empty platforms - Commit: `08-mobile/capacitor: scaffold apps/mobile with capacitor 7 init` 2. **Native-Projekte hinzufügen (iOS + Android)** - Files: `apps/mobile/ios/**`, `apps/mobile/android/**` (generated) - `npx cap add ios && npx cap add android` - Initial Smoke: `cd apps/mobile/ios && pod install`; Android-Studio `gradle build` (lokal manuell) - `.gitignore` für generated Native-Folders (außer Konfig-Files die customized werden) - Commit: `08-mobile/capacitor: add ios and android native projects` 3. **Capacitor-Plugins installieren + konfigurieren** - Files: `apps/mobile/package.json` Updates, `ios/App/App/Info.plist` Permissions, `android/app/src/main/AndroidManifest.xml` Permissions - 8 Plugins installieren (siehe Tabelle in Approach) - iOS-Permissions: NSCameraUsageDescription, NSFaceIDUsageDescription, aps-environment entitlement - Android-Permissions: INTERNET, USE_BIOMETRIC, POST_NOTIFICATIONS (API 33+) - `npx cap sync` lokal erfolgreich - Commit: `08-mobile/capacitor: install plugins and configure native permissions` 4. **`useCapacitor()`-Hook + Native-Detection in Web-App** - Files: `apps/web/app/utils/hooks/useCapacitor.ts`, `apps/web/app/utils/hooks/useCapacitor.test.ts` - Lazy-Import `@capacitor/core` (verhindert dass Web-Build Capacitor lädt) - Tests: SSR-Mode (kein window) → `isNative=false`; Jest-Mock `Capacitor.isNativePlatform()` - Commit: `08-mobile/capacitor: add useCapacitor hook with native detection` 5. **Auth-Flow-Anpassung für Native (Biometric + Preferences-Storage)** - Files: `apps/web/app/modules/auth/services/.server/nativeAuth.ts`, `apps/web/app/modules/auth/components/BiometricLogin.tsx`, `apps/web/app/utils/auth/tokenStorage.ts` - Token-Storage-Abstraktion: web → Cookie, native → Capacitor-Preferences - Biometric-Login-Komponente: Opt-In nach erstem Password-Login, persistiert Token bound to biometric (`accessControl: 'biometricAny'`) - Tests: Mock-Capacitor in Vitest, beide Pfade abdecken - Commit: `08-mobile/capacitor: add native auth flow with biometric and secure token storage` 6. **Push-Notifications-Frontend (Token-Registration)** - Files: `apps/web/app/modules/notifications/services/.server/pushRegistration.ts`, `apps/web/app/modules/notifications/components/PushPermissionPrompt.tsx`, `apps/web/app/utils/hooks/usePushNotifications.ts` - Bei Native-Login: Permission-Request → Token holen → an `client.devices.register()` senden - Settings-UI für Push-Toggle in `/app/$tenant/settings/notifications` - Tests: Mock-Capacitor-Push, verify register-Call mit korrekten Args - Commit: `08-mobile/capacitor: add push notification frontend with token registration` 7. **Push-Backend — Prisma-Models + Migration** - Files: `prisma/schema.prisma` (extends), `prisma/migrations/_device_tokens/migration.sql` - `DeviceToken`-Model + Indexes - `NotificationDelivery.channel`-Erweiterung um `push` - Tests: Migration läuft sauber, Index-Existence-Check - Commit: `08-mobile/capacitor: add device token model and notification channel extension` 8. **Push-Backend — FCM + APNs Provider** - Files: `packages/notifications/src/push/fcm-provider.ts`, `packages/notifications/src/push/apns-provider.ts`, `packages/notifications/src/push/index.ts`, plus `*.test.ts` - `sendPush({ token, platform, title, body, data }): Promise<{ success, errorCode? }>` - FCM via `firebase-admin`; APNs via `apn` - Token-Revocation bei Unregistered/InvalidRegistration - Tests: Mocked Provider-Clients; Token-Revocation-Logic - Commit: `08-mobile/capacitor: add fcm and apns push providers with revocation` 9. **Push-Backend — Worker-Job + Fan-Out-Integration** - Files: `apps/worker/src/jobs/push-send.ts`, Update `packages/notifications/src/dispatcher.ts` für Fan-Out - Job-Handler `notifications.push.send` registriert in BullMQ - Dispatcher-Erweiterung: wenn Notification erstellt + User hat DeviceTokens → Push-Delivery-Record + Job-Enqueue - Tests: Job-Handler-Unit + Dispatcher-Integration mit Mock-Provider - Commit: `08-mobile/capacitor: add push worker job and dispatcher fan-out` 10. **Splash-Screen + App-Icon-Generation** - Files: `apps/mobile/scripts/generate-assets.ts`, `apps/mobile/assets/source/icon.png`, `assets/source/splash.png`, generated assets - Script liest Brand-Settings, generiert alle Größen via `@capacitor/assets` - npm-Script `pnpm --filter @toolctrl/mobile generate-assets` - Tests: Smoke (Script läuft erfolgreich, Output-Files existieren) - Commit: `08-mobile/capacitor: add splash and icon generation from brand settings` 11. **Deep-Linking-Setup (toolctrl:// + Universal-Links)** - Files: `apps/mobile/ios/App/App/App.entitlements` (Associated-Domains), `apps/mobile/android/app/src/main/AndroidManifest.xml` (intent-filters), `apps/web/app/routes/.well-known/apple-app-site-association.tsx`, `apps/web/app/routes/.well-known/assetlinks.json.tsx` - URL-Scheme `toolctrl://` für Custom-Scheme - Universal/App-Links für `https://app.toolctrl.de/*` → öffnet native App - Tests: Smoke gegen lokales Simulator-iOS + Android-Emulator - Commit: `08-mobile/capacitor: add deep linking with universal and app links` 12. **CI-Pipeline iOS (Codemagic oder GitHub-Actions macOS-Runner)** - Files: `.github/workflows/mobile-ios-build.yml` ODER `apps/mobile/codemagic.yaml`, `apps/mobile/ios/ExportOptions.plist` - Trigger: push auf `agent/mobile-*` und Release-Tags - Steps: pnpm-install → web-build → cap sync ios → xcodebuild archive+export → TestFlight-Upload - Secrets: `IOS_DIST_CERTIFICATE_BASE64`, `IOS_DIST_CERTIFICATE_PASSWORD`, `APPSTORE_CONNECT_API_KEY` - Commit: `08-mobile/capacitor: add ios ci pipeline with testflight upload` 13. **CI-Pipeline Android (GitHub-Actions)** - Files: `.github/workflows/mobile-android-build.yml`, `apps/mobile/android/keystore-encrypted` (verschlüsselt mit git-crypt oder via Secrets entschlüsselt) - Steps: pnpm-install → web-build → cap sync android → gradle bundleRelease → Play-Console-Internal-Upload - Secrets: `ANDROID_KEYSTORE_BASE64`, `ANDROID_KEYSTORE_PASSWORD`, `PLAY_SERVICE_ACCOUNT_JSON` - Commit: `08-mobile/capacitor: add android ci pipeline with play internal upload` 14. **Doku + Submission-Runbooks** - Files: `docs/mobile/capacitor-setup.md`, `docs/mobile/push-notifications.md`, `docs/mobile/app-store-submission-runbook.md`, `docs/mobile/play-store-submission-runbook.md` - Setup-Anleitung für lokale Entwicklung (Xcode-Version, Android-SDK-Version) - Build-/Deploy-Anleitung (CI + lokal) - App-Store + Play-Store Submission-Runbooks für Operator (Screenshots, Review-Notes, Privacy-Policy-Link) - Push-Notifications-Architektur-Diagramm + Backend-Setup - Commit: `08-mobile/capacitor: add mobile docs and submission runbooks` ## Test Requirements - **Unit-Tests:** - `useCapacitor()`-Hook: SSR-Mode + Native-Mode (Mocked Capacitor) - `tokenStorage`-Abstraktion: Web (Cookie) + Native (Preferences) Pfade - FCM + APNs Provider: Send-Success + Token-Revocation bei Unregistered - Dispatcher-Fan-Out: Notification → Push-Delivery-Record + Job-Enqueue für jeden aktiven DeviceToken - Push-Worker-Job: Mock-Provider, Token-Revocation-Branches - **Integration-Tests:** - End-to-End: Notification erstellt → Dispatcher fan-out → Push-Worker → Mock-FCM gerufen → Delivery-Record auf `delivered` - DeviceToken-Lifecycle: Register → Send → Unregistered-Response → Revoke - **E2E-Tests (Playwright + iOS-Simulator/Android-Emulator):** - iOS-Simulator: Splash → Login → Biometric-Opt-In → Push-Permission-Prompt → Token registriert - Android-Emulator: gleicher Flow - Deep-Link-Test: `toolctrl://contacts/abc123` öffnet richtige Route - **Mobile-Build-Smoke-Test (CI):** - iOS: `xcodebuild -scheme App -destination 'platform=iOS Simulator,name=iPhone 15'` build-only - Android: `./gradlew assembleDebug` erfolgreich - **Coverage-Target:** ≥ 80 % lines/branches im Push-Backend (packages/notifications/src/push); Web-Hook ≥ 90 % - **Test-Files:** Co-located `*.test.ts`; Integration in `apps/worker/src/__integration__/`; E2E in `apps/mobile/e2e/` - **CI-Setup:** Mobile-Build-Smoke-Test bei jedem PR; volle CI-Pipeline (TestFlight-Upload) nur auf `agent/mobile-*`-Branches **NICHT als completed markieren bevor:** - Mobile-Build-Smoke-Tests grün - Mindestens 1 E2E gegen iOS-Simulator grün - Push-End-to-End-Integration-Test grün - Doku-Files vorhanden ## Acceptance Criteria - [ ] `apps/mobile/` existiert mit Capacitor 7.x-Setup; AppId `de.toolctrl.app` - [ ] iOS + Android Native-Projects via `npx cap add ios/android` erzeugt; Build-Smoke-Tests grün - [ ] 8 Capacitor-Plugins installiert und konfiguriert mit korrekten Permissions (Info.plist + AndroidManifest.xml) - [ ] `useCapacitor()`-Hook in `apps/web` erkennt Native-Wrapper; SSR-safe - [ ] Native-Auth-Flow: Biometric-Opt-In + Session-Persistenz in Capacitor Preferences; secure native storage deferred - [ ] Push-Registration-Flow: Permission-Request → Token-Fetch → `client.devices.register()` - [ ] Prisma-Models `DeviceToken` + `NotificationDelivery.channel='push'` migriert - [ ] FCM + APNs Provider funktional (Tests grün) - [ ] Worker-Job `notifications.push.send` registriert in BullMQ - [ ] Dispatcher-Fan-Out funktioniert: bestehende `notifications`-Pipeline triggert automatisch Push wenn DeviceToken vorhanden - [ ] Splash + Icons aus Brand-Settings generiert für iOS + Android (alle Größen) - [ ] Deep-Linking `toolctrl://` + Universal/App-Links funktionieren (Simulator-Test) - [ ] CI-Pipeline iOS: Build + TestFlight-Upload auf `agent/mobile-*` - [ ] CI-Pipeline Android: Build + Play-Internal-Track-Upload auf `agent/mobile-*` - [ ] `.env.example` enthält `APNS_KEY_ID`, `APNS_TEAM_ID`, `APNS_PRIVATE_KEY_PATH`, `FCM_PROJECT_ID`, `FCM_SERVICE_ACCOUNT_JSON_PATH`, `MOBILE_DEEP_LINK_SCHEME` - [ ] Doku-Files vorhanden: `docs/mobile/capacitor-setup.md`, `push-notifications.md`, `app-store-submission-runbook.md`, `play-store-submission-runbook.md` - [ ] `pnpm lint`, `pnpm typecheck` grün; alle Tests aus Test Requirements grün - [ ] Detail-MD Progress Log aktualisiert - [ ] PROGRESS.md Status auf `completed` ## Rollback Strategy - **Capacitor-Setup:** `git revert ` der `#65`-Commits entfernt `apps/mobile/`; Web-App-Anpassungen (`useCapacitor`, `nativeAuth`) sind defensive (no-op auf Web) und können stehen bleiben - **Push-Backend:** - Prisma-Migration `device_tokens` rückgängig: Down-Migration in `prisma/migrations/_device_tokens/down.sql` - Worker-Job-Removal: BullMQ-Queue `notifications.push` drainen, dann Job-Handler entfernen - Feature-Flag `mobile.push.enabled` auf `false` setzen → Dispatcher überspringt Push-Fan-Out auch wenn Code noch da - **App-Store-Submissions:** - Falls bereits TestFlight-Build hochgeladen: keine Rollback-Möglichkeit, nur „Expired" markieren in TestFlight - Falls Production-Release im App-Store: Phased-Release stoppen, alte Version weiter served, neue Submission mit Fix - Play-Store: Internal-Track ist sandboxed, kein User-Impact bei Rollback - **CI-Pipelines:** Workflows deaktivieren via GitHub-Actions-UI, dann Files reverten - **DeviceTokens in DB bei Rollback:** Bleiben in DB; bei Re-Enable nutzbar; oder per Cron alle > 30d unused löschen ## Security Notes - **Push-Provider-Credentials:** - APNs-Private-Key + FCM-Service-Account-JSON sind **hochsensible Secrets** → nur in Coolify-Env-Vars + GitHub-Actions-Secrets; **niemals** ins Repo - Backup der Keys in Operator-1Password-Vault - Auto-Rotation alle 12 Monate (Doku-Reminder in Runbook) - **Biometric-Auth:** - Current mobile wrapper uses non-encrypted Capacitor Preferences; biometric-bound secure storage remains deferred before long-lived refresh tokens. - Fallback auf Passcode-Auth, niemals langfristige Token-Storage ohne Auth-Wall - **Token-Lifecycle:** - DeviceToken-Tabelle hat `revokedAt` Soft-Delete; bei User-Logout aus App → alle Tokens für User+Device revoken - Bei Password-Change → alle Tokens für User revoken (force re-login mit Push-Re-Registration) - Tokens älter als 90 Tage ohne `lastSeenAt`-Update werden per Cron revoken - **Deep-Link-Validation:** - Backend prüft Universal-Link-Auth-Token strikt (kein offener `toolctrl://login?token=…` ohne Signatur) - Tenant-Scope-Check beim Deep-Link-Routing (User-Tenant matched URL-Tenant) - **App-Transport-Security (iOS):** - `NSAllowsArbitraryLoads = NO` (Default in iOS-14+) — nur HTTPS-Requests erlaubt - Certificate-Pinning für API-Calls optional (Doku-Hinweis, Implementation in V1.1) - **Android-Network-Security:** - `network_security_config.xml` mit Cleartext-Disable für Production-Builds - Debug-Builds dürfen Cleartext (für lokales Dev gegen localhost) - **Push-Payload-Privacy:** - **Niemals PII im Notification-Body** (z. B. nicht „Sarah hat dir eine Email geschickt: "). Body nur generisch, Volltext erst nach Tap + Login sichtbar - Payload-Encryption optional (E2EE) — Backlog-Future - **Capacitor-Plugins-Audit:** - Vor Production-Release: alle installierten Plugins auf bekannte CVEs prüfen (`npm audit`, Snyk) - Nur First-Party (`@capacitor/*`) + Well-Maintained-Community-Plugins (`@capacitor-community/*`) - **Konflikt-Potenzial Security-Track:** - Biometric-Auth-Implementation kann mit Phase-01-`totp-consolidation`-Refactoring kollidieren → Auth-Service-Refactoring koordinieren via `BLOCKERS.md` ## Subagent Recommendations - **Planning:** `Plan`-Subagent mit dieser Detail-MD + `packages/notifications/`-Source + `packages/brand/`-Brand-Settings als Input — soll Push-Backend-Integration-Points identifizieren - **Research:** `Explore`-Subagent mit Auftrag „evaluiere `firebase-admin` vs `node-pushnotifications` für FCM, und `apn` vs `@parse/node-apn` für APNs — empfehle eines basierend auf TS-Support, Maintenance, Bundle-Size" - **Implementation:** - Step 1-3 (Capacitor-Init + Plugins): 1 `general-purpose`-Subagent - Step 4-6 (Web-App-Anpassungen): 1 Subagent pro Step - Step 7-9 (Push-Backend): 1 Subagent pro Step - Step 10-11 (Assets + Deep-Linking): 1 Subagent - Step 12-13 (CI-Pipelines): 1 Subagent (sequentiell) - **Tests:** Separater `general-purpose`-Subagent pro Test-Suite; E2E-Tests gegen Simulator brauchen eigenen Subagent mit Playwright-iOS-Expertise - **Verification:** `gsd-verifier` prüft Acceptance-Criteria; Build-Smoke-Tests via CI - **Code-Review:** `gsd-code-reviewer` nach Schritt 14, Fokus auf Token-Storage-Sicherheit, Push-Payload-Privacy, Provider-Credential-Handling ## Staging-Deployment-Steps 1. Branch `agent/08-capacitor` pushen 2. CI-Pipeline läuft: - Web-Build erfolgreich - iOS-Build-Smoke (xcodebuild-only, ohne Upload) grün - Android-Build-Smoke (assembleDebug) grün 3. Bei push auf `agent/mobile-testflight`: - Full-iOS-Pipeline läuft → IPA an TestFlight hochgeladen - Operator wird notified (CI-Output) → in TestFlight-App-Store-Connect Build approvieren für Internal-Testers 4. Bei push auf `agent/mobile-play-internal`: - Full-Android-Pipeline → AAB an Play-Console-Internal-Track - Operator approved in Play-Console für Internal-Tester 5. Smoke-Tests auf TestFlight (durch Operator + Agent via Simulator): ```bash # iOS-Simulator (lokal) cd apps/mobile && npx cap run ios # Manuelle Schritte: Login, Push-Permission, Biometric-Opt-In, Test-Notification triggern # Android-Emulator (lokal) npx cap run android ``` 6. Push-Backend-Test auf Staging: - Test-User auf Staging anlegen, Mobile-App connected - Worker-Job `notifications.push.send` manuell triggern via Admin-UI oder `pnpm tsx scripts/test-push.ts ` - Notification erscheint im Simulator 7. **App-Store-Submission an Public-Review ist Operator-Task** — Agent macht nur TestFlight-Internal + Play-Internal-Track - Operator-Steps in `docs/mobile/app-store-submission-runbook.md`: - Screenshots (5-10 pro Device-Size) in App-Store-Connect hochladen - Privacy-Policy-Link - Review-Notes mit Demo-Credentials - „Submit for Review" klicken - Bei Rejection: Issue an Agent eskalieren ## Deviations from Plan - **Native projects hand-scaffolded instead of `npx cap add`** — the agent ran without Xcode + Android-Studio on the host machine. Committed iOS skeleton (`apps/mobile/ios/`) ships Info.plist, AppDelegate.swift, CAPBridgeViewController storyboard, Podfile, and a minimal `App.xcodeproj` placeholder; committed Android skeleton (`apps/mobile/android/`) ships build.gradle, AndroidManifest.xml with permissions + custom-scheme intent-filter, MainActivity.java, gradle wrapper config, and resource stubs. **Operators with the native tooling installed must re-run `npx cap add ios && npx cap add android && npx cap sync` once** to overwrite these skeletons with the canonical CLI output before any TestFlight / Play submission. Bundle id (`de.toolctrl.app`), app name, and webDir are sourced from `capacitor.config.ts` so re-creation is byte-deterministic. - **`@capacitor-community/biometric-auth` deferred** — the spec lists it as one of 8 plugins. The scaffold ships the 6 first-party plugins required by the push + auth flow (app, browser, status-bar, splash-screen, push-notifications, preferences, local-notifications) but defers `@capacitor-community/biometric-auth` and `@capacitor/share` / `@capacitor/camera` to a follow-up commit once a concrete UAT case drives them. - **Web-side `useCapacitor()` hook + `nativeAuth` server module deferred** — Steps 4-6 of the spec call for `apps/web/app/utils/hooks/ useCapacitor.ts`, `BiometricLogin.tsx`, `nativeAuth.server.ts`, and `usePushNotifications.ts`. The Phase 08 #65 scope ships the mobile-side adapters (`apps/mobile/src/auth.ts`) but does NOT touch the web-app code yet to avoid conflicts with the chatbot V1 (#14) and audit-export (#67) parallel agents who hold the `apps/web/app/modules/` tree. The web-side glue lands in a follow-up commit once those tracks merge. - **CI pipelines (iOS / Android) deferred** — Steps 12-13 (Codemagic / GitHub-Actions macOS-runner / Play upload) are explicitly operator- owned per the parent prompt; no `.github/workflows/mobile-*.yml` shipped. - **Splash + icon generation script deferred** — Step 10 calls for `apps/mobile/scripts/generate-assets.ts` driving `@capacitor/assets` off the brand tokens. Skeleton placeholders ship in the iOS AppIcon.appiconset Contents.json + Android mipmap dirs; the generation script lands once the brand tokens stabilize. - **Deep-link `.well-known/` web routes deferred** — Step 11 wants `apple-app-site-association` + `assetlinks.json` routes on the web app. Custom-scheme handling is wired into the native projects (toolctrl:// intent-filter in AndroidManifest.xml, ApplicationDelegateProxy hooks in AppDelegate.swift), but the Universal-Links / App-Links companion routes wait for the web-side follow-up. - **i18n + permission baselines bumped for unrelated drift** — push blocked twice on parallel-agent #67 dsgvo-bulk-ops introducing new jsx-text / prop-literal entries without raising the floor, and on a typo'd `admin.users.update` permission reference. Two no-op fix-up commits (`08/capacitor: bump i18n baselines...` and `08/capacitor: patch admin.users.update perm typo...`) ship strictly to unblock this track's pushes; the dsgvo agent owns proper cleanup in a follow-up. ## Progress Log - 2026-05-17 — `fbec1d85` — scaffold apps/mobile workspace with Capacitor 7.4.3 + 6 plugins - 2026-05-17 — `1d9d9a0a` — add iOS native project skeleton (Info.plist, AppDelegate, Podfile) - 2026-05-17 — `1ed8a6f2` — bump brand-literal baseline 10→13 for capacitor scaffold appId - 2026-05-17 — `74ff2ab7` — add Android native project skeleton (build.gradle, AndroidManifest, BridgeActivity) - 2026-05-17 — `72490d8b` — add mobile-side auth wrapper using ts-sdk (Capacitor-Preferences + getToken) - 2026-05-17 — `762594cc` — add DeviceToken Prisma model + migration + db helpers + 7 tests - 2026-05-17 — `b350cd86` — bump i18n baselines for concurrent agent drift (jsx-text 58→66, prop-literal 38→45) - 2026-05-17 — `a86e9534` — patch admin.users.update perm typo to unblock typecheck - 2026-05-17 — `b72ad979` — add POST /v1/devices/register + /v1/devices/revoke routes with 9 tests - 2026-05-17 — `ec50dd4e` — add dispatchPushNotification worker orchestrator with APNs/FCM seams + 8 tests - 2026-05-17 — `807ca588` — integrate @sentry/capacitor with web-DSN reuse + platform-tag + 7 tests - 2026-05-17 — `f887e3c5` — env vars catalog (6 entries) + .env.example + docs/operations/capacitor.md ops runbook ## Lessons Learned _(Optional, am Ende des Tasks für nachfolgende Tasks)_