Lars
76cc81a385
All checks were successful
Deploy Development / deploy (push) Successful in 42s
Test Suite / pytest-backend (push) Successful in 37s
Test Suite / lint-backend (push) Successful in 0s
Test Suite / build-frontend (push) Successful in 20s
Test Suite / k6 /health Baseline (push) Successful in 33s
Test Suite / playwright-tests (push) Successful in 1m8s
- Updated CLAUDE.md and PROJECT_STATUS.md to reflect the latest app version (0.8.140) and database schema (20260515063) as of 2026-05-14. - Enhanced DOMAIN_MODEL.md and PARALLEL_TRAINING_STREAMS_CONCEPT.md to clarify the implementation of phases and parallel streams in training units. - Improved HANDOVER.md with detailed descriptions of the coaching and breakout functionalities, including rejoin logic and session management. - Updated FACHLICHE_NUTZERFUNKTIONEN.md to include new features related to training planning and execution, emphasizing the integration of phases and parallel streams. - Revised FEATURES_DELIVERED_2026-Q2.md to document the latest changes and improvements in the training framework and media management.
300 lines
11 KiB
Markdown
300 lines
11 KiB
Markdown
# 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` |
|
||
> | 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`** |
|
||
|
||
## 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-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
|