PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki/c-work/1-plan/2026-04-comcoach-greenfield-ia.md
ValueOn AG 6eeeb962f6 upd
2026-04-29 20:23:03 +02:00

249 lines
12 KiB
Markdown
Raw Blame History

<!-- status: plan -->
<!-- started: 2026-04-29 -->
<!-- component: gateway, frontend-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`
(`frontend_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
(`frontend_nyla/src/pages/views/commcoach/CommcoachKeepAlive.tsx`)
beibehalten -- die Voice-Session darf nicht gekillt werden bei
Sidebar-Wechsel.
## 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:
- `gateway/modules/features/commcoach/datamodelCommcoach.py` --
`CoachingContext` -> `TrainingModule` (Rename + neue Felder
`kpiTargets jsonb`, `moduleType enum`, `goals text`).
- `gateway/modules/features/commcoach/interfaceFeatureCommcoach.py` --
Methoden umbenennen (intern), DB-Migration anwenden.
- `gateway/modules/features/commcoach/routeFeatureCommcoach.py` --
Routes umbenennen `/contexts` -> `/modules` (oder Alias-Periode).
- `gateway/modules/features/commcoach/mainCommcoach.py` -- RBAC-Keys
auf neue Tab-Struktur (5 Keys: dashboard, assistant, modules,
session, settings).
- Frontend:
- `frontend_nyla/src/types/mandate.ts` 277-286 -- Sidebar 4 -> 5
Eintraege.
- `frontend_nyla/src/pages/FeatureView.tsx` 168-173 -- View-Mapping
aktualisieren.
- `frontend_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).
- `frontend_nyla/src/api/commcoachApi.ts` -- API-Wrapper aktualisieren.
- `frontend_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 |
| `goals` | text | freie Zielbeschreibung |
| `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 |
## Umsetzungs-Checkliste
### Phase 1 -- Backend Datenmodell + Routes
- [ ] `datamodelCommcoach.py`:
- Klasse `CoachingContext` -> `TrainingModule` (Rename, alle
FKs in Childs `contextId` -> `moduleId`).
- Neue Felder `kpiTargets jsonb`, `moduleType enum`, `goals text`.
- [ ] 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
- [ ] `frontend_nyla/src/types/mandate.ts` 277-286 ComCoach-Eintraege
auf 5 Eintraege umstellen.
- [ ] `frontend_nyla/src/App.tsx` 185-187 Routes ergaenzen (`assistant`,
`modules`, `session`).
- [ ] `frontend_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.
### 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/gateway/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 | frontend_nyla/src/types/__tests__/mandate.test.ts | pending |
| T2 | 2 | e2e | ja | frontend_nyla/tests/e2e/commcoach-assistant.spec.ts | pending |
| T3 | 3,4 | e2e | ja | frontend_nyla/tests/e2e/commcoach-modules-crud.spec.ts | pending |
| T4 | 5 | e2e | ja | frontend_nyla/tests/e2e/commcoach-dashboard-link.spec.ts | pending |
| T5 | 6 | unit | ja | frontend_nyla/src/pages/views/commcoach/__tests__/CommcoachSettingsView.test.tsx | pending |
| T6 | 7 | integration | ja | gateway/tests/features/commcoach/test_migration_rename.py | pending |
| T7 | 8 | manual | nein | -- | pending |
## Links
- Audit-Quelle: Subagent-Report 2026-04-29.
- Aktueller Code:
`gateway/modules/features/commcoach/`,
`frontend_nyla/src/pages/views/commcoach/`.
- Aktuelles Konzept (veraltet):
`gateway/modules/features/commcoach/CONCEPT.md`.
## Abschluss
- [ ] `wiki/b-reference/gateway/features/commcoach.md` neu anlegen
- [ ] `wiki/TOPICS.md` Eintrag "ComCoach"
- [ ] `gateway/modules/features/commcoach/CONCEPT.md` aktualisieren
- [ ] Dieses Dokument -> `z-archive/` verschoben
Reference in a new issue View git blame Copy permalink