16 KiB
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, keinemodel Session), auf dieMobileAppSession.session_idals FK verweisen könnte. Diese zentraleSession-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, keinindexeddb-Store-Code). - Kein Read-Cache (Spec A.4 —
cache.assigned_projectsetc.) 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-routesnur 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-autho.ä.); kein OS-Keychain-Secret-Adapter; kein Setup-/Login-Flow; kein 2FA-Interaktions-Wiring. - Kamera (C.3) —
@capacitor/cameranicht 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.jsonDateien 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, keinmin_supported_app_version-Server-State, kein Force-Update-Modal, kein Web-Bundle-Hot-Update mit Atomic-Swap. (Vorhandenerversion-check.tsist Plugin-Runtime-intern, nicht mobile.) - Submission-Playbook + Reject-Recovery (Spec K) — Doku fehlt (Operator-Runbook
capacitor.mdist 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; nurtest: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):
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)- Capacitor-Config + Live-Reload + CI-
test:mobile-Gate 1:1 übernehmen. (M167) - Push-Pipeline übernehmen:
devices-routes.ts+device-tokens.server.ts+DeviceToken-Modell + Workerpush-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) - 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.