shinkan-jinkendo/docs/HANDOVER.md

Shinkan Jinkendo – Entwicklungsstand & Handover

Stand: 2026-05-14
App-Version / DB-Schema: App 0.8.114, DB-Schema 20260514060 (backend/version.py: APP_VERSION, DB_SCHEMA_VERSION)

Diese Datei ist die Einstiegs-Doku für neue Chat-Sessions: Anforderungen im Detail stehen in .claude/docs/ (siehe unten); hier der implementierte Stand, Medien-Meilenstein und sinnvolle nächste Schritte.

Produktion: relation … does not exist (z. B. skill_main_categories)

Das Schema ist gegenüber dem Code zurück: Migration 022_skills_schema_complete (und ggf. Folgende) wurden auf dieser Datenbank noch nicht erfolgreich ausgeführt.

• Automatisch: Die Dateien migrations/*.sql (numerisch sortiert) bilden eine Warteschlange. Bereits erfolgreiche Läufe stehen in schema_migrations — diese Dateien werden übersprungen (idempotent). Pro Datei läuft eine Transaktion (im Container vorzugsweise psql -1 -f, sonst Fallback sqlparse + psycopg2).

• Fix / manuell: docker exec shinkan-api python /app/run_migrations.py — Exit-Code 0.

• Aktuelle Builds: Bei fehlgeschlagenem Migrate startet main.py die API nicht. Lokal ohne DB: SKIP_DB_MIGRATE=1.

---

1. Pflichtlektüre (Kontext & Anforderungen)

Thema	Pfad
Architektur-Zielbild, Refaktor, Roadmap, Regeln	docs/architecture/README.md
Performance-Baseline (Phase 0)	docs/architecture/BASELINE_SNAPSHOT.md, scripts/load/README.md
Projekt-Setup, Domain grob	.claude/docs/working/SHINKAN_PROJECT_SETUP.md
Projekt-Status (aktuell)	.claude/docs/PROJECT_STATUS.md
Medien-Archiv, Lifecycle, Inline-Plan (§11)	.claude/docs/technical/MEDIA_ASSETS_AND_ARCHIVE_SPEC.md
Übungen: API, DB, Architektur, Routing	.claude/docs/technical/EXERCISES_API_SPEC.md, EXERCISES_DATABASE_FINAL.md, EXERCISES_ARCHITECTURE.md, EXERCISES_FRONTEND_ROUTING.md
Media / Upload-Limits / Embed	.claude/docs/technical/MEDIA_UPLOAD_SPEC.md
MediaWiki-Import	.claude/docs/technical/MEDIAWIKI_IMPORT_SPEC.md
Zugriffsschicht, Mandant, Governance	.claude/docs/technical/ACCESS_LAYER_AND_GOVERNANCE_PLAN.md
Tenant-Endpoints (Audit)	.claude/docs/working/ACCESS_LAYER_ENDPOINT_AUDIT.md
Rahmenprogramm · Planung	.claude/docs/technical/TRAINING_FRAMEWORK_SPEC.md
Trainingsmodule & Kombinationsübungen (Fachspez, Drift-Schutz)	.claude/docs/functional/Shinkan Trainingsmodule Kombinationsuebungen Spezifikation V2.md (§ 10.2.1 Archetyp-IDs, § 10.4 Coaching-Stufen, Anhang A Code-Abgleich)
Umsetzungsplan (Module/Kombination/Coach)	.claude/docs/working/TRAINING_MODULES_IMPLEMENTATION_PLAN.md
Überblick DB	.claude/docs/technical/DATABASE_SCHEMA.md
Domäne	.claude/docs/functional/DOMAIN_MODEL.md
Lieferliste inkl. Medien	.claude/docs/library/FEATURES_DELIVERED_2026-Q2.md §12
Fachlicher Nutzerüberblick (Design/Product)	docs/FACHLICHE_NUTZERFUNKTIONEN.md

---

2. Implementierter Stand: Fähigkeiten & Reifegradmodelle

2.1 Datenbank

• maturity_models, model_levels, model_skills, model_skill_levels: Matrix-Inhalt pro Modell.
• Kontext am Modell (Legacy, M:N): maturity_model_focus_areas, maturity_model_style_directions, maturity_model_target_groups (Migration 025).
• Hierarchische Kontext-Zuordnung (Resolve): maturity_model_context_bindings mit optional style_direction_id, training_type_id (Migration 026, 027).
• 027: u. a. Fokus + Trainingsstil ohne Stilrichtung (partielle Unique-Indizes).

2.2 Resolve-Logik (Backend)

• GET /api/maturity-models/resolve: Bindings zum Fokus, die zur Anfrage passen; Merge nach Spezifität (weniger spezifisch zuerst); spezifischere Zeilen überschreiben Zelltexte.
• Matching: Gesetzte Spalten einer Binding-Zeile müssen mit der Anfrage übereinstimmen; NULL in der Zeile = Wildcard.
• Legacy-Fallback: Nur wenn für den Fokus keine einzige Zeile in maturity_model_context_bindings existiert.

2.3 Export / Import (einzelnes Modell & aufgelöst)

• GET /api/maturity-models/{id}/export: shinkan.maturity_model.v1 inkl. context_bindings_for_model (IDs).
• GET /api/maturity-models/export-resolved: shinkan.maturity_matrix_resolved.v1 (Query: focus_area_id, optional style_direction_id, training_type_id).
• POST /api/maturity-models/import: create | replace, optional import_bindings.

2.4 Komplett-Stack Test → Prod

• GET /api/admin/matrix-stack/export, POST /api/admin/matrix-stack/import — siehe matrix_stack_bundle.py.

2.5 Frontend (Admin)

• AdminMaturityModelsPage.jsx, MaturityModelBindingsAdmin.jsx, MaturityMatrixToolsAdmin.jsx; APIs in api.js.

---

3. Trainingsrahmenprogramm & Planungs‑Blueprint (kurz)

• 036 / 037: Bibliotheks-Rahmen, Slot-Inhalt als training_units mit framework_slot_id; POST /api/training-units/from-framework-slot.
• Code: training_framework_programs.py, training_planning.py; Frontend TrainingFrameworkProgramEditPage.jsx, createTrainingUnitFromFrameworkSlot in api.js.

Trainingsmodule, Kombinationsübungen und Coach (Stand 0.8.114)

• Fachspez & Drift-Schutz: .claude/docs/functional/Shinkan Trainingsmodule Kombinationsuebungen Spezifikation V2.md (§ 10.2.1 IDs, § 10.4 Coaching-Stufen, § 10.6 Produkt-Backlog, Anhang A Abgleich).
• Umsetzungsplan: .claude/docs/working/TRAINING_MODULES_IMPLEMENTATION_PLAN.md (Phase 2 / 4 teilweise; Pakete 4a–g — u. a. 4e Archetyp-Admin, 4f Massen-Vorbelegung, 4g Backend-Validierung).
• Ist kurz: Trainingsmodule-Bibliothek (Phase 1) umgesetzt; Kombi-Katalog (056), Planungs-Snapshot planning_method_profile (057) mit Client-Merge Katalog+Planung (comboPlanningMethodProfile.js); Planung: Modal „Ablauf bearbeiten…“, Klammer CombinationPlanBracket; Coach Stufe A mit lesenden Profil-Labels und konsistenter Slot-Darstellung (CombinationCoachSlots, ExerciseFullContent). Offen: Coach Stufe B/C (individuelle Archetyp-Steuerung), Administrierbarkeit der Archetypen (derzeit nur Konstanten), einfache Vorbelegung aller Zeit-/Anzahlfelder, serverseitige Profil↔Archetyp-Restriktionen — siehe Fachspez § 10.6.

---

4. Stand: Medien-Management (Ist, 2026-05-07)

Datenmodell (Kurz):

• media_assets: Physische oder logische Archiv-Datei (u. a. sha256, visibility, club_id, lifecycle_state, copyright_notice, Speicherpfad/storage_key, tags ab passender Migration).
• exercise_media: optional media_asset_id; weiterhin Embeds ohne Asset; Kontext/Sortierung/Titel wie bisher.
• platform_media_storage: Superadmin — relativer Unterpfad unter MEDIA_ROOT.

API (Auszug):

• GET /api/media-assets, Filter (Lifecycle, media_kind, Verein, Suche, Tags), Berechtigungen pro Zeile.
• PATCH /api/media-assets/{id} / Bulk-PATCH, Lifecycle (POST …/lifecycle, Bulk).
• GET …/media-assets/{id}/file (inkl. Kontext ssetoken wo vorgesehen).
• POST /api/exercises/{id}/media/from-asset: bestehendes Asset verknüpfen.
• Übungs-Uploads erzeugen/verknüpfen media_assets; Governance wie library_content_* / TenantContext.

Frontend:

• Route /media (Medienbibliothek): Kacheln/Liste, Filter, Copyright, Lifecycle-Actions (Rollen gemäß Spec; official: bearbeiten/Lifecycle im Wesentlichen Superadmin, andere Rollen Lesemodus im Bearbeiten-Dialog).
• Übungsformular: Archiv-Picker, Vorschau, Reaktivierung bei Dedupe-Konflikt (Papierkorb).

Speicher & Pfade:

• Struktur unter library/ mit Vereinssegment (aus Vereinsname abgeleitet + c{id}), Unterordner nach Medienkind (image/video/pdf/other), Dateiname z. B. SHA-basiert — Details und Drift-Vermeidung in MEDIA_ASSETS_AND_ARCHIVE_SPEC.md.

Governance & Mandant:

• visibility=official für Übungen: nur Superadmin; Medien official: Lifecycle/PATCH schwerpunktmäßig Superadmin (Plattform-Admin nicht gleich Superadmin).
• Aktiver Verein: profiles.active_club_id, Header X-Active-Club-Id, Response effective_club_id — nach 0.8.59 konsistent inkl. Plattform-Admin beim Reload (Backend tenant_context, Frontend getResolvedActiveClubIdForUi + Profil-Refresh nach Vereinswechsel).

---

5. Inline-Medien im Fließtext (Spec Abschnitt 11 — umgesetzt)

Ist: Platzhalter-Syntax, zentraler Render-Pfad, Modal-Picker, Größenwahl, Drag-and-Drop in den Übungstextfeldern — siehe MEDIA_ASSETS_AND_ARCHIVE_SPEC.md (Abschnitt 11), FEATURES_DELIVERED_2026-Q2.md Abschnitt 12.3 und PROJECT_STATUS.md.

Weiteres: UX-Politik, ggf. strategische Vereinheitlichung der Referenzmodellierung (reine Asset-Referenz vs. exercise_media) — siehe Nächste Schritte in PROJECT_STATUS.md.

---

6. P-13: Content-Meldeverfahren (vollständig implementiert, 2026-05-11)

DSA-konformes Meldeverfahren (KRIT-03) — App 0.8.87–0.8.94.

Backend (backend/routers/content_reports.py, Migrationen 052–053):

• POST /api/content-reports — optionale Auth; official-Medien ohne Login meldbar; E-Mail-Bestätigung an Melder + Benachrichtigung aller Plattform-Admins (best-effort).
• GET /api/me/inbox/content-reports — Plattform-Admin: alle Meldungen; Club-Admin: nur Meldungen zu Medien eigener Vereine.
• GET /api/content-reports/{id} — Plattform-Admin + zuständiger Club-Admin.
• PATCH /api/content-reports/{id} — Status-Übergang (submitted → under_review → resolved/rejected); Wiedereröffnen (→ submitted) setzt Prüferfelder zurück; Audit-Log-Einträge bei Status- und Notizänderungen.
• POST /api/content-reports/{id}/legal-hold — Superadmin (immer) oder Club-Admin (Vereinsmedien, nicht official); integriert P-11 set_legal_hold(); plain Admin erhält früh 403.
• Automatische Priorisierung high für minors/illegal_content/youth_protection.
• Migration 053: content_report_filed Event-Typ in media_asset_audit_log CHECK-Constraint.
• open_report_count in list_media_assets-Response für Admin-Nutzer.
• 15 Backend-Tests in backend/tests/test_p13_content_reports.py (alle grün nach CI-Fix 0.8.94).

Frontend:

• ReportContentModal.jsx — Melde-Formular; onSuccess-Callback; readOnly-Felder für eingeloggte Nutzer.
• MediaPreviewModal.jsx — geteilter Vorschau-Dialog; optionale Melden- und Bearbeiten-Buttons.
• InboxPage.jsx — zweiter Abschnitt „Inhaltsmeldungen”; WorkflowBar (3-Schritte-Fortschrittsbalken); ReportDetailModal mit Workflow, Prüferinfo, Notiz, Wiedereröffnen-Button; Archiv-Trennung (offen vs. abgeschlossen, kollabierbar); Legal-Hold-Button für Superadmin + Club-Admin.
• OrgInboxContext.jsx — liefert contentReports, contentReportCount, canAccessContentReports, isClubAdmin, isPlatformAdmin, isSuperadmin, contentReportsError; Club-Admins haben Zugriff auf Berichte.
• MediaLibraryPage.jsx — rotes Badge mit open_report_count auf Medienkarten; Journal-Eintrag für content_report_filed; Badge-Aktualisierung via onSuccess.
• Melde-Button in MediaLibraryPage (Grid + Liste + Viewer), ExerciseFormPage (Viewer), ExerciseAttachmentMediaStrip (Viewer).

Offen (explizit zurückgestellt):

• P-14 Moderations-UI (eigene Seite), P-15 Uploader-Benachrichtigung bei Sperrung, P-16 Beschwerdeverfahren.
• Melde-Einstieg im Coaching-Modus (Feedback-Schritt, nicht kritisch).

---

7. Nächste Session — sinnvolle Arbeitspakete

1. P-13 Frontend-Verifikation: Melde-Flow in Medienbibliothek, Inbox-Workflow (Status, Archiv, Wiedereröffnen), Club-Admin-Ansicht manuell auf Dev-System durchspielen. E-Mail-Benachrichtigungen verifizieren (SMTP-Log).
2. Inline (Spec Abschnitt 11): Basis umgesetzt — verbleibend: gezielte UX-Politik; optional Server-Normalisierung/Absicherung prüfen, falls Produkt es verlangt.
3. Tests: pytest für media_assets-Router (Leserechte, Lifecycle, from-asset); ggf. Snapshot der Pfad-Umzug-Logik.
4. Retention: Job-Dokumentation + Betrieb (ENV, Intervall); Dry-Run beschreiben.
5. S3/Adapter: Speicher-Abstraktion (Spec Abschnitt 7) — wenn Produkt es verlangt.
6. Rahmen/UI: Kalender „aus Rahmen übernehmen” weiter anbinden (parallel, unabhängig von Medien).
7. Fachlicher Nutzerüberblick: bei größeren UX-Änderungen docs/FACHLICHE_NUTZERFUNKTIONEN.md mitpflegen.
8. Kombinations-Coach (Archetyp B/C): Fachspez § 10.4 / § 10.6; nach Implementierung Anhang A + TRAINING_MODULES_IMPLEMENTATION_PLAN.md aktualisieren (kein Doc-Drift).
9. Archetyp-Administration: Konfiguration oder DB statt nur COMBINATION_ARCHETYPE_IDS / combinationArchetypes.js (Paket 4e).
10. Kombi-Zeitfelder: Massen-Vorbelegung aller Slots aus Archetyp/Global + optionales Modal beim Archetypwechsel (Paket 4f, COMBINATION_TIMING_PROFILE_PLAN.md).
11. Backend-Validierung method_profile / planning_method_profile je Archetyp (Paket 4g).

---

8. Technische Referenz (kurz)

Bereich	Einstieg
Backend API	backend/main.py; u. a. media_assets.py, exercises.py (COMBINATION_ARCHETYPE_IDS, enrich_exercise_detail), profiles.py, training_framework_programs.py, tenant_context.py
Coach-Kombination / Merge-Profil (Frontend)	TrainingCoachPage.jsx, ExerciseFullContent.jsx, CombinationCoachSlots.jsx, CombinationPlanBracket.jsx, utils/comboPlanningMethodProfile.js, utils/combinationMethodProfileUi.js, constants/combinationArchetypes.js
Migrationen	backend/migrations/ (040+ Mitgliedschaft/Governance; 045+ Medien-Stack)
Frontend API	frontend/src/utils/api.js
Aktiver Verein (UI)	frontend/src/utils/activeClub.js, AuthContext.jsx
Version / Changelog	backend/version.py

---

9. Veraltete Hinweise

.claude/docs/working/HANDOVER_NEXT_SESSION.md verweist auf dieses Dokument (docs/HANDOVER.md) als aktuelle Basis.

---

Ende Handover-Dokument.