df6f67ee45
ManaCore + ManaTokens als Swift-Package für alle nativen mana-e.V.-Apps. Phase α aus mana/docs/MANA_SWIFT.md durch. ManaCore: - AuthClient gegen mana-auth (Login, Refresh, Status-Maschine) - AuthenticatedTransport (URLSession + 401-Retry) - ManaAppConfig-Protocol für App-injizierbare Konfig - KeychainStore mit optionaler Shared-Access-Group - JWT-Parser für lokale Expiry-Prüfung - AuthError, CoreLog (interne OSLog-Logger) ManaTokens: - 12 Vereins-Tokens als dynamic Light/Dark Colors - 5 Brand-Literale (mana-yellow, spectrum-orange, ...) - Spacing, Radius, Typography aus mana/docs/THEMING.md Tests: 12 Unit-Tests grün via swift test. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
107 lines
4.4 KiB
Markdown
107 lines
4.4 KiB
Markdown
# CLAUDE.md — mana-swift-core
|
||
|
||
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. Dieses CLAUDE.md ist die Repo-lokale
|
||
> Konventionen-Doku.
|
||
|
||
## Was dieses Repo ist
|
||
|
||
Swift-Package-Plattform für alle nativen mana-e.V.-Apps. Enthält genau
|
||
zwei Library-Products:
|
||
|
||
- **ManaCore** — Auth (mana-auth-Login, JWT-Refresh, Keychain),
|
||
Transport (URLSession-Wrapper mit 401-Retry).
|
||
- **ManaTokens** — Verein-Designwerte. Spiegelt `mana/docs/THEMING.md`.
|
||
|
||
Wird konsumiert von `memoro-native`, geplant `cards-native`,
|
||
`nutriphi-native` und weiteren.
|
||
|
||
## Status
|
||
|
||
**v1.0.0 — initiale Extraktion aus memoro-native (2026-05-12).**
|
||
|
||
Phase α aus `mana/docs/MANA_SWIFT.md` — wortwörtliche Verschiebung
|
||
von `Core/Auth`, `Core/API/Transport`, plus `ManaTokens` neu aus
|
||
`mana/docs/THEMING.md`. Keine spekulativen Verallgemeinerungen.
|
||
|
||
## Architektonische Invarianten
|
||
|
||
Nicht ohne explizite Diskussion antasten:
|
||
|
||
1. **Genau zwei Library-Products.** ManaCore + ManaTokens. Ein
|
||
`ManaUI`-Komponenten-Package entsteht später in einem **eigenen**
|
||
Repo, nicht hier (`mana/docs/MANA_SWIFT.md` Phase ε).
|
||
2. **Keine externen Dependencies.** ManaCore darf nur Foundation,
|
||
Security, OSLog, Combine importieren. Kein Alamofire, kein Sentry,
|
||
kein nichts. Compliance (`mana/docs/COMPLIANCE.md`) + Build-Stabilität.
|
||
3. **Public API ist `Sendable`.** Jeder Cross-Actor-Type. Swift-6-
|
||
Concurrency-Korrektheit.
|
||
4. **Keine app-spezifischen Annahmen.** ManaCore weiß nichts über
|
||
Memos, Decks, Meals. PRs, die "irgendwas für Memoro" hinzufügen
|
||
wollen, gehören in memoro-native, nicht hier.
|
||
5. **mana-auth-Wissen ist erlaubt.** Endpoint-Pfade `/api/v1/auth/login`,
|
||
`/api/v1/auth/refresh`, Wire-Format mit `accessToken`/`refreshToken`.
|
||
Das ist Verein-Plattform-Konstante, nicht App-Detail.
|
||
6. **OSLog statt print/Sentry.** ManaCore loggt intern unter Subsystem
|
||
`ev.mana.core`. Apps haben ihr eigenes Subsystem.
|
||
7. **App injiziert ihre Config.** ManaCore hardcoded *nichts* (außer
|
||
die mana-auth-Endpoint-Pfade als Konstante). `authBaseURL`,
|
||
`keychainService`, `keychainAccessGroup` kommen vom App-Caller.
|
||
8. **Tests gegen reine Logik.** JWT-Decode, Token-Expiry, Keychain-
|
||
Key-Mapping. URLSession-Calls werden über Protokoll-Injection
|
||
getestet, nicht über echtes Netzwerk.
|
||
|
||
## Versionierung
|
||
|
||
- **Semver strikt.** Patch = Bugfix ohne API-Änderung. Minor = neue
|
||
API additiv. Major = breaking.
|
||
- **Git-Tag nach jedem Sinn-Abschnitt** auf `main`. Nicht jeden Commit.
|
||
- **CHANGELOG.md pflicht.** Was hat sich geändert, müssen Apps was anpassen.
|
||
- **Pflege-Politik:** Letzte zwei Major-Versionen werden mit Patches
|
||
bedient. Ältere nicht.
|
||
|
||
## Konventionen
|
||
|
||
- **Swift 6.0**, Strict Concurrency komplett
|
||
- **iOS 18 / macOS 15** Minimum (gleiche Targets wie memoro-native)
|
||
- **SwiftFormat** mit `.swiftformat` (4-space, 120-col, sorted imports)
|
||
- **SwiftLint** mit `.swiftlint.yml`
|
||
- **Doc-Comments** pflicht auf jedem `public`-Symbol (`///`)
|
||
- **Lokalisierung:** Public-API-Strings auf Deutsch (Verein-Konvention),
|
||
Code-Identifier auf Englisch
|
||
|
||
## Lokal entwickeln
|
||
|
||
```bash
|
||
swift build # baut beide Targets
|
||
swift test # Unit-Tests
|
||
swift package generate-xcodeproj # optional, für Xcode
|
||
```
|
||
|
||
Für die Integration in eine App (memoro-native, cards-native):
|
||
|
||
- Dev-Cycle: in `project.yml` der App `path: ../mana-swift-core` setzen
|
||
- Release: `from: 1.0.0` mit Git-Tag
|
||
|
||
## Wenn eine neue Funktion dazukommt
|
||
|
||
1. Frage: gehört das wirklich in ManaCore/ManaTokens, oder ist es
|
||
App-spezifisch? Wenn unsicher: in die App, später extrahieren.
|
||
2. Public API mit Doc-Comments.
|
||
3. Unit-Tests gegen die State-Machine, nicht gegen echtes Netzwerk.
|
||
4. CHANGELOG.md ergänzen.
|
||
5. Bei Breaking-Change: Major-Bump-Plan in `mana/docs/MANA_SWIFT.md`
|
||
notieren, alle aktiven Apps informieren.
|
||
|
||
## Wichtige Cross-Repo-Doks
|
||
|
||
- `mana/docs/MANA_SWIFT.md` — Plattform-SOT für native Apps
|
||
- `mana/docs/MANA_AUTH_FEDERATION.md` — Auth-Protokoll
|
||
- `mana/docs/THEMING.md` — Token-SOT, spiegelt sich in ManaTokens
|
||
- `mana/docs/COMPLIANCE.md` — Telemetrie/Crash-Reporter-Regeln
|
||
- `mana/services/mana-auth/CLAUDE.md` — Server-Konventionen, §
|
||
"Native-App-Koordination" beschreibt die Refresh-Token-Invariante
|
||
- `memoro-native/CLAUDE.md` — erste Konsumenten-App, Konventionen
|
||
hier sind aus deren PLAN.md gewachsen
|