108 lines
4.0 KiB
Markdown
108 lines
4.0 KiB
Markdown
|
# 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)
|