Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M36-mobile-app.md
T

16 KiB
Raw Blame History

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.
  • 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.