gartenmanager/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Projekt

**Gartenmanager** – Docker-basierte Web-Platform zur Verwaltung von Gartenaktivitäten. Multi-User, Multi-Tenant.

## Dokumente – wo was steht

| Dokument | Inhalt |
|---|---|
| [docs/development-standards.md](docs/development-standards.md) | **Alle Regeln:** Branching, Versionierung, Workflow, Coding, Testing |
| [docs/project-structure.md](docs/project-structure.md) | **Alle Module & Funktionen** – hier zuerst lesen, bevor Quellcode geöffnet wird |
| [CHANGELOG.md](CHANGELOG.md) | Versionshistorie |
| [VERSION](VERSION) | Aktuelle Versionsnummer |
| [.claude/session-context.md](.claude/session-context.md) | **Sessionstart hier lesen:** aktiver Branch, Version, offene Arbeit |

## Techstack

| Schicht | Technologie |
|---|---|
| Frontend | Vue 3 + Vite + PrimeVue + Pinia + Vue Router |
| Backend | FastAPI (Python 3.11) + Uvicorn |
| ORM | SQLAlchemy 2.x async + Alembic |
| Datenbank | PostgreSQL 15 (asyncpg) |
| Container | Docker Compose (3 Services: db, backend, frontend/nginx) |

## Build & Entwicklung

```bash
# Gesamtes System starten (Produktion)
docker compose up -d

# Entwicklungsmodus (mit Hot-Reload)
docker compose -f docker-compose.dev.yml up

# Nur Backend lokal starten (setzt laufende DB voraus)
cd backend && uvicorn app.main:app --reload --port 8000

# Nur Frontend lokal starten
cd frontend && npm run dev

# Datenbankmigrationen ausführen
docker compose exec backend alembic upgrade head

# Neue Migration erstellen
docker compose exec backend alembic revision --autogenerate -m "beschreibung"

# Seed-Daten einspielen
docker compose exec backend python -m app.seeds.initial_data

# Version bumpen + commit + push
bash .claude/scripts/bump.sh patch "Beschreibung"

# Neuen Feature-Branch erstellen
bash .claude/scripts/new-feature.sh feature <name>
```

## Architektur

### Backend (`backend/app/`)

```
core/
  config.py     – pydantic-settings, liest .env (DATABASE_URL, SECRET_KEY, ...)
  security.py   – JWT-Erzeugung/-Prüfung (Access 30min, Refresh 7 Tage)
  deps.py       – FastAPI-Dependencies: get_db, get_current_user, require_role(...)

db/
  base.py       – SQLAlchemy DeclarativeBase
  session.py    – async Engine + AsyncSession Factory

models/         – SQLAlchemy ORM-Modelle (alle UUID-PKs, async-kompatibel)
schemas/        – Pydantic v2 Schemas (Create/Update/Read je Entität)
crud/           – CRUD-Funktionen (kein Business-Logik, nur DB-Zugriff)
api/v1/         – FastAPI Router je Ressource
seeds/          – Initiale Pflanzenbibliothek + Kompatibilitätsdaten
```

### Tenant-Kontext
Alle Nicht-Auth-Endpoints erwarten Header `X-Tenant-ID: <uuid>`. Die Dependency `get_current_tenant` prüft Mitgliedschaft des eingeloggten Users.

### Berechtigungsebenen
`READ_ONLY` → `READ_WRITE` → `TENANT_ADMIN` → `is_superadmin` (User-Flag, überspringt alle Prüfungen)

### Frontend (`frontend/src/`)
Vue 3 SFC mit PrimeVue-Komponenten, Pinia für State, Axios-Client mit JWT-Interceptor und automatischem Token-Refresh.

## Pflichtregeln (immer befolgen)

Vollständige Regeln in [docs/development-standards.md](docs/development-standards.md). Kurzfassung:

1. **Nie direkt nach `main`** – nur per Pull-Request, nur auf explizite Anweisung
2. **Jede Arbeit in eigenem Branch** unter `develop` (`feature/`, `fix/`, `debug/`)
3. **Nach jeder Änderung:** `bash .claude/scripts/bump.sh` + commit + push
4. **Vor Merge:** README, CHANGELOG, `docs/project-structure.md` prüfen
5. **Branches selbstständig wechseln** – passend zur aktuellen Aufgabe