Lars
c4fbabd8f6
- Incremented APP_VERSION to 0.8.10 and DB_SCHEMA_VERSION to 20260505037. - Updated project status and domain model documentation to reflect recent changes. - Enhanced training framework program handling with new slot-blueprint structure. - Introduced API endpoint for creating training units from framework slots. - Improved documentation for training planning and governance concepts.
21 KiB
21 KiB
Konzept: Trainingsplanung über Einheiten hinweg, Kurspläne, Governance, Assessments
Status: Arbeitspapier (lebend)
Stand: 2026-05-05 (Rahmen‑Bibliothek 036, Slot‑Blueprint 037 / API from-framework-slot; CURR‑002 Stufe 1 Graph unverändert 032–034)
Zweck: Erkenntnisse und getroffene Entscheidungen festhalten, um Spec- und Implementierungsdrift zu vermeiden.
Kanons: Bei Widersprüchen mit produktiven Specs zuerst diese Datei mit dem Team abstimmen; technische Details ergänzen später in technical/.
1. Kurz-Zielbild (Problem)
- Heute: Planung denkt stark pro einer Trainingseinheit (Struktur + Übungen).
- Gewünscht:
- Trainingsrahmenprogramm (über mehrere Session-Slots): mehrere Entwicklungsziele über denselben Zeitraum sowie Zuordnung von Übungen zu Sessions; unterstützt manuelle Verteilung (ohne Pflicht-Progressionsgraph) und optional persistente Progressionsbäume (v. a. Verwalter) — siehe CURR‑010, CURR‑011, CURR‑013.
- Mehrwöchige / periodische Planung (z. B. Monat) mit Entwicklungszielen und Verteilung aufbauender Elemente über mehrere Einheiten – auch ohne vollständiges „Kursprogramm“-Produkt.
- Standard-Kurs-/Stufenpläne (zeitlos, mehrschrittig) als Basis für konkrete Durchführung; Instanzen editierbar ohne Änderung der Vorlage.
- Governance einheitlich über Domänen (Übungen, Verein, Trainingspläne, Kurspläne …), ohne spätere Modellbrüche.
- Nachvollziehbarkeit: real durchgeführte Einheiten an Pläne/Vorlagen zurückführen; Feedback zur Verbesserung von Standardplänen.
- Assessments als Spezialfall eines Plans (Tests, z. B. Gürtel), später ggf. Teilnehmerbezug und Erwartungsniveau.
2. Geführte Konzepterstellung (Arbeitsschritte)
Konzept-Arbeit: Ziele klären → Optionen → Entscheidung in §5 → Glossar §4 pflegen.
2.a Umsetzungs-Reihenfolge „Rahmenprogramm“ (product / binding laut CURR-001–002)
| Stufe | Inhalt | Status |
|---|---|---|
| 1 | Progressionsbezüge zwischen Übungen persistent speicherbar (Progressionsbaum / -graph zwischen Übungseinheiten, nicht nur UI) | ✅ Zwischenstand im Produkt (Migrationen 032–034, UI/API); UX für parallele gleichwertige Alternativ‑Pakete noch kein Erstklass‑Fall — siehe technical/TRAINING_FRAMEWORK_SPEC.md §4 |
| 2 | Planungs-/Rahmenmodus: Übungen auf mehrere Session-Slots verteilen; mehrere Ziele; speicherbare Rahmen-Vorlage (CURR‑002 (2) i. V. m. CURR‑010–013) | in Arbeit: Bibliotheks‑Backend + Slot‑Blueprint + Kopie‑API (037); UI Kalender/Bulk folgt (CURR‑012) |
| 3 | Konkrete Einheit: aus Rahmen-/Verteilungsplan Vorschläge beim Ausarbeiten laden; Bezug zur Idee „Warenkorb“ bei der Übungsplanung | folgt nach 2 |
2.b Übrige Konzept-Schritte (noch durchzuarbeiten)
| Schritt | Thema | Status |
|---|---|---|
| A | Scope & Reihenfolge relativ zu Kursprogramm, Backlog-Themen | ✅ siehe §5 CURR-001–004 |
| B | Governance-Muster (einheitliche Sichtbarkeit; Bibliothek vs. Instanz) | ✅ Leitplan §2.c; Entscheidungen §5 CURR-005–007 |
| C | Rahmenprogramm — §2.d (C1–C4 ✅ · C5 Leitplan) | ✅ Kern i. V. m. CURR‑009–013 |
| D | Kurs-/Stufenprogramm: nach Rahmenprogramm; plantechnisch ähnlich | 📌 zeitlich nachgelagert (CURR-003) |
| E | Lineage & Feedback (Einheit ↔ Vorlage/Rahmen; Issues zur Nachbesserung) | ➕ teilweise: training_units.origin_framework_slot_id; vollständiges Konzept/UX offen |
| F | Assessments | 📌 Backlog (CURR-003) |
| G | Progressions-Automatik (KI, komplexe Vorschläge) | 📌 Backlog (CURR-003) |
Aktueller Fokus: Kalender-/Planungs‑UI an POST /api/training-units/from-framework-slot und Visibility für geteilte Rahmen; weiteres Lineage (Schritt E) ergänzend zu origin_framework_slot_id.
2.c Schritt B – Governance-Muster (Leitplan)
B.1 Ziel
Ein wiedererkennbares Muster für alle Bibliotheksobjekte (Übung, Trainingsplan-Vorlage, Übungsblock, künftig Rahmen-/Kurs-Vorlage, Progressions-Paket …), damit CURR-004 (spätere Rechte nach Rolle/Zugehörigkeit) ohne Modellbruch nachrüstbar ist.
B.2 Ist-Stand im Produkt (kurz, Stand Code-Review)
| Objekt | Relevante Felder / Muster |
|---|---|
exercises, exercise_blocks |
visibility ∈ private | club | official, club_id, created_by — Referenzmuster |
training_plan_templates |
club_id, created_by, visibility seit 035 (Backfill club); Referenz‑Muster an Übung angleichen (CURR‑007 erledigt für dieses Feld) |
training_framework_programs |
visibility, club_id, created_by; Kontext focus_area_id, style_direction_id; keine Kopf‑group_id; Slot‑Inhalt über Blueprint‑training_units (036–037) |
training_units |
group_id, created_by, plan_template_id — Instanz oder Blueprint (framework_slot_id); Lineage‑Light origin_framework_slot_id |
B.3 Prinzipien (binding mit §5)
-
Bibliothek vs. Instanz
- Bibliothek: zeitlose Objekte (Übung, Vorlage, Rahmen-Template, Graph-Definition …). Tragen Sichtbarkeits-Metadaten nach gemeinsamem Muster.
- Instanz: z. B.
training_unitam Termin; inhaltliche Bearbeitung entkoppelt von der Vorlage (Kopie der Struktur, nicht „Live-Link“ zur Überschreibung der Vorlage). - Zugriff auf Instanzen: primär über Trainingsgruppe / Rolle (Trainer, Co-Trainer); nicht zwingend über
visibilityder Vorlage dublett führen in Phase 1.
-
Einheitlicher Governance-Kern für neue & nachzuziehende Bibliothekstypen
- Minimal:
visibility(gleiche Semantik wie bei Übungen),club_id(optional, NULL = nicht vereinsgebunden / global nutzbar je nach Policy),created_by. - Sparte (
division): optional späterdivision_idoder M:N — nicht im MVP-Kern erzwingen, damit keine parallele „Rights-Welt“ pro Objekttyp entsteht.
- Minimal:
-
Policy vs. Speicherung
- DB-Felder beschreiben „wem gehört es / welche Lesestufe“ intentionell; durchsetzende Filter in API/UI folgen schrittweise (CURR-004).
- Vermeiden: Objekttypen mit völlig anderen Spaltennamen für dieselbe Idee (
ownervscreated_byohne Konvention).
-
Herkunft / Lineage (nur Metadaten)
- Wo sinnvoll:
plan_template_id, späterframework_program_template_id, optionalforked_from_*für Nachvollziehbarkeit ohne Kopplung für Writes. - Detail Arbeitspaket Schritt E; nicht mit Governance-Kern vermischen.
- Wo sinnvoll:
-
Progressionsgraph
- Als eigener Bibliotheks-Kontainer oder als Annotion an Übung(en): gleicher Governance-Kern; Ausnahmen nicht vorwegnahmen ohne technische Spec (§6 offene Fragen).
B.4 Bewusste Nicht-Ziele in diesem Schritt
- Keine endgültige Matrix „Welche Rolle sieht welches
official“. - Keine Pflicht-Anbindung Sportler/Lehrender außerhalb bestehender Gruppenmitgliedschaft.
2.d Schritt C – Trainingsrahmenprogramm (Ausarbeitung · Status Kern geklärt)
Checkliste — Abgleich Produktfeedback 2026‑04‑29
| Check | Ergebnis | Verweis |
|---|---|---|
| C1 | ✅ Eigene Rahmen-Entität (C1a) — nicht die Einheitenvorlage überladen | CURR‑009 |
| C2 | ✅ Slots erlauben beliebige Übungen über Trainings-/Slots zu verteilen; persistenter Progressionsgraph ist unterstützend, Pflicht‑Pflege im Graph gilt nicht (Admin‑Aufwand; v. a. global) | CURR‑010, CURR‑013 |
| C3 | ✅ Über denselben Planungszeitraum mehrere gleichzeitige Entwicklungsziele (nicht nur ein Sammelfeld) | CURR‑011 |
| C4 | ✅ Zwei Nutzungsbilder, kein „entweder C4a oder C4b global“ — siehe Ausführungen unten zu Konkret vs. Bibliothek | CURR‑012 |
| C5 | ✅ training_plan_template bleibt eine‑Einheit‑Mikrovorlage; Rahmen adressiert n Sessions; pro Slot weiterhin möglich: optional training_plan_template_id (Technical Spec entscheidet MVP‑Pflicht) |
Glossar |
C4 verständlich: „Materialisierung“ = zwei echte Situationen
| Nutzungsbild | Kontext | Gruppe / Datum | Typische Persistenz‑Schicht |
|---|---|---|---|
| A – Kurzfrist‑ / Basisplanung („nächste Wochen“) | Konkret für eine Trainingsgruppe geplant | Immer: Gruppe + Termin(e) wie heute beim Training | Existierende oder neu angelegte training_units; Rahmen fungiert als Planhilfe/Vorlage über mehrere dieser Einheiten |
| B – Kursprogramm-/Lehrplan‑Bibliothek | Übergeordnete Struktur ohne laufenden Kurs | In der Bibliotheksvorlage selbst oft: keine Gruppe/Zeit | Rahmen-/Kurs‑Vorlage zeit‑ und gruppenlos gespeichert; Übertrag (Instanziierung) erst bei „wir machen einen Kurs daraus“: dann Wahl Gruppe + Zeitraum → Anlegen oder Befüllen von training_units |
Klartext zur früheren Frage „C4a vs. C4b“: Bei Modus A passen automatisches Anlegen n Einheiten (früheres C4a) oder Zuordnung zu bereits geplanten Einheiten (C4b) — je nach Produkt/UI. Bei Modus B existieren erst bei der Übernahme überhaupt Gruppe/Zeiten; die Bibliotheksvorlage bleibt neutral.
Stand Code 036–037: Am Rahmenkopf gibt es keine plan_mode/group_id mehr — die Bibliothek ist immer „Modus B“; konkrete Gruppe/Zeit entstehen nur in training_units (Kalender‑Zeilen oder Übernahme‑API from-framework-slot).
C2 (Klärung fürs Team)
„C2“ im Entwurf bezog sich auf „wie weiß ich pro Slot welche Übungen (nur Progression oder auch Mikro‑Vorlage)?“ — aktueller Beschluss:
Pro Slot: Zuordnung von Übung(en) als Teil des vollständigen Ablaufs (wie geplante Einheit: Sektionen und Items, 037) ist tragend; Progressionsgraph liefert Vorschläge / Pakete, wenn Admins sie pflegen — Trainer können ohne Graph planen.
C1/Erinnerung Checkbox (historisch)
[x] C1aeigene Rahmen‑Entität bestätigt (Chat 2026‑04‑29).
Konkretisierung technischer Felder (ein Objekt zwei Modi vs. zwei Typen) → Technical Spec; keine neuen Contradicts zu CURR‑001 ohne expliziten Beschluss.
3. Richtungen aus Diskussion (nicht-binding, wenn nicht in §5)
| Thema | Richtung |
|---|---|
| Assessments als Plantyp | Spezielle Form eines Trainingsplans; Test-Übungen; später Sportlerbezug/Erwartungsniveau (Gürtel) — aktuell Backlog, siehe CURR-003. |
| Bibliothek vs. Durchführung | Konkrete Pläne/Einheiten editierbar ohne Änderung am Standard-/Rahmen-Template (Kopien / Instanzen). |
Scope-Reihenfolge und Governance-Startpunkt sind ab 2026-04-29 in §5 festgehalten (CURR-001 bis CURR-004).
4. Glossar (wird ergänzt)
| Begriff | Bedeutung (vorläufig) |
|---|---|
| Bibliotheksobjekt | Zeitlose Vorlage (Übung, Trainingsplan-Vorlage, Kursrahmen, später Assessment-Vorlage …) |
| Governance-Kern | Einheitliches Minimalset an Metadaten für Bibliotheksobjekte: v. a. visibility, club_id, created_by (siehe §2.c) |
| Instanz (Training) | training_unit o. Ä.; Zugriff über Gruppe/Rolle; Inhalt als Kopie aus Vorlagen, nicht schreibend an Vorlage gekoppelt |
| Trainingsrahmenprogramm | Über mehrere Session-Slots: mehrere gleichzeitige Entwicklungsziele und Zuordnung von Übungen zu Slots/Einheiten; manuelle Zuordnung + optional Progression (CURR‑010, CURR‑011, CURR‑013) |
| Progressionsbaum / -graph | Optionale gerichtete Beziehungen zwischen Übungen zur Unterstützung beim Planen (CURR‑010 — kein Pflicht‑Pflegeschritt für jede Zuordnung); v. a. für globale Pflege |
| Rahmen-Vorlage („Framework“) | Bibliothekskontainer mit ordered Slots, zeitlos möglich (Modus B) oder im Konkretkontext an Gruppe geknüpfte Planung (CURR‑012); eigene Entität (CURR‑009) |
| Slot | Position in der Reihenfolge eines Rahmens; trägt Übungszuweisungen („Stückliste“), optional Hinweise/Text; Datum optional bis Materialisierung |
| Materialisierung / Instanziierung | Überführung aus (ggf. zeit‑/gruppenloser) Rahmen-Bibliothek in konkrete training_units mit Gruppe/Zeitraum — CURR‑012 Modus B. Modus A bleibt nahe bestehender Einheiten-Planung |
| Konkret-Planung (Modus A) | Mehr‑Wochen für bekannte Trainingsgruppe + Terminen — training_units |
| Bibliotheks-Rahmen (Modus B) | Strukturierte Vorlage ohne Gruppe/Uhrzeit („Kursprogramm“‑Wurzel bis zum Import in einen Kurs) |
| Kursprogramm | Wie Curriculum-/Stufen-Standard; planerisch nachgelagert an Rahmenprogramm (CURR-003) |
5. Entscheidungsprotokoll (binding)
| ID | Datum | Entscheidung | Begründung / Kontext |
|---|---|---|---|
| CURR-013 | 2026-04-29 | Präzisierung zu CURR‑002 (1)+(2): Persistenter Progressionsgraph ist unterstützend, nicht die alleinige Quelle für Slot‑geplante Übungen. Der Planungsmodus muss beliebige Übungen auf Slots verteilen ohne Pflicht zur Graph‑Pflege im Alltag. Reichhaltiges Pflegen von Progressionsbezügen v. a. durch globale Verwalter erwünscht, nicht verpflichtend pro Übungszuordnung. | Chat C2 |
| CURR-012 | 2026-04-29 | Zwei Nutzungsbilder: Modus A (Konkret) — Mehr‑Wochenplan für bekannte Trainingsgruppe + Termine → bestehende/neue training_units; Rahmen als Planhilfe über mehrere Einheiten. Modus B (Bibliothek) — Kurs-/Stufen‑Struktur ohne Gruppe/Uhrzeit bis zur Übernahme; dann Zuordnung von Gruppe+Zeitraum und Instanziierung in training_units. Bulk‑Anlegen (C4a) und Verknüpfen existierender (C4b) sind Modus‑A‑Alternativen. |
Chat C4 |
| CURR-011 | 2026-04-29 | Mehrere parallele Entwicklungsziele im selben Planungszeitraum → Datenmodell: Zielliste mit ≥1 Einträgen auf Rahmen‑Ebene (Details Technical Spec). Nicht nur ein einziges Sammelziel‑Feld. | Chat C3 |
| CURR-010 | 2026-04-29 | Slot‑Inhalt: tragend direkte Zuordnung beliebiger Übungen („Stückliste“); Option Graph für Vorschläge/Anreicherung. training_plan_template_id pro Slot weiterhin optional (MVP offen). |
Chat C2 |
| CURR-009 | 2026-04-29 | C1a: Neue eigene Bibliotheks‑Entität für Mehr‑Slot‑Rahmen (Framework/training_framework_*-Arbeitscode); training_plan_template bleibt eine Einheit‑Mikrovorlage (C5). |
Chat C1 |
| CURR-008 | 2026-04-29 | Migration / Backfill (Early-Installation): Migrationen betreffen aktuell nur frühe Systeme ohne weitere Nutzer. Vereins‑Zuordnung für Bestands-/Default‑Zeilen erfolgt beim Backfill mit dem Standard‑Verein der Installation (konkret: Club‑ID bzw. Konvention im Migrate‑Skript dokumentieren — z. B. erster Verein oder DEFAULT_CLUB_ID in Env). visibility-Default beim Hinzufügen der Spalte: club, wenn fachlich alles diesem Vereinskontext zugeordnet wird; anderenfalls bei Multi‑Tenant eigene Migrate‑Anweisung. |
Nutzerfestlegung; pragmatisches Backfill ohne Mehr‑Mandanten‑Heuristik; §6 entsprechend vereinfacht. |
| CURR-007 | 2026-04-29 | training_plan_templates weichen aktuell vom Übungs-Muster ab (kein visibility). Festlegung: Bei der nächsten sinnvollen Migration auf den gemeinsamen Governance-Kern angleichen (visibility zusätzlich zu club_id / created_by), Semantik analog zu Übungen im Vereinskontext; von dieser Linie nur abweichen, wenn ausdrücklich anders dokumentiert. |
Bekannte Schulden bis Migration vermeiden; neue Objekttypen sollen CURR-005 folgen; Zuordnung/Backfill CURR‑008. |
| CURR-006 | 2026-04-29 | Instanz-Ebene (training_unit u. Ä.): In der Rahmenprogramm-Phase keine neue parallele visibility-Schicht auf der Einheit; Zugriff über group_id und bestehende Trainer-/Mitgliedschaftslogik. Lineage zu Vorlagen/Rahmen nur als optionale Metadaten-FKs (plan_template_id, spätere Erweiterungen), ohne dass Schreiben in der Einheit die Vorlage ändert. |
CURR-004-kompatibel: API-Policy später ergänzbar ohne Instanz-Umbau. |
| CURR-005 | 2026-04-29 | Governance-Kern für Bibliotheksobjekte (Übung, neue/alte Vorlagen, künftig Rahmen-/Kurs-/Progressions-Container): visibility im Sinne von exercises (private | club | official), club_id optional (NULL wenn nicht vereinsspezifisch), created_by. Sparte später optional division_id oder Verknüpfungstabelle — nicht Blocker für ersten Progressions-/Rahmen-Entwurf. |
Einheitliche Semantik; Altabweichungen gezielt nachziehen (CURR-007). |
| CURR-004 | 2026-04-29 | Sichtbarkeit: Aktuell globale Nutzungs-/Planungssicht für alle; Architektur und Datenmodell aber von Anfang an so gestalten, dass spätere Einschränkungen nach Rollen und Zugehörigkeiten (Verein, Gruppe, Sparte …) ohne Bruch eingeführt werden können. | Vorbereitung einheitlicher Governance; siehe CURR-005/006 für Konkretisierung. |
| CURR-003 | 2026-04-29 | Nachgelagert / explizites Backlog (nicht Phase Rahmenprogramm): Kursprogramm kommt nach dem Rahmenprogramm (planerisch ähnlich); Assessments, Sportlerakte, KI-Optimierungen ebenfalls zurückgestellt bis Rahmenkern steht. | Priorität liegt auf Persistenz Progression → Multi-Einheiten-Planung → Einheitenvorschläge. |
| CURR-002 | 2026-04-29 | Umsetzungsreihenfolge Rahmenprogramm: (1) Progressionsbezüge zwischen Übungen müssen als persistierter Graph/Baum modellierbar sein. (2) Planungsmodus, der Übungen (u. a. aus Progression, auch manuell, CURR‑010) auf mehrere Trainingseinheiten verteilt, mehrere Ziele (CURR‑011) enthält und als speicherbares Rahmen‑Template dient. (3) Warenkorb-Idee beim Ausarbeiten einer einzelnen Einheit. | Reihenfolge vom Datenkern zur UX; Zuordnung/Graph CURR‑013 |
| CURR-001 | 2026-04-29 | Vor dem separaten Produkt „Kursprogramm“ wird das „Trainingsrahmenprogramm“ (Ziele + Progression über mehrere Einheiten) angegangen — nicht umgekehrt. | Kursprogramm baut auf derselben Planungslogik auf; erst gemeinsamen Kern liefern. |
Format: Neue Zeile oben einfügen (neueste zuerst).
6. Offene Fragen (Backlog)
- Minimal-UI Rahmenprogramm vs. bestehende Kalender/Liste
training_units? Governance Migrate Default→ CURR‑008Slots / C4 generisch→ CURR‑012 (Modi A/B)Relation zwei Vorlagenfamilien→ CURR‑009 (Rahmen neu, Einheit bleibttraining_plan_template)- Technical:
gleiche DB‑Entität mit→ Festgelegt: eine Entitätplan_mode(A | B) vs. konsequente Teilung zweier Objekttypen?training_framework_programs+plan_mode; siehetechnical/TRAINING_FRAMEWORK_SPEC.md§2.0. - Progressionsgraph: Kantentypen (nächste Übung vs. Variante vs. Level innerhalb gleicher Übung); optional Skills-Anbindung
7. Produkt-Backlog (explizit, nicht aktuelle Phase)
Siehe CURR-003: Kurs-/Stufenprogramm (nach Rahmenkern), Assessments (Plantyp/Testübungen/Sportler), Sportlerakte, KI-/optimierungsunterstützte Planung.
8. Nächste Aktion (für dich / Team)
Schritt C· siehe §2.d · CURR‑009 bis CURR‑013Progressionsgraph Stufe 1✅ siehetechnical/TRAINING_FRAMEWORK_SPEC.md§3–§4 · Jetzt:TRAINING_FRAMEWORK_SPEC.md§2 (Checkliste) mit DDL-/API-Abschnitt Rahmen ergänzen (CURR‑002 (2)); Modus A/B siehe Funktionskonzept §6- Migrate weiter CURR‑007 / CURR‑008 (ideal parallel oder vor erster Rahmen‑Migration mit neuem Bibliothekstyp)
- Konzeptpaket optional Schritt E Lineage vor Implementierung Großrelease
9. Changelog dieser Datei
| Datum | Änderung |
|---|---|
| 2026-04-30 | §8 Punkt 2 angepasst (Graph ✅; nächster Fokus Rahmen‑Spec CURR‑002 (2)). |
| 2026-04-28 | Technische Ausarbeitung gebündelt: neue Datei technical/TRAINING_FRAMEWORK_SPEC.md (Stub); Verweis §8. |
| 2026-04-29 | CURR‑009–013, CURR‑002 präzisiert; Glossar Modi A/B Slot; §2.d C geklärt; §6‑Backlog gekürzt. |
| 2026-04-29 | CURR‑008 (Migration Standard‑Verein); §2.d Schritt C Checkpoints C1–C5; Glossar/§6 angepasst. |
| 2026-04-29 | CURR-001–004; Umsetzungsreihenfolge §2.a; Glossar Rahmenprogramm/Progressionsgraph; Scope-Backlog. |
| 2026-04-28 | Erstanlage aus Konzept-Arbeitsphase Chat; Schritttabelle und Protokollstruktur. |