306 lines
15 KiB
Markdown
306 lines
15 KiB
Markdown
<!-- status: build -->
|
|
<!-- started: 2026-04-29 -->
|
|
<!-- verified: 2026-05-03 -->
|
|
<!-- component: gateway, ui-nyla -->
|
|
|
|
# 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
|
|
|
|
```mermaid
|
|
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.
|
|
- [x] `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
|