Lars/shinkan-jinkendo
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 3 Wiki Activity
e5291256d0
shinkan-jinkendo/.claude/docs/working/AI_EXERCISE_IMPLEMENTATION_PLAN.md
Lars e5291256d0
All checks were successful
Deploy Development / deploy (push) Successful in 43s
Details
Test Suite / pytest-backend (push) Successful in 38s
Details
Test Suite / lint-backend (push) Successful in 0s
Details
Test Suite / build-frontend (push) Successful in 13s
Details
Test Suite / k6 /health Baseline (push) Successful in 38s
Details
Test Suite / playwright-tests (push) Successful in 1m21s
Details
Enhance AI Exercise Suggestion Functionality and UX 
- Updated the AI Exercise Implementation Plan to include a detailed description of the new suggestion dialog for AI proposals, allowing users to preview and selectively adopt AI-generated summaries and skills.
- Implemented a new preview feature in the ExerciseFormPageRoot component, enabling users to review AI suggestions before applying them to the form.
- Enhanced the skill management process by normalizing AI-suggested skills and integrating them into the exercise form, improving user interaction and data handling.
2026-05-22 09:21:44 +02:00

4.1 KiB
Raw Blame History

Umsetzungsplan – KI bei Übungen (stufenweise, Driftschutz)

Version: 0.1
Datum: 2026-05-22
Bezüge: functional/AI_EXERCISE_ASSISTANT_VISION.md · technical/KI_FEATURES_SPEC.md · technical/AI_PROMPT_SYSTEM_SPEC.md · technical/AI_TRAINING_PLANNING_CONCEPT.md (§1.1 Ist-Stand)

1. Drift vermeiden – verbindliche Regeln

  1. Spec vor Code: Request/Response-Felder und Statuscodes an KI_FEATURES_SPEC.md ausrichten; Abweichungen zuerst Spec oder dieses Dokument anpassen.
  2. Prompts in der DB: Keine produktionskritischen Prompt-Langtexte nur im Code; Defaults per Migration in ai_prompts, Anpassung durch Admins über vorgesehene Oberfläche (später) oder SQL.
  3. Stufen-Slugs & Intensität: Nur kanonische Werte wie in exercises.py (basis … optimierung, niedrig|mittel|hoch); LLM-Ausgaben normalisieren, ungültige skill_id verwerfen.
  4. Kein stiller DB-Write: KI liefert Vorschläge; Persistenz nur über bestehende PUT/POST exercises inkl. Trainer-Aktion (und optional summary_ai_generated / ai_suggested wie Spec).
  5. Mandant: Übungsbezogene KI-Endpunkte nutzen Depends(get_tenant_context); keine Ausnahme ohne Eintrag in ACCESS_LAYER_ENDPOINT_AUDIT.md.
  6. Schema: Neue DB-Objekte nur nummerierte Migration backend/migrations/067_*.sql (oder folgend); DB_SCHEMA_VERSION in backend/version.py anheben.

2. Stufen (Releases)

Stufe Inhalt Exit-Kriterium
S0 Dieses Dokument + Verweise konsistent Review abgehakt
S1 Migration ai_prompts + Defaults exercise_summary, exercise_skill_suggestions; exercises.summary_ai_generated Migrierte DB, App startet
S2 httpx-Client OpenRouter; Modul lädt Prompt, ersetzt Platzhalter, parst Antwort Unit-/Smoke: 503 ohne Key
S3 POST /api/exercises/ai/suggest, POST /api/exercises/{id}/ai/regenerate OpenAPI/Handtest mit Key
S4 Frontend: KI-Vorschlag, Änderungsdialog (Vorschau, Kurzfassung wählbar, Fähigkeiten pro Zeile an-/abwählbar), dann Übernahme ins Formular Manuelle UX-Prüfung
S5 (später) Auto-Fallback beim Speichern laut KI_FEATURES_SPEC §7 Feature-Flag / Config
S6 (später) Zielausbau, Anleitung-only, Varianten, Admin-Masse laut Vision Separate Epics

Aktueller Implementierungsstand nach Merge: S0–S4 anstreben; S5/S6 nicht Teil dieses Laufs.

3. Implementierungs-Checkliste (Technik)

  • OPENROUTER_API_KEY / OPENROUTER_MODEL in .env.example dokumentiert (bereits teils vorhanden – prüfen).
  • Fehlerbilder: 400 zu wenig Inhalt, 503 KI nicht konfiguriert, 502 Upstream-Fehler mit kurzer Message.
  • Logging: keine vollständigen Prompts mit personenbezogenen Daten in Prod-Logs (optional DEBUG).
  • Optional: Rate-Limit KI-Endpunkte (slowapi) – nach Bedarf.
  • MODULE_VERSIONS["exercises"] / Changelog bei API-Erweiterung setzen.

4. Changelog dieses Plans

  • 2026-05-22: Initial; S1–S4 als erster Umsetzungspfad.
  • 2026-05-22: S1–S4 im Code umgesetzt (Migration 067, exercise_ai + Router, Übungsformular); S5 weiter offen.
  • 2026-05-22: UX: Übernahmedialog für KI-Vorschläge (Vorschau, selektive Übernahme) im Übungsformular (ExerciseFormPageRoot).

5. Umsetzungsstand (Zwischencheckpoint)

Erledigt (2026-05-22): Migration 067_ai_prompts_exercise_assistant, openrouter_chat, exercise_ai, POST /api/exercises/ai/suggest und POST /api/exercises/{id}/ai/regenerate, Formular-Schaltflächen (Kurzfassung / Fähigkeiten / kombiniert).

Nacharbeit S4 UX: Übernahmedialog ExerciseFormPageRoot: keine sofortige Überschreibung; Kurzfassung mit Vergleich + Checkbox; Fähigkeiten mit Neu/Aktualisierung, Checkboxen, „Alle auswählen/abwählen“; Escape schließt; KI-Schaltflächen blockiert solange Dialog offen.

Bewusst noch nicht: automatische KI beim Speichern (S5), Setzen von summary_ai_generated bei manuellen UI-Änderungen, Prompt-Admin-UI, Rate-Limits.