# Gewichtetes Fähigkeiten-Scoring (Phase 3)

**Stand:** 2026-05-20  
**Status:** Variante A (regelbasiert) umgesetzt — v1.0  
**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.0)

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 dieser Übung × Link-Faktor`
   - Link-Faktor = 1.0 × (1.5 wenn `is_primary`) × Intensität (`niedrig` 0.85, `mittel` 1.0, `hoch` 1.2) × Entwicklungsbeitrag (`low` 0.9, `medium` 1.0, `high` 1.15)

Aggregation:

- Summe pro `skill_id` → `weight`
- `share_percent` = Anteil an `total_weight` (100 % über alle Skills im Profil)

## 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
- Trainings**einheiten** (Kalender) optional als nächste Erweiterung

## Tests

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