Capacitor Setup für die Tenant Admin App

Status

Version: 1.0.0 (2025-09-13)
Fokus: Mobile Packaging, Distribution und Native-Integration basierend auf ADR-0006.

Überblick

Die Tenant Admin App wird als Progressive Web App (PWA) entwickelt und mit Capacitor für native Mobile-Distribution gepackt. Dies ermöglicht:

Android: Trusted Web Activity (TWA) für Chrome-basierte Installation (Google Play) oder voller Capacitor-Build bei Bedarf an Native APIs.
iOS: Capacitor-App für App Store-Distribution mit Push-Notifications und Keychain-Support.
Web/PWA: Fallback für Browser-Installation (A2HS) mit Service Worker.

Der Build-Prozess integriert sich in das bestehende Vite-Setup (resources/js/admin). Nach npm run build wird npx cap sync ausgeführt, um die Web-Assets in native Projekte zu kopieren.

Projektstruktur

apps/admin-pwa/          # React/Vite Source (Haupt-App)
├── src/                 # Components, Pages, API
├── vite.config.ts       # Framework7 + Capacitor-Integration
├── capacitor.config.ts  # Native Config
├── android/             # Capacitor Android-Projekt (TWA oder App)
├── ios/                 # Capacitor iOS-Projekt (Xcode)
└── package.json         # Dependencies (framework7, @capacitor/*)

packages/mobile/         # Shared Native-Config (optional)
├── fastlane/            # iOS/Android Deployment
├── assetlinks.json      # TWA Digital Asset Links
└── privacy-manifest.json # iOS Privacy

Packaging und Build-Prozess

1. Vite + Framework7 Setup

Dependencies: framework7, framework7-react, @capacitor/core, @capacitor/cli.

vite.config.ts (Auszug):

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { framework7 } from 'framework7/vite';

export default defineConfig({
  plugins: [react(), framework7()],
  build: {
    outDir: 'dist',
    sourcemap: true,
  },
  define: {
    __CAPACITOR__: true, // Enable Capacitor globals
  },
});

Build-Skript (package.json): "build": "vite build && npx cap sync".

2. Capacitor Initialisierung

Befehle:

npx cap init com.fotospiel.tenantadmin "Event Photo Admin"
npx cap add android
npx cap add ios
npx cap sync  # Kopiert dist/ in native Projekte

capacitor.config.ts (siehe settings-config.md für erweiterte Plugins).

3. Android Packaging (TWA bevorzugt)

Trusted Web Activity (TWA): Für store-ready Distribution ohne vollen Native-Wrapper.
- Voraussetzungen: App bound an admin.fotospiel.app (HTTPS); Digital Asset Links.
- assetlinks.json (public/.well-known/assetlinks.json):
```
[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.fotospiel.tenantadmin",
    "sha256_cert_fingerprints": ["DE:AD:BE:EF:..."]  // Von Play Console
  }
}]
```
- Build: npx cap open android → Android Studio → Generate Signed Bundle (AAB für Play Store).
- Vorteile: Kleiner Footprint, Web-Push via Chrome; Fallback zu Capacitor bei Bedarf (z.B. Biometrie).
- TWA-Tools: npm i -g @bubblewrap/cli → bubblewrap init --manifest=https://admin.fotospiel.app/manifest.json.
Vollständiger Capacitor-Build (falls Native-Plugins benötigt):
- npx cap sync android
- npx cap open android → Build APK/AAB mit ProGuard.

4. iOS Packaging (Capacitor)

Xcode-Setup: npx cap open ios → Signing mit Apple Developer Account.

Privacy Manifest (ios/App/App/PrivacyInfo.xcprivacy):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>CA92.1</string>  <!-- Preferences für Settings -->
            </array>
        </dict>
        <!-- Push, Camera, etc. -->
    </array>
</dict>
</plist>

Build: Archive in Xcode → Upload zu App Store Connect.
Entitlements: Push-Notifications (APNs), Background App Refresh für Sync.

5. Distribution und CI/CD

Google Play:
- TWA: Internal Testing Track; Target SDK 34+; Feature: Installable.
- Fastlane: packages/mobile/fastlane/android mit supply für Metadata/Screenshots.
- Versioning: Align mit Backend (z.B. 1.0.0); Feature Flags via API.
Apple App Store:
- Capacitor: Review-Guidelines beachten (HTTPS-only, No Crash-Reporting ohne Consent).
- Fastlane: packages/mobile/fastlane/ios mit deliver für Upload.
- Privacy: Usage Descriptions in Info.plist (z.B. "Kamera für QR-Scans").
PWA-Fallback (Web):
- manifest.json: start_url: '/admin/', display: 'standalone'.
- Service Worker: Caching von Assets; Background Sync für Mutations.
- Distribution: Hosting auf admin.fotospiel.app mit A2HS-Prompt.

Native Features (Erweiterung zu settings-config.md)

Push-Notifications:
- Android: FCM-Integration; Token an Backend (POST /tenant/push-tokens).
- iOS: APNs; Silent-Pushes für Sync-Triggers.
- Cross-Platform: Capacitor Push-Plugin handhabt Plattform-Unterschiede.
Secure Storage:
- Tokens: Capacitor Preferences mit Auto-Encryption.
- Offline Data: IndexedDB (Web) + Native Storage; Encryption via Web Crypto API.
Background Processing:
- Sync: Capacitor App-State-Listener für Foreground/Background; Queue Mutations.
- iOS: Background Fetch (via Plugin); Android: WorkManager für periodische Syncs.
Biometrie (optional): @capacitor-community/biometric-auth für App-Lock.

Testing und Deployment

E2E-Tests: Cypress für Web; Detox/Appium für Native (z.B. Push-Handling).
CI/CD: GitHub Actions oder Gogs-Integration (siehe docs/prp/11-ops-ci-cd.md).
- Steps: Build → Test → Cap Sync → Fastlane Deploy (Staging → Production).
Version Alignment: App-Version matcht Backend-API-Version; Changelog in Store-Listing.

Constraints & Red-Lines

GDPR: Keine implizite Tracking; Explizite Consent für Push/Camera.
Security: HTTPS-only; Token-Rotation alle 24h; No Jailbreak-Detection.
Performance: Bundle-Size < 10MB (Web-Assets komprimiert); Lazy-Loading.

Diese Setup ergänzt die funktionalen Specs und UI-Beschreibungen. Für Repo-Integration siehe ADR-0006.

6.7 KiB Raw Blame History