PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki/c-work/4-done/2026-04-comcoach-greenfield-ia.md
ValueOn AG aabf7cb7a9 ui enhance
2026-06-11 15:44:54 +02:00

15 KiB
Raw Blame History

ComCoach Greenfield-IA: TrainingModule + Sessions

Beschreibung und Kontext

Die ComCoach-UI ist gewachsen und chaotisch:

  • 4 Sidebar-Eintraege (dashboard, coaching, dossier, settings), aber coaching und dossier rendern die identische Komponente CommcoachDossierView (ui-nyla/src/pages/FeatureView.tsx 168-173).
  • RBAC-Definition kennt nur 3 UI-Keys (mainCommcoach.py 19-34) -> Inkonsistenz mit Sidebar.
  • Das Dashboard verlinkt mit ?context={id}, die Dossier-View liest diesen Query-Param nicht -> falscher Default-Kontext nach Klick (CommcoachDossierView.tsx 142-146).
  • CRUD fuer "Coachings" (heute CoachingContext) ist unvollstaendig: Backend hat PUT/DELETE /contexts/{id}, UI bietet nur Create + Archive.
  • Statistik wird doppelt gezeigt (Dashboard + Settings).
  • Die Datenstruktur ist heute flach: CoachingContext -> Sessions, ohne Modul/Reihen-Konzept. Das passt nicht zum gewuenschten Use-Case "ein Psychologe (Modul) macht m Sessions zu einem Thema, alle tragen zu Modul-KPI bei" oder "E-Learning-Modul + Pruefungs-Modul".

Geschaeftstreiber: User finden sich nicht zurecht -> ComCoach wird unterbenutzt. Mit klarer Modul-of-Sessions-IA und 5 sauberen Tabs wird ComCoach erst zum vermarktbaren Produkt.

Fokus und kritische Details

  • Bestehende Daten (alle aktuellen CoachingContext-Eintraege) muessen migriert werden -> 1:1 Rename auf TrainingModule mit Default moduleType="coaching".
  • "Module" und "Coaching" sind im UI gleichwertig zu verwenden -- intern ist es immer ein TrainingModule. Im UI je nach moduleType das Label anpassen ("Coaching", "Training", "Pruefung", "E-Learning").
  • KeepAlive-Mechanismus (ui-nyla/src/pages/views/commcoach/CommcoachKeepAlive.tsx) beibehalten -- die Voice-Session darf nicht gekillt werden bei Sidebar-Wechsel.
  • Bestehendes goals-Feld: CoachingContext.goals existiert bereits als Optional[str] (JSON-Array [{id, text, status, createdAt}]). Beim Rename wird es zu Freitext umgewidmet; bestehende JSON-Werte per Migration zu Plain-Text konvertieren (Ziel-Texte extrahieren).
  • Bestehendes category-Feld: CoachingContext.category ist ein Enum (leadership, conflict, negotiation, ..., custom). Beim Rename wird category durch moduleType ersetzt. Migration: alle bestehenden category-Werte -> moduleType="coaching", altes Feld category wird deprecated/entfernt.
  • Bestehendes description-Feld: Bleibt erhalten, ergaenzt goals.

Ziel und Nicht-Ziele

  • Ziel: 5-Tab-IA (Dashboard, Assistent, Module, Session, Einstellungen) mit klarer Use-Case-Zuordnung. Datenmodell TrainingModule mit KPIs + N Sessions.
  • NICHT: Voice-Pipeline aendern.
  • NICHT: Persona-Marketplace (eigener Plan).
  • NICHT: Multi-Tenant-Sharing von Modulen ueber Mandate-Grenzen (eigener Plan, falls je gewollt).

Betroffene Module

  • Gateway:
    • platform-core/modules/features/commcoach/datamodelCommcoach.py -- CoachingContext -> TrainingModule (Rename + neue Felder kpiTargets jsonb, moduleType enum, goals text).
    • platform-core/modules/features/commcoach/interfaceFeatureCommcoach.py -- Methoden umbenennen (intern), DB-Migration anwenden.
    • platform-core/modules/features/commcoach/routeFeatureCommcoach.py -- Routes umbenennen /contexts -> /modules (oder Alias-Periode).
    • platform-core/modules/features/commcoach/mainCommcoach.py -- RBAC-Keys auf neue Tab-Struktur (5 Keys: dashboard, assistant, modules, session, settings).
  • Frontend:
    • ui-nyla/src/types/mandate.ts 277-286 -- Sidebar 4 -> 5 Eintraege.
    • ui-nyla/src/pages/FeatureView.tsx 168-173 -- View-Mapping aktualisieren.
    • ui-nyla/src/pages/views/commcoach/ -- bestehende CommcoachDossierView zerlegen in:
      • CommcoachDashboardView (existiert, KPIs ergaenzen).
      • CommcoachAssistantView (NEU): Wizard-Flow neues Modul + erste Session.
      • CommcoachModulesView (NEU): Liste, CRUD, Sessions je Modul.
      • CommcoachSessionView (NEU, ehem. coaching-Tab): aktive Session.
      • CommcoachSettingsView (existiert, Statistik raus).
    • ui-nyla/src/api/commcoachApi.ts -- API-Wrapper aktualisieren.
    • ui-nyla/src/pages/views/commcoach/CommcoachKeepAlive.tsx -- Komponenten-Mapping aktualisieren (Session bleibt KeepAlive).
  • DB-Migration: ja -- Rename CoachingContext -> TrainingModule, additive Felder.
  • RBAC: ja -- 5 statt 3 UI-Keys.

Zieldatenmodell

flowchart LR
  Inst[FeatureInstance commcoach] --> Mod[TrainingModule]
  Mod --> Sess[Session]
  Sess --> Msg[Message]
  Sess --> Score[Score]
  Mod --> Task[Task]
  Mod --> Kpi[ModuleKpi]
  Mod --> Per[Persona ref]

TrainingModule Felder (Auszug):

Feld Typ Bedeutung
id UUID PK
instanceId UUID FeatureInstance-Scope
userId UUID Owner
mandateId UUID Tenant
title text "Konfliktgespraeche", "JS-Grundkurs"
moduleType enum coaching | training | exam | elearning
personaId UUID? Default-Persona fuer Sessions
description text Kurzbeschreibung (besteht bereits)
goals text freie Zielbeschreibung (existiert als JSON, wird zu Freitext migriert)
kpiTargets jsonb strukturierte Ziel-KPIs
status enum active | archived | completed
createdAt / updatedAt timestamp --

IA: 5 Tabs (final)

# Tab Zweck Komponente
1 Dashboard Gamification, Streak, Levels, aktive Module-Karten, Tipp des Tages, Schnell-Aktion "Neues Modul" CommcoachDashboardView
2 Assistent Wizard: Modul-Typ -> Thema -> Persona -> KPIs -> "Erste Session starten" CommcoachAssistantView
3 Module CRUD-Liste aller Module (Filter nach Status/Typ), pro Modul aufklappbare Sessions CommcoachModulesView
4 Session aktive/laufende Session als Single-Page (TTS, Voice, Anhaenge, Agent-Aktivitaet, Abschliessen/Abbrechen). Erreichbar nur ueber Modul oder Assistent CommcoachSessionView
5 Einstellungen Stimme/Sprache, Erinnerungen, E-Mail-Zusammenfassung. KEINE Statistik mehr CommcoachSettingsView

Use-Case-Mapping

Use-Case Tab(s) Hauptaktion
1 Gamification-Dashboard Dashboard KPIs + Streak ansehen
2 Assistent: neues Coaching Assistent -> Session Wizard durchklicken
3 Session-Operations Session TTS, Voice, Tasks waehrend Session
4 Listen CRUD Module Module pflegen, Sessions je Modul aufklappen
5 Instanzen-Einstellungen Einstellungen Stimme, Erinnerungen

Entscheidungen

Datum Entscheidung Begruendung
2026-04-29 Backend-Entity heisst neu TrainingModule (Rename von CoachingContext) Generischer Begriff deckt Coaching, Training, Exam, ELearning ab
2026-04-29 Im UI je nach moduleType Labelt "Coaching/Training/..." UX-Klarheit
2026-04-29 Sidebar 5 Tabs (statt 4 mit Doppelung) Use-Cases brauchen klare Trennung Assistent vs. Liste
2026-04-29 Statistik im Settings-Tab raus, nur Dashboard Doppelung weg
2026-04-29 KeepAlive bleibt nur fuer Session-Tab (nicht Module/Dashboard) Voice-Session muss persistieren, Listen koennen unmounten
2026-05-03 goals-Feld wird von JSON-Array zu Freitext migriert Vereinfachung, JSON-Struktur war overengineered
2026-05-03 category-Enum entfaellt zugunsten von moduleType Keine zwei Klassifizierungs-Dimensionen noetig
2026-05-03 Alle Zeilennummern gegen Codebase verifiziert, alle korrekt Pre-Build-Audit

Umsetzungs-Checkliste

Phase 1 -- Backend Datenmodell + Routes

  • datamodelCommcoach.py: - Klasse CoachingContext -> TrainingModule (Rename, alle FKs in Childs contextId -> moduleId). - Neues Feld kpiTargets jsonb, neues Feld moduleType enum. - Bestehendes goals (JSON-Array) -> Freitext migrieren. - Bestehendes category (Enum) -> entfernen (ersetzt durch moduleType). Bestehende Werte per Migration alle auf moduleType="coaching". - description bleibt unveraendert.
  • DB-Migration: script_db_rename_coaching_context_to_training_module.py. Tabellenname Postgres-Rename, FK-Spalte contextId -> moduleId auf allen abhaengigen Tabellen (CoachingSession, CoachingTask, CoachingScore).
  • interfaceFeatureCommcoach.py -- Methodennamen umstellen (createContext -> createModule etc.) mit camelCase intern.
  • routeFeatureCommcoach.py: - Neue Pfade /api/commcoach/{instanceId}/modules/.... - Alias-Periode: alte /contexts/...-Routen zeigen 301 auf neue Routen (1 Release lang), dann raus.
  • mainCommcoach.py: - RBAC-Keys: dashboard, assistant, modules, session, settings. - Templates fuer Standard-Modulvorlagen optional (z.B. "Konflikt- Coaching", "Sprach-Training").

Phase 2 -- Frontend Routing & Sidebar

  • ui-nyla/src/types/mandate.ts 277-286 ComCoach-Eintraege auf 5 Eintraege umstellen.
  • ui-nyla/src/App.tsx 185-187 Routes ergaenzen (assistant, modules, session).
  • ui-nyla/src/pages/FeatureView.tsx 168-173 View-Mapping auf neue Komponenten.
  • KeepAlive nur noch fuer session-Tab konfigurieren.

Phase 3 -- Frontend Komponenten

  • CommcoachDashboardView -- KPI-Karten verfeinern (pro Modul-Typ Aggregat), neuer "Modul anlegen"-CTA.
  • NEU CommcoachAssistantView -- Wizard 4 Steps (Typ/Thema/Persona/ KPIs) + "Erste Session starten" -> Navigation session?moduleId=....
  • NEU CommcoachModulesView -- Liste, Filter (moduleType, Status), CRUD-Dialoge (Edit/Delete vorhanden, jetzt im UI), pro Zeile aufklappbar Sessions inkl. Sessions-CRUD (zumindest Delete).
  • NEU CommcoachSessionView -- aus existierender Dossier-Tab- Logik die "coaching"-Tab-Inhalte rausziehen.
  • CommcoachSettingsView -- Statistik-Sektion entfernen.
  • CommcoachDossierView ENTFERNEN nach Migration aller Inhalte (erledigt: c-work/4-done/2026-06-ui-nyla-legacy-cleanup.md).

Phase 4 -- Bugfixes (Vor-Ort)

  • ?context={id} auf neuen Param ?moduleId={id} umstellen, in allen Views konsistent lesen.
  • commcoachApi.ts Wrapper updateContextApi, deleteContextApi, activateContextApi, updateTaskApi aus Backend nutzen (heute ungenutzt).

Phase 5 -- Doku

  • Neue b-reference wiki/b-reference/platform-core/features/commcoach.md anlegen.
  • wiki/TOPICS.md Eintrag "ComCoach Architecture".

Akzeptanzkriterien

# Kriterium (Given-When-Then) Prio
1 Given Sidebar ComCoach, When User es oeffnet, Then sieht er 5 Tabs (Dashboard, Assistent, Module, Session, Einstellungen) must
2 Given Tab Assistent, When User Wizard durchklickt, Then ist am Ende ein neues Modul + eine erste Session aktiv must
3 Given Tab Module, When User auf "Bearbeiten" eines Moduls klickt, Then kann er Titel, Typ, Persona, Goals, KPIs editieren must
4 Given Tab Module, When User auf "Loeschen" eines Moduls klickt, Then ist das Modul + alle Sessions weg (mit Confirm) must
5 Given Tab Dashboard, When User auf eine Modul-Karte klickt, Then landet er im Tab Module mit dem richtigen Modul aufgeklappt (moduleId-Param wird gelesen) must
6 Given Tab Einstellungen, When User es oeffnet, Then sieht er KEINE Statistik-Sektion mehr should
7 Given Bestand-CoachingContext-Eintraege, When Migration laeuft, Then heissen sie alle TrainingModule mit moduleType=coaching und alle FKs zeigen korrekt must
8 Given Voice-Session laeuft im Tab Session, When User auf Tab Module wechselt und zurueck, Then laeuft die Session weiter (KeepAlive) should

Testplan

ID AC Art Automatisiert Repo-Pfad Status
T1 1 unit ja ui-nyla/src/types/tests/mandate.test.ts pending
T2 2 e2e ja ui-nyla/tests/e2e/commcoach-assistant.spec.ts pending
T3 3,4 e2e ja ui-nyla/tests/e2e/commcoach-modules-crud.spec.ts pending
T4 5 e2e ja ui-nyla/tests/e2e/commcoach-dashboard-link.spec.ts pending
T5 6 unit ja ui-nyla/src/pages/views/commcoach/tests/CommcoachSettingsView.test.tsx pending
T6 7 integration ja platform-core/tests/features/commcoach/test_migration_rename.py pending
T7 8 manual nein -- pending

Links

  • Audit-Quelle: Subagent-Report 2026-04-29.
  • Aktueller Code: platform-core/modules/features/commcoach/, ui-nyla/src/pages/views/commcoach/.
  • Aktuelles Konzept (veraltet): platform-core/modules/features/commcoach/CONCEPT.md.

Iteration: Persona-Management (2026-05-04)

Personas (Gespraechspartner) sind jetzt voll konfigurierbar:

Backend

  • Neue Builtin-Personas: Paartherapeutin, Psychologe, Rechtsanwalt, Mediatorin, HR-Managerin (serviceCommcoachPersonas.py)
  • ModulePersonaMapping M:N-Modell: datamodelCommcoach.py
    • Felder: id, moduleId, personaId, instanceId
    • DB-Migration M8 (idempotent) in mainCommcoach.py
  • API-Endpoints:
    • GET /modules/{moduleId}/personas -> { personaIds: string[] }
    • PUT /modules/{moduleId}/personas -> { personaIds: string[] } (replace-all)
    • PUT /personas/{personaId} (fehlte vorher, jetzt ergaenzt)
  • Interface-Methoden: getModulePersonas(), setModulePersonas(), getAllPersonas()
  • RBAC: data.feature.commcoach.ModulePersonaMapping + resource.feature.commcoach.persona.manage + resource.feature.commcoach.modulePersonas.manage

Frontend

  • Settings-Tab 'Gespraechspartner': FormGeneratorTable mit CRUD fuer custom Personas. Builtin-Personas: nur sichtbar, nicht editierbar/loeschbar. Inline-Toggle fuer isActive.
  • Modul-Edit-Dialog: Persona-Multi-Select-Checkbox-Liste. Ohne Auswahl = alle verfuegbar.
  • Session-Persona-Picker: Filtert Anzeige basierend auf Modul-Zuordnung. Zeigt Hinweis wenn modulspezifisch konfiguriert.

Dateien

  • platform-core/modules/features/commcoach/serviceCommcoachPersonas.py (5 neue Personas)
  • platform-core/modules/features/commcoach/datamodelCommcoach.py (ModulePersonaMapping, SetModulePersonasRequest)
  • platform-core/modules/features/commcoach/interfaceFeatureCommcoach.py (3 neue Methoden)
  • platform-core/modules/features/commcoach/routeFeatureCommcoach.py (2 neue Endpoints)
  • platform-core/modules/features/commcoach/mainCommcoach.py (DATA_OBJECTS, RESOURCE_OBJECTS, Migration M8)
  • ui-nyla/src/api/commcoachApi.ts (updatePersonaApi, getModulePersonasApi, setModulePersonasApi)
  • ui-nyla/src/pages/views/commcoach/CommcoachSettingsView.tsx (Tab-Layout, Persona CRUD)
  • ui-nyla/src/pages/views/commcoach/CommcoachSettingsView.module.css (Tab-Styles, Modal)
  • ui-nyla/src/pages/views/commcoach/CommcoachModulesView.tsx (Persona-Multi-Select im Edit)
  • ui-nyla/src/pages/views/commcoach/CommcoachSessionView.tsx (Persona-Filter nach Modul)

Abschluss

  • wiki/b-reference/platform-core/features/commcoach.md neu anlegen
  • wiki/TOPICS.md Eintrag "ComCoach"
  • platform-core/modules/features/commcoach/CONCEPT.md aktualisieren
  • Dieses Dokument -> z-archive/ verschoben