Track HiveGrid Cloud planning reference
This commit is contained in:
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)_
|
||||
Reference in new issue
Block a user