further rework to the documentation

2025-11-20 12:31:21 +01:00
parent 6afa44d947
commit 9afcaa7836
90 changed files with 1721 additions and 29 deletions
--- a/docs/archive/prp/tenant-app-specs/capacitor-setup.md
+++ b/docs/archive/prp/tenant-app-specs/capacitor-setup.md
@@ -0,0 +1,155 @@
+# 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**: liegt unter `public/manifest.json` (Scope `/event-admin/`, Theme-Farbe `#f43f5e`, Shortcuts für Welcome & Dashboard).
+  - **Service Worker**: `public/admin-sw.js` cached Shell + Assets, liefert Offline-Fallback `/event-admin` für Navigations-Anfragen.
+  - **Distribution**: Hosting auf `admin.fotospiel.app` mit A2HS-Prompt; Bubblewrap/TWA nutzt `https://admin.fotospiel.app/manifest.json`.
+
+### 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.