shinkan-jinkendo/docs/FACHLICHE_NUTZERFUNKTIONEN.md

Shinkan Jinkendo – Fachliche Nutzerfunktionen (Ist-Stand)

Zweck: Überblick über die wesentlichen, produktiv nutzbaren Funktionen aus Nutzer- und Fachperspektive – zur Weitergabe an Design, Product Discovery oder externe Fachplanung.

Technischer Detailstand: App-Version (APP_VERSION) und Datenbankschema (DB_SCHEMA_VERSION) siehe backend/version.py — dort ist der autoritative Stand.

Vertiefung: Domänenmodell .claude/docs/functional/DOMAIN_MODEL.md, Lieferdetal .claude/docs/library/FEATURES_DELIVERED_2026-Q2.md, Projektstatus .claude/docs/PROJECT_STATUS.md, Entwickler-Handover docs/HANDOVER.md.

---

1. Produktauftrag und Zielgruppe

Shinkan Jinkendo ist eine Web-Applikation für Trainer, Vereinsadmins und Inhaltsverantwortliche in der Kampfsport- und Trainingsplanung: zentrale Übungs- und Methodenverwaltung, strukturierte Trainingsplanung für Gruppen, wiederverwendbare Rahmenprogramme, sowie Governance von Inhalten (Sichtbarkeit, Vereinszuordnung, Plattform-Inhalte).

Explizit keine persönliche Sportler-App: Es geht nicht um individuelles Leistungstracking von Endnutzern oder um ein Athleten-Tagebuch; der Fokus liegt auf vereinlicher/trainersicher Organisation von Wissen und Ablaufplänen.

---

2. Rollen (vereinfachte Nutzerbilder)

Die sichtbaren Funktionen hängen von Rolle und Kontext ab (eingeloggter Nutzer, aktiver Verein, Plattform- vs. Vereins-Admin).

Rollenprofil (fachlich)	Typische Aufgaben in der App
Trainer / Redakteur	Übungen anlegen und pflegen, medienreich beschreiben, filtern/suchen; Trainingseinheiten für Gruppen planen; Rahmenprogramme nutzen oder mitgestalten (je nach Berechtigung); Medienbibliothek nutzen.
Vereinsadmin	Vereinsdaten, Mitgliedschaften, ggf. vereinsgebundene Inhalte und Medien; kann je nach Implementierung Inhaltsmeldungen zu Vereinsmedien bearbeiten und Legal Hold für Vereinsmedien auslösen.
Plattform-Admin	Globale Kataloge, Hierarchien, Importe, Nutzerverwaltung (soweit freigeschaltet); Posteingang inkl. organisationsbezogener Meldungen; Reifegradmodelle / Matrix-Stack.
Superadmin	Stärkste technische Rolle: u. a. offizielle Plattform-Inhalte (official), tiefe Medien-Lifecycle-Operationen, ausgewählte Hochrisiko-Aktionen (z. B. bestimmte Legal-Hold-Fälle).

Aktiver Verein: Nutzer mit Vereinsbezug arbeiten oft im Kontext eines gewählten aktiven Vereins (Profil, API-Header); das beeinflusst Sichtbarkeit von Inhalten und Mandantenlogik.

---

3. Hauptnavigation (Nutzerpfade)

Über die Hauptnavigation (mobil und Desktop) sind u. a. erreichbar:

• Übersicht – Einstieg / Dashboard.
• Posteingang – für berechtigte Nutzer: Änderungs- und Organisationsanfragen sowie Inhaltsmeldungen (Workflow, Status, Archiv).
• Übungen – Katalogarbeit, Suche, Filter, Detail, Bearbeitung; Progressionsgraphen zwischen Übungen; Fähigkeiten (Skills) als verknüpfte Dimension.
• Planung – Kalender-/Listenlogik für Trainingseinheiten (Sektionen, Übungen, optional Übungsvarianten); Trainingsrahmen (Bibliothek) mit Zielen und Slots; Durchführungsansicht und Coaching-Modus pro Einheit (je Route).
• Medien – zentrale Medienbibliothek (Filter, Suche, Tags, Lifecycle, Copyright-Hinweise; rollenabhängige Bearbeitung).
• Vereine – Organisation: Vereine, Struktur, Gruppen (soweit für den Nutzer freigeschaltet).
• Einstellungen – Profil, Systeminfos, ggf. Rechtstexte; Trainer-Kontexte separat (Route trainer-contexts).
• Admin (nur Admin-Rolle) – Plattformbereich: Nutzer, Hierarchie/Kataloge, Reifegradmodelle, MediaWiki-Import, Rechtstexte/P-01 u. a.

Öffentlich bzw. ohne volle App: Impressum, Datenschutz, Nutzungsbedingungen, Medienrichtlinie; Login/Registrierung/Verifizierung.

---

4. Funktionsblöcke im Detail (fachlich)

4.1 Übungen (Kernobjekt)

• Anlegen, Bearbeiten, Archivieren/Löschen je nach Rolle und Freigabelevel (siehe §4.7).
• Bearbeitungsformular (Registerkarten): Stammdaten · Anleitung · Einordnung · (Kombination) · Varianten · Medien & Mehr — reduziert Scroll-Tiefe; farbige Panel-Trenner; Varianten und Medien erst nach erstem Speichern.
• Mehrdimensionale Einordnung: Fokusbereiche, Stilrichtungen, Trainingsstile, Zielgruppen, Fähigkeiten mit Stufen und Intensität (niedrig/mittel/hoch); Suche und Filter über diese Dimensionen.
• Übungsvarianten: mehrere Ausprägungen einer Übung (z. B. Aufbau, Schwierigkeit, Material), mit Reihenfolge und optionaler Voraussetzungsvariante; Bearbeitung im Tab Varianten; Änderungen werden mit Speichern in der Aktionsleiste mitgesichert (oder „Variante anlegen“ für sofortiges Anlegen).
• Progressionsgraph: gerichtete Beziehungen von Übung zu Übung (und Variantenbezug), Pflege in der Übungswelt; unterstützt didaktische „weiter“-Ketten.
• Medien an der Übung: Upload, Einbettung, Verknüpfung aus dem Archiv; Darstellung in Detail- und Bearbeitungsansicht.
• Rich-Text-Felder (Ablauf, Ziele, Hinweise): Inline-Verweise auf verknüpfte Medien über eine einheitliche Platzhalter-/Renderlogik (konsistent mit Archiv-Governance).
• Exercise Blocks („Bausteine“) und gespeicherte Suchpräferenzen, wo implementiert.
• Kombinationsübungen („combination“, Migration 056): Sonderform im Übungskatalog mit Stationen/Slots, Trainingsmethode-/Archetyp (method_archetype), optionalem strukturierten Ablaufprofil (method_profile). In der Planung wie eine Übung ohne Variante einsetzbar; im Coach werden Stations-Kandidaten und Archetyp-Hilfstexte angezeigt (Ausbauschritte B/C nach Fachspez § 10.4 dokumentiert unter .claude/docs/functional/… Kombinationsübungen Spezifikation V2.md Anhang A).

4.2 Fähigkeiten, Methoden, Kataloge

• Globaler Fähigkeitskatalog mit hierarchischer Struktur (Kategorien, Stufen); Zuordnung zu Übungen.
• Trainingsmethoden-Katalog (bestehende Domäne).
• Admin/Katalog-Pflege für Fokusbereiche, Stile, Zielgruppen und Zusammenhänge (Plattform-Admin-Bereich).
• Planungs-Vorschläge (Phase 3): Auf der Fähigkeiten-Seite können Schwerpunkte gewählt werden; Shinkan schlägt passende Rahmenprogramme, Trainingsmodule und Regressionspfade vor (Sortierung nach Trainingsgewicht).
• Fähigkeiten-Profile an Planungs-Bausteinen: Listen zeigen pro Modul/Rahmenprogramm KPI-Kacheln (Top je Kategorie) mit Score und Peer-Prozent — Vergleich nur unter sichtbaren Bausteinen desselben Typs (Modul vs. Modul, nicht Modul vs. Plan). Filter analog zur Übungsliste (Modal, Chips, Baumauswahl).

4.3 Reifegradmodelle (Fähigkeitsmatrix)

• Matrixbasierte Modelle mit Stufen und Zelltexten; kontextsensitive Auflösung (Fokus, optional Stilrichtung, Trainingsart) über Bindings.
• Export/Import einzelner Modelle und Komplett-Stack (Admin-Werkzeuge) für Übertrag zwischen Umgebungen oder Backup.

4.4 Trainingsplanung

• Trainingseinheiten als planbare Objekte mit Sektionen und Einträgen (Übungen, ggf. mit Variante und Metadaten wie Dauer).
• Phasen & parallele Streams (Breakout): Eine Einheit kann aus abwechselnden Ganzgruppenphasen und Parallelphasen bestehen; in einer Parallelphase führen mehrere Streams (Teilstrecken) je eigene Abschnitte/Übungen. Planung über Breakout-UI; API liefert phases und flache sections (Migration 063, siehe docs/HANDOVER.md). Technische Details: .claude/docs/technical/PARALLEL_TRAINING_STREAMS_SPEC.md.
• Trainingsvorlagen / Mikrovorlagen (wo eingerichtet): Struktur wiederverwenden (Phasen in Vorlagen: Ausbau siehe Handover „offen“).
• Trainingsrahmenprogramm (Bibliothek): übergeordnete Programme mit Zielen und Slots; Slot-Inhalt technisch als Blueprint-Trainingsunit abgebildet.
• Trainingsmodule (Bibliothek): wiederverwendbare Übungsfolgen; Übernahme in geplante Einheiten; Fähigkeiten-Profil und Filter in der Modul-Liste (Peer-Vergleich nur unter Modulen).
• Rahmenprogramm-Liste: Suche und Filter (Katalog, Dauer, Fähigkeiten) — Peer-Vergleich nur unter Rahmenprogrammen.
• Materialisierung: aus einem Rahmen-Slot kann eine konkrete Kalender-Einheit für eine Gruppe erzeugt werden (API vorhanden; UI-Anbindung kann erweitert werden).
• Durchführung („Plan & Ablauf“): Ablauf anhand Phasen/Streams darstellen und abarbeiten (inkl. Split-Logik in der Anzeige).
• Coaching-Modus: eigener Ablauf mit Schritt-für-Schritt-Timeline, Stream-Wahl pro Parallelphase, Hinweis „Parallelphase · Abschluss“ (Gruppen zusammenführen) vor der nächsten Ganzgruppenphase oder vor dem nächsten Split; Nachbereitung mit Ist-Minuten und Speichern wie in der Planung (inkl. phases). Nach erfolgreichem Speichern Wechsel zur Plan- und Ablaufsicht derselben Einheit. Bei Kombinationsübungen zusätzlich Stations-/Kandidaten-Schicht und Archetyp-Hinweise (Fachspez Anhang A; Ausbauschritte B/C).

4.5 Medienbibliothek und Archiv

• Zentrale Medienverwaltung: Suche, Filter (u. a. Lifecycle, Medientyp, Verein für Admins), Tags, Copyright-Felder.
• Lifecycle: aktive Nutzung, Papierkorb-Stufen, Wiederherstellung; endgültiges Entfernen stark eingeschränkt (Superadmin-Kontext).
• Governance: Sichtbarkeit (z. B. privat, vereinsbezogen, official); official ist fachlich „Plattform offiziell“ und an Superadmin gebunden.
• Rechtliche Sofortmaßnahme: Legal Hold kann Medien vor automatisiertem Lifecycle schützen (Fälle aus Meldungen oder Admin-Prozessen).

4.6 Organisation und Mitgliedschaft

• Vereine (Clubs) mit Struktur (Sparten/Divisions, Trainingsgruppen) je nach Ausprägung.
• Beitritts- und Mitgliedschaftslogik (Requests, Rollen) für mandantenfähige Zusammenarbeit.

4.7 Governance von Übungsinhalten

• Freigabelevel (visibility in der API): steuert, wer eine Übung lesen darf — Werte u. a. privat, Verein (club), offiziell (official). In der Oberfläche heißt das Feld durchgängig Freigabelevel (nicht „Sichtbarkeit“).
• Status: Entwurf, in Prüfung, freigegeben, archiviert — konkrete Werte siehe Datenmodell.
• Owner: Der anlegende Nutzer (created_by). Varianten haben keinen eigenen Owner; Rechte folgen der Eltern-Übung.
• Bearbeiten (Stammdaten, Varianten, Medien): Ersteller; Plattform-Admin; bei Vereins-Übungen zusätzlich Planungs-/Inhaltsrollen im Objekt-Verein (Trainer, Content-Editor, Spartenleitung, Vereins-Admin).
• Löschen: privat — Ersteller (Vereins-Admin im gemeinsamen Verein mit Ersteller); Verein — nur Vereins-Admin; offiziell — nur Plattform-Admin.
• Änderungsanfragen (Content Change Requests) für vorgeschlagene Änderungen an Inhalten – Einreichung und Bearbeitung über Posteingang/Admin-Prozesse (Detailtiefe siehe Fachdoku).

4.8 Inhaltsmeldungen (P-13, vertrauens- und compliance-orientiert)

• Melden von problematischen Inhalten (auch aus Medien- und Übungskontexten; official-Medien teils ohne Login meldbar).
• Posteingang für Admins: Eingang neuer Meldungen, Statusworkflow (z. B. eingereicht, in Prüfung, erledigt/abgelehnt), Notizen, Wiedereröffnen; getrennte Darstellung abgeschlossener Fälle (Archiv).
• Priorisierung bei sensiblen Kategorien (Minderjährige, illegaler Inhalt, Jugendschutz – fachlich automatisch höher gewichtet).
• Anbindung an Legal Hold und Audit-Spuren im Medien-Journal wo vorgesehen.

4.9 Import und Plattform-Werkzeuge

• MediaWiki-basierter Import von Übungsinhalten mit Tracking und Duplikat-Referenzen (Admin).
• Plattformnutzerverwaltung und Rechtstexte mit editorseitiger und listenbasierter Vorschau (Markdown, strukturierte Ausgabe inkl. PDF-Darstellung – siehe technische Versionsnotizen).

---

5. Bekannte Lücken und Planungshinweise (kurz)

Nicht als „broken“ gemeint, sondern als typische nächste Ausbaustellen für Product/Design:

• Kalender-UX: „Aus Rahmen übernehmen“ flächendeckend und ggf. bulkfähig anbinden.
• Policies für geteilte Rahmen (Wer darf Bibliotheks-Rahmen sehen/kopieren?).
• Skill-Kategorie-Admin-UI, Dark Mode/Responsive/PWA-Ausbau, KI-Suche über Volltext hinaus – je nach Backlog.
• Coach / Kombination: Kombi-spezifische Archetyp-Stufen B/C (Zeitleisten-Splitting, archetypnahe Timer — Fachspez § 10.4); geführtes Erfassen von method_profile im Übungseditor.
• Breakout: vollständige Server-Spiegelung neuer Abschnitte in phases; Vorlagen phasengleich mit Kalendereinheit; optional Stream-Tabs in der Durchführungsansicht laut technischer Spec — siehe docs/HANDOVER.md (Arbeitspaket „Coaching & Breakout“).

---

6. Änderungshistorie dieser Zusammenfassung

Datum	Änderung
2026-05-20	Fähigkeiten-Scoring Phase 3: Peer-Kontext, Listen-Filter Module/Rahmen, Planungs-Vorschläge.
2026-05-14	Trainingsplanung: Phasen/parallele Streams, Coaching (Rejoin, Nachbereitung → Planansicht); Lücken §5 ergänzt. Verweis HANDOVER.md.
2026-05-12	Erstfassung für Übergabe an fachliches Design; Abgleich mit Code-Navigation, version.py, HANDOVER.md, FEATURES_DELIVERED, DOMAIN_MODEL.
2026-05-12	Kombinationsübungen + Coaching Stufe A; Verweise auf Fachspezifikation (…Kombinationsuebungen… V3 Anhang A) und TRAINING_MODULES_IMPLEMENTATION_PLAN.md.