Lars/shinkan-jinkendo
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 3 Wiki Activity
3dc4c9c79e
shinkan-jinkendo/docs/FACHLICHE_NUTZERFUNKTIONEN.md
Lars 59d53d6154
All checks were successful
Deploy Development / deploy (push) Successful in 38s
Details
Test Suite / pytest-backend (push) Successful in 35s
Details
Test Suite / lint-backend (push) Successful in 1s
Details
Test Suite / build-frontend (push) Successful in 11s
Details
Test Suite / playwright-tests (push) Successful in 56s
Details
docs: update project status and add user overview documentation 
- Updated project status to version 0.8.96 as of 2026-05-12, reflecting recent enhancements and features.
- Added a new section for the user overview in `docs/FACHLICHE_NUTZERFUNKTIONEN.md`, providing a compact perspective for design and product teams.
- Revised references in various documents to include the new user overview and updated project status.
- Enhanced the requirements documentation to link to the user overview for better clarity.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-12 21:20:36 +02:00

9.2 KiB
Raw Blame History

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 und Schema siehe backend/version.py (Stand Code: 0.8.96, DB_SCHEMA_VERSION siehe dort).

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 Sichtbarkeit.
  • Mehrdimensionale Einordnung: Fokusbereiche, Stilrichtungen, Trainingsstile, Zielgruppen, Fähigkeiten mit Stufen; Suche und Filter über diese Dimensionen.
  • Übungsvarianten: mehrere Ausprägungen einer Übung (z. B. Aufbau, Schwierigkeit, Material), mit Reihenfolge und optionaler Voraussetzungsvariante.
  • 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.

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).

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).
  • Trainingsvorlagen / Mikrovorlagen (wo eingerichtet): Struktur wiederverwenden.
  • Trainingsrahmenprogramm (Bibliothek): übergeordnete Programme mit Zielen und Slots; Slot-Inhalt technisch als Blueprint-Trainingsunit abgebildet.
  • 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: Ansicht zum Abarbeiten einer Einheit; Coaching-Modus als separater Erlebnispfad.

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

  • Änderungsanfragen (Content Change Requests) für vorgeschlagene Änderungen an Inhalten – Einreichung und Bearbeitung über Posteingang/Admin-Prozesse (Detailtiefe siehe Fachdoku).
  • Sichtbarkeits- und Statusmodelle für Übungen (Entwurf, veröffentlicht, archiviert – konkrete Werte siehe Datenmodell).

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.
  • Moderations-Fläche, Uploader-Benachrichtigung bei Sperre, Beschwerdeverfahren – laut Handover bewusst noch nicht umgesetzt (Nachfolge von P-13).

6. Änderungshistorie dieser Zusammenfassung

Datum Änderung
2026-05-12 Erstfassung für Übergabe an fachliches Design; Abgleich mit Code-Navigation, version.py, HANDOVER.md, FEATURES_DELIVERED, DOMAIN_MODEL.