Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,489 @@
# 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/<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: <Volltext>"). 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 <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)_