# Skill Scoring – Designprinzipien (Extraktion)

**Status:** Analyse / Arbeitspapier  
**Stand:** 2026-07-04  
**Geltungsbereich:** Modul „Skill Scoring & Profile“ — gewichtete Fähigkeiten-KPIs

**Serie:** Designprinzipien für Produktfamilie · Shinkan Dokument 8 von 15  
**Mitai-Vergleich:** [DATA_LAYER_DESIGN_PRINCIPLES.md](file:///c:/Dev/mitai-jinkendo/.claude/docs/technical/DATA_LAYER_DESIGN_PRINCIPLES.md) (#2, analog: Berechnungs-SSoT)

**Kernkomponenten:**

| Bereich | Pfade |
|---------|-------|
| Kern | `backend/skill_scoring.py` |
| Profile-API | `backend/routers/skill_profiles.py` |
| Planungs-Vorschläge | Planung-Router + Fähigkeiten-Seite |
| Spec | `.claude/docs/technical/SKILL_SCORING_SPEC.md` |

---

## Modul

**Skill Scoring & Profiles**

Regelbasierte Aggregation von `exercise_skills` über Artefakte (Module, Rahmenprogramme, Pläne, Graphen) zu gewichteten Profilen mit Peer-Vergleich innerhalb desselben Artefakttyps.

---

## Designprinzipien

### 1. Berechnung in einer Schicht (`skill_scoring.py`)

| | |
|---|---|
| **Prinzip** | Scores, Gewichte, Peer-Perzentile — nicht in React oder Router-SQL duplizieren. |
| **Begründung** | Analog Mitai Data Layer: Charts, Listen-KPIs, Planungs-Vorschläge nutzen dieselbe Logik. |
| **Quelle** | `SKILL_SCORING_SPEC.md`; `skill_scoring.py` |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | Einzelne UI-Fallbacks können noch vereinfacht rechnen. |

### 2. Gewichtung aus Trainings-Signalen

| | |
|---|---|
| **Prinzip** | Dauer, Vorkommen, Intensität (`niedrig`/`mittel`/`hoch`), Stufen-Spanne — explizite Multiplikatoren. |
| **Begründung** | Nachvollziehbares Ranking ohne Black-Box-ML. |
| **Quelle** | `_INTENSITY_MULT`, `_level_range_multiplier` |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | `is_primary` / `development_contribution` bewusst ignoriert. |

### 3. Peer-Vergleich nur unter gleichem Artefakttyp

| | |
|---|---|
| **Prinzip** | Modul vs. Modul, Rahmen vs. Rahmen — nie Modul vs. Plan gemischt. |
| **Begründung** | Fachlich sinnvoller Vergleich; vermeidet irreführende Prozentwerte. |
| **Quelle** | Phase 3 Lieferung; Nutzerfunktionen §4.2 |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | UI muss Typ-Kontext klar labeln. |

### 4. Sichtbarkeits-filterte Peer-Menge

| | |
|---|---|
| **Prinzip** | Peer-Pool = nur für Nutzer sichtbare Artefakte (Access Layer). |
| **Begründung** | Keine Leaks über Scores fremder Vereins-Inhalte. |
| **Quelle** | `skill_scoring.py` + Tenant-Filter in Aufrufern |
| **Tragfähigkeit** | **hoch** |
| **Einschränkung** | Performance bei großen Pools. |

### 5. Planungs-Vorschläge aus Profil-Delta

| | |
|---|---|
| **Prinzip** | Fähigkeiten-Schwerpunkte → sortierte Vorschläge für Module/Rahmen/Regressionspfade. |
| **Begründung** | Schließt Loop zwischen Katalog und Planung. |
| **Quelle** | Fähigkeiten-Seite Phase 3 |
| **Tragfähigkeit** | **mittel** |
| **Einschränkung** | KI-Suche über Volltext — Backlog. |

### 6. Default-Minuten für fehlende Dauer

| | |
|---|---|
| **Prinzip** | `DEFAULT_ITEM_MINUTES` / `GRAPH_DEFAULT_ITEM_MINUTES` als explizite Konstanten. |
| **Begründung** | Deterministische Scores bei unvollständigen Planungsdaten. |
| **Quelle** | `skill_scoring.py` |
| **Tragfähigkeit** | **mittel** |
| **Einschränkung** | Fachlich kalibrierbar — dokumentieren statt verstecken. |

---

## Nicht übernehmen

1. **Score-Berechnung im Frontend** für Listen-KPIs.
2. **Peer-Vergleich über Artefakttypen hinweg** — irreführend.
3. **ML-Black-Box statt regelbasierter Gewichte** — ohne explizite Produktentscheidung.
4. **Ignorieren der Tenant-Sichtbarkeit** im Peer-Pool.

---

## Verwandte Dokumentation

- [SKILL_SCORING_SPEC.md](../../../.claude/docs/technical/SKILL_SCORING_SPEC.md)
- [EXERCISE_CATALOG_DESIGN_PRINCIPLES.md](./EXERCISE_CATALOG_DESIGN_PRINCIPLES.md)
- [TRAINING_PLANNING_DESIGN_PRINCIPLES.md](./TRAINING_PLANNING_DESIGN_PRINCIPLES.md)
- [DESIGN_PRINCIPLES_INDEX.md](./DESIGN_PRINCIPLES_INDEX.md)