Lars
532e17c4cd
- Introduced a new section for the Jinkendo Foundation, detailing design principles for the product family. - Updated README files to include references to the new design principles documentation. - Enhanced the overall documentation structure to improve navigation and accessibility of design resources. - Ensured consistency across documentation related to the Jinkendo Foundation and its principles.
137 lines
7.3 KiB
Markdown
137 lines
7.3 KiB
Markdown
# Designprinzipien – Index (Jinkendo Foundation)
|
||
|
||
**Teil von:** [Jinkendo Foundation](../README.md)
|
||
|
||
**Status:** Arbeitspapier / Übergabe
|
||
**Stand:** 2026-07-04
|
||
**Zweck:** Zentraler Einstieg für die aus Mitai extrahierte Serie **tragfähiger Designprinzipien** — für neue Apps der Jinkendo-Produktfamilie oder vergleichbare Self-Hosted-PWAs.
|
||
|
||
**Nicht enthalten:** Mitai-Gesamtarchitektur, Domänenlogik (Gesundheit/Ernährung), Kairo-/Framework-Empfehlungen.
|
||
|
||
**Ablage:** `.claude/docs/jinkendo-foundation/design-principles/` · Regeln: [DOCUMENTATION.md](../../../rules/DOCUMENTATION.md)
|
||
|
||
---
|
||
|
||
## Wofür diese Serie?
|
||
|
||
Mitai Jinkendo implementiert wiederkehrende **Querschnittsmuster** (Prompt-Ausführung, Data Layer, Entitlements, Registries, Auth, Import, Dashboard, Navigation, Deploy). Die neun 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, Agent-Guides)
|
||
|
||
Jedes Dokument ist **eigenständig lesbar**; dieser Index ordnet Abhängigkeiten und Lese-Reihenfolge.
|
||
|
||
---
|
||
|
||
## Dokumente (9/9)
|
||
|
||
| # | Modul | Datei | Kernidee (1 Satz) |
|
||
|---|-------|-------|-------------------|
|
||
| 1 | Prompt Engine | [PROMPT_ENGINE_DESIGN_PRINCIPLES.md](./PROMPT_ENGINE_DESIGN_PRINCIPLES.md) | Ein Executor, Pipeline/Workflow-Typen, Platzhalter über Registry — keine Raw-Template-Ausführung. |
|
||
| 2 | Data Layer | [DATA_LAYER_DESIGN_PRINCIPLES.md](./DATA_LAYER_DESIGN_PRINCIPLES.md) | Layer 0→1→2: Single Source of Truth für Berechnungen; Charts und KI nutzen dieselbe Schicht. |
|
||
| 3 | Feature & Entitlement | [FEATURE_ENTITLEMENT_DESIGN_PRINCIPLES.md](./FEATURE_ENTITLEMENT_DESIGN_PRINCIPLES.md) | Zentrale `check_feature_access`, DB-Registry, 4-Phasen-Rollout — Enforcement an der API. |
|
||
| 4 | Registry / Plugin (Meta) | [REGISTRY_PLUGIN_DESIGN_PRINCIPLES.md](./REGISTRY_PLUGIN_DESIGN_PRINCIPLES.md) | Drei Registry-Muster (Platzhalter, Widgets, CSV): SSoT, Validierung an der Grenze, Runtime-Registrierung. |
|
||
| 5 | Auth & Session | [AUTH_SESSION_DESIGN_PRINCIPLES.md](./AUTH_SESSION_DESIGN_PRINCIPLES.md) | Server-Sessions, `require_auth` als Depends — bekannte Schwäche: Profile-Header ohne Session-Bindung. |
|
||
| 6 | Universal Import | [UNIVERSAL_IMPORT_DESIGN_PRINCIPLES.md](./UNIVERSAL_IMPORT_DESIGN_PRINCIPLES.md) | Modul-Registry + Executor + Vorlagen; Ingest ≠ Interpretation; SAVEPOINT pro Zeile. |
|
||
| 7 | Dashboard Widgets | [DASHBOARD_WIDGETS_DESIGN_PRINCIPLES.md](./DASHBOARD_WIDGETS_DESIGN_PRINCIPLES.md) | Backend-Katalog, Profil-Layout, Config-Whitelist, Entitlements — Dual Registry mit Frontend. |
|
||
| 8 | Navigation / IA | [NAVIGATION_IA_DESIGN_PRINCIPLES.md](./NAVIGATION_IA_DESIGN_PRINCIPLES.md) | `appNav` als SSoT, Shells für tiefe Bereiche, Admin-Hub, ein Breakpoint 1024px. |
|
||
| 9 | Migration & Deploy | [MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md](./MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md) | `XXX_*.sql` beim Container-Start; develop/main → Dev/Prod; fail-fast, kein Auto-Rollback. |
|
||
|
||
---
|
||
|
||
## Empfohlene Lesereihenfolge
|
||
|
||
### Schnellüberblick (30 Min)
|
||
|
||
1. [REGISTRY_PLUGIN_DESIGN_PRINCIPLES.md](./REGISTRY_PLUGIN_DESIGN_PRINCIPLES.md) — Meta-Muster für viele Module
|
||
2. [DATA_LAYER_DESIGN_PRINCIPLES.md](./DATA_LAYER_DESIGN_PRINCIPLES.md) — Daten vs. Darstellung
|
||
3. [MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md](./MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md) — Betrieb & Schema-Evolution
|
||
|
||
### Vollständige Implementierung (neues Produkt)
|
||
|
||
```
|
||
Foundation: (9) Migration & Deploy → (5) Auth → (3) Feature & Entitlement
|
||
Daten: (2) Data Layer → (6) Universal Import
|
||
Erweiterung: (4) Registry Meta → (1) Prompt Engine → (7) Dashboard Widgets
|
||
Oberfläche: (8) Navigation / IA
|
||
```
|
||
|
||
### Nur ein Modul nachbauen
|
||
|
||
| Ziel | Lese zuerst | Dann |
|
||
|------|-------------|------|
|
||
| KI-Analysen | #1 Prompt Engine | #2 Data Layer, #4 Registry |
|
||
| Charts & KPIs | #2 Data Layer | #7 Dashboard Widgets |
|
||
| Freemium / Limits | #3 Feature & Entitlement | #7 Widgets (Gating) |
|
||
| CSV-Import | #6 Universal Import | #2 Data Layer, #4 Registry |
|
||
| Admin-PWA | #8 Navigation / IA | #3, #5 |
|
||
|
||
---
|
||
|
||
## Querschnittsthemen (über alle Docs)
|
||
|
||
| Thema | Primär | Ergänzend |
|
||
|-------|--------|-----------|
|
||
| Single Source of Truth | #2 Data Layer | #4 Registry, #7 Widget-Katalog, #6 Modul-Registry |
|
||
| Validierung an der Grenze | #4 Registry | #7 Layout-Pydantic, #6 Template-Validator |
|
||
| Feature-Gating | #3 Entitlement | #7 Widget `allowed`, #6 Import-Limits |
|
||
| Dual Registry (Backend + Frontend) | #4 Registry | #7 `registerDashboardWidgets`, Platzhalter-UI |
|
||
| Idempotenz / Recovery | #9 Migration | #6 SAVEPOINT, Migration `IF NOT EXISTS` |
|
||
| Bekannte Lücken dokumentieren | alle „Nicht übernehmen“ | z. B. IDOR Profile-Header (#5), fehlender Cross-Check Widget-IDs (#7) |
|
||
|
||
---
|
||
|
||
## Verwandte normative Docs (Mitai-spezifisch)
|
||
|
||
Diese Agent-Guides sind **Implementierungsdetail**; die Designprinzipien-Serie ist **extrahiertes Muster**:
|
||
|
||
| Thema | Agent-Guide / Spec |
|
||
|-------|-------------------|
|
||
| Platzhalter | [PLACEHOLDER_REGISTRY_FRAMEWORK.md](../../technical/PLACEHOLDER_REGISTRY_FRAMEWORK.md) |
|
||
| Data Layer erweitern | [DATA_LAYER_EXTENSION_GUIDE.md](../../technical/DATA_LAYER_EXTENSION_GUIDE.md) |
|
||
| CSV Import | [UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md](../../technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md) |
|
||
| Dashboard Widgets | [DASHBOARD_WIDGETS_AGENT_GUIDE.md](../../technical/DASHBOARD_WIDGETS_AGENT_GUIDE.md) |
|
||
| GUI / Admin / Nav | [GUI_IA_ADMIN_NAV_2026-04-05.md](../../../../docs/issues/GUI_IA_ADMIN_NAV_2026-04-05.md) |
|
||
| Migrationen (operativ) | [MIGRATIONS.md](../../technical/MIGRATIONS.md) |
|
||
| Membership | [MEMBERSHIP_SYSTEM.md](../../technical/MEMBERSHIP_SYSTEM.md), [FEATURE_ENFORCEMENT.md](../../architecture/FEATURE_ENFORCEMENT.md) |
|
||
| Architektur-Regeln | [ARCHITECTURE.md](../../../rules/ARCHITECTURE.md) |
|
||
|
||
---
|
||
|
||
## Übergabe-Checkliste (neues Produkt in der Familie)
|
||
|
||
Nutze diese Liste beim Start eines Schwester-Projekts — **Prinzipien ja, Mitai-Pfade nein**:
|
||
|
||
```
|
||
[ ] Deploy: nummerierte SQL-Migrationen + Tracking-Tabelle + Startup vor App
|
||
[ ] Auth: Session server-side; Depends(require_auth); Admin-Route-Guard
|
||
[ ] Entitlements: eine check_feature_access-Funktion; keine Tier-Logik in UI-Widgets
|
||
[ ] Data Layer: Berechnungen nicht in Router/React duplizieren
|
||
[ ] Registry: neue erweiterbare IDs nur über zentralen Katalog + Validierung
|
||
[ ] Import (falls CSV): Modul-Registry + Vorlagen + Import-Grenze (keine Scores beim Insert)
|
||
[ ] Dashboard (falls konfigurierbar): Backend-Katalog + Layout-JSON + allowed-Flag
|
||
[ ] Navigation: eine appNav-SSoT; Shells für >6 Top-Level-Bereiche
|
||
[ ] Prompt/KI (falls): ein Executor; Platzhalter-Registry; kein Raw-Template an LLM
|
||
[ ] Dokumentieren: pro Modul „Nicht übernehmen“ aus Mitai-Lücken mitnehmen
|
||
```
|
||
|
||
---
|
||
|
||
## Pflege
|
||
|
||
| Aktion | Wo |
|
||
|--------|-----|
|
||
| Neues Querschnittsmodul extrahiert | Neues `*_DESIGN_PRINCIPLES.md` + Zeile in Tabelle oben |
|
||
| Mitai-Implementierung ändert Muster | Betroffenes Einzeldokument + ggf. Querschnittstabelle hier |
|
||
| Nur Mitai-Bugfix ohne Muster-Änderung | Agent-Guides / Code; Designprinzipien optional |
|
||
|
||
---
|
||
|
||
## Changelog Index
|
||
|
||
| Datum | Änderung |
|
||
|-------|----------|
|
||
| 2026-07-04 | Index angelegt; Serie 1–9 abgeschlossen |
|
||
| 2026-07-04 | Nach `jinkendo-foundation/design-principles/` verschoben |
|