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>
12 KiB
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· Roadmapdocs/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, Speicherpfadelibrary/…, Governanceofficial/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, keinetraining_framework_slot_exercisesmehr — sieheDATABASE_SCHEMA.md/FEATURES_DELIVERED_2026-Q2.md. - 2026-04-27: Übungsvarianten API/UI, Migration 030, Listen-UX-Suche, Admin-Upload-Limits — siehe
PROJECT_STATUS.mdunddocs/library/FEATURES_DELIVERED_2026-Q2.md.
Domänenmodell (MVP Core)
Kern-Objekte
Organisation:
clubs- Vereinedivisions- Sparten (optional)training_groups- Trainingsgruppen
Kataloge:
skills- Fähigkeiten (global)training_methods- Trainingsmethoden (global)
Übungen:
exercises- Übungen (Kernobjekt)exercise_variants- Übungsvariantenexercise_skills- M:N Übung ↔ Fähigkeitexercise_media- Medien (Bilder, Videos); Zielbild Archiv & Lifecycle:MEDIA_ASSETS_AND_ARCHIVE_SPEC.md. Inline im Fließtext (Übungstexte) ist implementiert (Spec §11): Ankerexercise_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_idab 037)training_framework_programs+ Ziele + Slots (Migration 035–036) — Bibliotheks‑Rahmen- Legacy:
training_templates/section_exerciseso. ä. — in älteren Skizzen; produktiver Pfad siehe Migrationen 006/031
Governance:
content_change_requests- Änderungsanfragen
Import:
wiki_import_log- Import-Trackingwiki_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:
api.jsfür ALLE API-Calls nutzen – nie direktesfetch()ohne Tokensession: dict = Depends(require_auth)als separater Parameterbcryptfür alle Passwort-Operationen- Neue DB-Spalten nur via Schema-Migration
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