Lars/mitai-jinkendo
1
0
Fork 0
Code Issues 33 Pull Requests Actions Packages Projects Releases 5 Wiki Activity
fa3e66fb31
mitai-jinkendo/.claude/docs/technical/ACTIVITY_SCALAR_KANON_TABLE.md
Lars fa3e66fb31
All checks were successful
Deploy Development / deploy (push) Successful in 51s
Details
Build Test / pytest-backend (push) Successful in 4s
Details
Build Test / lint-backend (push) Successful in 0s
Details
Build Test / build-frontend (push) Successful in 18s
Details
feat: Update activity documentation and enhance API responses with session metrics 
- Added new updates for Phase A and Phase B in `CLAUDE.md`, detailing the completion of Phase A and the introduction of enriched session metrics in the API response for `GET /api/activity`.
- Enhanced the README to include references to new documentation files for scalar canon and composite metrics implementation.
- Updated `ACTIVITY_PRODUCTION_ARCHITECTURE_AND_PHASES.md` to reflect the current status of phases and added navigation rules for data access.
- Improved `ACTIVITY_SESSION_METRICS_EAV_AGENT_GUIDE.md` with links to new implementation concepts for composite metrics.
- Refactored the activity router to integrate enriched session metrics into the activity list responses, ensuring a more comprehensive data presentation.
2026-04-17 12:55:12 +02:00

4.9 KiB
Raw Blame History

Aktivität: Skalar-Kanon (eine Semantik → eine Quelle)

Stand: 2026-04-16
Normativer Code: backend/data_layer/activity_data_canon.py
Kontext: ACTIVITY_PRODUCTION_ARCHITECTURE_AND_PHASES.md (Phase A abgeschlossen)

1. Spine & Identität (activity_log, nicht EAV)

Diese Felder sind keine training_parameters-Skalare. Sie gehören zur Session-Zeile.

Semantik DB / API Kanonische Quelle Lesefallback Sync Spalte↔EAV
Primärschlüssel activity_log.id activity_log — —
Profil profile_id activity_log — —
Kalendertag date activity_log — —
Start / Ende (Zeit) start_time, end_time, started_at, ended_at activity_log — —
Trainingsart (Freitext/Legacy) activity_type activity_log — —
Referenz Trainingstyp training_type_id, training_category, … activity_log (+ training_types) — —
Notiz notes activity_log — —
Quelle / Import source, created, … activity_log — —
Session-Auswertung evaluation, quality_label, overall_score, … activity_log (Blob/Ergebnis) — Kein EAV-Raster

2. Kernfelder CSV-Modul activity (= „heiße“ Skalare)

Abgeleitet aus csv_parser.module_registry.MODULE_DEFINITIONS["activity"].fields — maschinenlesbar über ACTIVITY_MODULE_REGISTRY_FIELD_KEYS in activity_data_canon.py.

Semantik Key (Registry/API) Kanonische Quelle Lesefallback Bemerkung
Dauer duration_min activity_log — Aggregates, Listen
Aktive Energie kcal_active activity_log —
Ruhe-Energie kcal_resting activity_log —
Distanz distance_km activity_log —
Ø HF hr_avg (Parameter oft avg_hr in EAV-Schema) activity_log EAV nur wenn source_field / Profil-Schema merge_column_backed_and_eav_metrics: Spalte schlägt EAV
Max-HF hr_max activity_log analog
RPE rpe activity_log analog

Schreibpfad: Universal-CSV und API sollen diese Keys auf activity_log mappen, sofern nicht ausdrücklich ein EAV-primärer Parameter (§3) gewählt ist.

3. EAV-primäre Parameter (erweiterte Skalare)

ACTIVITY_EAV_PRIMARY_PARAMETER_KEYS in activity_data_canon.py. training_parameters.source_field = NULL (nach Kanon / Migration 057): kanonischer Speicher ist activity_session_metrics.

Parameter-Key (training_parameters.key) Legacy-Spalte activity_log (nur Lesefallback) Kanonische Quelle Lesefallback
min_hr hr_min EAV Spalte, wenn EAV leer
pace_min_per_km pace_min_per_km EAV Spalte, wenn EAV leer
cadence cadence EAV Spalte, wenn EAV leer
avg_power avg_power EAV Spalte, wenn EAV leer
elevation_gain elevation_gain EAV Spalte, wenn EAV leer
temperature_celsius temperature_celsius EAV Spalte, wenn EAV leer
humidity_percent humidity_percent EAV Spalte, wenn EAV leer
avg_hr_percent avg_hr_percent EAV Spalte, wenn EAV leer
kcal_per_km kcal_per_km EAV Spalte, wenn EAV leer

Merge-Implementierung: merge_column_backed_and_eav_metrics in activity_session_metrics.py.

4. Profil-/Typ-dynamische Skalare (EAV, nicht in Registry-Kernliste)

Semantik Kanonische Quelle Lesefallback
Admin-definierte Parameter (Attributprofil Kategorie/Typ) activity_session_metrics + training_parameters —
Parameter mit source_field → Spalte activity_log (Spalte) EAV ergänzend; Leseregel: Spalte bevorzugt (kein veraltetes EAV)

5. Composites (Zielbild, noch nicht Kanon-Zeile pro Slot)

Semantik Kanonische Quelle (Ziel)
Strukturierte Composite-Dokumente (z. B. Zonen/Bänder) EAV ein Dokument pro Parameter/Session (siehe ACTIVITY_COMPOSITE_METRICS_IMPLEMENTATION_CONCEPT.md)

Kein dauerhaftes Spiegeln derselben Semantik in activity_log-Spalten.

6. Sync & Übergang

  • Kein automatischer Dauer-Sync „Spalte → EAV“ für dieselbe Semantik; Lesepfad vereinheitlicht die Sicht (merge_column_backed_and_eav_metrics).
  • Optionale Backfill-Migration/Skript (idempotent) nur nach fachlicher Freigabe — siehe EAV-Agent-Guide §6.

7. Referenzen

  • ACTIVITY_PRODUCTION_ARCHITECTURE_AND_PHASES.md — Phasen A–F
  • ACTIVITY_SESSION_METRICS_EAV_AGENT_GUIDE.md — APIs, Tests
  • activity_data_canon.py — ACTIVITY_LOG_PATCHABLE_COLUMNS, Legacy-Map