docs: update CLAUDE.md and add git helper scripts

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-06 07:56:33 +02:00
parent 26e8b2cd0c
commit 5b00036951
6 changed files with 195 additions and 82 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,97 +2,89 @@

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

-## Projekt
+## Verhaltensregeln

-**Gartenmanager** – Docker-basierte Web-Platform zur Verwaltung von Gartenaktivitäten. Multi-User, Multi-Tenant.
+- Kein erklärender Text bei Routineaufgaben (Commits, Pushes, Branch-Wechsel)
+- Bei Fehlern: erst 2x selbst versuchen, dann fragen
+- Branches selbstständig wechseln wie benötigt

-## Dokumente – wo was steht
+## Sprache & Konventionen

-| 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 |
+- **Code-Bezeichner, Commit-Messages:** Englisch, Imperativ (`Add`, `Fix`, `Refactor`)
+- **Dokumentation & Kommentare:** Deutsch
+- **Commit-Format:** `<type>: <short description>` (max. 72 Zeichen)  
+  Types: `feat` | `fix` | `refactor` | `test` | `docs` | `chore`
+- Nach jedem Commit sofort pushen
+- Keine `console.log`/`print` in Produktionscode, keine auskommentierten Code-Blöcke

-## Techstack
+## Projektkontext (Schnelleinstieg)

-| 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) |
+**Gartenmanager** – Docker-basierte Gartenverwaltung. Multi-User, Multi-Tenant, Rollensystem.  
+**Stack:** Vue 3 + PrimeVue → FastAPI (Python 3.11) → PostgreSQL 15  
+**Phase:** 1 abgeschlossen (Auth, Beete, Pflanzen, Bepflanzung). Phase 2 = Testing & CI/CD.  
+**Version:** `cat VERSION` | **Branch:** `git branch --show-current`  
+**Sessionstart:** [.claude/session-context.md](.claude/session-context.md) lesen.  
+**Modulreferenz:** [docs/project-structure.md](docs/project-structure.md) – vor Quellcode-Reads.

-## Build & Entwicklung
+## Scripts (immer diese verwenden)

 ```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>
+bash .claude/scripts/git-commit.sh "message"              # stage all + commit + push
+bash .claude/scripts/git-switch.sh <branch>               # branch wechseln
+bash .claude/scripts/git-switch.sh <branch> from <base>   # neuer branch aus base
+bash .claude/scripts/git-pr.sh create <head> <base> "titel"  # PR erstellen
+bash .claude/scripts/git-pr.sh merge <nr> squash          # PR mergen
+bash .claude/scripts/git-pr.sh list                       # offene PRs
+bash .claude/scripts/bump.sh [patch|minor] "beschreibung" # version + commit + push
+bash .claude/scripts/new-feature.sh [feature|fix] <name>  # branch aus develop
 ```

 ## 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(...)
+backend/app/
+  core/config.py      – Settings (DATABASE_URL, SECRET_KEY, ...)
+  core/security.py    – JWT (Access 30min / Refresh 7d), Passwort-Hashing
+  core/deps.py        – get_current_user, get_tenant_context, require_min_role()
+  db/session.py       – async Engine + get_session()
+  models/             – SQLAlchemy ORM (UUID-PKs): User, Tenant, Plant, Bed, BedPlanting
+  schemas/            – Pydantic v2 Create/Update/Read je Entität
+  crud/               – CRUDBase + spezialisierte Klassen, nur DB-Zugriff
+  api/v1/             – Router: auth, plants, beds, plantings
+  seeds/initial_data.py – 28 Pflanzen + 15 Kompatibilitäten (idempotent)

-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
+frontend/src/
+  api/client.js       – Axios + JWT-Interceptor + Auto-Refresh bei 401
+  stores/             – Pinia: auth, beds, plants
+  router/index.js     – Auth-Guard, /login /beete /beete/:id /pflanzen
+  views/              – LoginView, BedsView, BedDetailView, PlantsView
+  components/         – AppLayout, BedForm, PlantingForm, PlantForm
 ```

-### Tenant-Kontext
-Alle Nicht-Auth-Endpoints erwarten Header `X-Tenant-ID: <uuid>`. Die Dependency `get_current_tenant` prüft Mitgliedschaft des eingeloggten Users.
+**Tenant-Kontext:** Header `X-Tenant-ID` bei allen Nicht-Auth-Requests.  
+**Rollen:** `READ_ONLY` < `READ_WRITE` < `TENANT_ADMIN` < `is_superadmin`

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

-### Frontend (`frontend/src/`)
-Vue 3 SFC mit PrimeVue-Komponenten, Pinia für State, Axios-Client mit JWT-Interceptor und automatischem Token-Refresh.
+1. **Nie direkt nach `main`** – nur PR, nur auf Anweisung
+2. **Arbeit in `feature/`, `fix/` oder `chore/`** unter `develop`
+3. **Nach jeder Änderung:** `bump.sh` ausführen (MINOR bei Features, PATCH bei Fixes)
+4. **MAJOR-Version** niemals selbstständig erhöhen
+5. **Vor Merge/PR:** CHANGELOG, README, `docs/project-structure.md` prüfen
+6. **In `develop` mergen erst** wenn alle Tests grün sind

-## Pflichtregeln (immer befolgen)
+## Testing

-Vollständige Regeln in [docs/development-standards.md](docs/development-standards.md). Kurzfassung:
+- Integrationstests testen gegen echte DB (keine DB-Mocks)
+- Backend: pytest in `backend/tests/` | Frontend: Vitest neben Quelldateien oder `__tests__/`
+- Run: `docker compose exec backend pytest` / `cd frontend && npm run test`

-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
+## Build
+
+```bash
+docker compose -f docker-compose.dev.yml up   # Dev (hot-reload)
+docker compose up -d                           # Prod
+docker compose exec backend alembic upgrade head
+docker compose exec backend python -m app.seeds.initial_data
+cd frontend && npm run dev
+```