shinkan-jinkendo/CLAUDE.md

# Shinkan Jinkendo – Entwickler-Kontext für Claude Code

## Pflicht-Lektüre für Claude Code

> VOR jeder Implementierung lesen:
> | Architektur-Regeln | `.claude/rules/ARCHITECTURE.md` |
> | Coding-Regeln      | `.claude/rules/CODING_RULES.md` |
> | Zugriffsschicht (Multi-Tenancy, Governance) | `.claude/docs/technical/ACCESS_LAYER_AND_GOVERNANCE_PLAN.md` |
> | Endpoint-Audit (Tenant/Governance) | `.claude/docs/working/ACCESS_LAYER_ENDPOINT_AUDIT.md` |
> | Cursor-Regel Zugriffsschicht | `.cursor/rules/access-layer.mdc` |
> | Lessons Learned    | `.claude/rules/LESSONS_LEARNED.md` |
> | Setup-Dokument     | `.claude/docs/working/SHINKAN_PROJECT_SETUP.md` |
> | Anforderungen      | `.claude/docs/functional/SHINKAN_REQUIREMENTS.md` |
> | Medien-Archiv, Lifecycle, Inline (Plan §11) | `.claude/docs/technical/MEDIA_ASSETS_AND_ARCHIVE_SPEC.md` |
> | Fähigkeiten-Scoring (Planungs-Bausteine) | `.claude/docs/technical/SKILL_SCORING_SPEC.md` |
> | Handover / nächste Session | **`docs/HANDOVER.md`** |
> | Fachlicher Nutzerüberblick (Design/Product) | **`docs/FACHLICHE_NUTZERFUNKTIONEN.md`** |
> | Architektur-Zielbild, Refaktor-Roadmap, verbindliche Shinkan-Regeln | **`docs/architecture/README.md`** |
> | Performance-Baseline (Phase 0) | **`docs/architecture/BASELINE_SNAPSHOT.md`** |
> | KI-Prompt-System — Zielarchitektur | `.claude/docs/technical/AI_PROMPT_TARGET_ARCHITECTURE.md` |
> | Planungs-KI Progressionsgraph (Ist-Stand) | **`docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md`** · Spec **`.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md`** · Roadmap **`docs/architecture/PLANNING_KI_ROADMAP.md`** |

## Projekt-Übersicht

**Shinkan Jinkendo** (真観 Jinkendo) – Trainer- und Vereinsplattform für Kampfsport-Trainingsplanung.
Teil der **Jinkendo**-App-Familie (人拳道). Domains: shinkan.jinkendo.de

**WICHTIG:** Shinkan ist KEINE persönliche Tracking-App!

**Fachlicher Fokus:**
- Übungsverwaltung und -suche
- Trainingsplanung für Gruppen
- Fähigkeiten- und Methodenkataloge
- Standardisierung und Wiederverwendung
- Freigabe und Governance von Inhalten

**Primäre Nutzer:** Trainer, Vereinsadmins, Redakteure  
**Nicht in MVP:** Individuelle Sportler, persönliches Tracking

## Tech-Stack

| Komponente | Technologie |
|-----------|-------------|
| Frontend  | React 18 + Vite + PWA (Node 20) |
| Backend   | FastAPI Python 3.12 |
| Datenbank | PostgreSQL 16 Alpine |
| Container | Docker + Docker Compose |
| Auth      | Token-basiert + bcrypt |
| KI        | OpenRouter API (optional, nicht MVP-kritisch) |

**Ports:** Prod 3003/8003 · Dev 3098/8098 – nie ändern!

## Verzeichnisstruktur

```
backend/
├── main.py          # App-Setup + Router-Registration
├── db.py            # PostgreSQL Connection Pool (von Mitai)
├── db_init.py       # DB-Init + Migrations-System (von Mitai)
├── auth.py          # Hash, Verify, Sessions (von Mitai)
├── models.py        # Pydantic Models
├── version.py       # Versionskontrolle
├── migrations/      # SQL-Migrationen (XXX_*.sql Pattern)
└── routers/         # Router-Module
    auth · profiles · clubs · groups · skills · methods
    exercises · exercise_progression_graphs · training_units · training_programs
    planning · import_wiki · admin · membership · media_assets

frontend/src/
├── App.jsx          # Root, Auth-Gates, Navigation
├── app.css          # CSS-Variablen + globale Styles
├── config/          # appNav.js · adminNav.js
├── layouts/         # AdminShell · RequireAdmin
├── context/         # AuthContext · ProfileContext
├── pages/           # Alle Screens
└── utils/
    api.js           # ALLE API-Calls

.claude/
├── commands/        # Slash-Commands
├── docs/
│   ├── functional/  # Fachliche Specs
│   ├── technical/   # Technische Specs
│   └── rules/       # Verbindliche Regeln
└── library/         # Auto-generierte Docs
```

## Aktuelle Version

**Siehe:** `backend/version.py` (`APP_VERSION`, `DB_SCHEMA_VERSION`, `MODULE_VERSIONS`) und `.claude/docs/PROJECT_STATUS.md`.

Kurz (Stand 2026-05-14): App- und DB-Version siehe **`backend/version.py`**; Kern: Übungen, Varianten, **Medien-Archiv & Bibliothek (`/media`)**, **Inline-Medien im Rich-Text**, **Inhaltsmeldungen (P-13)** im Posteingang, Mandanten-Sync aktiver Verein, Planung mit **Phasen & parallelen Streams (Breakout, 063)**, **Trainingsrahmen Bibliothek + Slot‑Blueprint** (036–037), Progressionsgraph, Reifegrad/Matrix‑Stack — Details `PROJECT_STATUS.md`, `docs/HANDOVER.md`, Nutzerüberblick **`docs/FACHLICHE_NUTZERFUNKTIONEN.md`**, `PARALLEL_TRAINING_STREAMS_SPEC.md`, `MEDIA_ASSETS_AND_ARCHIVE_SPEC.md` (Abschnitt 11 umgesetzt).

### Log (Auszug)

- 2026-05-20: **Fähigkeiten-Scoring Phase 3** — gewichtete Profile für Module/Rahmen/Pfade; Peer-Vergleich getrennt nach Artefakttyp; Listen-Filter + Discovery — siehe `SKILL_SCORING_SPEC.md`, `docs/HANDOVER.md` §2.6, `FEATURES_DELIVERED_2026-Q2.md` §15.
- 2026-05-07: **Medien** — zentrales Archiv (`media_assets`), Bibliothek-UI, Lifecycle/Papierkorb, `from-asset`, Speicherpfade `library/…`, Governance `official`/Copyright; **0.8.59** aktiver Verein UI/API-Sync — siehe `.claude/docs/library/FEATURES_DELIVERED_2026-Q2.md` §12, `docs/HANDOVER.md`.
- 2026-05-05: Rahmen nur Bibliothek (**036**), Slot‑Ablauf = `training_units` + Sektionen (**037**), `POST /api/training-units/from-framework-slot`, keine `training_framework_slot_exercises` mehr — siehe `DATABASE_SCHEMA.md` / `FEATURES_DELIVERED_2026-Q2.md`.
- 2026-04-27: Übungsvarianten API/UI, Migration 030, Listen-UX-Suche, Admin-Upload-Limits — siehe `PROJECT_STATUS.md` und `docs/library/FEATURES_DELIVERED_2026-Q2.md`.

## Domänenmodell (MVP Core)

### Kern-Objekte

**Organisation:**
- `clubs` - Vereine
- `divisions` - Sparten (optional)
- `training_groups` - Trainingsgruppen

**Kataloge:**
- `skills` - Fähigkeiten (global)
- `training_methods` - Trainingsmethoden (global)

**Übungen:**
- `exercises` - Übungen (Kernobjekt)
- `exercise_variants` - Übungsvarianten
- `exercise_skills` - M:N Übung ↔ Fähigkeit
- `exercise_media` - Medien (Bilder, Videos); Zielbild Archiv & Lifecycle: **`MEDIA_ASSETS_AND_ARCHIVE_SPEC.md`**. **Inline im Fließtext** (Übungstexte) ist implementiert (Spec §11): Anker `exercise_media.id`, einheitlicher Render-Pfad.

**Trainingsplanung / Rahmen:**
- `training_plan_templates` + Sektionsvorlagen — Mikrovorlage pro Einheit (Migration **031**)
- `training_units` — Kalender‑Instanzen **und** Rahmen‑Slot‑Blueprints (`framework_slot_id` ab **037**)
- `training_framework_programs` + Ziele + Slots (Migration **035–036**) — Bibliotheks‑Rahmen
- Legacy: `training_templates` / `section_exercises` o. ä. — in älteren Skizzen; produktiver Pfad siehe Migrationen **006**/**031**

**Governance:**
- `content_change_requests` - Änderungsanfragen

**Import:**
- `wiki_import_log` - Import-Tracking
- `wiki_import_references` - Duplikat-Erkennung

## Deployment

```
Internet → Fritz!Box (privat.stommer.com) → Synology NAS → Raspberry Pi 5 (192.168.2.49)

Git Workflow:
  develop → Auto-Deploy → dev.shinkan.jinkendo.de  (shinkan-dev/, Port 3098/8098)
  main    → Auto-Deploy → shinkan.jinkendo.de       (shinkan/, Port 3003/8003)

Gitea: http://192.168.2.144:3000/Lars/shinkan-jinkendo
Runner: Raspberry Pi (/home/lars/gitea-runner/)

Manuell:
  cd /home/lars/docker/shinkan[-dev]
  docker compose -f docker-compose[.dev-env].yml build --no-cache && up -d

Migrations:
  Werden automatisch beim Container-Start ausgeführt (db_init.py)
  Nur nummerierte Dateien: backend/migrations/XXX_*.sql
```

## Datenbank-Schema (PostgreSQL 16)

```
-- Von Mitai übernommen
profiles          – Nutzer (role, pin_hash/bcrypt, email, tier)
sessions          – Auth-Tokens
features          – Feature-Definitionen
tier_limits       – Limits pro Tier
subscriptions     – Nutzer-Subscriptions

-- Shinkan-spezifisch
clubs                    – Vereine
divisions                – Sparten
training_groups          – Trainingsgruppen
skills                   – Fähigkeiten-Katalog
training_methods         – Methoden-Katalog
exercises                – Übungen (Kernobjekt)
exercise_variants        – Übungsvarianten
exercise_skills          – M:N Übung ↔ Fähigkeit
exercise_media           – Medien
training_templates       – Vorlagen / Standards
training_sections        – Trainingsabschnitte
section_exercises        – Übungen in Abschnitten
training_units           – Trainingseinheiten
training_programs        – Trainingsprogramme
program_units            – Programm-Einheiten
content_change_requests  – Änderungsanfragen
wiki_import_log          – Import-Tracking
wiki_import_references   – Duplikat-Erkennung

Schema-Datei: backend/schema.sql (später)
Migrationen: backend/migrations/*.sql (automatisch beim Start)
```

## API & Auth

```
Alle Endpoints:     /api/...
Auth-Header:        X-Auth-Token: <token>
Fehler:             {"detail": "Fehlermeldung"}

Auth-Flow:
  Login → E-Mail + Passwort → Token in localStorage
  Token → X-Auth-Token Header → require_auth()
  Profile-Id → immer aus Session, nie aus Header!
```

## Umgebungsvariablen (.env)

```
DB_HOST/PORT/NAME/USER/PASSWORD  # PostgreSQL
OPENROUTER_API_KEY               # KI (optional)
OPENROUTER_MODEL=anthropic/claude-sonnet-4
SMTP_HOST/PORT/USER/PASS/FROM    # E-Mail
APP_URL=https://shinkan.jinkendo.de
ALLOWED_ORIGINS=https://shinkan.jinkendo.de
MEDIA_DIR=/app/media
```

## Produktions-/Sicherheitsaudit (Drift vermeiden)

Aktuelle Befunde und Umsetzungsstände: `.claude/docs/working/PRODUCTION_READINESS_AUDIT_2026-05.md` (Fortlaufend pflegen.)

## Kritische Regeln für Claude Code

### Must-Do:
1. `api.js` für ALLE API-Calls nutzen – nie direktes `fetch()` ohne Token
2. `session: dict = Depends(require_auth)` als **separater** Parameter
3. `bcrypt` für alle Passwort-Operationen
4. Neue DB-Spalten nur via Schema-Migration
5. `npm install` (nicht npm ci) – kein package-lock.json

### Bekannte Fallstricke:
```python
# ❌ FALSCH – führt zu ungeschütztem Endpoint:
def endpoint(x: str = Header(default=None, session=Depends(require_auth))):

# ✅ RICHTIG:
def endpoint(x: str = Header(default=None), session: dict = Depends(require_auth)):
```

```python
# PostgreSQL Boolean (nicht SQLite 0/1):
WHERE active = true   # ✅
WHERE active = 1      # ❌
```

## Design-System (Kurzreferenz)

```css
/* Farben */
--accent: #1D9E75    --accent-dark: #085041    --danger: #D85A30
--bg · --surface · --surface2 · --border · --text1 · --text2 · --text3

/* Klassen */
.card · .btn · .btn-primary · .btn-secondary · .btn-full
.form-input · .form-label · .form-row · .spinner

/* Abstände */
Seiten-Padding: 16px · Card-Padding: 16-20px · Border-Radius: 12px/8px
Bottom-Padding Mobile: 80px (Navigation)
```

## Dokumentations-Struktur

```
.claude/
├── docs/
│   ├── functional/         ← Fachliche Specs (WAS soll gebaut werden)
│   ├── technical/          ← Technische Specs (WIE wird es gebaut)
│   ├── working/            ← Arbeitspapiere / Analysen
│   └── rules/              ← Verbindliche Regeln
└── library/                ← Ergebnis-Dokumentation (WAS wurde gebaut)
```

## Abgrenzung zu Mitai

**Mitai (身体):**
- Persönliches Körper- und Trainings-Tracking
- Gewicht, Umfänge, Ernährung, Aktivität
- Individuelle Ziele und Fortschritte
- KI-Analysen für persönliche Entwicklung

**Shinkan (真観):**
- Trainer- und Vereinsarbeit
- Übungsverwaltung und -suche
- Trainingsplanung für Gruppen
- Fähigkeiten- und Methodenkataloge
- Standardisierung und Wiederverwendung

**Technisch gemeinsam:**
- Auth-System
- Membership-Basis
- Design-System
- Docker/Deployment-Infrastruktur

## Jinkendo App-Familie

```
mitai.jinkendo.de    → Körper-Tracker (身体)
shinkan.jinkendo.de  → Trainingsplanung (真観)
miken.jinkendo.de    → Meditation (眉間)
ikigai.jinkendo.de   → Lebenssinn (生き甲斐)
```

---

**Version:** 0.1.0  
**Stand:** 21.04.2026  
**Autor:** Claude Code