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>
9.5 KiB
9.5 KiB
Designprinzipien – Index (Jinkendo Produktfamilie)
Status: Arbeitspapier / Übergabe
Stand: 2026-07-04
Zweck: Zentraler Einstieg für tragfähige Designprinzipien der Jinkendo-Produktfamilie — Shinkan-Serie (15 Module), Abgleich mit Mitai (9 Module), Basis für Schwester-Apps.
Nicht enthalten: App-Gesamtarchitektur, domänenspezifische Fachlogik im Detail, vollständige API-Referenz.
Ablage (Shinkan-Serie): docs/jinkendo-family/design-principles/*_DESIGN_PRINCIPLES.md
Übergeordnet: docs/jinkendo-family/README.md
Mitai-Serie: mitai-jinkendo/.claude/docs/jinkendo-foundation/design-principles/
Abgleich Mitai ↔ Shinkan: DESIGN_PRINCIPLES_ALIGNMENT.md
Wofür diese Serie?
Shinkan implementiert wiederkehrende Querschnittsmuster (Mandanten-Zugriff, Capabilities, Medien-Archiv, Planungsdomäne, KI-Laufzeit, Import, Navigation, Deploy) sowie domänenspezifische Bausteine (Übungskatalog, Fähigkeiten-Scoring, Trainingsplanung, Compliance-Meldungen). Die 15 Dokumente destillieren daraus:
- Was übertragbar ist (Prinzip + Begründung + Tragfähigkeit)
- Was bewusst nicht kopiert werden soll („Nicht übernehmen“)
- Wo im Code nachgeschaut werden kann (Pfade, Specs)
- Mitai-Abgleich — welches Schwester-Dokument vergleichbar ist
Jedes Dokument ist eigenständig lesbar; dieser Index ordnet Abhängigkeiten, Lese-Reihenfolge und den geplanten Familien-Review.
Dokumente (15/15)
| # | Modul | Datei | Kernidee (1 Satz) | Mitai-Vergleich |
|---|---|---|---|---|
| 1 | Access Layer & Tenant | ACCESS_LAYER_DESIGN_PRINCIPLES.md | Ein TenantContext pro Request; einheitliche visibility/club_id-Semantik für Bibliotheksartefakte. |
— (Shinkan-spezifisch) |
| 2 | Capability & Club Features | CAPABILITY_ENTITLEMENT_DESIGN_PRINCIPLES.md | Capabilities + Vereins-Kontingente; GET /me/entitlements; 4-Phasen-Rollout mit Env-Flags. |
#3 Feature & Entitlement |
| 3 | Rights Registry | RIGHTS_REGISTRY_DESIGN_PRINCIPLES.md | Module registrieren Capabilities/Features bei Startup — kein vollständiger Vorab-Katalog in Migrationen. | #4 Registry / Plugin |
| 4 | Auth & Session | AUTH_SESSION_DESIGN_PRINCIPLES.md | Server-Sessions, require_auth als Depends; gemeinsame Mitai-Basis. |
#5 Auth & Session |
| 5 | AI Prompt Runtime | AI_PROMPT_RUNTIME_DESIGN_PRINCIPLES.md | Schmale Laufzeit (ai_prompt_runtime); DB-Templates + Mustache; Kontext-Arten pro Domäne. |
#1 Prompt Engine |
| 6 | Media Assets & Archiv | MEDIA_ASSETS_DESIGN_PRINCIPLES.md | Physisches Asset einmal, mehrfach verknüpft; Lifecycle, Legal Hold, Inline-Rich-Text. | — |
| 7 | Exercise Catalog | EXERCISE_CATALOG_DESIGN_PRINCIPLES.md | Übung als Kernobjekt; Varianten, Governance, Progressionsgraph, Kombinationsübungen. | — |
| 8 | Skill Scoring | SKILL_SCORING_DESIGN_PRINCIPLES.md | Regelbasiertes gewichtetes Profil; Peer-Vergleich nur unter gleichem Artefakttyp. | #2 Data Layer (teilweise) |
| 9 | Training Planning | TRAINING_PLANNING_DESIGN_PRINCIPLES.md | Einheiten mit Phasen/Streams; Rahmen-Bibliothek + Module; Coach/Durchführung getrennt. | — |
| 10 | Content Reports (P-13) | CONTENT_REPORTS_DESIGN_PRINCIPLES.md | Melde-Workflow in Posteingang; Priorität sensibler Gründe; Legal-Hold-Anschluss. | — |
| 11 | Wiki Import | WIKI_IMPORT_DESIGN_PRINCIPLES.md | SMW-API-Ingest + Mapper; Preview/Dry-Run; Duplikat-Tracking — kein Raw-Wiki in DB. | #6 Universal Import |
| 12 | Navigation / IA | NAVIGATION_IA_DESIGN_PRINCIPLES.md | appNav.js als SSoT; Admin-Hub horizontal; Onboarding-Nav ohne Verein. |
#8 Navigation / IA |
| 13 | Migration & Deploy | MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md | XXX_*.sql beim Container-Start; develop/main → Dev/Prod; fail-fast. |
#9 Migration & Deploy |
| 14 | Dashboard KPIs | DASHBOARD_KPI_DESIGN_PRINCIPLES.md | Aggregierter /dashboard/kpis-Roundtrip statt mehrerer Listen-Calls. |
#7 Dashboard Widgets (vereinfacht) |
| 15 | Maturity Models | MATURITY_MODELS_DESIGN_PRINCIPLES.md | Kontextsensitive Matrix-Auflösung; Export/Import-Stack für Admin-Portabilität. | — |
Empfohlene Lesereihenfolge
Schnellüberblick (45 Min)
- ACCESS_LAYER_DESIGN_PRINCIPLES.md — Shinkan-Kernunterscheidung zu Mitai
- RIGHTS_REGISTRY_DESIGN_PRINCIPLES.md — Meta-Muster für Erweiterbarkeit
- MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md — Familien-Basis
Vollständige Implementierung (neues Produkt)
Foundation: (13) Migration & Deploy → (4) Auth → (1) Access Layer → (2) Capabilities → (3) Registry
Domäne: (7) Exercise Catalog → (6) Media → (9) Training Planning → (8) Skill Scoring
Erweiterung: (5) AI Prompt Runtime → (11) Wiki Import → (15) Maturity Models
Compliance: (10) Content Reports
Oberfläche: (12) Navigation → (14) Dashboard KPIs
Nur Familien-Review (Mitai ↔ Shinkan)
| Mitai-Dokument | Shinkan-Gegenstück | Review-Fokus |
|---|---|---|
| #1 Prompt Engine | #5 AI Prompt Runtime | Executor-Reife, Registry, Workflows |
| #2 Data Layer | #8 Skill Scoring | Berechnungs-SSoT vs. Router-Duplikat |
| #3 Feature & Entitlement | #2 Capability & Club Features | Subjekt: Profil vs. Verein |
| #4 Registry | #3 Rights Registry | Registrierungsmuster |
| #5 Auth | #4 Auth & Session | Gemeinsamer Code, IDOR-Risiken |
| #6 Universal Import | #11 Wiki Import | Ingest ≠ Interpretation |
| #7 Dashboard Widgets | #14 Dashboard KPIs | Konfigurierbarkeit vs. Aggregation |
| #8 Navigation | #12 Navigation | appNav-Pattern |
| #9 Migration & Deploy | #13 Migration & Deploy | Gleiches Startup-Muster |
Querschnittsthemen (über alle Docs)
| Thema | Primär | Ergänzend |
|---|---|---|
Mandanten-Isolation (club_id) |
#1 Access Layer | #6 Media, #7 Exercise, #9 Planning |
Sichtbarkeit private/club/official |
#1 Access Layer | #6 Media, #7 Exercise |
| Capability-Gating | #2 Entitlement | #3 Registry, #5 AI Runtime |
| Validierung an der Grenze | #3 Registry | #6 Inline-Media, #11 Import-Mapper |
| Single Source of Truth (Berechnung) | #8 Skill Scoring | #5 AI Kontext-Builder |
| Dual Registry (Code + DB) | #3 Rights Registry | #2 Capabilities in DB |
| Bekannte Lücken dokumentieren | alle „Nicht übernehmen“ | Endpoint-Audit, Architekturschuld |
Verwandte normative Docs (Shinkan-spezifisch)
| Thema | Agent-Guide / Spec |
|---|---|
| Zugriffsschicht | ACCESS_LAYER_AND_GOVERNANCE_PLAN.md, ACCESS_LAYER_ENDPOINT_AUDIT.md |
| Capabilities | CAPABILITY_CATALOG.v1.md |
| Vereins-Features | CLUB_MEMBERSHIP_AND_FEATURES.v1.md |
| Medien | MEDIA_ASSETS_AND_ARCHIVE_SPEC.md |
| KI-Zielbild | AI_PROMPT_TARGET_ARCHITECTURE.md |
| Planung Streams | PARALLEL_TRAINING_STREAMS_SPEC.md |
| Skill Scoring | SKILL_SCORING_SPEC.md |
| Architektur-Schuld | docs/architecture/SCHULDEN_UND_REMEDIATION.md |
Übergabe-Checkliste (Familien-Review)
[ ] Pro Modul: Prinzipien vs. Mitai-Gegenstück abgleichen
[ ] Architekturschuld pro Modul in SCHULDEN_UND_REMEDIATION / „Nicht übernehmen“ verknüpfen
[ ] Gemeinsame Familien-Prinzipien aus Übereinstimmungen ableiten
[ ] Abweichungen bewusst dokumentieren (z. B. Vereins- vs. Profil-Entitlements)
[ ] Shared Code (auth.py, db_init) — eine Quelle oder Fork-Drift?
Pflege
| Aktion | Wo |
|---|---|
| Neues Querschnittsmodul extrahiert | Neues *_DESIGN_PRINCIPLES.md + Zeile in Tabelle oben |
| Shinkan-Implementierung ändert Muster | Betroffenes Einzeldokument + ggf. Querschnittstabelle |
| Mitai-Review abgeschlossen | Abschnitt „Familien-Prinzipien“ (separates Doc, Backlog) |
Changelog Index
| Datum | Änderung |
|---|---|
| 2026-07-04 | Verweis auf FAMILY_ENTITLEMENT_MODEL.md |
| 2026-07-04 | Verweis auf DESIGN_PRINCIPLES_ALIGNMENT.md |
| 2026-07-04 | Shinkan-Serie nach docs/jinkendo-family/design-principles/ verschoben (Familien-Foundation) |
| 2026-07-04 | Index angelegt; Serie 1–15 aus Shinkan-Ist-Stand extrahiert |