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

30 KiB

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:

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:

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/<ts>_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 <range> 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/<ts>_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):
    # 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 <userId>
    • 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)