Lars
c3be745efa
- Added details for Issue #53 regarding the audit of activity placeholders between Layer 1 and Layer 2a in `CLAUDE.md` and `README.md`. - Updated the `ACTIVITY_SESSION_METRICS_EAV_AGENT_GUIDE.md` to reflect the new registry checks and dynamic session metrics handling. - Revised the `placeholder_resolver.py` and `activity_metrics.py` to clarify the registration of activity metrics and session insights, ensuring consistency in the handling of dynamic keys and metrics. - Improved descriptions and semantic contracts in `activity_session_insights.py` to better outline the structure and limitations of session data.
187 lines
9.0 KiB
Markdown
187 lines
9.0 KiB
Markdown
# Mitai Jinkendo – Dokumentations-Index
|
||
|
||
Willkommen zur Entwicklerdokumentation von **Mitai Jinkendo** (身体 Jinkendo).
|
||
|
||
**Parallel im Repository:** Issue-Epics und Placeholder-Governance im Projekt-[`docs/`](../../docs/) · siehe [`docs/README.md`](../../docs/README.md).
|
||
|
||
**Ablage-Regeln:** [`.claude/rules/DOCUMENTATION.md`](../rules/DOCUMENTATION.md) · **Issue-Landkarte:** [`GITEA_ISSUES_INDEX.md`](./GITEA_ISSUES_INDEX.md).
|
||
|
||
_Dieser Ordner `.claude/docs/` ist per `.gitignore`-Ausnahme **versioniert** (Specs + Regeln)._
|
||
|
||
---
|
||
|
||
## Dokumentationsstruktur (Ist-Stand)
|
||
|
||
```
|
||
.claude/docs/
|
||
├── README.md ← Index (diese Datei)
|
||
├── GITEA_ISSUES_INDEX.md ← Themen-Landkarte zu Gitea (lokal gepflegt)
|
||
├── BACKLOG.md ← Feature-Katalog nach Versionen
|
||
├── ROADMAP.md ← Strategische Phasen (0–3)
|
||
├── CLEANUP_PLAN.md ← Historie Bereinigung März 2026
|
||
├── prompts/ ← Exportierte Prompt-Artefakte (JSON)
|
||
├── functional/ ← Fachliche Spezifikationen (WAS)
|
||
├── technical/ ← Technische Spezifikationen & Referenz (WIE)
|
||
├── working/ ← Arbeitspapiere, Analysen, Session-Snapshots
|
||
├── architecture/ ← Querschnitt: Backend/Frontend/Enforcement (kompakt)
|
||
└── audit/ ← Audits, Matrizen, Gitea-Vorlagen
|
||
```
|
||
|
||
**Externes Tracking:** [Gitea Issues](http://192.168.2.144:3000/Lars/mitai-jinkendo/issues)
|
||
|
||
**Erzeugte Library (Kurzreferenz, ggf. `/document`):** `.claude/library/` – API-, DB- und Architektur-Übersichten; bei Abweichungen gewinnt der **Code**, dann **`technical/`** bzw. **`functional/`**.
|
||
|
||
---
|
||
|
||
## Rollen der Ordner
|
||
|
||
| Ordner | Zweck | Pflege |
|
||
|--------|--------|--------|
|
||
| `functional/` | Domäne, UX, fachliche Datenflüsse | Bei Feature-Änderungen / Abnahme |
|
||
| `technical/` | APIs, Migrationen, Implementierungsmuster, Agent-Guides | Nach größeren Code-Änderungen |
|
||
| `architecture/` | Kompakte Architektur-Snippets (z. B. Frontend-Struktur, Backend-Überblick) | Bei strukturellen Umbauten |
|
||
| `audit/` | Snapshots (Code-Audit, Platzhalter-Reconciliation) – **nicht** normative Spec | Nur bei neuen Audits erweitern |
|
||
| `working/` | Zwischenstände (Migration, Goals-Analysen, STATUS, NEXT_STEPS, PHASE_0C_TASKS, …) | Archivarisch; keine alleinige Norm |
|
||
| Root (`ROADMAP`, `BACKLOG`, `GITEA_ISSUES_INDEX`) | Planung, Katalog, Issue-Landkarte | Mit Gitea / `working/` abstimmen |
|
||
|
||
---
|
||
|
||
## Abgleich „Dokument ↔ Code“ (Orientierung)
|
||
|
||
| Thema | Dokument(e) | Prüfpunkt im Repo |
|
||
|--------|-------------|-------------------|
|
||
| Data Layer / Charts (Phase 0c) | `functional/DATA_ARCHITECTURE.md`, `technical/DATA_LAYER_EXTENSION_GUIDE.md` | `backend/data_layer/`, `backend/routers/charts.py` |
|
||
| Platzhalter / Registry | `technical/PLACEHOLDER_REGISTRY_FRAMEWORK.md`, `technical/PLACEHOLDER_DEVELOPMENT_GUIDE.md` | `backend/placeholder_registrations/`, `backend/placeholder_resolver.py` |
|
||
| Dashboard-Lab-Widgets | `technical/DASHBOARD_WIDGETS_AGENT_GUIDE.md` | Widget-Katalog + Registrierung (siehe Guide) |
|
||
| Training Profiler / Resolver | `technical/TRAINING_PROFILE_RESOLVER_LAYER1.md`, `functional/TRAINING_TYPE_PROFILES.md` | Resolver-Module wie im Guide genannt |
|
||
| Universal CSV Import | `technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md` | `backend/csv_parser/`, `routers/csv_import.py`, `routers/admin_csv_templates.py` |
|
||
| Aktivität Produktionsreife | `technical/ACTIVITY_PRODUCTION_ARCHITECTURE_AND_PHASES.md` (+ EAV-Guide) | `backend/data_layer/activity_session_metrics.py`, `activity_metrics.py`, CSV-Orchestrierung |
|
||
| Mitgliedschaft / Features | `technical/MEMBERSHIP_SYSTEM.md`, `architecture/FEATURE_ENFORCEMENT.md` | `backend/auth.py`, Feature-Logging, Router mit Enforcement |
|
||
|
||
---
|
||
|
||
## Projekt-Übersicht & Regeln (außerhalb dieses Ordners)
|
||
|
||
| Dokument | Inhalt |
|
||
|----------|--------|
|
||
| `CLAUDE.md` (Root) | Agent-Kontext, Tech-Stack, kritische Regeln |
|
||
| `.claude/rules/ARCHITECTURE.md` | Verbindliche Architektur-Regeln |
|
||
| `.claude/rules/CODING_RULES.md` | Code-Standards |
|
||
| `.claude/rules/LESSONS_LEARNED.md` | Wiederkehrende Fehler vermeiden |
|
||
|
||
---
|
||
|
||
## Fachliche Spezifikationen (`functional/`)
|
||
|
||
| Dokument | Thema | Hinweis |
|
||
|----------|--------|---------|
|
||
| `ACTIVITY_QUALITY_GATES.md` | Qualitäts-Gates Aktivität | |
|
||
| `AI_PROMPTS.md` | KI-Prompts, Pipeline, Platzhalter (fachlich) | |
|
||
| `DATA_ARCHITECTURE.md` | **Fachliche** Datenarchitektur, Domänenflüsse | Schema-Details → `.claude/library/DATABASE.md` |
|
||
| `DEVELOPMENT_ROUTES.md` | Entwicklungsrouten (Roadmap-Thema) | |
|
||
| `GOALS_VITALS.md` | Ziele & Vitalwerte (fachlich) | |
|
||
| `mitai_jinkendo_konzept_diagramme_auswertungen.md` | Konzept Diagramme (ältere Linie) | |
|
||
| `mitai_jinkendo_konzept_diagramme_auswertungen_v2.md` | Konzept Diagramme v2 | |
|
||
| `PHASE_0B_IMPROVEMENTS.md` | Phase-0b-Verbesserungen | |
|
||
| `RESPONSIVE_UI.md` | Responsive Layout-Spec | siehe auch `docs/issues/PHASE_PLAN_RESPONSIVE_UI.md` |
|
||
| `SLEEP_MODULE.md` | Schlaf-Modul | |
|
||
| `TRAINING_TYPES.md` | Trainingstypen, Mapping | |
|
||
| `TRAINING_TYPE_PROFILES.md` | Trainings-Profile (fachlich) | Techn. Ergänzung: `technical/TRAINING_TYPE_PROFILES_TECHNICAL.md` |
|
||
|
||
---
|
||
|
||
## Technische Spezifikationen (`technical/`)
|
||
|
||
| Dokument | Thema |
|
||
|----------|--------|
|
||
| `AGGREGATION_METHODS.md` | Aggregation |
|
||
| `API_REFERENCE.md` | HTTP-API-Katalog |
|
||
| `ARCHITECTURE.md` | System-Architektur |
|
||
| `AUTH.md` | Authentifizierung |
|
||
| `CENTRAL_SUBSCRIPTION_SYSTEM.md` | Abo-Zentralismus |
|
||
| `DASHBOARD_WIDGETS_AGENT_GUIDE.md` | Dashboard-Widgets für Agents |
|
||
| `DATABASE.md` | DB-Referenz (docs-Kopie; Library kann aktueller sein) |
|
||
| `DATABASE_MODEL_COMPLETE.md` | Vollständiges Modell (Referenz) |
|
||
| `DATA_LAYER_EXTENSION_GUIDE.md` | Erweiterung Data Layer |
|
||
| `FEATURE_ENFORCEMENT_MAPPING.md` | Feature-IDs / Mapping |
|
||
| `FRONTEND.md` | Frontend ausführlich (Seiten, Patterns) |
|
||
| `INTERNAL_API_REFERENCE.md` | Interne APIs |
|
||
| `MEMBERSHIP_SYSTEM.md` | Tiers, Grants, Enforcement-Details |
|
||
| `MIGRATIONS.md` | Migrations-Prozess |
|
||
| `PLACEHOLDER_DEVELOPMENT_GUIDE.md` | Platzhalter entwickeln |
|
||
| `PLACEHOLDER_REGISTRY_FRAMEWORK.md` | Registry-Pflicht, Metadaten |
|
||
| `PROFILE_REFERENCE_VALUES.md` | Profil-Referenzwerte |
|
||
| `TRAINING_PROFILE_RESOLVER_LAYER1.md` | Training-Resolver Schicht 1 |
|
||
| `TRAINING_TYPE_PROFILES_TECHNICAL.md` | Trainingsprofile technisch |
|
||
| `UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md` | Universal CSV: Registry, Executor, Vorlagen, Agent-Checkliste |
|
||
| `ACTIVITY_SESSION_METRICS_EAV_AGENT_GUIDE.md` | Session-Metriken EAV, Attributprofile, Layer-1, Prod-Migration |
|
||
| `ACTIVITY_COMPOSITE_METRICS_IMPLEMENTATION_CONCEPT.md` | Composite-Metriken in EAV (JSONB), Archetypen, CSV-Slots, Layer-1-Expand, Migration/Test-Checkliste |
|
||
| `ACTIVITY_PRODUCTION_ARCHITECTURE_AND_PHASES.md` | **Zielarchitektur** Aktivität (Spine/EAV/Composites/Import/Layer 1–2) + **Phasenplan A–F** Produktionsreife |
|
||
| `ACTIVITY_LAYER2A_PLACEHOLDER_AUDIT.md` | Issue #53: Aktivitäts-Platzhalter Layer 1 ↔ 2a (Audit Schritt 1) |
|
||
| `ACTIVITY_SCALAR_KANON_TABLE.md` | **Skalar-Kanon** Aktivität (eine Semantik → eine Quelle); Phase A |
|
||
| *(Code)* `backend/data_layer/activity_data_canon.py` | **Kanon** activity CSV-Modul vs. EAV-primär; Legacy-Lesefallback |
|
||
| `V9D_PHASE2_VITALS_SLEEP.md` | v9d Vitalwerte/Schlaf (Release-Bezug) |
|
||
|
||
---
|
||
|
||
## Architektur-Kurzdoks (`architecture/`)
|
||
|
||
| Dokument | Inhalt |
|
||
|----------|--------|
|
||
| `BACKEND.md` | Backend-Querschnitt |
|
||
| `FEATURE_ENFORCEMENT.md` | 4-Phasen Enforcement |
|
||
| `FRONTEND.md` | Strukturbaum `frontend/src` (kompakt) |
|
||
|
||
*Hinweis:* `architecture/FRONTEND.md` ist die **kurze** Strukturübersicht; Details und Seitenliste stehen in `technical/FRONTEND.md`.
|
||
|
||
---
|
||
|
||
## Audit (`audit/`)
|
||
|
||
Siehe [`audit/README.md`](./audit/README.md).
|
||
|
||
---
|
||
|
||
## Gitea vs. Docs
|
||
|
||
**Prinzip:** Gitea für **Tracking**, Docs für **Spezifikationen** und **Referenz**.
|
||
|
||
### Gehört in Gitea Issues
|
||
- Konkrete Tasks (typisch ≤ wenige Tage), Bugs, Quick Wins, Technical Debt
|
||
|
||
### Gehört in `functional/`
|
||
- Größere Feature-Pakete, Domänenanforderungen, Use Cases, Konzeptdiagramme
|
||
|
||
### Gehört in `technical/`
|
||
- API-, DB- und Implementierungsreferenz, Agent-Leitfäden, Migrations-Details
|
||
|
||
### Gehört in `ROADMAP.md` / `BACKLOG.md`
|
||
- Strategische Phasen bzw. Versions-Katalog mit Links auf Specs und Issues
|
||
|
||
### Nicht dauerhaft in Docs
|
||
- Temporäre To-do-Listen ohne Kontext (→ Issue); reine Duplikate anderer Dateien
|
||
|
||
---
|
||
|
||
## Workflow nach Feature-Abschluss
|
||
|
||
1. Gitea Issue schließen (Commit-Referenz).
|
||
2. `BACKLOG.md` / `ROADMAP.md` bei Meilensteinen anpassen.
|
||
3. Betroffene `functional/` / `technical/` / `.claude/library/`-Dateien aktualisieren.
|
||
4. Bei sichtbaren Agent-Regeln: `CLAUDE.md` ergänzen.
|
||
|
||
---
|
||
|
||
## Deployment (Kurzreferenz)
|
||
|
||
| Umgebung | Frontend | Backend |
|
||
|----------|----------|---------|
|
||
| Production | Port 3002 | Port 8002 |
|
||
| Development | Port 3099 | Port 8099 |
|
||
|
||
**Gitea:** http://192.168.2.144:3000/Lars/mitai-jinkendo
|
||
|
||
---
|
||
|
||
**Letzte Aktualisierung:** 9. April 2026 (Universal CSV Agent-Guide, Abgleich-Tabelle)
|