Lars/shinkan-jinkendo
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 3 Wiki Activity
ae6c089366
shinkan-jinkendo/.claude/docs/technical/TRAINING_FRAMEWORK_SPEC.md
Lars 1b7a0405e9
Some checks failed
Deploy Development / deploy (push) Successful in 39s
Details
Test Suite / lint-backend (push) Successful in 0s
Details
Test Suite / build-frontend (push) Successful in 7s
Details
Test Suite / playwright-tests (push) Failing after 41s
Details
feat: add exercise progression graph functionality and update versioning 
- Integrated exercise progression graphs into the backend and frontend, allowing users to visualize relationships between exercises.
- Updated API endpoints for managing exercise progression graphs and edges, enhancing the exercise management capabilities.
- Added a new tab in the ExercisesListPage for displaying progression graphs and included a panel in the ExerciseFormPage for editing.
- Incremented application version to 0.8.6 and updated changelog to reflect new features and improvements.
2026-04-30 11:47:50 +02:00

5.6 KiB
Raw Blame History

Trainingsrahmenprogramm — Technische Spezifikation (Stub)

Status: Entwurf · angelegt 2026-04-28
Bindendes Fachkonzept / Entscheide: .claude/docs/functional/TRAINING_CURRICULUM_AND_GOVERNANCE_CONCEPT.md (CURR‑001 bis CURR‑013)

1. Abgrenzung zu anderen Dokumenten

Dokument Rolle · warum nicht hier hineinmischen
EXERCISES_DATABASE_FINAL.md, EXERCISES_ARCHITECTURE.md, EXERCISES_API_SPEC.md Übungskatalog inkl. Varianten-Progression (Migration 014). Kein Ort für Multi-Session-Rahmen, Slots, Rahmen-Ziele oder training_units-Orchestrierung.
DATABASE_SCHEMA.md Nachgeordnete Übersicht: Migrationshistorie und kompakte Tabellenliste. Neue Migrationen hier einzeilig ergänzen, Detail-DDL gehört primär hierher (§3) oder in Migrations-SQL.
functional/DOMAIN_MODEL.md Fachliche Kernbegriffe; bei Release des Rahmenfeatures ein kurzer Unterabschnitt „Rahmen-Vorlage / Slots“ ergänzen, Verweis auf diese Datei.
TRAINING_CURRICULUM_AND_GOVERNANCE_CONCEPT.md Was und warum (Modus A/B, Governance, CURR‑Tabelle). Keine DDL-Pflicht.

Konsequenz: Diese Datei ist der technische Arbeitspool für Rahmenprogramm-Stufe 1–2 (Graph + Rahmenentität + Slots + Zielliste + API/Migrationen).

2. Noch auszuarbeiten (Checkliste)

  • Entität(en): eigene Bibliotheks-Entität für Mehr-Slot-Rahmen (training_framework_* o. Ä., siehe CURR‑009); Abgrenzung zu training_plan_templates (C5).
  • Modus A vs. B: ein Typ mit nullable group_id / plan_mode vs. zwei Objekttypen — offen (Funktionskonzept §6).
  • Zielliste: ≥1 Zieleinträge pro Rahmen (CURR‑011); Felder und Optionalität.
  • Slots: Reihenfolge, Notizen, direkte Übungszuordnungen (M:N oder Join-Tabelle); optionales training_plan_template_id pro Slot (CURR‑010, MVP offen).
  • Progressionsgraph zwischen Übungen: Tabellen/Kanten, getrennt von Varianten-Progression in exercise_variants (CURR‑002 (1), CURR‑013) — siehe §3.
  • Instanziierung (Modus B): FK/Metadaten zu training_units, Bulk vs. Verknüpfen (CURR‑012).
  • Governance: visibility, club_id, created_by für neue Bibliothekstypen (CURR‑005); Nachzug training_plan_templates (CURR‑007, CURR‑008).
  • REST/API: Endpoints grob, AuthZ analog Trainingsplanung.

3. Progressionsgraph Übung → Übung (Stufe 1, Migration 032)

Abgrenzung: Kanten verbinden exercises.id → exercises.id. Die Varianten-Kette innerhalb einer Übung bleibt in exercise_variants (Migration 014).

Schema

Tabelle Zweck
exercise_progression_graphs Kontainer für mehrere getrennte Graphen (Name, Beschreibung, visibility private|club|official, club_id, created_by).
exercise_progression_edges Gerichtete Kante: graph_id, from_exercise_id, to_exercise_id, edge_type (VARCHAR, Default next_exercise, erweiterbar ohne ENUM-Zwang).
  • Eindeutigkeit: UNIQUE (graph_id, from_exercise_id, to_exercise_id, edge_type); CHECK (from_exercise_id <> to_exercise_id).
  • Löschregeln (FK):
    • Kante → Graph: ON DELETE CASCADE (Graph löschen entfernt alle Kanten).
    • Kante → Übung (von/nach): ON DELETE CASCADE (Übung löschen entfernt alle incident Kanten in allen Graphen — konsistent mit anderen Übungs-Abhängigkeiten wie exercise_skills).
  • Indizes: graph_id, from_exercise_id, to_exercise_id.

API (FastAPI, Prefix /api)

Methode Pfad Kurzbeschreibung
GET /exercise-progression-graphs Liste (Admin/Superadmin: alle; sonst nur eigene created_by).
GET /exercise-progression-graphs/{id} Detail; Query include_edges=true für eingebettete Kanten.
POST /exercise-progression-graphs Anlegen (_has_planning_role, wie Trainingsvorlagen).
PUT /exercise-progression-graphs/{id} Metadaten (name, description, visibility, club_id).
DELETE /exercise-progression-graphs/{id} Graph + Kanten (CASCADE).
GET /exercise-progression-graphs/{id}/edges Kantenliste; optional Filter from_exercise_id, to_exercise_id.
POST /exercise-progression-graphs/{id}/edges Kante anlegen; Duplikat → 409.
DELETE /exercise-progression-graphs/{id}/edges/{edge_id} Kante löschen.

AuthZ: Analog training_plan_templates: Zugriff auf einen Graphen nur Admin/Superadmin oder Ersteller (created_by).

Offen / später

  • Weitere edge_type-Semantik und Filter in der UI („Vorschläge“ beim Planen).
  • CURR‑013: Graph bleibt unterstützend; keine Pflicht, jeden Trainingsplan über den Graph zu modellieren.
  • Anbindung training_units / Rahmen-Slots (Stufe 2, CURR‑009–012).

Manuelle Prüfung

  1. Nach Migration: GET /api/exercise-progression-graphs mit gültigem X-Auth-Token.
  2. POST /exercise-progression-graphs mit {"name":"Testgraph"} → 201.
  3. POST …/{id}/edges mit gültigen from_exercise_id / to_exercise_id; zweites identisches Quadrupel → 409.
  4. Übung löschen, die an einer Kante beteiligt ist: Kanten verschwinden (CASCADE).

4. Changelog

Datum Änderung
2026-04-30 §3: Migration 032 + REST-Endpunkte Progressionsgraph (CURR‑002 (1)); Checkliste Graph erledigt.
2026-04-28 Erstanlage: Abgrenzung + Checkliste (Artefakt der Doku-Entscheidung „eigene technische Spec“).