shinkan-jinkendo/.claude/docs/working/EXERCISE_ENRICHMENT_ADMIN.md

Superadmin: Übungs-Anreicherung per KI

Stand: 2026-05-23 · App 0.8.178

Zweck

Plattform-weites Werkzeug für Superadmins, um Übungen (typisch draft, ohne Skills) batchweise per KI mit Fähigkeiten anzureichern und kontrolliert auf in_review zu setzen.

Verbessert indirekt die Planungs-KI (POST /api/planning/exercise-suggest), die gegen Skill-Profile rankt — unvollständige exercise_skills führen dort zu Volltext-dominiertem Ranking.

UI

• Route: /admin/exercise-enrichment (nur Superadmin)
• Admin-Menü: „Übungs-Anreicherung“

API

Prefix: /api/admin/exercise-enrichment

Methode	Pfad	Beschreibung
GET	/candidates	Paginierte Kandidaten (Filter: status, visibility, focus_area, without_skills, with_ai_suggested_skills, include_club, search)
POST	/preview	Dry-Run — { exercise_ids[], modes: { skills, summary }, merge_mode }
POST	/apply	{ items: [{ exercise_id, merged_skills }], merge_mode, set_status }

Auth: require_auth + is_superadmin — kein TenantContext (EXEMPT, siehe ACCESS_LAYER_ENDPOINT_AUDIT.md).

KI

Wiederverwendet run_exercise_form_ai_suggestion → Prompts exercise_skill_suggestions (MVP Pflicht), optional exercise_summary. Skill-Katalog via build_contextual_skills_catalog_block / ai_skill_retrieval_profiles.

Merge-Modi (Skills)

• additive (Default): manuelle Skills bleiben; KI ergänzt neue; bestehende ai_suggested-Links werden aktualisiert
• replace_ai_only: nur ai_suggested=true entfernen, dann KI-Set anwenden
• replace_all: alle Skills ersetzen (explizit)

Defaults

• Kandidaten: Status primär (Default draft); Sichtbarkeit Default private, wählbar bis „Alle“
• Skill-Merge Default: replace_all (alle Skills KI-neu, ai_suggested=true — unterscheidbar von manuell)
• Nach Apply: set_status=in_review (nie automatisch approved)
• Batch: keine Gesamtgrenze (bis 10.000 IDs); Analyze + explizite Nutzerbestätigung
• Preview: max. 3 Übungen/HTTP-Request (parallel LLM), Frontend chunked — vermeidet Gateway-504 (~60s Fritz!Box)
• Apply: HTTP-Chunks à 25 (nur DB, kein LLM)

Inhalte (modular)

Modus	Prompt	Apply-Felder
Skills	exercise_skill_suggestions	exercise_skills inkl. Intensität, required/target_level, ai_suggested
Summary	exercise_summary	summary, summary_ai_generated=true
Anleitung	exercise_instruction_rewrite	goal, execution, preparation, trainer_notes

API (ergänzt)

Methode	Pfad	Beschreibung
GET	/candidate-ids	Alle IDs zum Filter (Select-all)
POST	/analyze	{ exercise_ids[], modes } → Kosten-Schätzung vor Start

Keine Migration

Bestehende Spalte exercise_skills.ai_suggested reicht; kein Enrichment-Log in MVP.

Tests

backend/tests/test_exercise_enrichment_admin.py — 403, Merge-Logik, Status draft→in_review.