# Boilerplate-Abgleich — M36 Mobile-App (Capacitor) - **Modul-ID:** M36 - **Name:** Mobile-App (Capacitor-Wrapper für iOS + Android) - **Zugehörige Milestones:** M167 (Capacitor-Setup + Build-Pipeline), M168 (Native-Features Push/Face-ID/Kamera + Universal Links), M169 (Native Tab-Bar + Mobile-First-Routes), M170 (Offline-Modus Phase-1-Pflicht), M171 (App-Store-Compliance + Force-Update) - **Pflichtenheft-Block:** Block 7 (Plattform-Außenseite), Pflichtenheft-Modul 36 - **Reuse-Level:** **medium** ## Kurzfazit Die Boilerplate liefert ein **vollständiges, getestetes Capacitor-7-Wrapper-Grundgerüst** (`apps/mobile`) inkl. der serverseitigen Push-Pipeline — das ist genau das Fundament, das M36 braucht und das normalerweise teuer zu bauen ist. **Stark abgedeckt:** Capacitor-Setup (M167), Push-End-to-End (M168 Teil C.1, M22-Dependency), Session-Persistenz, Sentry, Native-Permission-Strings (Info.plist + AndroidManifest), Shell-Mobile-Registry (Tab-Bar-Datenmodell). **Komplett fehlend:** der gesamte **Offline-Modus** (M170 — IndexedDB-Cache, OfflineSyncQueue, Sync-on-Reconnect, Konflikt-Resolution), **Biometrie/Face-ID** (M168 C.2), **Kamera-Plugin + lokales Resize** (M168 C.3), **Apple-Compliance-Schicht** (M171 — Pricing-Hide-Flag, Demo-Account, Privacy-Manifest, Submission-Playbook), **Universal-Links** (AASA/assetlinks Files), **Force-Update / Web-Bundle-Version-Check** und die Prisma-Modelle `MobileAppSession` + Biometrie-Felder. Wichtig: Die Boilerplate kennt `de.toolctrl.app` als App-ID und `ToolCtrl` als Namen — beim Übernehmen müssen App-ID, Name, Bundle-IDs, Permission-Strings und alle Klartexte auf HiveGrid umgestellt werden. Außerdem ist die Boilerplate-Auth **token-basiert ohne eigene DB-Session-Tabelle**, während M36 (über M27) eine zentrale `Session`-Tabelle voraussetzt — das ist eine Lücke, die in M27 zu schließen ist, nicht in M36. --- ## Übernehmbar aus Boilerplate | Boilerplate-Pfad | Was | Wie nutzbar | |---|---|---| | `apps/mobile/` (gesamtes Workspace) | Capacitor-7-Wrapper-Skeleton: `package.json`, `capacitor.config.ts`, `ios/`, `android/`, `src/`, `tsconfig.json`, `.gitignore` | **als-vorlage** — Struktur 1:1, aber App-ID/Name/Strings auf HiveGrid umstellen | | `apps/mobile/capacitor.config.ts` | Config mit `webDir: "../web/build/client"`, `readLiveReloadUrl()` (Live-Reload via `MOBILE_LIVE_RELOAD_URL`), Plugin-Config (Splash/StatusBar/Push/Preferences-Suite) | **anpassen** — `appId`/`appName` ändern, Plugins ergänzen (Camera, Network, Biometric) | | `apps/mobile/src/index.ts` | `bootstrapMobileShell()` — idempotenter Boot: Sentry-Init + Auth-Rehydrate + opt-in Push-Registration; test-seam-fähig | **anpassen** — Boot-Schritte um Offline-Pre-Cache + Biometrie-Rehydrate erweitern | | `apps/mobile/src/auth.ts` | Session-Persistenz-Adapter (`SessionStorage`-Interface, `MobileSession`-Typ, `rehydrateAuth`/`persistSession`/`clearSession`, `createMobileApiClient`); Capacitor-Preferences + localStorage-Fallback | **anpassen** — Achtung: Preferences ist NICHT verschlüsselt; für Biometrie-Secret muss OS-Keychain-Adapter ergänzt werden (Spec A.2-Constraint) | | `apps/mobile/src/pushRegistration.ts` | `registerPushNotifications()` — kompletter APNs/FCM-Flow: Permission-Check → Token holen (mit Timeout) → `POST /v1/devices/register`; graceful skip-reasons | **anpassen** — Endpoint-Pfad auf HiveGrid-Konvention (`/api/v1/notifications/mobile-device`), Pre-Prompt-UI ergänzen (Spec C.1) | | `apps/mobile/src/sentry.ts` | `initMobileSentry()` (Sentry-Capacitor, spiegelt Web-Sentry, platform-Tag) | **1:1** (nur DSN/Projekt-Config) | | `apps/mobile/ios/App/App/Info.plist` | Permission-Strings: `NSCameraUsageDescription`, `NSFaceIDUsageDescription`, `NSPhotoLibraryUsageDescription`, `UIBackgroundModes: remote-notification`, ATS strict | **anpassen** — Klartexte auf HiveGrid-Wortlaut (Spec C.2/C.3 Pflicht-Strings), Universal-Links-Entitlement + `PrivacyInfo.xcprivacy` ergänzen (fehlen) | | `apps/mobile/android/app/src/main/AndroidManifest.xml` | Permissions: `INTERNET`, `ACCESS_NETWORK_STATE`, `POST_NOTIFICATIONS` (API 33+), `USE_BIOMETRIC`, `CAMERA`; Custom-URL-Scheme `toolctrl://`-Intent-Filter; FileProvider | **anpassen** — Scheme auf `hivegrid://`, App-Links-Intent-Filter für `app.hivegrid.de` ergänzen, `READ_MEDIA_IMAGES` ergänzen | | `apps/worker/src/jobs/push-notification.ts` | **Push-Fan-out-Worker** — APNs/FCM/WebPush-Versand pro DeviceToken, provider-pluggable (firebase-admin + node-apn injectable), Auto-Revoke bei `Unregistered`/`InvalidRegistration`/`BadDeviceToken`; ENV: `FCM_SERVICE_ACCOUNT_JSON`, `APNS_KEY/KEY_ID/TEAM_ID/BUNDLE_ID` | **anpassen** — gehört zu M22-Push-Pipeline; M36 ist Konsument. EU-Stack-Vorgabe (Novu, LP-13) prüfen — Boilerplate nutzt direkt FCM/APNs | | `apps/api/src/routes/devices-routes.ts` | `POST /v1/devices/register` + `/v1/devices/revoke` mit Validierung, Upsert-by-token (idempotent), Klartext-Fehler-Envelope | **anpassen** — Pfad/Auth auf HiveGrid (Self-Scope statt service-credential), `tenant_id`-Multi-Registrierung pro Tenant (Spec A.1) sicherstellen | | `packages/db/src/device-tokens.server.ts` | `registerDeviceToken`/`revokeDeviceToken`/`parseDevicePlatform`/`parsePushProvider` (188 Zeilen Domänen-Logik) | **anpassen** — RLS/Tenant-Scope nach HiveGrid-Konvention | | `prisma/schema/notifications.prisma` → `DeviceToken` | Modell für APNs/FCM/WebPush-Token (`token @unique`, `pushProvider`, `appVersion`, `lastSeenAt`, `revokedAt`, User+Tenant-Relation, Indizes) | **als-vorlage** — deckt M36-Block-A.1 (`NotificationDevice`-Konsum) konzeptionell ab; in HiveGrid als M22-Entität spec'd | | `apps/web/app/lib/pwa/registerServiceWorker.ts` + `apps/web/public/sw.js` | PWA-Service-Worker-Registrierung + minimaler SW (cache-first für `/assets/`, network-first für `/api`/`/app`/`/admin`, Offline-Fallback) | **als-vorlage** — solides Fundament für M170-Offline, aber **kein** Workbox, **keine** IndexedDB/Queue-Integration; muss massiv erweitert werden | | Shell-Registry: `MobileRegistryItem`, `createMobileRegistry()` (`packages/foundation` / `packages/ui-shell`, siehe Inventur `foundation.md:77`, `ui-shell.md:59/90`) | Typ + Builder für Mobile-Tab-Bar-Einträge (priority-sortiert, `RegistryGate` für Permission+Flag) | **anpassen** — Datenmodell für M169-Tab-Bar vorhanden; eigentliche native Tab-Bar-Rendering + UI-Modus-Logik (Baustelle/Büro) fehlt | | `apps/web/public/.well-known/` | Verzeichnis existiert (aktuell `security.txt`, `pgp-key.txt`) | **als-vorlage** — Ablageort für `apple-app-site-association` + `assetlinks.json` (Spec I.1) — Dateien selbst fehlen | | `packages/api-client-ts` | TS-SDK (`createToolctrlClient`, refresh-aware Bearer via `getToken`-Callback) — vom Mobile-Wrapper konsumiert | **1:1** (HiveGrid-eigene SDK-Variante) | | `docs/operations/capacitor.md` + `docs/improvement-plan/08-mobile-cli-storybook-sdk/capacitor.md` | Build/Signing/Submission-Runbook + Spec/Deviation-Log | **als-vorlage** — Operator-Runbook übernehmen, Submission-Strategie (Spec K) ergänzen | | `package.json` `test:mobile` + `.gitea/workflows/ci.yml` (Schritt `test:mobile`) | CI-Gate für Mobile-Unit-Tests bereits verdrahtet | **1:1** (Pattern) — native Build-Pipeline (Tag `mobile-vX.Y.Z` → TestFlight/Play, Spec B.3) fehlt | | `apps/mobile/src/*.test.ts` (auth/push/sentry/index/capacitor-config) | Vitest-Tests als Test-Pattern für Mobile-Layer | **als-vorlage** | --- ## Vorhandene Daten-Modelle | Modell | Pfad | Deckt M36-Spec ab | |---|---|---| | `DeviceToken` | `prisma/schema/notifications.prisma:66` | Block A.1 (`NotificationDevice`-Konsum): `token @unique`, `pushProvider` (fcm/apns/webpush), `platform`, `appVersion`, `lastSeenAt`, `revokedAt`, User+Tenant-Relation. **Lücke:** pro-Tenant-Mehrfachregistrierung (mehrere Einträge gleicher Token + verschiedene `tenant_id`) ist nicht durch `token @unique` abgedeckt — Constraint muss in HiveGrid auf `(token, tenantId)` o.ä. angepasst werden (Spec A.1). | | `NotificationDelivery`, `UserNotificationPreference` | `prisma/schema/notifications.prisma:14/41` | Notification-Querschnitt (M22) — Channels nur `IN_APP`/`EMAIL`, **kein** `PUSH`-Channel im Preference-Enum (siehe Lücken). | | `User`, `Tenant`, `TenantUser` | `prisma/schema/accounts.prisma:1/129/286` | Auth-/Tenant-Basis, an die Device-Token + Mobile-Session hängen. | **Nicht vorhanden (M36-Spec-Modelle fehlen komplett):** - `MobileAppSession` (Spec A.2) — Device-Kind, biometric_enabled/kind, os_version, app_version, web_bundle_version, last_foreground_at, last_sync_at. **Voraussetzung-Lücke:** Es gibt in der Boilerplate gar keine zentrale Prisma-`Session`-Tabelle (Auth ist token/JWT-basiert, keine `model Session`), auf die `MobileAppSession.session_id` als FK verweisen könnte. Diese zentrale `Session`-Tabelle muss in M27 entstehen. - `OfflineSyncQueue` (Spec A.3) — ist laut Spec ohnehin client-seitig in IndexedDB (kein Cloud-Modell), aber die client-seitige Implementierung fehlt vollständig. - Biometrie-Felder/-Speicher (Spec A.2-Constraint, OS-Keychain) — Capacitor-Preferences-Adapter vorhanden, aber **unverschlüsselt**; Keychain-Adapter fehlt. --- ## Lücken / komplett neu zu bauen ### Offline-Modus (M170, Spec Block D + E) — **größte Lücke, Phase-1-Pflicht** - **Kein IndexedDB / Dexie.js** im gesamten Repo (verifiziert: kein `dexie`, kein `indexeddb`-Store-Code). - **Kein Read-Cache** (Spec A.4 — `cache.assigned_projects` etc.) und kein Pre-Cache-beim-Login-Flow (Spec D.2). - **OfflineSyncQueue** (Spec A.3/D.4) — Queue-Entität, Stati (`pending/syncing/synced/failed/conflict`), Binary-Blob-Storage für Fotos, Aufbewahrungs-/Cleanup-Logik (Spec E.6). - **Sync-on-Reconnect** (Spec E) — Trigger (Network-Wechsel/Foreground/Force-Sync/periodisch), Sync-Reihenfolge (Read-Refresh → Queue-Drain mit Idempotency-Key → Read-Refresh), Backoff-Retry, Konflikt-Erkennung (409), Last-Write-Wins + Konflikt-Resolution-UI (Spec E.3/E.4). - **Network-Status-Detection** — `@capacitor/network`-Plugin **nicht installiert**. - **Service-Worker** vorhanden, aber minimal (kein Workbox, keine Offline-Queue-Integration, keine Offline-Fallback-Page für nicht-gecachte Routen). - **Idempotenz** — HiveGrid hat M007 (Idempotenz-Wrapper) zur Wiederverwendung; Boilerplate-Wrapper hat in `devices-routes` nur Upsert-by-token, kein generischer Idempotency-Key-Mechanismus. ### Native-Features (M168, Spec Block C) - **Biometrie / Face-ID / Touch-ID (C.2)** — kein Biometric-Plugin installiert (kein `capacitor-biometric-auth` o.ä.); kein OS-Keychain-Secret-Adapter; kein Setup-/Login-Flow; kein 2FA-Interaktions-Wiring. - **Kamera (C.3)** — `@capacitor/camera` **nicht installiert**; kein Foto-Capture/Galerie-Flow, kein lokales Resize (max 2400×2400, JPEG-85), keine Offline-Foto→Queue-Anbindung. - **Push-Pre-Prompt-UI (C.1)** — Backend-Flow vorhanden, aber die User-Pre-Prompt-Erklärung VOR System-Dialog (Apple-Compliance) fehlt im Web-Code. - **Push-Empfangs-Handling** — Token-Registrierung vorhanden, aber Vordergrund-In-App-Banner + Klick→Deeplink-Routing fehlen. ### Routing / Deeplinks (M168/M169, Spec Block I) - **Universal Links (iOS) / App Links (Android)** — `apple-app-site-association` + `assetlinks.json` Dateien fehlen; nur Custom-Scheme (`toolctrl://`) im AndroidManifest vorhanden. - **Deeplink-Routing-Logik** — Auth-Status-Check, Deeplink-Park-bei-Login, Tenant-Switch-Prompt, Permission-Mismatch-Fallback (Spec I.3) fehlen. - **Native Tab-Bar (M169, Spec I.5)** — Datenmodell (`MobileRegistryItem`) vorhanden, aber kein Tab-Bar-Rendering, keine UI-Modus-Logik (Baustelle/Büro, Default-Tabs pro Modus), kein persistierter UI-Modus pro Gerät. - **Mobile-First-Routes** (M169) — neue Routen `/{tenant}/settings/security/biometric/`, `/settings/mobile/`, `/settings/mobile/storage/`, `/settings/mobile/queue/` fehlen komplett. ### Apple/Google-Compliance (M171, Spec Block F + K) - **Pricing-UI-Hide-Flag** (`IS_MOBILE_APP=true` / `PRICING_UI=false`) — nicht vorhanden; keine Verdrahtung in M28-Subscription-UI. - **Privacy-Manifest** (`PrivacyInfo.xcprivacy`) — fehlt; kein Master-Listen-generierter Build-Step; Android Data-Safety-Form ebenfalls. - **Reviewer-Demo-Account** (`apple-review`-Tenant) — fehlt; gehört zu M37-Plattform-Admin-Pflege. - **Force-Update / Web-Bundle-Version-Check** (Spec B.3/J) — kein `/api/v1/mobile/version-check`-Endpoint, kein `min_supported_app_version`-Server-State, kein Force-Update-Modal, kein Web-Bundle-Hot-Update mit Atomic-Swap. (Vorhandener `version-check.ts` ist Plugin-Runtime-intern, nicht mobile.) - **Submission-Playbook + Reject-Recovery** (Spec K) — Doku fehlt (Operator-Runbook `capacitor.md` ist Build-fokussiert, nicht Submission-Strategie). - **SIWA-Backup-Implementation** (Spec F.2) — nicht vorbereitet. ### Account-Löschung in App (M171, Spec Block G — Verweis M35) - Lokal-Cleanup bei App-Löschung (IndexedDB leeren, Keychain entfernen, Push-Token revoke) — Push-Revoke-Endpoint vorhanden, IndexedDB+Keychain-Cleanup hängt an noch zu bauenden Offline/Biometrie-Schichten. ### Native-Build-Pipeline (M167, Spec B.3) - CI-Tag `mobile-vX.Y.Z` → Multi-Pipeline (Web-Build → iOS-TestFlight + Android-Play) fehlt; nur `test:mobile`-Unit-Gate vorhanden. Echte Builds/Signing sind laut Boilerplate-Doku bewusst Operator-Tasks. ### Querschnitt-Wiring (HiveGrid-spezifisch) - Klartext-Strings (Spec L) als i18n-Keys (M002/M003), Audit-Einträge für Mobile-Aktionen (Biometrie-Setup, Account-Löschung, Konflikt-Resolution — Spec O AV#6), Feature-Flag-Schaltbarkeit (M006), Permission-Snapshot-Cache offline (Spec H.2/M.4) — alles neu zu verdrahten. --- ## Empfohlenes Vorgehen **Phase 1 — Fundament aus Boilerplate übernehmen (schnell, hoher Hebel):** 1. **`apps/mobile`-Workspace klonen** als HiveGrid-Mobile-App-Vorlage; App-ID (`de.hivegrid.app`), Name, Bundle-IDs, Custom-Scheme (`hivegrid://`) und alle Permission-Strings/Klartexte umstellen. (M167) 2. **Capacitor-Config + Live-Reload + CI-`test:mobile`-Gate** 1:1 übernehmen. (M167) 3. **Push-Pipeline übernehmen:** `devices-routes.ts` + `device-tokens.server.ts` + `DeviceToken`-Modell + Worker `push-notification.ts` — auf HiveGrid-Auth (Self-Scope), Tenant-pro-Token-Constraint und EU-Stack (Novu/LP-13 prüfen) anpassen. Verdrahtung gehört primär zu M22, M36 konsumiert. (M168 C.1) 4. **Sentry-Mobile + Auth-Rehydrate** übernehmen (`sentry.ts`, `auth.ts`-Adapter-Pattern). (M167) **Phase 2 — Native-Features ergänzen (neu, plugin-getrieben):** 5. **`@capacitor/camera` installieren** + Foto-Flow + lokales Resize; Anbindung an M52-Foto-Upload. (M168 C.3) 6. **Biometric-Plugin + OS-Keychain-Secret-Adapter** (ersetzt/ergänzt den unverschlüsselten Preferences-Adapter); Setup-/Login-Flow mit 2FA-Pflicht (M22). (M168 C.2) 7. **Universal-Links/App-Links:** AASA + `assetlinks.json` in `apps/web/public/.well-known/`, iOS-Entitlement + Android-Intent-Filter, Deeplink-Routing-Logik. (M168/M169 Block I) **Phase 3 — Offline-Modus neu bauen (größter Aufwand, Phase-1-Pflicht):** 8. **`@capacitor/network` + IndexedDB (Dexie.js)** einführen; Read-Cache-Stores (Spec A.4) + Pre-Cache-beim-Login. 9. **OfflineSyncQueue** (client-seitig) + Sync-Engine mit Idempotency-Key (M007 wiederverwenden) + Backoff + Konflikt-Erkennung + LWW-Resolution-UI. 10. **Service-Worker erweitern** (vorhandene `sw.js`/`registerServiceWorker.ts` als Basis → Workbox-Strategie + Offline-Fallback). (M170 gesamt) **Phase 4 — Compliance + Mobile-UI:** 11. **Native Tab-Bar** auf vorhandenem `MobileRegistryItem`/`createMobileRegistry` aufsetzen; UI-Modus-Logik (Baustelle/Büro) + Mobile-First-Routes + neue Settings-Routen. (M169) 12. **Pricing-Hide-Build-Flag** (`IS_MOBILE_APP`), Verdrahtung in M28-UI; Privacy-Manifest-Build-Step (Master-Liste M35/M37); Force-Update + `version-check`-Endpoint; Demo-Account (M37); Submission-Playbook-Doku. (M171) **Reihenfolge-Logik:** Erst das geschenkte Boilerplate-Fundament (Schritte 1-4) übernehmen — das eliminiert das Capacitor-/Push-Risiko sofort. Danach die echten Neubauten (Offline > Biometrie/Kamera > Compliance), bei denen die Boilerplate nur Vorlagen/Querschnitt liefert.