fotospiel-app/docs/prp/tenant-app-specs/capacitor-setup.md

# 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):
  ```typescript
  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):
    ```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
  <?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.