hellth-hub/.claude/rules.md

# Claude Project Rules - Hellth Hub

## 1. Type Safety

- TypeScript strict mode
- Kein `any`
- Keine unsicheren Type Assertions (`as X`)
- Drizzle-Query-Builder-Typen nutzen statt eigene Interfaces dupliziert beschreiben

## 2. Trennung der Verantwortlichkeiten

```
Business-Logik  → packages/api  (tRPC Router, Coach, Domain-Helper)
DB-Logik        → packages/db   (Drizzle-Schema, Migrationen)
Apps            → apps/admin    (nur UI + dünner Glue zur API)
```

Die Admin-App enthält keine Business-Logik. Wenn Berechnung in beiden Seiten gebraucht wird (z. B. Nährwerte), gehört der Kanon in `packages/api/src/lib/`; das Frontend bekommt ihn über tRPC oder dupliziert nur die UI-nahe Anzeige-Variante in `apps/admin/lib/hellth-data.ts`.

## 3. Domäne

Hellth Hub ist eine Single-User-Health-App pro Benutzer-Account. Datenmodell siehe `packages/db/src/schema/health.ts` (Foods, Recipes, MealLogs, ShoppingLists, Stores, ActivityLogs, Wearables, ClubActivities, Coach …).

Keine Naturfreunde-Begriffe wiederbeleben (News, Events, Fachgruppen, Mandanten, Häuser, Buchungen, `tenantId`, `verband_admin`, `haus_admin`, Mitgliedsausweise, Google-Wallet).

## 4. Rollen

- `user` (default) - normaler Benutzer
- `admin` - Plattform-Admin (z. B. `admin@onl1.eu`)
- Admins haben Pflicht-2FA (siehe `enforceTwoFactorForPrivilegedUsers` in `packages/api/src/trpc/init.ts`)

Rechte immer **serverseitig** prüfen (tRPC-Procedure-Auswahl: `protectedProcedure` für eingeloggte User, `platformProcedure` für Admins).

## 5. Performance

- Keine N+1-Queries (Drizzle `.with()` / Joins / `inArray` für Batch-Loads nutzen)
- Listen-Endpoints mit Suche: Filterung auf DB-Seite (`ilike`), nicht in-Memory
- Index-Pfade respektieren (siehe Index-Definitionen in `schema/health.ts`)

## 6. Sicherheit

- Auth-Pflicht für alle Routen außer Login / Health-Check
- Keine Secrets im Repo - nur `.env` (in `.gitignore`)
- 2FA-Recovery nur für Admins (`platformProcedure`)
- Bei `twoFactorRecoveryRequired = true` muss 2FA-Neueinrichtung erzwungen werden
- Login auf `/login/otp` muss sowohl TOTP-Code als auch Backup-Code unterstützen
- Better-Auth-Konfiguration (`packages/api/src/lib/auth.ts`) ist Single Source of Truth für Auth-Optionen
- CSP / Security-Headers in `apps/admin/next.config.ts` und `packages/api/src/app.ts` synchron halten

### User-Security-Felder (aktiv)

```
twoFactorEnabled
twoFactorRecoveryRequired
twoFactorRecoveryStartedAt
twoFactorRecoveryStartedBy
```

## 7. UI-Regeln

- Mobile-first - Hellth Hub wird primär am Handy benutzt
- Klar, modern, funktional - keine visuellen Spielereien
- Bottom-Navigation auf Mobile, Sidebar auf Desktop (`apps/admin/app/_components/`)
- Neue Formulare über `FormField` und `inputClassName` aus `apps/admin/app/_components/form-field.tsx`
- Deutsche UI: echte Umlaute (`ä`, `ö`, `ü`, `ß`)
- UI-Inspiration siehe `docs/inspiration/bitepal/`

## 8. DB-Änderungen

- Schema-Änderung, Migration, API-Endpoint und UI immer zusammen denken
- `pnpm --filter @hellth/db db:generate` für Migrationen
- Migrationen nicht nachträglich umbenennen oder löschen (Drizzle tracked sie per Datei + Hash)
- Neue Tabellen brauchen passende Indizes für die Haupt-Queries

## 9. Tests

Mindestens absichern:
- Auth- und 2FA-Pfade
- Nährwert- / Kalorien- / Wochenbudget-Berechnung
- Hellfireclub-Punkte-Logik

Vor PR / größerer Änderung lokal grün:

```powershell
pnpm --filter @hellth/api test
pnpm --filter admin test
pnpm exec tsc --noEmit --project packages/api/tsconfig.json
$env:NEXT_PUBLIC_API_URL='http://localhost:3002'; pnpm --filter admin build
```

## 10. Arbeitsweise mit Claude

- Bestehende User-Änderungen nicht zurücksetzen
- Keine destruktiven Git-Befehle ohne ausdrückliche Anweisung
- Cleanup an Altlasten nur nach expliziter Freigabe (siehe `docs/projektreferenz.md` Abschnitt "Bekannte Altlasten")