Sprint-0-Grundlagen: Spec-Handover, Designprinzipien-Referenz, Medien optional.
Test Suite / lint-backend (push) Waiting to run
Test Suite / build-frontend (push) Waiting to run
Test Suite / k6 /health Baseline (push) Waiting to run
Test Suite / playwright-tests (push) Waiting to run
Deploy Development / deploy (push) Failing after 0s
Test Suite / pytest-backend (push) Has been cancelled
Test Suite / lint-backend (push) Waiting to run
Test Suite / build-frontend (push) Waiting to run
Test Suite / k6 /health Baseline (push) Waiting to run
Test Suite / playwright-tests (push) Waiting to run
Deploy Development / deploy (push) Failing after 0s
Test Suite / pytest-backend (push) Has been cancelled
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
ea445a9263
commit
0e2b938fbd
36 files changed
+6041
-130
No files matched your search
@@ -0,0 +1,358 @@
|
||||
# Designprinzipien – Abgleich Mitai ↔ Shinkan
|
||||
|
||||
**Status:** Review / Entscheidungsgrundlage
|
||||
**Stand:** 2026-07-04
|
||||
**Zweck:** Widersprüche, bewusste Abweichungen und Implementierungslücken zwischen den Designprinzipien-Serien identifizieren — Basis für **Familien-Entscheidungen** und langfristige Konvergenz von Mitai und Shinkan.
|
||||
|
||||
**Quellen:**
|
||||
|
||||
| App | Index |
|
||||
|-----|--------|
|
||||
| Mitai (Foundation) | [mitai-jinkendo/.claude/docs/jinkendo-foundation/design-principles/README.md](file:///c:/Dev/mitai-jinkendo/.claude/docs/jinkendo-foundation/design-principles/README.md) — 9 Module |
|
||||
| Shinkan | [design-principles/DESIGN_PRINCIPLES_INDEX.md](./design-principles/DESIGN_PRINCIPLES_INDEX.md) — 15 Module |
|
||||
|
||||
---
|
||||
|
||||
## 1. Kurzfassung
|
||||
|
||||
| Kategorie | Anzahl | Bedeutung |
|
||||
|-----------|--------|-----------|
|
||||
| **Familien-Konsens** | 12 Muster | In beiden Serien gleich oder kompatibel — **verbindlich für neue Apps** |
|
||||
| **Bewusste Produkt-Abweichung** | 8 | Fachlich/Architektur begründet — **nicht angleichen**, aber im Familienmodell verankern |
|
||||
| **Konzeptuelle Spannung** | 6 | Widersprüche oder gegenläufige Defaults — **Familien-Entscheidung nötig** |
|
||||
| **Ist vs. Prinzip (Schuld)** | 14+ | Mindestens eine App verletzt eigene oder Schwester-Prinzipien — **Remediation** |
|
||||
| **Nur Shinkan** | 6 Module | Mandanten-/Domänen-Bausteine ohne Mitai-Pendant |
|
||||
| **Nur Mitai (reifer)** | 3 Muster | Data Layer, Widget-Dashboard, Universal Import — Shinkan vereinfacht oder fehlt |
|
||||
|
||||
**Kernbefund:** Mitai und Shinkan teilen dieselbe **technische Basis** (Auth, Migration, Nav-SSoT, Registry-Denken, Probe→Enforce), divergieren aber strukturell bei **Entitlement-Subjekt** (Profil vs. Verein), **Berechnungsarchitektur** (generischer Data Layer vs. domänenspezifisches Scoring) und **KI-Reife** (Unified Executor vs. schmale Laufzeit).
|
||||
|
||||
---
|
||||
|
||||
## 2. Familien-Konsens (für neue Produkte übernehmen)
|
||||
|
||||
Diese Muster sind in beiden Serien explizit oder implizit tragfähig:
|
||||
|
||||
| # | Muster | Mitai | Shinkan |
|
||||
|---|--------|-------|---------|
|
||||
| F1 | Server-Sessions + `Depends(require_auth)` | Auth #1–3 | Auth #1–2 |
|
||||
| F2 | `profile_id` aus Session, nie aus Client-Header | Auth #3 | Auth #3 |
|
||||
| F3 | Auth getrennt von Authorization/Entitlements | Auth #10 | Capabilities + Access Layer |
|
||||
| F4 | Nummerierte SQL-Migrationen + Tracking beim Container-Start | Migration #1–5 | Migration #1–3 |
|
||||
| F5 | Fail-fast, kein Auto-Rollback | Migration #5 | Migration #2 |
|
||||
| F6 | `appNav` / zentrale Nav-Config als SSoT | Navigation #1 | Navigation #1 |
|
||||
| F7 | Admin als eigener Hub/Realm | Navigation #6–7 | Navigation #2 |
|
||||
| F8 | DB-konfigurierbare KI-Prompts (nicht hardcoded Prod) | Prompt #2 | AI Runtime #2 |
|
||||
| F9 | Template vs. Kontext/Daten trennen | Prompt #5 | AI Runtime #4 |
|
||||
| F10 | Ingest ≠ Interpretation beim Import | Import #2 | Wiki Import #1 |
|
||||
| F11 | Preview/Dry-Run vor Massenimport | Import #3+ | Wiki Import #2 |
|
||||
| F12 | 4-Phasen-Rollout Entitlements (Log → Enforce) | Feature #8 | Capability #2 |
|
||||
|
||||
**Empfehlung:** Als **`JINKENDO_FOUNDATION_CHECKLIST`** in künftigen Apps verpflichtend; Details pro Modul in den Einzeldokumenten.
|
||||
|
||||
---
|
||||
|
||||
## 3. Modul-Abgleich (9 vergleichbare Paare)
|
||||
|
||||
Legende **Bewertung:**
|
||||
|
||||
| Symbol | Bedeutung |
|
||||
|--------|-----------|
|
||||
| ✅ | Prinzipien aligned / kompatibel |
|
||||
| ⚠️ | Teilweise aligned; Lücken in Implementierung oder Doku |
|
||||
| 🔀 | Bewusste Produkt-Divergenz (kein Bug) |
|
||||
| ❌ | Widerspruch oder gegenläufiges Konzept — Entscheidung nötig |
|
||||
| 🏗️ | Ist-Stand verletzt dokumentierte Prinzipien (Architekturschuld) |
|
||||
|
||||
---
|
||||
|
||||
### 3.1 Prompt Engine (Mitai #1) ↔ AI Prompt Runtime (Shinkan #5)
|
||||
|
||||
| Aspekt | Mitai | Shinkan | Bewertung |
|
||||
|--------|-------|---------|-----------|
|
||||
| Single Entry Point | `execute_prompt` / Unified System | `ai_prompt_runtime` + verteilte Orchestratoren | ❌ Konzept |
|
||||
| Prompt-Typen | base / pipeline / workflow | nur slug + Mustache | 🔀 Shinkan bewusst schlanker |
|
||||
| Platzhalter-Registry | zentral, API-Verträge | Kontext-Arten (`AiPromptContextKind`), kein Registry-Katalog | ⚠️ |
|
||||
| Data Layer-Anbindung | Layer 1 → Resolver | Domänen-Builder ad hoc | ⚠️ |
|
||||
| Debug/Preview | ausgereift | Admin-Vorschau, weniger Runtime-Transparenz | ⚠️ |
|
||||
| Feature-Gating an Execute | teils fehlend (Legacy) | Capability geplant, teils Probe | 🏗️ beide |
|
||||
|
||||
**Widersprüche / gegenläufig:**
|
||||
|
||||
- Mitai: **Ein Executor** ist Kernprinzip. Shinkan: **kein** vergleichbarer Executor — Planungs-KI umgeht teils die Laufzeit.
|
||||
- Beide warnen vor **parallelen KI-Pfaden**; beide haben sie noch (Mitai `insights.py`, Shinkan Router-OpenRouter).
|
||||
|
||||
**Familien-Entscheidung (Vorschlag):**
|
||||
|
||||
| Option | Inhalt |
|
||||
|--------|--------|
|
||||
| **Zielbild** | Gemeinsame **`prompt_executor`-Fassade** (Package oder Copy mit Namespace); Shinkan-Kontext-Builder als Plugins |
|
||||
| **Shinkan-Roadmap** | Planungs-Orchestrierung in Laufzeit ziehen; keine Workflow-Graphs vor Planungs-Kontext-Reife |
|
||||
| **Nicht kopieren** | Mitai: doppelte Pipeline-Modelle, PLACEHOLDER_MAP-Duplikat, Roh-SQL im Executor |
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Data Layer (Mitai #2) ↔ Skill Scoring (Shinkan #8)
|
||||
|
||||
| Aspekt | Mitai | Shinkan | Bewertung |
|
||||
|--------|-------|---------|-----------|
|
||||
| Berechnungs-SSoT | `data_layer/` Layer 0→1→2 | nur `skill_scoring.py` | ❌ Abdeckung |
|
||||
| Router delegieren | explizites Prinzip #13 | Skill-Router ja; Planung teils nicht | ⚠️ |
|
||||
| Confidence / data_points | Pflicht-Metadaten | nicht analog | 🔀 Domäne anders |
|
||||
| Chart/KPI-Anbindung | Layer 2b Adapter | KPI-Dashboard ruft Router-Helfer | ⚠️ |
|
||||
| Import-Grenze | keine Scores beim Insert | Wiki: explizit kein Scoring beim Insert | ✅ |
|
||||
|
||||
**Widerspruch:**
|
||||
|
||||
- Mitai postuliert **generische Berechnungsschicht** für die ganze App. Shinkan hat **kein** Data Layer — nur ein **domänenspezifisches** Scoring-Modul. Das ist keine Implementierungslücke allein, sondern **unterschiedliche Architektur-Tiefe**.
|
||||
|
||||
**Familien-Entscheidung (Vorschlag):**
|
||||
|
||||
| Option | Inhalt |
|
||||
|--------|--------|
|
||||
| **Familien-Prinzip** | „Berechnungen in benannter Schicht, nicht in Router/React“ — **Ja** |
|
||||
| **Implementierung** | Mitai: `data_layer/` bleibt Referenz. Shinkan: Skill Scoring **ist** Layer-1-Vorbild; langfristig **`planning_metrics/`** o. ä. statt Router-SQL |
|
||||
| **Nicht verallgemeinern** | Mitai-Formeln (TDEE, WHR) — nur Schichtenmodell übernehmen |
|
||||
|
||||
---
|
||||
|
||||
### 3.3 Feature & Entitlement (Mitai #3) ↔ Capability & Club Features (Shinkan #2)
|
||||
|
||||
| Aspekt | Mitai | Shinkan | Bewertung |
|
||||
|--------|-------|---------|-----------|
|
||||
| Subjekt | **Profil** + Tier | **Verein** (`club_id`) + Plan | ❌ Scope |
|
||||
| Auflösungs-API | `check_feature_access` | `check_capability` + `club_features` + `/me/entitlements` | 🔀 |
|
||||
| Rollout 4 Phasen | ja | ja (Env-Flags) | ✅ |
|
||||
| Registry | DB `features` + Tiers | Code-Registry → DB Sync | ⚠️ |
|
||||
| Capabilities vs. Features | Features only | Capabilities **und** Kontingente getrennt | 🔀 Shinkan feiner |
|
||||
| Widget/Layout-Gating | zentral | Entitlements-API, kein Widget-Layout | ⚠️ |
|
||||
|
||||
**Größter Familien-Konflikt:**
|
||||
|
||||
Mitai-Dokument #3 „Nicht übernehmen“ Punkt 10: *„Profile as Entitlement-Subject — Multi-App-Familie braucht separates Identity/Subscription-Boundary.“*
|
||||
Shinkan **ist** die Antwort mit Verein als Subjekt — aber es gibt **kein gemeinsames Familienmodell**, das Profil-Tier **und** Org-Limits kombiniert.
|
||||
|
||||
**Familien-Entscheidung (Vorschlag):**
|
||||
|
||||
```
|
||||
Entitlement-Subjekt (familie):
|
||||
├── account (profile_id) → Tier, persönliche Limits (Mitai)
|
||||
└── tenant (club_id?) → Org-Plan, Capabilities (Shinkan, optional null)
|
||||
|
||||
API: GET /me/entitlements?tenant_id=
|
||||
Enforcement: eine resolve_entitlement(subject, capability|feature)
|
||||
```
|
||||
|
||||
| App | Remediation |
|
||||
|-----|-------------|
|
||||
| Mitai | Org-Scope reservieren; Tier-Drift (#3 Schuld) bereinigen |
|
||||
| Shinkan | `CLUB_FEATURE_ENFORCE=1` produktiv; Mitai-Legacy `check_feature_access` nicht nutzen (bereits Regel) |
|
||||
|
||||
---
|
||||
|
||||
### 3.4 Registry / Plugin (Mitai #4) ↔ Rights Registry (Shinkan #3)
|
||||
|
||||
| Aspekt | Mitai | Shinkan | Bewertung |
|
||||
|--------|-------|---------|-----------|
|
||||
| Registry-first | Platzhalter, Widgets, CSV-Module | Capabilities + Features only | ⚠️ Abdeckung |
|
||||
| Validierung an Grenze | ja | ja (`register_*` wirft) | ✅ |
|
||||
| Runtime + DB | Dual (Katalog + DB-Overrides) | Code → DB Upsert | ✅ |
|
||||
| Dual Registry FE/BE | Widgets + `registerDashboardWidgets` | nicht vorhanden | 🔀 |
|
||||
| Metadaten-Tiefe | nach Risiko (Matrix in Doc) | schlankere Dataclasses | ✅ |
|
||||
|
||||
**Kein Widerspruch** — Shinkan Rights Registry ist **Teilmenge** des Mitai-Meta-Musters.
|
||||
|
||||
**Familien-Entscheidung:** Mitai-Registry-Matrix (Platzhalter / UI-Plugin / Import-Modul / Rechte) als **Familien-Taxonomie**; Shinkan erweitert um Import-/Prompt-Registry wenn Wiki-Import generisch wird.
|
||||
|
||||
---
|
||||
|
||||
### 3.5 Auth & Session (Mitai #5 ↔ Shinkan #4)
|
||||
|
||||
| Aspekt | Mitai | Shinkan | Bewertung |
|
||||
|--------|-------|---------|-----------|
|
||||
| Session-Modell | opaque token | gleich (shared `auth.py`) | ✅ |
|
||||
| Depends-Pattern | ja | ja (+ TenantContext) | ✅ |
|
||||
| IDOR Profile-Header | dokumentierte Schwäche | Shinkan: Session-only betont | ⚠️ prüfen |
|
||||
| RBAC | `role` admin/user | Portal-Rolle **+** Vereinsrollen | 🔀 |
|
||||
| Rate Limiting | ja | (Mitai-spezifisch in Router) | ⚠️ |
|
||||
| Feature-Flags in Session | Legacy-Spalten | Account-Lifecycle separat | 🏗️ Mitai |
|
||||
|
||||
**Gegenläufig:** Shinkan **erweitert** Auth um Mandanten — darf Mandantenlogik **nicht** in `auth.py` legen (Shinkan-Prinzip „Nicht übernehmen“).
|
||||
|
||||
**Familien-Entscheidung:** Gemeinsames Auth-Modul; **TenantContext** als optionales Add-on-Pattern für mandantenfähige Apps.
|
||||
|
||||
---
|
||||
|
||||
### 3.6 Universal Import (Mitai #6) ↔ Wiki Import (Shinkan #11)
|
||||
|
||||
| Aspekt | Mitai | Shinkan | Bewertung |
|
||||
|--------|-------|---------|-----------|
|
||||
| Ingest ≠ Interpretation | ✅ | ✅ | ✅ |
|
||||
| Modul-Registry | zentral | fehlt (wiki-hardcoded) | ⚠️ |
|
||||
| SAVEPOINT pro Zeile | ja | nicht dokumentiert | ⚠️ |
|
||||
| Vorlagen/Mappings | generisch | SMW-Kategorien via Env | 🔀 |
|
||||
| Feature-Limits | an Import gebunden | Admin-only | ⚠️ |
|
||||
|
||||
**Kein Konflikt** — unterschiedliche Reife. Shinkan ist **Spezialfall** des Mitai-Musters.
|
||||
|
||||
**Familien-Entscheidung:** Neue Import-Quellen über **Universal-Import-Gerüst** (Mitai); Wiki als `import_type=mediawiki` registrieren.
|
||||
|
||||
---
|
||||
|
||||
### 3.7 Dashboard Widgets (Mitai #7) ↔ Dashboard KPIs (Shinkan #14)
|
||||
|
||||
| Aspekt | Mitai | Shinkan | Bewertung |
|
||||
|--------|-------|---------|-----------|
|
||||
| UX-Modell | konfigurierbares Widget-Layout | festes KPI-Aggregat | ❌ UX-Konzept |
|
||||
| Chatty Client vermeiden | via Widget-Daten | via `/dashboard/kpis` | ✅ Ziel |
|
||||
| Entitlements | `allowed` pro Widget | TenantContext auf KPIs | ✅ |
|
||||
| Data Layer | Widgets konsumieren Layer 1 | intern Router-Helfer | ⚠️ |
|
||||
|
||||
**Gegenläufig:** Mitai: **Nutzer konfiguriert Dashboard**. Shinkan: **Produkt definiert feste Kacheln** — bewusste MVP-Vereinfachung.
|
||||
|
||||
**Familien-Entscheidung:**
|
||||
|
||||
| App-Typ | Dashboard-Pattern |
|
||||
|---------|-------------------|
|
||||
| Personal Tracking (Mitai) | Widget-Katalog + Layout-JSON |
|
||||
| Trainer/Verein (Shinkan) | Aggregierte KPI-Endpoints ausreichend; Widget-System optional Phase 2 |
|
||||
| Neue App | Aggregat-Endpoint **mindestens**; Widget-System wenn Personalisierung nötig |
|
||||
|
||||
---
|
||||
|
||||
### 3.8 Navigation / IA (Mitai #8 ↔ Shinkan #12)
|
||||
|
||||
| Aspekt | Mitai | Shinkan | Bewertung |
|
||||
|--------|-------|---------|-----------|
|
||||
| appNav SSoT | ja | ja | ✅ |
|
||||
| Admin-Hub | Shell + Hub-Gruppen | horizontale `AdminPageNav` | ⚠️ |
|
||||
| Breakpoint 1024px | explizit | „prüfen“ | ⚠️ |
|
||||
| Onboarding-Nav | — | reduziert ohne Verein | 🔀 Shinkan |
|
||||
| adminNav.js SSoT | empfohlen | hardcoded Array in JSX | 🏗️ Shinkan |
|
||||
| Safe Area PWA | ja | Design-System, weniger explizit | ⚠️ |
|
||||
|
||||
**Familien-Entscheidung:** `appNav.js` + **`adminNav.js`** als Pflicht; Shinkan `AdminPageNav` refactoren.
|
||||
|
||||
---
|
||||
|
||||
### 3.9 Migration & Deploy (Mitai #9 ↔ Shinkan #13)
|
||||
|
||||
| Aspekt | Mitai | Shinkan | Bewertung |
|
||||
|--------|-------|---------|-----------|
|
||||
| XXX_*.sql + schema_migrations | ✅ | ✅ | ✅ |
|
||||
| Startup vor App | ✅ | ✅ | ✅ |
|
||||
| develop/main | ✅ | ✅ | ✅ |
|
||||
| Feste Ports | ✅ | ✅ | ✅ |
|
||||
| Immutabler Docker-Build | dokumentiert | nicht im Shinkan-Doc | ⚠️ Doku |
|
||||
| Health-Check / PG wait | ausführlich | kürzer | ⚠️ Doku |
|
||||
|
||||
**Aligned** — Shinkan-Dokument ist **Untermenge**; Implementierung vermutlich gleich (shared Infra).
|
||||
|
||||
---
|
||||
|
||||
## 4. Nur Shinkan (6 Module) — Einordnung für die Familie
|
||||
|
||||
| Modul | Familien-Relevanz | Mitai-Bezug |
|
||||
|-------|-------------------|------------|
|
||||
| **Access Layer & Tenant** | **Pflicht** für mandantenfähige Apps | Mitai #3 fordert Org-Boundary — hier ausformuliert |
|
||||
| **Media Assets & Archiv** | Optional (Content-Apps) | — |
|
||||
| **Exercise Catalog** | Shinkan-Domäne | — |
|
||||
| **Training Planning** | Shinkan-Domäne | — |
|
||||
| **Content Reports (P-13)** | Empfohlen für UGC/Plattform | — |
|
||||
| **Maturity Models** | Optional (Kompetenz-Apps) | — |
|
||||
|
||||
**Kein Widerspruch zu Mitai** — ergänzen das Familienmodell um **Mandant + Content-Governance**.
|
||||
|
||||
---
|
||||
|
||||
## 5. Querschnitt: Ist-Stand vs. dokumentierte Prinzipien
|
||||
|
||||
Gemeinsame **Architekturschuld** (beide Apps verletzen teils eigene „Nicht übernehmen“-Listen):
|
||||
|
||||
| Thema | Mitai | Shinkan |
|
||||
|-------|-------|---------|
|
||||
| Parallele KI-Pfade | `insights.py` Legacy | OpenRouter direkt in Routern |
|
||||
| Entitlement Enforcement | teils UI-only / Legacy-Spalten | Env Probe-only |
|
||||
| Registry-Sync / Duplikat | PLACEHOLDER_MAP + Registry | Capabilities-Sync, kein Prompt-Registry |
|
||||
| Frontend ohne Backend-Gate | teils | Capabilities Probe |
|
||||
| Dokumentations-Drift | Tier vs. Enforcement-Docs | Endpoint-Audit unvollständig |
|
||||
| Monolithische Pages/Client | God Pages, api.js | God Pages, api.js (Roadmap Phase 4) |
|
||||
| Fehlende JSON-Schema-KI | TODO | TODO (explizit vermeiden) |
|
||||
|
||||
---
|
||||
|
||||
## 6. Entscheidungs-Matrix (Priorisiert)
|
||||
|
||||
| Prio | Entscheidung | Betroffene Apps | Empfohlene Familien-Regel |
|
||||
|------|--------------|-----------------|---------------------------|
|
||||
| **P0** | Entitlement-Subjekt: Profil **und** optional Tenant | Mitai, Shinkan, neu | Ein API-Shape `/me/entitlements`; zwei Subjekt-Ebenen |
|
||||
| **P0** | Kein Client-`profile_id` für AuthZ | alle | Session-only; Tenant via Header + Membership |
|
||||
| **P1** | KI: ein Executor pro App | Mitai (fertig), Shinkan (Ziel) | `execute_prompt(slug, context_dto)` |
|
||||
| **P1** | Berechnungs-SSoT-Schicht | Shinkan erweitern | Mindestens ein `*/metrics.py` pro Domäne mit KPIs |
|
||||
| **P1** | Enforcement produktiv | beide | Phase 4 Enforce in Prod für kritische Features |
|
||||
| **P2** | Registry-Taxonomie vereinheitlichen | beide | Rechte / Platzhalter / Import / UI-Plugin |
|
||||
| **P2** | Admin-Nav SSoT | Shinkan | `adminNav.js` wie Mitai |
|
||||
| **P2** | Import: Universal + Spezialmodule | Shinkan | Wiki als registriertes Modul |
|
||||
| **P3** | Dashboard: Aggregat vs. Widgets | produktabhängig | Entscheidungsbaum §3.7 |
|
||||
| **P3** | Shared `auth.py` / `db_init` | beide | Monorepo-Package oder Sync-Disziplin |
|
||||
|
||||
---
|
||||
|
||||
## 7. Konvergenz-Roadmap (langfristig)
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph foundation [Familien-Foundation]
|
||||
M9[Migration]
|
||||
M5[Auth]
|
||||
F3[Entitlements 2-Ebenen]
|
||||
R4[Registry Meta]
|
||||
end
|
||||
|
||||
subgraph mitai [Mitai]
|
||||
DL[Data Layer]
|
||||
PE[Prompt Engine]
|
||||
DW[Dashboard Widgets]
|
||||
end
|
||||
|
||||
subgraph shinkan [Shinkan]
|
||||
AL[Access Layer]
|
||||
AR[AI Runtime → Executor]
|
||||
SS[Skill Scoring → Layer 1]
|
||||
end
|
||||
|
||||
M9 --> mitai
|
||||
M9 --> shinkan
|
||||
M5 --> mitai
|
||||
M5 --> shinkan
|
||||
F3 --> mitai
|
||||
F3 --> shinkan
|
||||
R4 --> mitai
|
||||
R4 --> shinkan
|
||||
AL -.->|Mandanten-Apps| foundation
|
||||
PE -.->|Konvergenz| AR
|
||||
DL -.->|Schichtenmodell| SS
|
||||
```
|
||||
|
||||
| Phase | Mitai | Shinkan |
|
||||
|-------|-------|---------|
|
||||
| **Kurz** | Legacy KI-Pfade entfernen; Enforcement-Doku vereinheitlichen | Access-Layer-Audit abschließen; `CAPABILITY_ENFORCE` |
|
||||
| **Mittel** | Org-Scope in Entitlements vorbereiten | `ai_prompt_runtime` → Unified Executor; Router-Helfer statt KPI-Duplikat |
|
||||
| **Lang** | SSO/Identity (Vision) | Data-Layer-ähnliche Module für Planung; optional Widget-Dashboard |
|
||||
|
||||
---
|
||||
|
||||
## 8. Nächste Schritte
|
||||
|
||||
1. **Review-Workshop:** Tabelle §6 P0–P1 durchgehen und Familien-Regeln verbindlich markieren.
|
||||
2. ~~**`FAMILY_ENTITLEMENT_MODEL.md`** anlegen (P0)~~ → [FAMILY_ENTITLEMENT_MODEL.md](./FAMILY_ENTITLEMENT_MODEL.md) (Entwurf 2026-07-04)
|
||||
3. **Shinkan-Index** und **Mitai-Foundation-README** auf dieses Dokument verlinken.
|
||||
4. **`FAMILY_ENTITLEMENT_MODEL.md`** — Entwurf angelegt (§6 Produkt-Abweichungen, §8 Regeln neue Apps).
|
||||
5. Pro **P1-Punkt** Issue/Remediation-Eintrag in jeweiliger `SCHULDEN_UND_REMEDIATION` / Mitai-Äquivalent.
|
||||
|
||||
---
|
||||
|
||||
## 9. Changelog
|
||||
|
||||
| Datum | Änderung |
|
||||
|-------|----------|
|
||||
| 2026-07-04 | Erstfassung Abgleich Mitai Foundation (9) ↔ Shinkan (15) |
|
||||
@@ -0,0 +1,316 @@
|
||||
# Familien-Modell: Entitlements & Limits
|
||||
|
||||
**Status:** Entwurf / verbindliche Zielrichtung (mit bewussten Produkt-Ausnahmen)
|
||||
**Stand:** 2026-07-04
|
||||
**Bezüge:**
|
||||
|
||||
- [DESIGN_PRINCIPLES_ALIGNMENT.md](./DESIGN_PRINCIPLES_ALIGNMENT.md) — Abgleich Mitai ↔ Shinkan
|
||||
- Mitai: [FEATURE_ENTITLEMENT_DESIGN_PRINCIPLES.md](file:///c:/Dev/mitai-jinkendo/.claude/docs/jinkendo-foundation/design-principles/FEATURE_ENTITLEMENT_DESIGN_PRINCIPLES.md)
|
||||
- Shinkan: [CAPABILITY_ENTITLEMENT_DESIGN_PRINCIPLES.md](./design-principles/CAPABILITY_ENTITLEMENT_DESIGN_PRINCIPLES.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. Zweck
|
||||
|
||||
Dieses Dokument definiert das **gemeinsame Entitlement-Modell** der Jinkendo-Produktfamilie:
|
||||
|
||||
- **Was** für neue Apps und Refactors **Standard** ist
|
||||
- **Welche Produkt-Profile** welche Scopes nutzen (Account, Tenant, beides, keins)
|
||||
- **Wie** bewusste Abweichungen dokumentiert werden — Abweichung ist erlaubt, **Undokumentiertheit** nicht
|
||||
|
||||
**Nicht enthalten:** Stripe/SSO (`auth.jinkendo.de`), vollständige Billing-Implementierung, app-spezifische Feature-IDs.
|
||||
|
||||
---
|
||||
|
||||
## 2. Leitgedanke: Vier getrennte Fragen
|
||||
|
||||
Jede geschützte Aktion durchläuft konzeptionell **vier unabhängige Prüfungen**. Nicht jede App implementiert alle vier — siehe §6.
|
||||
|
||||
| # | Frage | Familien-Begriff | Typische Quelle |
|
||||
|---|--------|------------------|-----------------|
|
||||
| **A** | Wer ist eingeloggt? | **Auth** (Identität) | Session → `profile_id` |
|
||||
| **B** | Darf diese Rolle die **Funktion** ausführen? | **Capability** (Permission) | Rollen-Matrix, `min_account_state` |
|
||||
| **C** | Ist das **Kontingent** erschöpft? | **Feature / Limit** (Quota) | Plan, Tier, Usage-Zähler |
|
||||
| **D** | Darf ich **dieses Objekt** lesen/ändern? | **Governance** (Object ACL) | `visibility`, `club_id`, Owner |
|
||||
|
||||
```
|
||||
Request → Auth (A) → [Capability (B)] → [Feature-Limit (C)] → [Governance (D)] → Handler
|
||||
```
|
||||
|
||||
**Familien-Regel:** B, C und D **nicht** in React-Widgets oder Router-Inline-Logik vermischen — jeweils eine Auflösungsfunktion pro Ebene.
|
||||
|
||||
**Shinkan-Ergänzung:** Governance ist dort ausgebaut (`TenantContext`, Access Layer); Mitai fokussiert A+B+C auf Profil-Ebene.
|
||||
|
||||
---
|
||||
|
||||
## 3. Familien-Standard: Zwei Subjekt-Ebenen
|
||||
|
||||
Limits und Pläne können an **zwei Subjekte** hängen. Beide sind im Familienmodell **first-class** — Apps wählen, welche sie nutzen (§6).
|
||||
|
||||
| Subjekt | ID | Typische Frage | Beispiel |
|
||||
|---------|-----|----------------|----------|
|
||||
| **Account** | `profile_id` | Was darf **ich** als Nutzer (Tarif)? | Mitai Free vs. Premium |
|
||||
| **Tenant** | `tenant_id` (z. B. `club_id`) | Was darf **meine Organisation**? | Shinkan Vereinsplan, KI-Kontingent |
|
||||
|
||||
### 3.1 Auflösungs-Reihenfolge (wenn beide Ebenen aktiv)
|
||||
|
||||
Für eine Aktion mit Capability `X` und Feature `Y`:
|
||||
|
||||
1. **Account-Lifecycle** — z. B. E-Mail verifiziert, Onboarding abgeschlossen
|
||||
2. **Capability(B)** — Rolle darf Funktion (Account- und/oder Tenant-Rollen)
|
||||
3. **Feature(C)** — Kontingent am **primären Billing-Subjekt** der App (siehe Produkt-Profil)
|
||||
4. **Governance(D)** — Objekt sichtbar/bearbeitbar
|
||||
|
||||
**AND-Verknüpfung:** Alle aktiven Ebenen müssen passieren. Ausnahmen nur in §6.3 dokumentiert.
|
||||
|
||||
### 3.2 Primäres Billing-Subjekt pro App
|
||||
|
||||
| Profil | Primäres Subjekt für Limits | Capability-Subjekt |
|
||||
|--------|----------------------------|-------------------|
|
||||
| Personal App (Mitai) | **Account** | Account |
|
||||
| Mandanten-App (Shinkan) | **Tenant** | Account + Tenant-Rolle |
|
||||
| Hybrid (Zukunft) | konfigurierbar | beide |
|
||||
|
||||
---
|
||||
|
||||
## 4. Familien-Standard: Capabilities vs. Features
|
||||
|
||||
| Konzept | Familien-Definition | Subjekt | Beispiel |
|
||||
|---------|---------------------|---------|----------|
|
||||
| **Capability** | Binäre oder rollenbasierte **Erlaubnis** („darf ich?“) | meist Account + Tenant-Kontext | `exercises.ai.suggest` |
|
||||
| **Feature** | **Kontingent** oder Boolean-Limit („wie oft/noch?“) | Account **oder** Tenant | `ai_calls` / Monat |
|
||||
| **Verknüpfung** | Capability kann `linked_feature_id` haben | — | KI-Capability → KI-Kontingent |
|
||||
|
||||
**Familien-Regel:**
|
||||
|
||||
- Capabilities **registry-first** registrieren (Code → DB-Sync, Shinkan-Muster).
|
||||
- Feature-IDs **nicht** in UI hardcoden — nur aus Entitlements-Response.
|
||||
- `NULL` Limit = unbegrenzt; `0` = deaktiviert (Mitai-Semantik, familienweit).
|
||||
|
||||
---
|
||||
|
||||
## 5. Familien-Standard: API & Enforcement
|
||||
|
||||
### 5.1 Ziel-API (neue Apps)
|
||||
|
||||
Ein **einheitlicher Snapshot** für das Frontend:
|
||||
|
||||
```
|
||||
GET /api/me/entitlements
|
||||
?tenant_id=<optional>
|
||||
|
||||
Response (skizziert):
|
||||
{
|
||||
"account": {
|
||||
"profile_id": 1,
|
||||
"account_state": "active_member",
|
||||
"tier_id": "premium", // optional, Account-Apps
|
||||
"features": { "ai_calls": { "allowed", "used", "limit", "remaining", "reset_at" } },
|
||||
"capabilities": { "analysis.run": { "allowed": true, "reason": null } }
|
||||
},
|
||||
"tenant": { // null wenn App keinen Tenant kennt
|
||||
"tenant_id": 42,
|
||||
"tenant_type": "club",
|
||||
"plan_id": "pro",
|
||||
"features": { ... },
|
||||
"capabilities": { ... },
|
||||
"roles": ["trainer"]
|
||||
},
|
||||
"enforcement": {
|
||||
"capabilities": "enforce|probe",
|
||||
"features": "enforce|probe"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Familien-Regel:** UI liest **nur** diesen Snapshot (oder domänenspezifische Teilmenge) — keine parallelen `/subscription/me` + `/features/usage` + Ad-hoc-Checks in neuen Apps.
|
||||
|
||||
### 5.2 Ist-API (bestehende Apps — Abweichung dokumentiert)
|
||||
|
||||
| App | Endpoint heute | Familien-Ziel |
|
||||
|-----|----------------|---------------|
|
||||
| **Mitai** | `/subscription/me`, `/features/usage`, `check_feature_access` | Snapshot schrittweise; Account-Block reicht |
|
||||
| **Shinkan** | `GET /api/me/entitlements?club_id=` | Tenant-Block + Capabilities; Account-Tier fehlt bewusst |
|
||||
|
||||
Migration: **kein Big-Bang** — alte Endpoints als Facade auf Snapshot mappen.
|
||||
|
||||
### 5.3 Vier-Phasen-Rollout (familienweit verbindlich)
|
||||
|
||||
| Phase | Verhalten | Env-Beispiel |
|
||||
|-------|-----------|--------------|
|
||||
| **1** | Cleanup Legacy-Flags | — |
|
||||
| **2** | **Probe** — JSON-Log, HTTP 200 | `*_ENFORCE=0` |
|
||||
| **3** | Frontend-Gates aus Entitlements | — |
|
||||
| **4** | **Enforce** — HTTP 403 | `*_ENFORCE=1` |
|
||||
|
||||
**Familien-Regel:** Phase 4 für **neue** kritische Features von Anfang an planbar; Bestands-Apps dürfen in Phase 2–3 bleiben bis kalibriert.
|
||||
|
||||
### 5.4 Enforcement-Priorität
|
||||
|
||||
1. **API** — autoritativ (`403`)
|
||||
2. **Frontend** — UX (Badges, disabled Buttons)
|
||||
3. **Niemals** — nur UI ohne API-Gate
|
||||
|
||||
---
|
||||
|
||||
## 6. Produkt-Profile & bewusste Abweichungen
|
||||
|
||||
Abweichungen vom Familien-Standard sind **zulässig**, wenn sie in der Tabelle **§6.2** stehen und begründet sind.
|
||||
|
||||
### 6.1 Profil-Matrix (Soll)
|
||||
|
||||
| Profil | Apps | Account-Limits | Tenant-Limits | Capabilities | Governance (Objekt) |
|
||||
|--------|------|----------------|---------------|--------------|---------------------|
|
||||
| **P1 Personal** | Mitai | ✅ primär | ❌ | ✅ Account | minimal / privat |
|
||||
| **P2 Mandant** | Shinkan | ⚠️ Lifecycle only | ✅ primär | ✅ Account + Tenant-Rollen | ✅ Access Layer |
|
||||
| **P3 Minimal** | Miken, Ikigai (geplant) | optional | ❌ | optional | minimal |
|
||||
| **P4 Hybrid** | (Reserve) | ✅ | ✅ | ✅ beide | ✅ |
|
||||
|
||||
### 6.2 Registrierter Abweichungs-Katalog
|
||||
|
||||
| ID | App | Abweichung vom Familien-Standard | Begründung | Review |
|
||||
|----|-----|----------------------------------|------------|--------|
|
||||
| **DEV-01** | Mitai | Kein `tenant`-Block in Entitlements | Persönliche Tracking-App; kein Verein | Beibehalten (P1) |
|
||||
| **DEV-02** | Mitai | Kein Capability-Katalog (nur Features+Tier) | RBAC = admin/user ausreichend | Optional später `account.*` Capabilities |
|
||||
| **DEV-03** | Mitai | Mehrere Nutzer-APIs statt einem Snapshot | Historisch gewachsen | Facade → Snapshot (mittelfristig) |
|
||||
| **DEV-04** | Mitai | Legacy Session-Spalten (`ai_enabled`, …) parallel Features | Migrationsschuld | Bereinigen, nicht in neue Apps |
|
||||
| **DEV-05** | Shinkan | Kein Account-Tier / `profiles.tier` | Verein zahlt, nicht Trainer | Beibehalten (P2) |
|
||||
| **DEV-06** | Shinkan | Capabilities **und** Governance (zwei Achsen) | Trainer vs. Objekt-Rechte | Familien-Vorbild für P2/P4 |
|
||||
| **DEV-07** | Shinkan | `check_feature_access` (Mitai-Legacy) explizit verboten | Falsches Subjekt | Beibehalten |
|
||||
| **DEV-08** | Shinkan | Enforcement oft Probe-only | Rollout-Sicherheit | → Phase 4 bis Datum X |
|
||||
| **DEV-09** | Shinkan | Inventar-Features live gezählt | Drift-Vermeidung | Abweichung OK; in P2 dokumentieren |
|
||||
| **DEV-10** | Beide | Kein atomares Check+Increment | Race bei Parallel-Requests | Familien-Backlog; Workaround dokumentieren |
|
||||
| **DEV-11** | Neue Apps | dürfen **nur** Account **oder** nur Tenant wählen | MVP | Eintrag hier anlegen vor Launch |
|
||||
|
||||
**Neue Abweichung:** Zeile in §6.2 + ggf. ein Satz im App-`CLAUDE.md`.
|
||||
|
||||
### 6.3 Dokumentierte Ausnahmen (Bypass)
|
||||
|
||||
| Ausnahme | Apps | Regel |
|
||||
|----------|------|-------|
|
||||
| Plattform-Admin Audit | Shinkan | Quota-Bypass über Grants, nicht pauschal superadmin |
|
||||
| Admin ohne Auto-Bypass | Mitai | Admins unterliegen Limits (Produktentscheid) |
|
||||
| Öffentliche Routen ohne Auth | alle | Kein Entitlement-Check |
|
||||
|
||||
---
|
||||
|
||||
## 7. Mapping: Familien-Begriff ↔ Implementierung
|
||||
|
||||
### 7.1 Mitai (Profil P1)
|
||||
|
||||
| Familien | Mitai-Implementierung |
|
||||
|----------|----------------------|
|
||||
| Account-Features | `features`, `tier_limits`, `user_feature_usage` |
|
||||
| Account-Tier | `get_effective_tier()`, `access_grants` |
|
||||
| Check | `check_feature_access(profile_id, feature_id)` |
|
||||
| Increment | `increment_feature_usage(profile_id, …)` |
|
||||
| UI | `UsageBadge`, Widget `allowed` |
|
||||
|
||||
### 7.2 Shinkan (Profil P2)
|
||||
|
||||
| Familien | Shinkan-Implementierung |
|
||||
|----------|-------------------------|
|
||||
| Tenant-Features | `club_plan_limits`, `club_feature_usage`, `club_features.py` |
|
||||
| Tenant-Plan | `get_effective_club_plan(club_id)` |
|
||||
| Capabilities | `check_capability`, `capabilities` + `rights_registry` |
|
||||
| Snapshot | `build_me_entitlements()` → `GET /me/entitlements` |
|
||||
| Governance | `TenantContext`, `club_tenancy` — **kein** Ersatz für Capabilities |
|
||||
|
||||
### 7.3 Gemeinsame Muster (copy-ready)
|
||||
|
||||
| Muster | Mitai | Shinkan |
|
||||
|--------|-------|---------|
|
||||
| Feature-Registry in DB | ✅ | ✅ (`app='shinkan'`) |
|
||||
| Plan × Feature Matrix | `tier_limits` | `club_plan_limits` |
|
||||
| Admin-Override | `user_feature_restrictions` | `club_feature_overrides` |
|
||||
| Promo/Trial | `access_grants` | `club_access_grants` |
|
||||
| 4-Phasen-Rollout | ✅ | ✅ |
|
||||
| Registry-first neue IDs | ⚠️ teils hardcoded | ✅ `rights_registrations/` |
|
||||
|
||||
---
|
||||
|
||||
## 8. Entscheidungsregeln für neue Produkte
|
||||
|
||||
### 8.1 Pflicht (alle Apps mit Auth)
|
||||
|
||||
- [ ] Session → `profile_id`; kein Client-Header als Autorität
|
||||
- [ ] Entitlements-Auflösung **eine Funktion pro Ebene** (Capability, Feature)
|
||||
- [ ] API-Enforcement vor UI-Gate
|
||||
- [ ] 4-Phasen-Rollout dokumentiert
|
||||
- [ ] Produkt-Profil (P1–P4) gewählt + Abweichungen in §6.2
|
||||
|
||||
### 8.2 Wenn Personal App (P1)
|
||||
|
||||
- [ ] Primäres Subjekt = Account
|
||||
- [ ] `tenant`-Block in API = `null` (DEV-01-Analog)
|
||||
- [ ] Feature-Registry + Tier-Matrix
|
||||
|
||||
### 8.3 Wenn Mandanten-App (P2)
|
||||
|
||||
- [ ] Primäres Subjekt = Tenant
|
||||
- [ ] `TenantContext` + Governance getrennt von Capabilities
|
||||
- [ ] Capabilities registry-first
|
||||
- [ ] Account nur Lifecycle (verified, member) — kein Tier nötig (DEV-05-Analog erlaubt)
|
||||
|
||||
### 8.4 Wenn Minimal App (P3)
|
||||
|
||||
- [ ] Explizit: „keine Limits“ oder nur Boolean-Features — in §6.2 eintragen
|
||||
- [ ] Kein halbes Mitai-v9c kopieren
|
||||
|
||||
---
|
||||
|
||||
## 9. Konvergenz-Roadmap (optional, nicht blockierend)
|
||||
|
||||
| Schritt | Mitai | Shinkan | Familie |
|
||||
|---------|-------|---------|---------|
|
||||
| **Kurz** | Legacy Session-Flags entfernen | `CAPABILITY_ENFORCE` / `CLUB_FEATURE_ENFORCE` Prod | DEV-04, DEV-08 schließen |
|
||||
| **Mittel** | `/me/entitlements` Account-Block | Snapshot um `tenant`-Typ metadata erweitern | Facade alte APIs |
|
||||
| **Lang** | Optional `tenant_id` reservieren (null) | Optional Account-Tier für Cross-Sell | Shared package `jinkendo_entitlements` |
|
||||
| **Vision** | SSO + zentraler Billing | Vereins-Abo Stripe | `CENTRAL_SUBSCRIPTION_SYSTEM` |
|
||||
|
||||
**Wichtig:** Konvergenz ist **empfohlen**, nicht Pflicht — solange §6.2 aktuell bleibt.
|
||||
|
||||
---
|
||||
|
||||
## 10. Anti-Patterns (familienweit verboten)
|
||||
|
||||
1. Tier- oder Plan-Namen in React-Komponenten hardcoden
|
||||
2. Limit-Logik nur im Frontend
|
||||
3. Shinkan-Vereinslimits über Mitai `check_feature_access(profile_id)`
|
||||
4. Capability-Check durch Governance ersetzen (oder umgekehrt)
|
||||
5. Neue Feature-IDs nur in SQL-Migration ohne Registry
|
||||
6. Enforcement Phase 4 „vergessen“ bei paid Features ohne dokumentierte Probe-Phase
|
||||
7. Undokumentierte Produkt-Abweichung (nicht in §6.2)
|
||||
|
||||
---
|
||||
|
||||
## 11. Offene Familien-Entscheidungen (Backlog)
|
||||
|
||||
| ID | Frage | Optionen | Default wenn unentschieden |
|
||||
|----|-------|----------|----------------------------|
|
||||
| **FD-01** | Atomares check+increment | DB-Lock / Transaction / Queue | Status quo + Retry-Hinweis in Doku |
|
||||
| **FD-02** | Shared Python-Modul | Monorepo-Paket vs. Copy+Sync | Copy+Sync mit gleicher API-Shape |
|
||||
| **FD-03** | Capability-Namespace global | `jinkendo.*` vs. app-prefix | `{app}.{domain}.{action}` |
|
||||
| **FD-04** | Mitai bekommt Capability-Layer? | ja/nein/später | nein (DEV-02) bis Bedarf |
|
||||
| **FD-05** | Ein `features.app` für alle Apps | gemeinsame DB vs. pro Deploy | pro Deploy (heute) |
|
||||
|
||||
---
|
||||
|
||||
## 12. Verwandte Dokumente
|
||||
|
||||
| Dokument | Inhalt |
|
||||
|----------|--------|
|
||||
| [DESIGN_PRINCIPLES_ALIGNMENT.md](./DESIGN_PRINCIPLES_ALIGNMENT.md) | Vollständiger Mitai ↔ Shinkan Abgleich |
|
||||
| [design-principles/CAPABILITY_ENTITLEMENT_DESIGN_PRINCIPLES.md](./design-principles/CAPABILITY_ENTITLEMENT_DESIGN_PRINCIPLES.md) | Shinkan Ist-Prinzipien |
|
||||
| [ACCESS_LAYER_DESIGN_PRINCIPLES.md](./design-principles/ACCESS_LAYER_DESIGN_PRINCIPLES.md) | Governance (Ebene D) |
|
||||
| Mitai Foundation #3 | Feature & Entitlement Ist Mitai |
|
||||
| Shinkan `CLUB_MEMBERSHIP_AND_FEATURES.v1.md` | Vereins-Abo Detail |
|
||||
| Shinkan `CAPABILITY_CATALOG.v1.md` | Capability-IDs |
|
||||
|
||||
---
|
||||
|
||||
## 13. Changelog
|
||||
|
||||
| Datum | Änderung |
|
||||
|-------|----------|
|
||||
| 2026-07-04 | Entwurf: Familien-Standard, Produkt-Profile P1–P4, Abweichungs-Katalog DEV-01–11 |
|
||||
Reference in new issue
Block a user