Lars/shinkan-jinkendo
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 3 Wiki Activity
c4fbabd8f6
shinkan-jinkendo/docs/HANDOVER.md

110 lines
7.3 KiB
Markdown
Raw Normal View History

feat: update version to 0.7.6 and add matrix stack bundle functionality - Incremented application version to 0.7.6 and updated maturity models version to 1.4.0. - Introduced new API endpoints for exporting and importing matrix stack bundles, enhancing the capabilities for managing maturity models and context bindings. - Updated frontend components to support the new matrix stack export and import features, including UI elements for stack management. - Documented changes in the changelog for version 0.7.6, detailing the new matrix stack functionality and its usage.
2026-04-27 13:13:36 +02:00
# Shinkan Jinkendo – Entwicklungsstand & Handover
chore: update versioning and enhance training framework features - Incremented APP_VERSION to 0.8.10 and DB_SCHEMA_VERSION to 20260505037. - Updated project status and domain model documentation to reflect recent changes. - Enhanced training framework program handling with new slot-blueprint structure. - Introduced API endpoint for creating training units from framework slots. - Improved documentation for training planning and governance concepts.
2026-05-05 13:39:30 +02:00
**Stand:** 2026-05-05
feat: enhance database migration handling and health check endpoint - Updated migration logic in main.py to allow skipping migrations during local development with SKIP_DB_MIGRATE environment variable. - Improved error handling for migration failures, ensuring the application does not start if migrations are incomplete. - Added a new health check endpoint (/api/health/ready) to verify database connection and essential tables, aiding in production debugging. - Enhanced run_migrations.py to support ordered execution of migration files and improved transaction handling. - Updated requirements.txt to include sqlparse for SQL statement parsing when psql is unavailable.
2026-04-29 12:29:39 +02:00
**App-Version / DB-Schema:** siehe `backend/version.py`
feat: update version to 0.7.6 and add matrix stack bundle functionality - Incremented application version to 0.7.6 and updated maturity models version to 1.4.0. - Introduced new API endpoints for exporting and importing matrix stack bundles, enhancing the capabilities for managing maturity models and context bindings. - Updated frontend components to support the new matrix stack export and import features, including UI elements for stack management. - Documented changes in the changelog for version 0.7.6, detailing the new matrix stack functionality and its usage.
2026-04-27 13:13:36 +02:00
Diese Datei ist die **Einstiegs-Doku für neue Chat-Sessions**: Anforderungen im Detail stehen in `.claude/docs/` (siehe unten); hier der **implementierte Stand** und **nächste Baustellen**.
feat: enhance database migration handling and health check endpoint - Updated migration logic in main.py to allow skipping migrations during local development with SKIP_DB_MIGRATE environment variable. - Improved error handling for migration failures, ensuring the application does not start if migrations are incomplete. - Added a new health check endpoint (/api/health/ready) to verify database connection and essential tables, aiding in production debugging. - Enhanced run_migrations.py to support ordered execution of migration files and improved transaction handling. - Updated requirements.txt to include sqlparse for SQL statement parsing when psql is unavailable.
2026-04-29 12:29:39 +02:00
### Produktion: `relation … does not exist` (z. B. `skill_main_categories`)
Das Schema ist gegenüber dem Code zurück: Migration **`022_skills_schema_complete`** (und ggf. Folgende) wurden auf dieser Datenbank noch nicht erfolgreich ausgeführt.
- **Automatisch:** Die Dateien `migrations/*.sql` (numerisch sortiert) bilden eine **Warteschlange**. Bereits erfolgreiche Läufe stehen in `schema_migrations` — diese Dateien werden **übersprungen** (idempotent). Pro Datei läuft **eine Transaktion** (im Container vorzugsweise `psql -1 -f`, sonst Fallback `sqlparse` + psycopg2).
- **Fix / manuell:** `docker exec shinkan-api python /app/run_migrations.py` — Exit-Code **0**.
- Aktuelle Builds: Bei fehlgeschlagenem Migrate startet **`main.py`** die API nicht. Lokal ohne DB: **`SKIP_DB_MIGRATE=1`**.
feat: update version to 0.7.6 and add matrix stack bundle functionality - Incremented application version to 0.7.6 and updated maturity models version to 1.4.0. - Introduced new API endpoints for exporting and importing matrix stack bundles, enhancing the capabilities for managing maturity models and context bindings. - Updated frontend components to support the new matrix stack export and import features, including UI elements for stack management. - Documented changes in the changelog for version 0.7.6, detailing the new matrix stack functionality and its usage.
2026-04-27 13:13:36 +02:00
---
## 1. Pflichtlektüre (Kontext & Anforderungen)
| Thema | Pfad |
|--------|------|
| Projekt-Setup, Domain grob | `.claude/docs/working/SHINKAN_PROJECT_SETUP.md` |
| Projekt-Status (Skills, Wiki, Stats) | `.claude/docs/PROJECT_STATUS.md` |
| Übungen: API, DB, Architektur, Routing | `.claude/docs/technical/EXERCISES_API_SPEC.md`, `EXERCISES_DATABASE_FINAL.md`, `EXERCISES_ARCHITECTURE.md`, `EXERCISES_FRONTEND_ROUTING.md` |
| Media / Upload | `.claude/docs/technical/MEDIA_UPLOAD_SPEC.md` |
| MediaWiki-Import | `.claude/docs/technical/MEDIAWIKI_IMPORT_SPEC.md` |
chore: update versioning and enhance training framework features - Incremented APP_VERSION to 0.8.10 and DB_SCHEMA_VERSION to 20260505037. - Updated project status and domain model documentation to reflect recent changes. - Enhanced training framework program handling with new slot-blueprint structure. - Introduced API endpoint for creating training units from framework slots. - Improved documentation for training planning and governance concepts.
2026-05-05 13:39:30 +02:00
| Rahmenprogramm · Planung (`training_units` Blueprints), Progressionsgraph | `.claude/docs/technical/TRAINING_FRAMEWORK_SPEC.md`; Überblick DB → `.claude/docs/technical/DATABASE_SCHEMA.md`; Domäne → `.claude/docs/functional/DOMAIN_MODEL.md` |
feat: update version to 0.7.6 and add matrix stack bundle functionality - Incremented application version to 0.7.6 and updated maturity models version to 1.4.0. - Introduced new API endpoints for exporting and importing matrix stack bundles, enhancing the capabilities for managing maturity models and context bindings. - Updated frontend components to support the new matrix stack export and import features, including UI elements for stack management. - Documented changes in the changelog for version 0.7.6, detailing the new matrix stack functionality and its usage.
2026-04-27 13:13:36 +02:00
---
## 2. Implementierter Stand: Fähigkeiten & Reifegradmodelle
### 2.1 Datenbank
- **`maturity_models`**, **`model_levels`**, **`model_skills`**, **`model_skill_levels`**: Matrix-Inhalt pro Modell.
- **Kontext am Modell (Legacy, M:N):** `maturity_model_focus_areas`, `maturity_model_style_directions`, `maturity_model_target_groups` (Migration 025).
- **Hierarchische Kontext-Zuordnung (Resolve):** `maturity_model_context_bindings` mit optional `style_direction_id`, `training_type_id` (Migration 026, 027).
- **027:** u. a. `Fokus + Trainingsstil` ohne Stilrichtung (partielle Unique-Indizes).
### 2.2 Resolve-Logik (Backend)
- **`GET /api/maturity-models/resolve`**: Bindings zum Fokus, die zur Anfrage passen; Merge nach Spezifität (weniger spezifisch zuerst); spezifischere Zeilen überschreiben Zelltexte.
- **Matching:** Gesetzte Spalten einer Binding-Zeile müssen mit der Anfrage übereinstimmen; `NULL` in der Zeile = Wildcard (z. B. Fokus+Trainingsstil gilt für alle Stilrichtungen, aber nur für diesen Trainingsstil).
- **Legacy-Fallback:** Nur wenn für den **Fokus keine einzige** Zeile in `maturity_model_context_bindings` existiert. Sonst bei fehlendem Treffer **`null`** (kein stilles Legacy mit falschem Trainingsstil).
### 2.3 Export / Import (einzelnes Modell & aufgelöst)
- **`GET /api/maturity-models/{id}/export`**: `shinkan.maturity_model.v1` inkl. `context_bindings_for_model` (IDs).
- **`GET /api/maturity-models/export-resolved`**: `shinkan.maturity_matrix_resolved.v1` (Query: `focus_area_id`, optional `style_direction_id`, `training_type_id`).
- **`POST /api/maturity-models/import`**: `create` | `replace`, optional `import_bindings` (nur bei `maturity_model.v1`).
### 2.4 Komplett-Stack Test → Prod
- **`GET /api/admin/matrix-stack/export`**: `shinkan.matrix_stack.v1` – Katalog (`skill_main_categories`, `skill_categories`, `skills`, `skill_level_definitions`) + alle Reifegradmodelle + Bindings mit **Namen** (Fokus/Stil/Trainingsstil).
- **`POST /api/admin/matrix-stack/import`**: Upsert Katalog per Slug; Skills per Kategorie+Name; Modelle neu anlegen; Bindings per Katalognamen. Optional **`replace_all_maturity_models`** + **`confirm_replace_all: "DELETE_MATURITY_STACK"`** (nur Superadmin).
- Router: `backend/routers/matrix_stack_bundle.py`, in `main.py` registriert.
### 2.5 Frontend (Admin)
- **`frontend/src/pages/AdminMaturityModelsPage.jsx`**: Tabs u. a. Katalog, Modelle, Kontext-Zuordnung, **Matrix-Ansicht und Export**.
- **`MaturityModelBindingsAdmin.jsx`**: Bindings CRUD, Erklärung Merge/Legacy.
feat: enhance exercise management and media handling - Introduced new API endpoints for managing exercise media, including upload, update, delete, and reorder functionalities. - Updated the exercise creation and update logic to ensure goal and execution fields are validated and normalized. - Refactored frontend components to support the new exercise media features, including a dedicated import section for complete stack files. - Removed the deprecated ExercisesPage component and replaced it with a more modular structure for exercise management. - Incremented database schema version to 20260427028 and updated changelog to reflect these changes.
2026-04-27 14:27:25 +02:00
- **`MaturityMatrixToolsAdmin.jsx`**: Kontext auflösen, hierarchische Matrix-Ansicht, Export einzelnes Modell / aufgelöst, Einzelmodell-Import; **Komplett-Stack** mit eigenem Export-Button und **eigenem Dateifeld für Stack-Import** (`POST /api/admin/matrix-stack/import`).
feat: update version to 0.7.6 and add matrix stack bundle functionality - Incremented application version to 0.7.6 and updated maturity models version to 1.4.0. - Introduced new API endpoints for exporting and importing matrix stack bundles, enhancing the capabilities for managing maturity models and context bindings. - Updated frontend components to support the new matrix stack export and import features, including UI elements for stack management. - Documented changes in the changelog for version 0.7.6, detailing the new matrix stack functionality and its usage.
2026-04-27 13:13:36 +02:00
- **`frontend/src/utils/api.js`**: u. a. `exportMatrixStackBundle`, `importMatrixStackBundle`, Reifegrad-APIs.
---
chore: update versioning and enhance training framework features - Incremented APP_VERSION to 0.8.10 and DB_SCHEMA_VERSION to 20260505037. - Updated project status and domain model documentation to reflect recent changes. - Enhanced training framework program handling with new slot-blueprint structure. - Introduced API endpoint for creating training units from framework slots. - Improved documentation for training planning and governance concepts.
2026-05-05 13:39:30 +02:00
## 3. Trainingsrahmenprogramm & Planungs‑Blueprint (kurz)
- **Migration 036:** Rahmenkopf nur Bibliothek (Kontext: Fokusbereich, Stilrichtung; M:N Trainingsarten/Zielgruppen); keine `plan_mode`/keine Kopf‑`group_id`.
- **Migration 037:** Pro Rahmen‑Slot eine **`training_units`‑Zeile mit `framework_slot_id`**; strukturierter Ablauf wie echte Einheiten (`training_unit_sections` / `training_unit_section_items`). Tabelle **`training_framework_slot_exercises`** entfällt.
- **API:** Rahmen unter **`/api/training-framework-programs`** (Slots liefern u. a. **`blueprint_training_unit_id`**, **`sections[]`**, **`exercises[]`**); Kalenderliste **`GET /api/training-units`** ohne Blueprints; Übernahme **`POST /api/training-units/from-framework-slot`**.
- **Code:** `backend/routers/training_framework_programs.py`, `training_planning.py`; Frontend **`TrainingFrameworkProgramEditPage.jsx`**; **`createTrainingUnitFromFrameworkSlot`** in `api.js`.
---
## 4. Stand: Übungen (Lücke für nächste Session)
feat: update version to 0.7.6 and add matrix stack bundle functionality - Incremented application version to 0.7.6 and updated maturity models version to 1.4.0. - Introduced new API endpoints for exporting and importing matrix stack bundles, enhancing the capabilities for managing maturity models and context bindings. - Updated frontend components to support the new matrix stack export and import features, including UI elements for stack management. - Documented changes in the changelog for version 0.7.6, detailing the new matrix stack functionality and its usage.
2026-04-27 13:13:36 +02:00
**Ist (laut Projektdoku und aktuellem Produktziel):**
- Backend: Übungen-CRUD, M:N, Suche, Blöcke, Medien-Struktur u. a. sind in `PROJECT_STATUS.md` als umgesetzt geführt; viele Übungen stammen aus **MediaWiki-Import** (Wiki-Tracking-Tabellen).
- **Soll / Nutzerfeedback:** In der Praxis fehlt oder ist unzureichend: **stabile Liste**, **gerenderte Detailansicht**, **Bearbeiten/Anlegen**, **Medien zuweisen/Upload** – konkrete Fehler (404, leere Liste, falsche Route) sind vor Ort zu verifizieren.
**Nächste Session sollte:**
1. Aktuelle Routen und Seiten prüfen (`App.jsx`, `EXERCISES_FRONTEND_ROUTING.md`).
2. `GET /api/exercises` (Filter, Auth) und eine Beispiel-Übung gegen die Dev-DB testen.
3. UI schrittweise: Liste → Detail → Formular → Medien (an Specs in `.claude/docs/technical/` ausrichten).
---
chore: update versioning and enhance training framework features - Incremented APP_VERSION to 0.8.10 and DB_SCHEMA_VERSION to 20260505037. - Updated project status and domain model documentation to reflect recent changes. - Enhanced training framework program handling with new slot-blueprint structure. - Introduced API endpoint for creating training units from framework slots. - Improved documentation for training planning and governance concepts.
2026-05-05 13:39:30 +02:00
## 5. Technische Referenz (kurz)
feat: update version to 0.7.6 and add matrix stack bundle functionality - Incremented application version to 0.7.6 and updated maturity models version to 1.4.0. - Introduced new API endpoints for exporting and importing matrix stack bundles, enhancing the capabilities for managing maturity models and context bindings. - Updated frontend components to support the new matrix stack export and import features, including UI elements for stack management. - Documented changes in the changelog for version 0.7.6, detailing the new matrix stack functionality and its usage.
2026-04-27 13:13:36 +02:00
| Bereich | Einstieg |
|---------|----------|
chore: update versioning and enhance training framework features - Incremented APP_VERSION to 0.8.10 and DB_SCHEMA_VERSION to 20260505037. - Updated project status and domain model documentation to reflect recent changes. - Enhanced training framework program handling with new slot-blueprint structure. - Introduced API endpoint for creating training units from framework slots. - Improved documentation for training planning and governance concepts.
2026-05-05 13:39:30 +02:00
| Backend API | `backend/main.py`; Router u. a. **`training_framework_programs.py`**, **`training_planning.py`**, `maturity_models.py`, `matrix_stack_bundle.py`, `exercises.py`, `catalogs.py`, `skills.py` |
| Migrationen | `backend/migrations/` (u. a. 024–027 Reifegrad/Bindings; **035–037** Rahmenprogramm / Slot‑Blueprint) |
feat: update version to 0.7.6 and add matrix stack bundle functionality - Incremented application version to 0.7.6 and updated maturity models version to 1.4.0. - Introduced new API endpoints for exporting and importing matrix stack bundles, enhancing the capabilities for managing maturity models and context bindings. - Updated frontend components to support the new matrix stack export and import features, including UI elements for stack management. - Documented changes in the changelog for version 0.7.6, detailing the new matrix stack functionality and its usage.
2026-04-27 13:13:36 +02:00
| Frontend API | `frontend/src/utils/api.js` |
| Version / Changelog | `backend/version.py` |
---
chore: update versioning and enhance training framework features - Incremented APP_VERSION to 0.8.10 and DB_SCHEMA_VERSION to 20260505037. - Updated project status and domain model documentation to reflect recent changes. - Enhanced training framework program handling with new slot-blueprint structure. - Introduced API endpoint for creating training units from framework slots. - Improved documentation for training planning and governance concepts.
2026-05-05 13:39:30 +02:00
## 6. Veraltete Hinweise
feat: update version to 0.7.6 and add matrix stack bundle functionality - Incremented application version to 0.7.6 and updated maturity models version to 1.4.0. - Introduced new API endpoints for exporting and importing matrix stack bundles, enhancing the capabilities for managing maturity models and context bindings. - Updated frontend components to support the new matrix stack export and import features, including UI elements for stack management. - Documented changes in the changelog for version 0.7.6, detailing the new matrix stack functionality and its usage.
2026-04-27 13:13:36 +02:00
Die Datei `.claude/docs/working/HANDOVER_NEXT_SESSION.md` (2026-04-22) ist **historisch**; für den aktuellen Stand gilt **`docs/HANDOVER.md`**.
---
*Ende Handover-Dokument.*
Reference in New Issue Copy Permalink