Lars/shinkan-jinkendo
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 3 Wiki Activity
develop
shinkan-jinkendo/docs/jinkendo-family/design-principles/SKILL_SCORING_DESIGN_PRINCIPLES.md
Lars 6c7c24e887
All checks were successful
Deploy Development / deploy (push) Successful in 48s
Details
Test Suite / pytest-backend (push) Successful in 45s
Details
Test Suite / lint-backend (push) Successful in 1s
Details
Test Suite / build-frontend (push) Successful in 15s
Details
Test Suite / k6 /health Baseline (push) Successful in 34s
Details
Test Suite / playwright-tests (push) Successful in 1m35s
Details
Add Jinkendo family design principles and entitlement model docs. 
Document cross-app architecture patterns, Mitai alignment, and family entitlement standards. Documentation only; no runtime changes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-14 09:12:48 +02:00

4.0 KiB
Raw Permalink Blame History

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 (#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