4b7c605a9c
CLAUDE.md war veraltet (nannte nur ManaAuthUI). Aktualisiert auf alle drei Products (ManaAuthUI, ManaWebShell, ManaLLMUI) + dokumentiert die Entscheidung (Till, 2026-05-25), ManaWebShell trotz 0 Konsumenten zu behalten: Baustein zum schnellen Hybrid-Start neuer Apps (Web-App in nativer Schale), bevor sie schrittweise nativ werden — der Weg von zitare + seepuls. Inkl. Bootstrap-Hinweis + Entfern-Rezept. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
142 lines
5.9 KiB
Markdown
142 lines
5.9 KiB
Markdown
# CLAUDE.md — mana-swift-ui
|
||
|
||
Guidance für Claude Code in diesem Repo.
|
||
|
||
> **Übergeordneter Plan:** `../mana/docs/MANA_SWIFT.md` ist die SOT für
|
||
> die ganze native-App-Plattform. Phase ε dort beschreibt dieses Paket.
|
||
|
||
## Was dieses Repo ist
|
||
|
||
Swift-Package mit native UI-Komponenten für alle nativen
|
||
mana-e.V.-Apps. Drei Library-Products:
|
||
|
||
- **ManaAuthUI** — vollständige Auth-Reise als SwiftUI-Views:
|
||
Login, Sign-Up, Email-Verifikation, Passwort-Reset,
|
||
Account-Management. Konsumiert `ManaCore` (für API-Calls) und
|
||
`ManaTokens` (für Vereins-Designwerte). Breit konsumiert (memoro,
|
||
seepuls, mukke, herbatrium, …).
|
||
- **ManaWebShell** — dünne `WKWebView`-Hülle (`WebShellView` +
|
||
`WebShellConfig` + `WebShellScripts`) zum Anzeigen einer Web-App in
|
||
einer nativen Schale. **Siehe Retention-Hinweis unten.**
|
||
- **ManaLLMUI** — Settings-UI für lokale LLMs (konsumiert `ManaLLM`).
|
||
|
||
## ManaWebShell — bewusst behalten, aktuell ohne Konsument
|
||
|
||
**Stand 2026-05-25: ManaWebShell hat null Konsumenten.** Die beiden
|
||
Hybrid-Apps wurden voll nativ (zitare η-0..η-9, seepuls σ-7); mukkes
|
||
toter Dependency-Eintrag wurde entfernt.
|
||
|
||
**Wir behalten das Paket trotzdem** — Entscheidung Till, 2026-05-25.
|
||
Begründung: Es ist der naheliegende Baustein, um eine **neue App
|
||
schnell als Hybrid zu starten** (Web-App in nativer Schale + Widget/
|
||
Share/Universal-Links), bevor sie — wenn sie sich bewährt — schrittweise
|
||
nativ wird. Genau diesen Weg sind zitare und seepuls gegangen. Das
|
||
Paket ist getestet (`ManaWebShellTests`), pure SwiftUI/WKWebView, ohne
|
||
Laufzeitkosten solange es niemand importiert.
|
||
|
||
**Wenn du eine neue App schnell bootstrappen willst:** `ManaWebShell`
|
||
als Dependency ziehen, `WebShellView(target:config:)` in einen Tab,
|
||
`WebShellConfig` mit `allowedHosts` + `userScripts` (z.B.
|
||
`preferDarkScheme`, `hideElements`) konfigurieren. Vorbild-Pattern (vor
|
||
der De-Hybridisierung): `seepuls-native` Git-History vor σ-7 bzw.
|
||
`zitare-native` vor η-0.
|
||
|
||
**Beim Entfernen** (falls je beschlossen): Library-Target +
|
||
`ManaWebShellTests` aus `Package.swift`, dann prüfen dass `swift build`
|
||
sauber bleibt.
|
||
|
||
## Status
|
||
|
||
**v0.1.0 — initiale Extraktion 2026-05-13.**
|
||
|
||
Phase 2 aus dem Native-Auth-Vollausbau-Plan (Option A — alles nativ).
|
||
Entstanden weil drei Apps fast-byte-identische `LoginView.swift`-
|
||
Dateien hatten und Sign-Up/Forgot-PW komplett fehlten.
|
||
|
||
## Architektonische Invarianten
|
||
|
||
Nicht ohne explizite Diskussion antasten:
|
||
|
||
1. **Keine externen UI-Libraries.** Pure SwiftUI. Identische Regel wie
|
||
in `ManaCore` (`mana-swift-core/CLAUDE.md` Invariante 2).
|
||
2. **App injiziert `ManaBrandConfig`.** Keine hardcoded Farben oder
|
||
App-Namen im Paket. `forest`/`mana`/zukünftige Themes leben in der
|
||
App, nicht hier — bis ManaTokens-Theme-Variants kommen.
|
||
3. **ViewModels sind testbar, Views sind dünn.** Jede non-triviale
|
||
View hat einen begleitenden `@Observable`-ViewModel mit reiner
|
||
State-Maschine. URLProtocol-Mock-Tests gehen gegen ViewModels.
|
||
4. **Lokalisierung DE first.** Public-API-Strings auf Deutsch, EN
|
||
später via `Localizable.xcstrings`. Konsistent mit Verein-Konvention.
|
||
5. **Account-Löschung ist Pflicht-Komponente.** App-Store-Guideline
|
||
5.1.1(v) — `ManaDeleteAccountView` MUSS in jeder App, die
|
||
`ManaSignUpView` einbaut, erreichbar sein.
|
||
6. **iOS 18 / macOS 15.** Gleiche Minimums wie `mana-swift-core`.
|
||
7. **Public API ist `Sendable`.** Swift-6-Strict-Concurrency.
|
||
|
||
## Repo-Layout
|
||
|
||
```
|
||
mana-swift-ui/
|
||
├── Package.swift
|
||
├── README.md
|
||
├── CHANGELOG.md
|
||
├── CLAUDE.md dieses File
|
||
├── Sources/
|
||
│ ├── ManaAuthUI/
|
||
│ │ ├── Brand/ ManaBrandConfig (App-injiziert)
|
||
│ │ ├── Components/ ManaAuthScaffold, ManaTextField, ...
|
||
│ │ ├── Login/ ManaLoginView + ViewModel
|
||
│ │ ├── Register/ ManaSignUpView + ViewModel
|
||
│ │ ├── Verify/ ManaEmailVerifyGateView
|
||
│ │ ├── Reset/ ManaForgotPasswordView, ManaResetPasswordView
|
||
│ │ └── Account/ ChangeEmail/ChangePassword/DeleteAccount
|
||
│ ├── ManaWebShell/ WebShellView + WebShellConfig + WebShellScripts
|
||
│ │ (Hybrid-Scaffold, aktuell ohne Konsument)
|
||
│ └── ManaLLMUI/ Lokal-LLM-Settings-UI
|
||
└── Tests/
|
||
├── ManaAuthUITests/
|
||
└── ManaWebShellTests/
|
||
```
|
||
|
||
## Konventionen
|
||
|
||
- **Swift 6.0**, Strict Concurrency komplett
|
||
- **iOS 18 / macOS 15** Minimum
|
||
- **Tabs** für Indent? Nein — wir nutzen 4 Spaces wie `mana-swift-core`
|
||
(SwiftFormat `.swiftformat`). Verein-TS-Repos nutzen Tabs, Swift-Repos
|
||
Spaces — bewusster Bruch wegen Xcode-Tooling
|
||
- **Doc-Comments** pflicht auf jedem `public`-Symbol (`///`)
|
||
- **Lokalisierung:** Public-API-Strings auf Deutsch
|
||
|
||
## Versionierung
|
||
|
||
- **Semver strikt.** UI ändert sich öfter als Auth-Core — getrenntes
|
||
Repo damit `mana-swift-core` stabil bleibt
|
||
- **CHANGELOG.md pflicht.** Was hat sich geändert, müssen Apps was anpassen
|
||
- **Pflege-Politik:** Letzte zwei Minor-Versionen mit Patches
|
||
|
||
## Lokal entwickeln
|
||
|
||
```bash
|
||
swift build # baut ManaAuthUI
|
||
swift test # Unit-Tests gegen ViewModels
|
||
```
|
||
|
||
`mana-swift-core` muss als Schwester-Verzeichnis existieren.
|
||
|
||
## Wenn ein neuer Auth-Flow dazukommt
|
||
|
||
1. ViewModel zuerst — pure State-Maschine, testbar
|
||
2. SwiftUI-View dünn, nur `@Observable`-State-Bindings
|
||
3. Public-API-Doc auf Deutsch
|
||
4. ViewModel-Tests via URLProtocol-Mock (Pattern in
|
||
`ManaAuthUITests/`)
|
||
5. CHANGELOG.md ergänzen
|
||
6. Bei Breaking-Change: Major-Bump-Plan + alle aktiven Apps informieren
|
||
|
||
## Wichtige Cross-Repo-Doks
|
||
|
||
- `../mana/docs/MANA_SWIFT.md` — Plattform-SOT, Phase ε
|
||
- `../mana-swift-core/CLAUDE.md` — Auth-Core, ManaTokens
|
||
- `../mana/docs/THEMING.md` — Token-SOT, spiegelt sich in ManaTokens
|
||
- `../mana/services/mana-auth/CLAUDE.md` — Server-Konventionen
|