Lars/shinkan-jinkendo
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 3 Wiki Activity
5200895a73
shinkan-jinkendo/.claude/docs/technical/SKILL_SCORING_SPEC.md
Lars 5200895a73
All checks were successful
Deploy Development / deploy (push) Successful in 42s
Details
Test Suite / pytest-backend (push) Successful in 38s
Details
Test Suite / lint-backend (push) Successful in 1s
Details
Test Suite / build-frontend (push) Successful in 13s
Details
Test Suite / k6 /health Baseline (push) Successful in 33s
Details
Test Suite / playwright-tests (push) Successful in 1m27s
Details
Update Skill Scoring Specification and Implementation to v1.2 
- Enhanced the skill scoring system with category grouping and a universal scale for improved comparability across programs.
- Introduced new calculations for artifact share percentage and universal percent, allowing for a more nuanced understanding of skill contributions.
- Updated the API to reflect changes in the skill profile structure, including main category and top skill details.
- Improved frontend components to display skills by main category, enhancing user experience in skill discovery and profile visualization.
- Adjusted tests to validate the new scoring logic and ensure accurate representation of skills and their weights.
2026-05-21 08:37:58 +02:00

4.1 KiB
Raw Blame History

Gewichtetes Fähigkeiten-Scoring (Phase 3)

Stand: 2026-05-20
Status: Variante A (regelbasiert) umgesetzt — v1.2 (Kategorien-Gruppierung + universelle Skala)
Modul: backend/skill_scoring.py, Router skill_profiles

Ziel

Trainer wählen Schwerpunkt-Fähigkeiten und erhalten Vorschläge für Rahmenprogramme, Trainingsmodule und Regressionspfade (Progressionsgraphen), deren Übungen diese Fähigkeiten stark abdecken.

Datenquellen

Artefakt Übungen aus
Rahmenprogramm (gesamt) Alle Blueprint-training_units der Slots → training_unit_section_items
Rahmenprogramm (pro Slot) Blueprint einer Session
Trainingsmodul training_module_items (nur item_type = exercise)
Progressionsgraph from_exercise_id + to_exercise_id je Kante (Vorkommen zählt)

Fähigkeiten je Übung: exercise_skills → skills (nur status = active).

Gewichtungsformel (v1.1)

Pro Übungsvorkommen (eine Zeile im Ablauf / Modul / Kanten-Endpunkt):

  1. Basis-Minuten = planned_duration_min der Position, sonst Default (Einheit/Modul: 8 Min, Graph: 10 Min).
  2. Pro verknüpfte Fähigkeit der Übung:
    • Beitrag = Basis-Minuten × Anzahl Vorkommen × Link-Faktor
    • Link-Faktor = Intensität × Stufen-Faktor

Intensität (Nutzeneinschätzung, UI-Feld)

Wert Faktor
niedrig 0,85
mittel / leer 1,0
hoch 1,2

Stufen-Spanne (required_level → target_level, UI „von/bis“)

Kanonische Slugs: basis … optimierung (1–5). Fehlen beide: Faktor 1,0.

  • Spanne = Anzahl Stufen von „von“ bis „bis“ (1–5)
  • Mittelpunkt = durchschnittliche Stufe
  • Faktor ≈ (0,92 + 0,04 × Spanne) × (0,95 + 0,025 × Mittelpunkt) → typisch 0,96–1,20

Beispiel: von Grundlagen bis Aufbau (Spanne 2) > nur Basis (Spanne 1).

Bewusst nicht im Scoring

Feld Grund
is_primary Perspektivabhängig; bleibt in Übungs-UI, fließt nicht ins Profil ein
development_contribution Legacy-DB-Feld, in UI nicht gepflegt

Aggregation:

  • Summe pro skill_id → weight / score (Trainingsgewicht in gewichteten Minuten — absolut, über Programme vergleichbar)
  • artifact_share_percent / share_percent = Anteil an total_weight innerhalb dieses Artefakts (summiert 100 % — nur noch sekundär)
  • by_main_category[] → je Unterkategorie top_skill (stärkste Fähigkeit nach absolutem Gewicht)
  • universal_percent = weight / max_weight_in_corpus(skill_id) × 100 — Referenz aus sichtbarer Bibliothek (compute_corpus_skill_max_weights, bis 50 Artefakte je Typ)

Discovery-Sortierung und Vorschläge nutzen match_score (= Summe absoluter Gewichte der gewählten Fähigkeiten), nicht den Plan-internen Anteil.

API

Methode Pfad Beschreibung
GET /api/training-framework-programs/{id}/skill-profile overall + slots[] mit je profile
GET /api/training-modules/{id}/skill-profile overall
GET /api/exercise-progression-graphs/{id}/skill-profile overall
GET /api/skill-discovery/suggestions?skill_ids=1,2,3 Ranking sichtbarer Artefakte; Query types, limit

Zugriff: get_tenant_context + gleiche Sichtbarkeit wie Parent-Artefakt (library_content_visibility_sql).

UI

  • Rahmenprogramm bearbeiten: Panel „Fähigkeiten-Schwerpunkte“, inkl. Aufklapp pro Session
  • Trainingsmodul bearbeiten: Panel „Fähigkeiten im Modul“
  • Progressionsgraph: Panel „Fähigkeiten entlang des Pfads“
  • Fähigkeiten-Seite → Planungs-Vorschläge: Multi-Select + Bibliothekssuche

Profil wird nach Speichern neu geladen (skillProfileTick).

Grenzen / später

  • Kein Cache in DB (skill_profile_json) — on-the-fly; bei Performance >50 Artefakte serverseitiger Index
  • Entwicklungsziele am Rahmenkopf bleiben Freitext (kein Scoring)
  • KI-Zusammenfassung (Variante B Roadmap) nicht Teil von v1.0
  • Trainingseinheiten (Kalender) optional als nächste Erweiterung

Tests

  • backend/tests/test_skill_scoring.py — Multiplikator, Aggregation, Match-Score