Files
shinkan-jinkendo/CLAUDE.md
T
LarsandClaude Opus 5.5 36d51d4c33
Deploy Development / deploy (push) Successful in 55s
Test Suite / pytest-backend (push) Successful in 51s
Test Suite / lint-backend (push) Successful in 0s
Test Suite / build-frontend (push) Successful in 17s
Test Suite / k6 /health Baseline (push) Successful in 35s
Test Suite / playwright-tests (push) Failing after 7m46s
Deploy production to llm-node alongside the Pi.
A separate workflow on the linux_host runner deploys main to llm-node with its own checkout, /etc/shinkan/prod.env and a compose override that mounts the NAS media without creating host paths. Media retention stays off there until it is explicitly enabled, because both installations share the media pool. The deploy only passes when /api/health/ready reports a ready database and complete schema. The Pi workflow keeps its name and label and now aborts on any other host.

Also documents both deployments and the recovery contract with the backup orchestrator.

version: 0.8.246 (backend)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 15:47:38 +01:00

12 KiB
Raw Blame History

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)

  main    → Auto-Deploy → llm-node (192.168.2.144, /home/llmadmin/docker/shinkan-prod)
            parallel, eigener Workflow deploy-prod-llm-node.yml
            Compose-Override docker-compose.llm-node.yml, Config /etc/shinkan/prod.env
            Details + Abschalten des Pi-Prod: .claude/docs/technical/PROD_DEPLOYMENTS.md

Gitea: http://192.168.2.144:3000/Lars/shinkan-jinkendo
Runner: Raspberry Pi (/home/lars/gitea-runner/, Label ubuntu-latest)
        llm-node (act_runner.service, Label linux_host)

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:

# ❌ 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)):
# PostgreSQL Boolean (nicht SQLite 0/1):
WHERE active = true   # ✅
WHERE active = 1      # ❌

Design-System (Kurzreferenz)

/* 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