mitai-jinkendo/.claude/docs/technical/functional_concept_composite_data.md

# Konzeptpapier: Speicherung und Bereitstellung von Scalar- und Composite-Sportdaten

## Status

Arbeitsstand auf Basis der fachlichen und architektonischen Diskussion.  
Dieses Dokument dient als Rahmenwerk für einen Coding Agent und beschreibt die Zielarchitektur, die Abgrenzung der Schichten sowie die empfohlene technische Struktur für Scalar- und Composite-Werte.

---

## 1. Ziel und Einordnung

Das System soll zu beliebigen Sportarten Daten speichern und für unterschiedliche nachgelagerte Zwecke bereitstellen, insbesondere:

- Diagramme
- Kennzahlen
- Scores
- regelbasierte Bewertungen
- KI-Platzhalter und KI-Kontextdaten

Das System ist bereits mehrschichtig aufgebaut. Diese Schichtung ist fachlich und technisch sinnvoll und soll ausdrücklich erhalten bleiben.

### Bestehende Schichten

- **Persistenz / Datenbank**
  - reiner Wertespeicher
  - Speicherung von Scalars und Composites
- **Layer 1**
  - Lesen der Daten
  - technische Aufbereitung
  - minimale Normalisierung
  - Validierung
- **Layer 2a**
  - fachliche Aufbereitung für Diagramme, Kennzahlen, Regeln, Auswertungen
- **Layer 2b**
  - fachliche Aufbereitung für KI-Platzhalter, KI-Zusammenfassungen, KI-Argumente

### Zentrale Erkenntnis

Die Persistenz darf **nicht** mit fachlichen Interpretationen aus Layer 2 überladen werden.

Das bedeutet konkret:

- Die Datenbank speichert **Fakten und strukturierte Werte**
- Layer 1 stellt **kanonische, technische Leseobjekte** bereit
- Layer 2 erzeugt daraus **fachliche Bedeutung**

---

## 2. Problemstellung

Bisher werden überwiegend **Scalar-Werte** gespeichert:

- Datentyp
- Ausprägung (`value`)
- Einheit

Nun sollen zusätzlich **Composite-Werte** gespeichert werden.  
Aktuell ist der gewünschte Ansatz:

- derselbe Value Store
- `datatype = composite`
- `value = jsonb`

Die Herausforderung besteht darin, Composite-Werte so einzuführen, dass:

1. die Architektur einfach bleibt
2. die Schichtentrennung nicht verletzt wird
3. das System sportartenübergreifend nutzbar bleibt
4. spätere Auswertungslogik nicht bereits in die Persistenz gepresst wird
5. die Lösung für Diagramme, Kennzahlen und KI gleichermaßen nutzbar ist

---

## 3. Architektonische Leitentscheidung

### 3.1 Grundsatz

**Composite-Werte werden als strukturierte Fakten gespeichert, nicht als fachlich fertig interpretierte Analyseobjekte.**

Das bedeutet:

- Die Datenbank kennt nur wenige **technische Composite-Container**
- Fachliche Archetypen entstehen erst in Layer 2
- Layer 1 vermittelt zwischen Persistenz und fachlicher Verarbeitung

### 3.2 Was bewusst vermieden wird

Nicht in die Persistenz gehören als Teil des Basis-Composite:

- Scores
- fachliche Bewertungen
- Trainingsqualitätsurteile
- KI-Texte
- narrative Einordnungen
- Interpretationen wie „intervallartig“, „polarisiert“, „gut regeneriert“
- abgeleitete Kennzahlen wie `switch_rate`, `transition_entropy`, `readiness_index`, `plan_match_score`

Diese Dinge sind **sekundäre Ableitungen** und gehören in Layer 2.

---

## 4. Fachliche Kernaussage des Konzepts

Die frühere Diskussion über viele fachliche Composite-Archetypen war fachlich sinnvoll, aber für die Persistenz zu komplex.

Deshalb wird das Modell in zwei Ebenen getrennt:

### Ebene A: technische Speicherformen

Diese werden in der Datenbank als `jsonb` gespeichert.

### Ebene B: fachliche Analyse-Archetypen

Diese werden in Layer 2 aus den technischen Speicherformen abgeleitet.

Damit gilt:

- **wenige Speicherformen**
- **viele fachliche Projektionen**

Das ist die zentrale Designentscheidung dieses Dokuments.

---

## 5. Zielbild

### 5.1 Persistenzebene

Einheitlicher Value Store für:

- Scalars
- Composites

#### Scalar

- `datatype != composite`
- `value` ist scalar
- `unit` als separate Spalte oder Feld

#### Composite

- `datatype = composite`
- `value` ist `jsonb`
- `jsonb` folgt einem kleinen, stabilen Basisschema

### 5.2 Layer 1

Layer 1 liefert für Composite-Werte:

- validierte Daten
- minimal normalisierte Daten
- kanonische Leseobjekte
- keine fachlichen Scores oder Bewertungen

### 5.3 Layer 2a

Layer 2a erzeugt aus Layer-1-Daten:

- Diagrammserien
- Kennzahlen
- Übergangsmetriken
- Intervallstrukturen
- Auswertungsobjekte
- sportartspezifische Projektionen

### 5.4 Layer 2b

Layer 2b erzeugt aus Layer-1- oder Layer-2a-Daten:

- KI-Platzhalter
- KI-Faktenlisten
- zusammengefasste Trainingsmerkmale
- explizite, strukturierte Aussagen für Prompts

---

## 6. Technische Speicherformen für Composite-Werte

Statt vieler spezieller Composite-Typen werden nur vier technische Container eingeführt:

1. `group_set`
2. `distribution_set`
3. `sequence_set`
4. `model_set`

Diese vier Typen reichen als Speicherebene aus.

---

## 7. Der gemeinsame Basiskern jedes Composite-Objekts

Jedes Composite-JSONB soll auf einem kleinen gemeinsamen Kern basieren.

### 7.1 Basisschema

    ```json
    {
      "v": 1,
      "kind": "group_set",
      "domain": "recovery",
      "basis": null,
      "items": [],
      "meta": {
        "source": "reported",
        "definition_ref": null,
        "quality": null
      }
    }
    ```

### 7.2 Pflichtfelder

- `v`
- `kind`
- `domain`
- `items`

### 7.3 Optionale, aber empfohlene Felder

- `basis`
- `meta.source`
- `meta.definition_ref`
- `meta.quality`

### 7.4 Semantik der Felder

#### `v`

Schema-Version des gespeicherten JSON-Objekts.

#### `kind`

Technischer Composite-Container.  
Erlaubte Werte:

- `group_set`
- `distribution_set`
- `sequence_set`
- `model_set`

#### `domain`

Fachlicher Bezugsraum der Daten, zum Beispiel:

- `heart_rate`
- `power`
- `speed`
- `recovery`
- `intervals`
- `technique`
- `critical_power`

#### `basis`

Optionale Bezugsgröße, zum Beispiel:

- `time`
- `distance`
- `repetitions`
- `work`
- `count`
- `score`

#### `items`

Liste der eigentlichen Teilwerte oder Segmente.

#### `meta.source`

Ursprung des Composite-Werts, z. B.:

- `reported`
- `imported`
- `detected`
- `derived_l1`

#### `meta.definition_ref`

Referenz auf eine externe oder interne Definition, etwa:

- HF-Zonenmodell
- Power-Zonenmodell
- Intervall-Template
- Testprotokoll
- Schwellenmodell

#### `meta.quality`

Optionale Qualitätskennzeichnung, z. B.:

- `raw`
- `validated`
- `estimated`
- `reported`
- `derived`

---

## 8. Composite-Typ 1: `group_set`

### 8.1 Zweck

Speicherung einer kleinen Menge benannter Teilwerte ohne zwingende Reihenfolge und ohne Bandgrenzen.

### 8.2 Typische Einsatzfälle

- HRV-Bundle
- Wellness-/Readiness-Bundle
- Technik-Bundle
- Submetriken eines Tests
- kleine Sammlungen korrelierter Werte

### 8.3 Struktur

    ```json
    {
      "v": 1,
      "kind": "group_set",
      "domain": "recovery",
      "items": [
        { "key": "rmssd", "value": 42.1, "unit": "ms" },
        { "key": "resting_hr", "value": 54, "unit": "bpm" },
        { "key": "sleep_score", "value": 78, "unit": "score" }
      ],
      "meta": {
        "source": "reported",
        "definition_ref": "morning_readiness_protocol_v1",
        "quality": "validated"
      }
    }
    ```

### 8.4 Pflichtfelder pro Item

- `key`
- `value`

### 8.5 Optionale Item-Felder

- `unit`
- `label`
- `note`

### 8.6 Regeln

- `key` muss innerhalb eines Objekts eindeutig sein
- `value` darf scalar oder `null` sein
- keine fachliche Interpretation im Objekt selbst

### 8.7 Nicht speichern in `group_set`

Nicht in `group_set` speichern:

- `readiness_index`
- `recovery_flag`
- `trend_direction`
- generierte Scores

Diese gehören in Layer 2.

---

## 9. Composite-Typ 2: `distribution_set`

### 9.1 Zweck

Speicherung einer Verteilung über Bänder, Klassen oder Bereiche.

### 9.2 Typische Einsatzfälle

- Herzfrequenzzonen
- Power-Zonen
- Geschwindigkeitszonen
- Pace-Bänder
- Kadenz-Zonen
- Beschleunigungsbänder
- Sprunghöhenklassen

### 9.3 Struktur

    ```json
    {
      "v": 1,
      "kind": "distribution_set",
      "domain": "heart_rate",
      "basis": "time",
      "items": [
        {
          "key": "z1",
          "value": 420,
          "unit": "s",
          "lower": 50,
          "upper": 60,
          "range_unit": "%hr_max"
        },
        {
          "key": "z2",
          "value": 780,
          "unit": "s",
          "lower": 60,
          "upper": 70,
          "range_unit": "%hr_max"
        },
        {
          "key": "z3",
          "value": 360,
          "unit": "s",
          "lower": 70,
          "upper": 80,
          "range_unit": "%hr_max"
        }
      ],
      "meta": {
        "source": "reported",
        "definition_ref": "hr_zone_model_5_hrmax",
        "quality": "validated"
      }
    }
    ```

### 9.4 Pflichtfelder pro Item

- `key`
- `value`

### 9.5 Empfohlene Item-Felder

- `unit`
- `lower`
- `upper`
- `range_unit`

### 9.6 Regeln

- `key` muss eindeutig sein
- `items` sollen logisch sortierbar sein
- `lower` und `upper` sind optional, aber bei bandbasierten Sets empfohlen
- `basis` definiert, worauf sich `value` bezieht, etwa Zeit, Distanz, Wiederholungen

### 9.7 Nicht speichern in `distribution_set`

Nicht in `distribution_set` speichern:

- Wechselhäufigkeit
- mittlere Verweildauer
- Polarized Index
- Pyramidal Index
- Intervallklassifikation

Das sind Auswertungsergebnisse aus Layer 2.

---

## 10. Composite-Typ 3: `sequence_set`

### 10.1 Zweck

Speicherung geordneter Sequenzen, Segmente, Zustandsfolgen oder Intervallblöcke.

### 10.2 Typische Einsatzfälle

- Work-/Recovery-Blöcke
- erkannte HF-Zonen-Segmente
- Pace-Wechsel
- Satz-/Rundenabfolgen
- Drill-Sequenzen
- Ereignisfolgen

### 10.3 Struktur: Intervallblöcke

    ```json
    {
      "v": 1,
      "kind": "sequence_set",
      "domain": "intervals",
      "basis": "time",
      "items": [
        { "seq": 1, "label": "work", "start": 0, "duration": 180, "unit": "s" },
        { "seq": 2, "label": "recovery", "start": 180, "duration": 90, "unit": "s" },
        { "seq": 3, "label": "work", "start": 270, "duration": 180, "unit": "s" }
      ],
      "meta": {
        "source": "detected",
        "definition_ref": "interval_template_optional",
        "quality": "derived_l1"
      }
    }
    ```

### 10.4 Struktur: Zustandssegmente

    ```json
    {
      "v": 1,
      "kind": "sequence_set",
      "domain": "heart_rate_zone_state",
      "basis": "time",
      "items": [
        { "seq": 1, "label": "z2", "start": 0, "duration": 300, "unit": "s" },
        { "seq": 2, "label": "z4", "start": 300, "duration": 90, "unit": "s" },
        { "seq": 3, "label": "z2", "start": 390, "duration": 120, "unit": "s" }
      ],
      "meta": {
        "source": "detected",
        "definition_ref": "hr_zone_model_5_hrmax"
      }
    }
    ```

### 10.5 Pflichtfelder pro Item

- `seq`
- mindestens eines von:
  - `label`
  - `key`
- mindestens eines von:
  - `duration`
  - `start` und `end`

### 10.6 Optionale Item-Felder

- `unit`
- `start`
- `end`
- `value`
- `note`

### 10.7 Regeln

- `seq` muss eindeutig und aufsteigend sein
- Segmente müssen logisch geordnet sein
- bei zeitbasierten Segmenten sollen Start/Dauer-Ende konsistent sein
- keine fachlich interpretierten Kennzahlen im Objekt

### 10.8 Nicht speichern in `sequence_set`

Nicht in `sequence_set` speichern:

- `switch_count`
- `switch_rate_per_min`
- `transition_entropy`
- `density_index`
- `plan_match_score`

Diese Metriken entstehen erst in Layer 2.

---

## 11. Composite-Typ 4: `model_set`

### 11.1 Zweck

Speicherung kleiner, strukturierter Parametersätze eines Modells.

### 11.2 Typische Einsatzfälle

- Critical Power / W′
- Critical Speed
- Last-Geschwindigkeits-Profil
- Schwellenmodelle
- Testmodellparameter

### 11.3 Struktur

    ```json
    {
      "v": 1,
      "kind": "model_set",
      "domain": "critical_power",
      "items": [
        { "key": "cp", "value": 286, "unit": "W" },
        { "key": "w_prime", "value": 16800, "unit": "J" },
        { "key": "r_squared", "value": 0.98, "unit": "ratio" }
      ],
      "meta": {
        "source": "derived_l1",
        "definition_ref": "critical_power_2_parameter",
        "quality": "validated"
      }
    }
    ```

### 11.4 Pflichtfelder pro Item

- `key`
- `value`

### 11.5 Optionale Item-Felder

- `unit`
- `ci_low`
- `ci_high`
- `error`
- `note`

### 11.6 Regeln

- `key` eindeutig
- Modellname und Herleitung über `meta.definition_ref`
- Modellinterpretation nicht im Objekt selbst speichern

### 11.7 Nicht speichern in `model_set`

Nicht in `model_set` speichern:

- Trainingsdiagnosen
- Handlungsempfehlungen
- automatische Coachingtexte

---

## 12. Warum genau diese vier Typen

Diese vier Typen decken den größten Teil realistisch auftretender Composite-Fälle ab, ohne die Persistenz fachlich zu überfrachten.

### `group_set`

Für kleine Bündel benannter Werte

### `distribution_set`

Für Verteilungen über Klassen oder Bänder

### `sequence_set`

Für geordnete Folgen, Segmente und Intervallstrukturen

### `model_set`

Für modellbasierte Parametersätze

Weitere Speichertypen sollen nur eingeführt werden, wenn ein neuer Fall mit diesen vier Typen **nicht sinnvoll oder nur mit klaren Verformungen** modellierbar ist.

---

## 13. Was ausdrücklich nicht Teil der Persistenz-Basisschicht ist

Die Persistenzschicht speichert keine fachlichen Endprodukte.

Nicht Bestandteil der Basis-Composite-Struktur sind:

- Visualisierungsvorgaben
- Diagrammfarblogik
- Scoring-Ergebnisse
- Kennzahlen aus Übergangsanalysen
- narrative KI-Bausteine
- Trainingsklassifikationen
- Empfehlungen
- Bewertungen
- Interpretationen
- sportartspezifische Schlussfolgerungen

---

## 14. Layer-1-Konzept

### 14.1 Zweck von Layer 1

Layer 1 ist die technische Aufbereitungsschicht zwischen Persistenz und Fachlogik.

Layer 1 darf:

- Composite-JSON validieren
- Schema-Version prüfen
- `kind` prüfen
- Items lesen
- Einheiten normalisieren
- Basisreferenzen auflösen
- technische DTOs erzeugen
- leichte Plausibilitätsprüfungen durchführen

Layer 1 darf nicht:

- Scores berechnen
- fachliche Bewertungen erzeugen
- Intervallqualität beurteilen
- KI-Platzhalter formulieren
- Trainingscharakter interpretieren

### 14.2 Layer-1-Output

Layer 1 erzeugt kanonische interne Datenobjekte, zum Beispiel:

- `ScalarValueDTO`
- `GroupSetDTO`
- `DistributionSetDTO`
- `SequenceSetDTO`
- `ModelSetDTO`

### 14.3 Beispielhafte DTOs

    ```ts
    type ScalarValueDTO = {
      id: string
      datatype: string
      value: number | string | boolean | null
      unit?: string | null
    }

    type GroupItemDTO = {
      key: string
      value: unknown
      unit?: string | null
    }

    type GroupSetDTO = {
      id: string
      domain: string
      items: GroupItemDTO[]
      meta?: Record<string, unknown>
    }

    type DistributionItemDTO = {
      key: string
      value: number | null
      unit?: string | null
      lower?: number | null
      upper?: number | null
      rangeUnit?: string | null
    }

    type DistributionSetDTO = {
      id: string
      domain: string
      basis?: string | null
      items: DistributionItemDTO[]
      meta?: Record<string, unknown>
    }

    type SequenceItemDTO = {
      seq: number
      label?: string | null
      start?: number | null
      end?: number | null
      duration?: number | null
      unit?: string | null
      value?: unknown
    }

    type SequenceSetDTO = {
      id: string
      domain: string
      basis?: string | null
      items: SequenceItemDTO[]
      meta?: Record<string, unknown>
    }

    type ModelItemDTO = {
      key: string
      value: unknown
      unit?: string | null
    }

    type ModelSetDTO = {
      id: string
      domain: string
      items: ModelItemDTO[]
      meta?: Record<string, unknown>
    }
    ```

### 14.4 Layer-1-Validierungsregeln

#### Allgemein

- JSON muss parsebar sein
- `v` muss unterstützt sein
- `kind` muss bekannt sein
- `domain` darf nicht leer sein
- `items` muss Array sein

#### `group_set`

- jeder Eintrag braucht `key`
- `key` eindeutig

#### `distribution_set`

- jeder Eintrag braucht `key`
- `key` eindeutig
- `value` numerisch oder `null`
- `lower <= upper`, wenn beide gesetzt sind

#### `sequence_set`

- jeder Eintrag braucht `seq`
- `seq` eindeutig
- `seq` sortierbar
- zeitliche Felder konsistent

#### `model_set`

- jeder Eintrag braucht `key`
- `key` eindeutig

### 14.5 Layer-1-Normalisierungen

Layer 1 darf minimale Normalisierung durchführen:

- Sekunden, Minuten, Stunden intern vereinheitlichen
- Meter/Kilometer intern vereinheitlichen
- Prozentwerte intern konsistent repräsentieren
- Feldnamen aus Legacy-Importen normalisieren

Wichtig:  
Diese Normalisierung ist technisch, nicht fachlich interpretierend.

---

## 15. Layer-2a-Konzept: fachliche Analyse- und Diagrammprojektionen

Layer 2a konsumiert Daten aus Layer 1 und erzeugt daraus fachliche Sichtweisen.

Die früher diskutierten fachlichen Archetypen leben **hier**, nicht in der Persistenz.

### 15.1 Fachliche Archetypen in Layer 2a

1. `BandDistribution`
2. `TransitionProfile`
3. `IntervalBlockProfile`
4. `EventActionProfile`
5. `CouplingEfficiencyProfile`
6. `ModelParameterProfile`
7. `TechniqueCycleProfile`
8. `ReadinessRecoveryProfile`

### 15.2 Mapping von Speicherformen auf Layer-2a-Archetypen

#### `distribution_set`

kann projiziert werden auf:

- `BandDistribution`

#### `sequence_set`

kann projiziert werden auf:

- `TransitionProfile`
- `IntervalBlockProfile`
- `EventActionProfile`

#### `group_set`

kann projiziert werden auf:

- `TechniqueCycleProfile`
- `ReadinessRecoveryProfile`
- Teile eines `EventActionProfile`

#### `model_set`

kann projiziert werden auf:

- `ModelParameterProfile`

#### Kombination mehrerer Werte

kann projiziert werden auf:

- `CouplingEfficiencyProfile`

### 15.3 Beispiel: TransitionProfile aus `sequence_set`

Aus einer Zustandssequenz wie:

- z2 -> 300s
- z4 -> 90s
- z2 -> 120s
- z5 -> 60s

kann Layer 2a berechnen:

- Anzahl Wechsel
- Wechselrate
- mittlere Verweildauer pro Zustand
- längste Verweildauer
- Zustandsübergänge
- Intervallcharakter

Diese Werte werden **nicht** im Basis-Composite gespeichert, sondern von Layer 2a berechnet.

### 15.4 Beispiel: BandDistribution aus `distribution_set`

Aus HF-Zonen-Zeiten kann Layer 2a erzeugen:

- Diagrammserien
- Prozentanteile
- Schwerpunktzone
- Exposition oberhalb einer Schwelle
- Intensitätsverteilung

Auch dies entsteht erst in Layer 2a.

---

## 16. Layer-2b-Konzept: KI-Projektionen

Layer 2b soll keine Rohwerte direkt in Prompts kippen, sondern fachlich brauchbare Platzhalter erzeugen.

### 16.1 Grundsatz

Layer 2b konsumiert bevorzugt:

- Layer-1-Daten für einfache Fakten
- Layer-2a-Daten für fachlich verdichtete Aussagen

### 16.2 Ziel von Layer 2b

Erzeugung strukturierter KI-Bausteine wie:

- „Zeit in hoher Intensität“
- „Intervallstruktur erkannt“
- „Belastungsdichte hoch“
- „geringe Variabilität“
- „Readiness reduziert“
- „Technikmetriken auffällig“
- „intern-externe Lastkopplung stabil“

### 16.3 Beispielhafte KI-Platzhalter

    ```json
    {
      "high_intensity_time_s": 480,
      "interval_structure_detected": true,
      "switch_count": 12,
      "dominant_hr_zone": "z2",
      "readiness_state": "normal",
      "technique_variability_flag": "elevated"
    }
    ```

Wichtig:  
Auch diese Objekte sind **keine Persistenz-Basisobjekte**, sondern bereitgestellte Kontexte für KI.

---

## 17. Composite-Speicherung im bestehenden Value Store

### 17.1 Annahme über den aktuellen Store

Der bestehende Store speichert Werte als Datensätze mit:

- Datentyp
- Value
- Einheit
- weiteren Metadaten

### 17.2 Empfohlene Nutzung

#### Scalar

unverändert speichern

#### Composite

als Datensatz mit:

- `datatype = composite`
- `value = jsonb`
- `unit = null` oder optional leer, sofern Einheit innerhalb der Items gespeichert wird

### 17.3 Empfohlene Zusatzmetadaten außerhalb von `value`

Soweit euer bestehendes Modell das unterstützt, sind diese Felder außerhalb des JSONB sinnvoll:

- `id`
- `athlete_id`
- `session_id`
- `source_system`
- `measured_at`
- `datatype`
- `subtype` oder `kind` als Hilfsspalte
- `domain` als Hilfsspalte
- `created_at`
- `updated_at`

### Empfehlung

`kind` und `domain` sollten nach Möglichkeit zusätzlich indexierbar sein, selbst wenn sie primär im JSONB liegen.

---

## 18. JSONB-Schema-Regeln

### 18.1 Schema-Versionierung

Jedes Composite trägt `v`.

Regel:

- neue inkompatible Strukturen erhöhen `v`
- Layer 1 unterstützt definierte Versionen
- unbekannte Versionen werden abgelehnt oder in Fallback-Modus versetzt

### 18.2 Rückwärtskompatibilität

Wenn möglich:

- neue optionale Felder hinzufügen, ohne `v` zu erhöhen
- nur strukturelle Brüche führen zu neuer Version

### 18.3 Dokumentgröße

Composite-Objekte sollen fachlich zusammenhängend, aber nicht unnötig groß sein.

Regel:

- ein Composite speichert einen **atomaren strukturierten Sachverhalt**
- keine beliebig großen Sammelobjekte
- keine Vermischung mehrerer unabhängiger Analyseebenen

---

## 19. Definitionen, Referenzen und Kataloge

Die Basis-Composite-Objekte können Definitionen referenzieren, sollen diese aber nicht voll duplizieren.

### 19.1 Beispiele für `definition_ref`

- `hr_zone_model_5_hrmax`
- `hr_zone_model_5_hrr`
- `power_zone_model_7_ftp`
- `morning_readiness_protocol_v1`
- `critical_power_2_parameter`
- `boxing_round_structure_3x3`
- `karate_interval_template_v2`

### 19.2 Nutzen von `definition_ref`

Damit kann Layer 2:

- bandbezogene Logik verstehen
- Diagrammbeschriftungen korrekt erzeugen
- Schwellenmodelle zuordnen
- KI-Kontext korrekt ableiten

Wichtig:  
`definition_ref` verweist auf eine Definition, ersetzt diese aber nicht.

---

## 20. Abgeleitete Werte zurückspeichern

### 20.1 Grundsatz

Falls Layer-2-Ergebnisse persistiert werden sollen, sollen sie **nicht** in das Basis-Composite zurückgeschrieben werden.

Stattdessen werden sie als eigene abgeleitete Werte gespeichert.

### 20.2 Begründung

So werden vermieden:

- doppelte Wahrheit
- inkonsistente alte Berechnungsergebnisse
- Vermischung von Fakt und Interpretation
- schwierige Rebuilds

### 20.3 Empfohlenes Muster

Ein abgeleiteter Wert bekommt:

- eigenen Datensatz
- Herkunftskennzeichnung
- Regel-/Berechnungsversion
- Referenz auf Quellwerte

### 20.4 Beispiel

    ```json
    {
      "origin": "derived",
      "layer": "2a",
      "rule": "transition_profile_v2",
      "source_ids": ["value_4711", "value_4712", "value_4713"]
    }
    ```

---

## 21. Beispielhafte Ende-zu-Ende-Flows

### 21.1 Flow A: Herzfrequenzzonen

#### Persistenz

`distribution_set` mit Zonenzeiten

#### Layer 1

`DistributionSetDTO`

#### Layer 2a

- Prozentanteile
- Diagrammwerte
- dominante Zone
- Zeit oberhalb bestimmter Zonen
- Intensitätsprofil

#### Layer 2b

- KI-Platzhalter wie:
  - `dominant_hr_zone`
  - `high_intensity_time_s`
  - `intensity_distribution_type`

### 21.2 Flow B: Intervalltraining

#### Persistenz

`sequence_set` mit Work-/Recovery-Segmenten

#### Layer 1

`SequenceSetDTO`

#### Layer 2a

- Anzahl Blöcke
- Work-Recovery-Verhältnis
- mittlere Blockdauer
- Dichte
- Compliance
- Intervallcharakter

#### Layer 2b

- KI-Platzhalter wie:
  - `interval_block_count`
  - `work_recovery_ratio`
  - `interval_density_state`

### 21.3 Flow C: Readiness

#### Persistenz

`group_set` mit RMSSD, Ruhepuls, Schlafscore

#### Layer 1

`GroupSetDTO`

#### Layer 2a

- Baseline-Abweichung
- Trend
- Zustandsklassifikation

#### Layer 2b

- `readiness_state`
- `recovery_attention_flag`

### 21.4 Flow D: Critical Power

#### Persistenz

`model_set` mit `cp`, `w_prime`, `r_squared`

#### Layer 1

`ModelSetDTO`

#### Layer 2a

- Modellgüte
- Vergleich zum Verlauf
- Zonen-/Schwellenableitung

#### Layer 2b

- KI-konforme Modellzusammenfassung

---

## 22. Regeln zur Entscheidung: Scalar oder Composite

### 22.1 Scalar verwenden, wenn

- genau ein Wert gespeichert wird
- keine strukturierte Untergliederung nötig ist
- keine zusammenhängende Teilwertgruppe existiert

Beispiele:

- Durchschnittspuls
- Maximalpuls
- Distanz
- Dauer
- Durchschnittsleistung

### 22.2 Composite verwenden, wenn

- mehrere Teilwerte logisch zusammengehören
- die Teilwerte nur gemeinsam sinnvoll interpretierbar sind
- Reihenfolge, Verteilung oder Modellstruktur relevant ist

Beispiele:

- HF-Zonen
- Intervallblöcke
- Readiness-Bundle
- Critical-Power-Parameter

### 22.3 Nicht jedes Mehrfachfeld ist automatisch Composite

Wenn mehrere Werte unabhängig voneinander existieren und auch einzeln sinnvoll sind, sollen sie weiterhin als Scalars gespeichert werden.

Composite nur dann verwenden, wenn die Gruppe selbst eine eigenständige semantische Einheit ist.

---

## 23. Regeln zur Einführung neuer Composite-Formate

Ein neues Composite-Format darf nur eingeführt werden, wenn mindestens eine der folgenden Bedingungen erfüllt ist:

1. Der neue Fall lässt sich mit den vier Basis-Typen nicht sinnvoll ausdrücken
2. Eine Abbildung wäre nur durch unsaubere oder missbräuchliche Nutzung möglich
3. Die Lesbarkeit und Wartbarkeit würden mit den vorhandenen Typen stark leiden

Vor Einführung eines neuen Typs ist zu prüfen:

- Kann es als `group_set` modelliert werden?
- Kann es als `distribution_set` modelliert werden?
- Kann es als `sequence_set` modelliert werden?
- Kann es als `model_set` modelliert werden?

Nur wenn alle vier Antworten fachlich und technisch nicht tragfähig sind, soll ein neuer Speichertyp diskutiert werden.

---

## 24. Implementierungsrichtlinien

### 24.1 Parser

Implementiere einen zentralen Composite-Parser:

- Eingang: Value-Record mit `datatype = composite`
- Ausgabe: konkretes Layer-1-DTO je `kind`

### 24.2 Validator

Implementiere einen zentralen Validator:

- allgemeine Prüfung
- kind-spezifische Prüfung
- strukturierte Fehlermeldungen

### 24.3 Mapper

Implementiere Mapper:

- `CompositeRecord -> GroupSetDTO`
- `CompositeRecord -> DistributionSetDTO`
- `CompositeRecord -> SequenceSetDTO`
- `CompositeRecord -> ModelSetDTO`

### 24.4 Projection Services in Layer 2

Beispiele:

- `BandDistributionProjectionService`
- `TransitionProfileService`
- `IntervalAnalysisService`
- `ReadinessProjectionService`
- `CouplingAnalysisService`
- `TechniqueProjectionService`

### 24.5 KI-Mapping in Layer 2b

Beispiele:

- `AiPlaceholderBuilder`
- `AiFactsBuilder`
- `AiNarrativeInputBuilder`

---

## 25. Fehler- und Fallback-Strategie

### 25.1 Ungültiges Composite

Wenn ein Composite ungültig ist:

- Layer 1 liefert strukturierten Fehler
- der Datensatz wird nicht als fachlich gültig weitergereicht
- optional kann ein „raw passthrough“ für Debugging existieren

### 25.2 Unbekannte Version

Wenn `v` unbekannt ist:

- Datensatz markieren
- nicht stillschweigend interpretieren
- optional Migration oder Fallback-Parser nutzen

### 25.3 Teilweise fehlende Felder

Wenn optionale Felder fehlen:

- lesen, sofern Kernschema gültig bleibt
- fehlende Informationen in Layer 2 berücksichtigen
- keine stillschweigende Erfindung fachlicher Werte

---

## 26. Performance- und Wartungsaspekte

### 26.1 Grundsatz

Die Persistenz soll flexibel, aber strukturiert bleiben.

### 26.2 Empfehlungen

- kleine, atomare Composite-Objekte
- keine übergroßen Sammelcontainer
- `kind` und `domain` indexierbar halten
- Definitionen referenzieren statt duplizieren
- fachliche Projektionen nicht als Pflichtbestandteil der Persistenz speichern

### 26.3 Vorteil dieser Struktur

- geringe Kopplung
- stabile Persistenz
- evolvierbare Fachlogik
- gute Eignung für mehrere Sportarten
- gute Wiederverwendbarkeit in Layer 2a und 2b

---

## 27. Migrationsstrategie

Falls bereits Composite-Ansätze existieren, wird folgendes Vorgehen empfohlen:

### Phase 1

- Einführung der vier `kind`-Typen
- Aufbau von Validator und Parser
- Speicherung neuer Composites nach neuem Muster

### Phase 2

- Layer-1-DTOs einführen
- bestehende Reader umstellen

### Phase 3

- Layer-2a-Projektionen implementieren
- Diagramme und Kennzahlen umstellen

### Phase 4

- Layer-2b-KI-Platzhalter auf neue Projektionen aufsetzen

### Phase 5

- bestehende Altformate optional migrieren oder kompatibel lesen

---

## 28. Nicht-Ziele dieses Dokuments

Dieses Dokument definiert bewusst nicht:

- konkrete UI-Diagrammgestaltung
- konkrete Score-Formeln
- sportartspezifische Bewertungslogiken
- konkrete KI-Prompttexte
- konkrete Datenbanktabellenmigrationen im Detail
- konkrete API-Endpunkte

Diese Punkte sind nachgelagerte Spezifikationen.

---

## 29. Offene Erweiterungspunkte

Die Architektur lässt folgende spätere Erweiterungen zu, ohne die Persistenzbasis zu brechen:

- zusätzliche `definition_ref`-Kataloge
- sportartspezifische Layer-2-Projektionen
- neue KI-Platzhaltertypen
- zusätzliche Qualitäts- und Provenienzfelder
- Rückspeicherung abgeleiteter Werte als eigene Datensätze
- spezielle Event-Detektion in Layer 2a

---

## 30. Endgültige Entscheidung

### Die Persistenzschicht speichert:

- Scalars
- vier einfache technische Composite-Typen

### Layer 1 übernimmt:

- Lesen
- Validieren
- minimale Normalisierung
- DTO-Bildung

### Layer 2a übernimmt:

- fachliche Analyse
- Diagrammaufbereitung
- Kennzahlen
- Profile
- Scores
- Interpretationen

### Layer 2b übernimmt:

- KI-Platzhalter
- KI-Fakten
- KI-Zusammenfassungen
- KI-taugliche Verdichtungen

---

## 31. Kurzfassung für einen Coding Agent

### Ziel

Erweitere den bestehenden Value Store um Composite-Werte auf `jsonb`-Basis, ohne fachliche Analyse-Logik in die Persistenz zu verlagern.

### Implementiere

1. Unterstützung für `datatype = composite`
2. vier `kind`-Typen:
   - `group_set`
   - `distribution_set`
   - `sequence_set`
   - `model_set`
3. Layer-1-Validatoren und Parser
4. kanonische DTOs pro `kind`
5. klare Trennung:
   - Persistenz = strukturierte Fakten
   - Layer 1 = technische Aufbereitung
   - Layer 2a = fachliche Projektionen
   - Layer 2b = KI-Projektionen

### Vermeide

- Scores im Basis-Composite
- Interpretationen im Basis-Composite
- Diagramm- oder KI-Logik in der Persistenz
- zu viele spezialisierte Composite-Speichertypen

---

## 32. Akzeptanzkriterien

Die Umsetzung gilt als fachlich passend, wenn:

1. ein Composite-Value mit `jsonb` gespeichert werden kann
2. Layer 1 den Typ sicher validieren und lesen kann
3. die Persistenz keine fachlichen Layer-2-Interpretationen erzwingt
4. HF-Zonen als `distribution_set` abbildbar sind
5. Intervallblöcke als `sequence_set` abbildbar sind
6. Readiness-Bundles als `group_set` abbildbar sind
7. Modellparameter als `model_set` abbildbar sind
8. Layer 2a daraus fachliche Projektionen erzeugen kann
9. Layer 2b daraus KI-Platzhalter erzeugen kann
10. neue Sportarten ohne neue Persistenzarchitektur integrierbar sind

---

## 33. Schlussformel

Die Leitentscheidung dieses Konzepts lautet:

**Die Datenbank speichert Struktur.  
Layer 1 liefert kanonische technische Objekte.  
Layer 2 erzeugt fachliche Bedeutung.  
KI konsumiert diese Bedeutung, nicht die rohe Persistenzstruktur.**

Damit bleibt das System einfach genug für die Implementierung und offen genug für spätere sportartspezifische Erweiterungen.