Lars
6c7c24e887
All checks were successful
Deploy Development / deploy (push) Successful in 48s
Test Suite / pytest-backend (push) Successful in 45s
Test Suite / lint-backend (push) Successful in 1s
Test Suite / build-frontend (push) Successful in 15s
Test Suite / k6 /health Baseline (push) Successful in 34s
Test Suite / playwright-tests (push) Successful in 1m35s
Document cross-app architecture patterns, Mitai alignment, and family entitlement standards. Documentation only; no runtime changes. Co-authored-by: Cursor <cursoragent@cursor.com>
118 lines
4.1 KiB
Markdown
118 lines
4.1 KiB
Markdown
# Maturity Models – Designprinzipien (Extraktion)
|
||
|
||
**Status:** Analyse / Arbeitspapier
|
||
**Stand:** 2026-07-04
|
||
**Geltungsbereich:** Modul „Maturity Models / Fähigkeitsmatrix“ — kontextsensitive Auflösung
|
||
|
||
**Serie:** Designprinzipien für Produktfamilie · Shinkan Dokument 15 von 15
|
||
**Mitai-Vergleich:** — (domänenspezifisch)
|
||
|
||
**Kernkomponenten:**
|
||
|
||
| Bereich | Pfade |
|
||
|---------|-------|
|
||
| API | `backend/routers/maturity_models.py`, `matrix_editor.py`, `matrix_stack_bundle.py` |
|
||
| Admin-UI | `/admin/maturity-models` |
|
||
| Import | Wiki-Import Typ Modelle; Matrix-Stack Export/Import |
|
||
| Spec | `.claude/docs/technical/SKILLS_MATRIX_SPEC.md` |
|
||
|
||
---
|
||
|
||
## Modul
|
||
|
||
**Maturity Models & Matrix Stack**
|
||
|
||
Matrixbasierte Reifegradmodelle mit Stufen und Zelltexten; kontextsensitive Auflösung über Bindings (Fokusbereich, Stilrichtung, Zielgruppe); Admin-Export/Import einzelner Modelle und Komplett-Stack.
|
||
|
||
---
|
||
|
||
## Designprinzipien
|
||
|
||
### 1. Kontext-Bindings M:N (leer = überall)
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Prinzip** | Modell verknüpft mit Fokus/Stil/Zielgruppe; leere Bindings = global gültig. |
|
||
| **Begründung** | Ein Stack deckt mehrere Trainingskontexte ab. |
|
||
| **Quelle** | `maturity_models.py` `_attach_context` |
|
||
| **Tragfähigkeit** | **hoch** |
|
||
| **Einschränkung** | Auflösungs-Priorität bei mehreren Treffern dokumentieren. |
|
||
|
||
### 2. Resolve-API für Laufzeit-Nutzung
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Prinzip** | Authentifizierte Nutzer listen/auflösen; Admin-only für Roh-ID-GET in Admin-UI. |
|
||
| **Begründung** | Trainer sehen passende Matrix; Rohdaten-Edit geschützt. |
|
||
| **Quelle** | Router-Docstring; Rollen-Checks |
|
||
| **Tragfähigkeit** | **hoch** |
|
||
| **Einschränkung** | — |
|
||
|
||
### 3. Matrix-Editor als separates Admin-Tool
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Prinzip** | `matrix_editor` Router für Zellbearbeitung — nicht im Trainer-Flow. |
|
||
| **Begründung** | Komplexe UI; Plattform-Redaktionsaufgabe. |
|
||
| **Quelle** | Admin-Nav „Fähigkeitsmatrix“ |
|
||
| **Tragfähigkeit** | **hoch** |
|
||
| **Einschränkung** | Frontend-Komplexität — eigene Schuld-Kategorie. |
|
||
|
||
### 4. Stack-Bundle Export/Import
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Prinzip** | `matrix_stack_bundle` — Komplett-Stack zwischen Umgebungen (Dev→Prod, Backup). |
|
||
| **Begründung** | Analog Prompt Import/Export — Konfiguration versionierbar außerhalb DB. |
|
||
| **Quelle** | Admin-Werkzeuge; Wiki-Import ergänzt |
|
||
| **Tragfähigkeit** | **mittel** |
|
||
| **Einschränkung** | Kein Diff/Merge wie Mitai Prompt-Import. |
|
||
|
||
### 5. Plattform-Admin-Schreibschutz
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Prinzip** | Schreiben nur `admin`/`superadmin`; Lesen breiter für authentifizierte Nutzer (Resolve). |
|
||
| **Begründung** | Offizielle Kompetenzrahmen zentral gepflegt. |
|
||
| **Quelle** | `_require_admin` |
|
||
| **Tragfähigkeit** | **hoch** |
|
||
| **Einschränkung** | — |
|
||
|
||
### 6. Integration Wiki-Import für Modelle
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Prinzip** | SMW-Kategorie Modelle → Import-Pfad neben Übungen/Skills. |
|
||
| **Begründung** | Bestehende Wissensbasis karatetrainer.net nutzen. |
|
||
| **Quelle** | `import_wiki.py` `CATEGORY_MODELS` |
|
||
| **Tragfähigkeit** | **mittel** |
|
||
| **Einschränkung** | Gap-Analyse SMW — nicht alle Wiki-Felder gemappt. |
|
||
|
||
### 7. Orthogonal zu Skill Scoring
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Prinzip** | Matrix = beschreibende Stufen; Skill Scoring = gewichtete Übungs-Aggregation — getrennte Module. |
|
||
| **Begründung** | Keine Vermischung von Kompetenz-Raster und Trainings-KPI. |
|
||
| **Quelle** | Domänen-Trennung in Specs |
|
||
| **Tragfähigkeit** | **hoch** |
|
||
| **Einschränkung** | UI kann beides nebenan zeigen — klare Labels nötig. |
|
||
|
||
---
|
||
|
||
## Nicht übernehmen
|
||
|
||
1. **Matrix-Zellen in Übungs-Score-Formel mischen** — ohne fachliche Spec.
|
||
2. **Trainer-Edit globaler offizieller Matrizen** — Admin-only.
|
||
3. **Import ohne Stack-Integrität** — Bundle-Validierung beachten.
|
||
4. **Resolve ohne Kontext-Parameter** wenn Mehrdeutigkeit — falsche Matrix.
|
||
|
||
---
|
||
|
||
## Verwandte Dokumentation
|
||
|
||
- [SKILLS_MATRIX_SPEC.md](../../../.claude/docs/technical/SKILLS_MATRIX_SPEC.md)
|
||
- [WIKI_IMPORT_DESIGN_PRINCIPLES.md](./WIKI_IMPORT_DESIGN_PRINCIPLES.md)
|
||
- [SKILL_SCORING_DESIGN_PRINCIPLES.md](./SKILL_SCORING_DESIGN_PRINCIPLES.md)
|
||
- [DESIGN_PRINCIPLES_INDEX.md](./DESIGN_PRINCIPLES_INDEX.md)
|