115 lines
6.5 KiB
Markdown
115 lines
6.5 KiB
Markdown
# Shuffle – Projektkontext für Claude Code
|
||
|
||
Diese Datei wird in jeder Claude-Code-Session automatisch geladen. Sie ist das "Gedächtnis" des Projekts.
|
||
Halte sie kurz, aktuell und verbindlich. Details gehören nach `docs/` oder in Outline.
|
||
|
||
## Was ist Shuffle?
|
||
Shuffle ist eine Brettspiel-App für **iOS, Android und Web** aus einer gemeinsamen Codebasis.
|
||
Die fachlichen Anforderungen liegen in `requirements/` (Quelle der Wahrheit) und werden als
|
||
User Stories in Forgejo-Issues umgesetzt.
|
||
|
||
## Tech-Stack (ADR-0001 angenommen, Hosting ADR-0002)
|
||
- **Frontend:** Flutter (stable) / Dart 3 – eine Codebasis für iOS, Android, Web
|
||
- **State-Management:** Riverpod (mit Code-Generierung)
|
||
- **Navigation:** go_router (Deep Links + Web-URLs)
|
||
- **Backend:** Supabase (PostgreSQL 17, Auth, Storage, Realtime, Edge Functions), **selbst gehostet auf Hetzner** (ADR-0002); lokal per Supabase CLI. Nur Features nutzen, die auch self-hosted verfügbar sind; Dashboard-Einstellungen im Repo dokumentieren.
|
||
- **Modelle:** freezed + json_serializable
|
||
- **Tests:** flutter_test, mocktail, integration_test, Playwright (Web-E2E)
|
||
- **CI/CD:** Forgejo Actions (`.forgejo/workflows/`)
|
||
- **Doku:** Outline (Collection „Shuffle“), Architektur-Entscheidungen als ADRs in `docs/adr/`
|
||
|
||
## Repository-Struktur
|
||
```
|
||
app/ Flutter-App
|
||
lib/
|
||
core/ Theme, Routing, DI, Fehlerbehandlung, gemeinsame Widgets
|
||
features/<feature>/ Feature-first: data/ domain/ presentation/
|
||
test/ Unit- und Widget-Tests (Spiegel von lib/)
|
||
integration_test/
|
||
supabase/
|
||
migrations/ SQL-Migrationen (nur additive Änderungen, nie bestehende editieren)
|
||
functions/ Edge Functions (TypeScript/Deno)
|
||
seed.sql
|
||
tests/database/ pgTAP-Tests für Schema und RLS (`supabase test db`)
|
||
requirements/ Fachliche Anforderungen (10-anforderungen.md, 20-r1-akzeptanzkriterien.md)
|
||
docs/
|
||
adr/ Architecture Decision Records
|
||
datenmodell-r1.md Datenmodell R1 inkl. Tabellenstruktur (Migrationen sind maßgeblich)
|
||
specs/ Technische Feature-Spezifikationen (eine pro Issue)
|
||
.claude/agents/ Spezialisierte Subagents
|
||
.claude/commands/ Slash-Commands für Workflows
|
||
```
|
||
|
||
## Arbeitsweise (verbindlich)
|
||
1. **Jede Änderung hat ein Forgejo-Issue.** Kein Code ohne Issue-Nummer.
|
||
2. **Branch pro Issue:** `feature/<nr>-<kurzname>`, `fix/<nr>-<kurzname>`.
|
||
3. **Spec vor Code:** Für jedes Feature-Issue entsteht zuerst `docs/specs/<nr>-<kurzname>.md` (Agent `architect`). Chris gibt die Spec frei, bevor implementiert wird.
|
||
4. **Tests sind Teil des Features**, nicht nachgelagert. Kein PR ohne Tests für neue Logik.
|
||
5. **Pull Request in Forgejo**, Review durch Agent `code-reviewer`, Merge **nur durch Chris**.
|
||
6. **Conventional Commits:** `feat(collection): ...`, `fix(auth): ...`, `test: ...`, `docs: ...`, mit `Refs #<nr>` bzw. `Closes #<nr>`.
|
||
|
||
## Definition of Done
|
||
- [ ] Akzeptanzkriterien des Issues erfüllt und im PR einzeln abgehakt
|
||
- [ ] `dart format --set-exit-if-changed .` und `flutter analyze` ohne Befund
|
||
- [ ] Unit-/Widget-Tests grün, neue Logik getestet
|
||
- [ ] Läuft auf Android, iOS und Web (oder Abweichung im PR begründet)
|
||
- [ ] Supabase: Migration + RLS-Policies + Policy-Tests vorhanden, wenn Tabellen betroffen
|
||
- [ ] Texte über l10n (`app/lib/l10n/*.arb`), keine hartkodierten UI-Strings (Deutsch + Englisch)
|
||
- [ ] Barrierefreiheit: Semantics-Labels, ausreichende Kontraste, Touch-Ziele ≥ 48dp
|
||
- [ ] Doku aktualisiert (Spec, ggf. ADR, ggf. Outline-Seite)
|
||
|
||
## Code-Konventionen
|
||
- Code, Bezeichner, Commits: **Englisch**. Doku, Specs, Issue-Texte: **Deutsch**.
|
||
- Feature-first-Struktur, Abhängigkeiten nur nach innen (presentation → domain ← data).
|
||
- Keine Geschäftslogik in Widgets. Widgets sind dumm, Logik in Notifiern/Use-Cases.
|
||
- Keine `print`-Aufrufe; Logging über das zentrale Logger-Utility.
|
||
- Secrets niemals ins Repo. Konfiguration über `--dart-define-from-file=env/<stage>.json` (in `.gitignore`).
|
||
- Sicherheit: Jede Tabelle hat RLS aktiviert. Der Client vertraut niemals Client-Daten für Berechtigungen.
|
||
|
||
## Agents (siehe `.claude/agents/`)
|
||
| Agent | Zuständig für |
|
||
|---|---|
|
||
| `requirements-analyst` | Anforderungen → User Stories mit Akzeptanzkriterien → Forgejo-Issues |
|
||
| `architect` | Architektur, Datenmodell, ADRs, Feature-Specs, Aufgaben-Schnitt |
|
||
| `backend-dev` | Supabase: Migrationen, RLS, Edge Functions, Seeds |
|
||
| `flutter-dev` | Flutter-UI, State, Navigation, Datenanbindung |
|
||
| `ui-designer` | Design-System, Theme, Komponenten, UX-Konsistenz, Barrierefreiheit |
|
||
| `test-engineer` | Teststrategie, Unit-/Widget-/Integration-/E2E-Tests |
|
||
| `code-reviewer` | Review gegen DoD, Sicherheit, Architektur (nur lesend) |
|
||
| `devops` | Forgejo Actions, Builds, Releases, Umgebungen |
|
||
| `docs-writer` | Outline-Doku, Changelog, Release Notes |
|
||
|
||
## Workflows (Slash-Commands)
|
||
- `/intake` – neue Anforderungen aus `requirements/` in Stories + Issues überführen
|
||
- `/feature <issue-nr>` – komplette Pipeline: Spec → Freigabe → Umsetzung → Tests → Review → PR
|
||
- `/review <pr-nr>` – Review eines PRs
|
||
- `/adr <titel>` – neue Architekturentscheidung dokumentieren
|
||
- `/release <version>` – Release vorbereiten
|
||
|
||
## Wichtige Befehle
|
||
```bash
|
||
cd app && flutter pub get
|
||
dart run build_runner build --delete-conflicting-outputs
|
||
flutter analyze && flutter test
|
||
flutter run -d chrome --dart-define-from-file=env/dev.json
|
||
supabase start # lokales Backend
|
||
supabase db reset # Migrationen + Seed neu einspielen
|
||
supabase test db # RLS-/pgTAP-Tests
|
||
```
|
||
|
||
## Werkzeuge (MCP)
|
||
- **forgejo** – Issues, PRs, Labels, Milestones im Repo `shuffle`
|
||
- **outline** – Doku-Collection „Shuffle“
|
||
- **dart** – Analyse, Tests, pub.dev-Suche, laufende App inspizieren
|
||
- **playwright** – Web-Build im Browser testen
|
||
|
||
## Daten & Sicherheit (R1)
|
||
- Datenmodell: `docs/datenmodell-r1.md`, Migrationen in `supabase/migrations/` (nie bestehende ändern).
|
||
- Alle Tabellen: `id` (uuid), `created_at`, `updated_at`; FKs nur zwischen verwandten Tabellen (`<tabelle>_id`).
|
||
- Jede neue Tabelle braucht RLS, Policies und pgTAP-Tests in `supabase/tests/database/`.
|
||
- In R1 sind alle Nutzerdaten privat; Katalog ist öffentlich lesbar, Pflege nur Admin.
|
||
- Akzeptanzkriterien werden als „KTO-01 Kriterium 3“ in Tests und PR-Checklisten referenziert.
|
||
|
||
## Grenzen
|
||
- Nichts nach `main` pushen. Kein Force-Push. Keine Releases ohne Freigabe von Chris.
|
||
- Bei unklaren fachlichen Fragen: **nicht raten** – Frage als Kommentar ins Issue schreiben und Label `needs-clarification` setzen.
|