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/notificationsund 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 Wrapper05-business-features/feature-flags.md— Mobile-Capabilities (mobile.push.enabled,mobile.biometric.enabled) hinter Feature-Flags08-mobile-cli-storybook-sdk/ts-sdk.md— Mobile-App konsumiert@toolctrl/api-client-tsfür alle API-Calls (insbesondere Push-Token-Registration)08-mobile-cli-storybook-sdk/cli-ops.md— profitiert von Build-Pipeline-Tooling und einemtoolctrl 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.tsmitwebDir: "../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→ erzeugtapps/mobile/ios/App/App.xcworkspacenpx cap add android→ erzeugtapps/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-tsmitauth: { type: 'getter', getToken }der Token aus Preferences liest und bei Bedarf refresht
Push-Token-Registration: Bei Login (native-only):
PushNotifications.requestPermissions()PushNotifications.register()→ liefert APNs/FCM-Tokenclient.devices.register({ platform, token, userId, tenantId })an Backend- 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-adminSDK für FCM (Android)@parse/node-apnoderapnfü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 }:
- Lookup aktive
DeviceTokenfür User - Per Platform-Token an APNs/FCM senden
- Bei
Unregistered/InvalidRegistration-Response → Token revoken (revokedAt = now) - 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.tsliest Brand-Settings (packages/brand/themes/default/) für Primary-Color + Logo-Variants - Nutzt
@capacitor/assetsodercordova-reszur 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:
- Trigger auf push to
agent/mobile-*oder Release-Tag pnpm install && pnpm --filter @toolctrl/web build(Web-Assets)cd apps/mobile && pnpm install && npx cap sync ioscd ios/App && xcodebuild -workspace App.xcworkspace -scheme App -archivePath build/App.xcarchive archivexcodebuild -exportArchive ...mit ExportOptions.plist (TestFlight-Profile)- Upload an TestFlight via
xcrun altool --upload-appodertransporter - TestFlight-Submission an App-Store-Review ist Operator-Task
Android-Pipeline:
- Trigger gleich wie iOS
npx cap sync androidcd android && ./gradlew bundleRelease→ AAB-Artifact- Signing via gespeichertem Keystore (CI-Secret)
- Upload an Play-Console-Internal-Track via
r0adkll/upload-google-play-Action odergradle-play-publisher - Play-Store-Submission an Play-Review ist Operator-Task
(h) Doku + Submission
docs/mobile/capacitor-setup.mdmit Setup, Build-Anleitung, Plugin-Referencedocs/mobile/app-store-submission-runbook.mdmit Operator-Steps für TestFlight → App-Store-Review + Play-Internal → Production-Trackdocs/mobile/push-notifications.mdmit 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
-
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 initmit AppIdde.toolctrl.app- WebDir auf
../web/build/client - Smoke:
cd apps/mobile && pnpm cap lszeigt empty platforms - Commit:
08-mobile/capacitor: scaffold apps/mobile with capacitor 7 init
- Files:
-
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-Studiogradle build(lokal manuell) .gitignorefür generated Native-Folders (außer Konfig-Files die customized werden)- Commit:
08-mobile/capacitor: add ios and android native projects
- Files:
-
Capacitor-Plugins installieren + konfigurieren
- Files:
apps/mobile/package.jsonUpdates,ios/App/App/Info.plistPermissions,android/app/src/main/AndroidManifest.xmlPermissions - 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 synclokal erfolgreich- Commit:
08-mobile/capacitor: install plugins and configure native permissions
- Files:
-
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-MockCapacitor.isNativePlatform() - Commit:
08-mobile/capacitor: add useCapacitor hook with native detection
- Files:
-
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
- Files:
-
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
- Files:
-
Push-Backend — Prisma-Models + Migration
- Files:
prisma/schema.prisma(extends),prisma/migrations/<ts>_device_tokens/migration.sql DeviceToken-Model + IndexesNotificationDelivery.channel-Erweiterung umpush- Tests: Migration läuft sauber, Index-Existence-Check
- Commit:
08-mobile/capacitor: add device token model and notification channel extension
- Files:
-
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 viaapn - Token-Revocation bei Unregistered/InvalidRegistration
- Tests: Mocked Provider-Clients; Token-Revocation-Logic
- Commit:
08-mobile/capacitor: add fcm and apns push providers with revocation
- Files:
-
Push-Backend — Worker-Job + Fan-Out-Integration
- Files:
apps/worker/src/jobs/push-send.ts, Updatepackages/notifications/src/dispatcher.tsfür Fan-Out - Job-Handler
notifications.push.sendregistriert 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
- Files:
-
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
- Files:
-
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
- Files:
-
CI-Pipeline iOS (Codemagic oder GitHub-Actions macOS-Runner)
- Files:
.github/workflows/mobile-ios-build.ymlODERapps/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
- Files:
-
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
- Files:
-
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
- Files:
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
- End-to-End: Notification erstellt → Dispatcher fan-out → Push-Worker → Mock-FCM gerufen → Delivery-Record auf
- 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 assembleDebugerfolgreich
- iOS:
- Coverage-Target: ≥ 80 % lines/branches im Push-Backend (packages/notifications/src/push); Web-Hook ≥ 90 %
- Test-Files: Co-located
*.test.ts; Integration inapps/worker/src/__integration__/; E2E inapps/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; AppIdde.toolctrl.app- iOS + Android Native-Projects via
npx cap add ios/androiderzeugt; Build-Smoke-Tests grün - 8 Capacitor-Plugins installiert und konfiguriert mit korrekten Permissions (Info.plist + AndroidManifest.xml)
useCapacitor()-Hook inapps/weberkennt 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.sendregistriert 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.exampleenthältAPNS_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 typecheckgrü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 entferntapps/mobile/; Web-App-Anpassungen (useCapacitor,nativeAuth) sind defensive (no-op auf Web) und können stehen bleiben - Push-Backend:
- Prisma-Migration
device_tokensrückgängig: Down-Migration inprisma/migrations/<ts>_device_tokens/down.sql - Worker-Job-Removal: BullMQ-Queue
notifications.pushdrainen, dann Job-Handler entfernen - Feature-Flag
mobile.push.enabledauffalsesetzen → Dispatcher überspringt Push-Fan-Out auch wenn Code noch da
- Prisma-Migration
- 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
revokedAtSoft-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
- DeviceToken-Tabelle hat
- 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)
- Backend prüft Universal-Link-Auth-Token strikt (kein offener
- 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.xmlmit 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/*)
- Vor Production-Release: alle installierten Plugins auf bekannte CVEs prüfen (
- Konflikt-Potenzial Security-Track:
- Biometric-Auth-Implementation kann mit Phase-01-
totp-consolidation-Refactoring kollidieren → Auth-Service-Refactoring koordinieren viaBLOCKERS.md
- Biometric-Auth-Implementation kann mit Phase-01-
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 „evaluierefirebase-adminvsnode-pushnotificationsfür FCM, undapnvs@parse/node-apnfü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)
- Step 1-3 (Capacitor-Init + Plugins): 1
- Tests: Separater
general-purpose-Subagent pro Test-Suite; E2E-Tests gegen Simulator brauchen eigenen Subagent mit Playwright-iOS-Expertise - Verification:
gsd-verifierprüft Acceptance-Criteria; Build-Smoke-Tests via CI - Code-Review:
gsd-code-reviewernach Schritt 14, Fokus auf Token-Storage-Sicherheit, Push-Payload-Privacy, Provider-Credential-Handling
Staging-Deployment-Steps
- Branch
agent/08-capacitorpushen - CI-Pipeline läuft:
- Web-Build erfolgreich
- iOS-Build-Smoke (xcodebuild-only, ohne Upload) grün
- Android-Build-Smoke (assembleDebug) grün
- 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
- 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
- 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 - Push-Backend-Test auf Staging:
- Test-User auf Staging anlegen, Mobile-App connected
- Worker-Job
notifications.push.sendmanuell triggern via Admin-UI oderpnpm tsx scripts/test-push.ts <userId> - Notification erscheint im Simulator
- 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
- Operator-Steps in
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 minimalApp.xcodeprojplaceholder; 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-runnpx cap add ios && npx cap add android && npx cap synconce 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 fromcapacitor.config.tsso re-creation is byte-deterministic. @capacitor-community/biometric-authdeferred — 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-authand@capacitor/share/@capacitor/camerato a follow-up commit once a concrete UAT case drives them.- Web-side
useCapacitor()hook +nativeAuthserver module deferred — Steps 4-6 of the spec call forapps/web/app/utils/hooks/ useCapacitor.ts,BiometricLogin.tsx,nativeAuth.server.ts, andusePushNotifications.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 theapps/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-*.ymlshipped. - Splash + icon generation script deferred — Step 10 calls for
apps/mobile/scripts/generate-assets.tsdriving@capacitor/assetsoff 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 wantsapple-app-site-association+assetlinks.jsonroutes 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.updatepermission reference. Two no-op fix-up commits (08/capacitor: bump i18n baselines...and08/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)