<!-- status: plan -->
<!-- started: 2026-04-29 -->
<!-- component: gateway, frontend-nyla, teams-bot -->

# TeamsBot Greenfield-IA: MeetingModule + Live-Update-Fixes

## Beschreibung und Kontext

Die TeamsBot-UI ist aktuell:

- 3 Tabs (Dashboard "Uebersicht", Sitzungen, Einstellungen).
- Kein Meeting-Entity -- alles ist `TeamsbotSession.meetingLink`. Wer
  z.B. ein wiederkehrendes Weekly-Standup ueber Wochen verfolgen will,
  muss die Sessions per Datum suchen.
- Kein "Modul"-Konzept fuer Reihen (wie der User wuenscht).
- Live-Updates haengen an SSE in `TeamsbotSessionView.tsx` mit
  `useEffect`-Deps `[instanceId, sessionId]` only (Z. 327-328) +
  `eslint-disable` -- reagiert daher NICHT zuverlaessig auf
  Status-Wechsel und auf neue `agentRun`-Events. Letztere sind nur
  `_dlog`, NICHT in der UI sichtbar.
- `stats`-Payload aus `getSession`-API
  (`routeFeatureTeamsbot.py` 357-358) wird vom Frontend ignoriert.
- Dashboard-Counts haben 10s Lag (Polling).

**Geschaeftstreiber:** User finden sich nicht zurecht; Live-Bedienung
wirkt fragil ("zeigt das hier ueberhaupt was Aktuelles?"). Mit Modul-
of-Sessions-IA (analog ComCoach) und sauberen Live-Update-Pfaden wird
TeamsBot zum verlaesslichen Meeting-Tool.

## Fokus und kritische Details

- **Live-Update ist UX-kritisch** -- Session-State, agentRun-Indicator
  und Stats muessen waehrend laufender Meetings sichtbar pulsieren.
- SSE-`useEffect`-Deps nicht naiv aufschnueren -- sonst Reconnect-
  Flicker bei jedem Status-Bit-Wechsel. Loesung: dedizierter Reconnect-
  Hook, der nur reconnektet wenn (a) sessionId wechselt oder (b) Session
  von "terminal" zurueck zu "active" geht (sehr selten).
- Backend `stats`-Payload bereits vorhanden, nur nicht gebunden.
- `MeetingModule` ist additiv -- alte `TeamsbotSession`-Eintraege
  bekommen `moduleId` per Migration (Default-Modul "Adhoc").

## Ziel und Nicht-Ziele

- Ziel:
  - 5-Tab-IA (Dashboard, Assistent, Module, Live-Session, Einstellungen).
  - `MeetingModule`-Entity (Reihe + KPIs + Default-Bot + Default-
    Director-Prompts).
  - 4 Live-Update-Fixes (siehe unten F-fix-1 .. F-fix-4).
- NICHT: Aenderung an Bot-Bridge (.NET Media-Bridge bleibt).
- NICHT: WebSocket-Migration im Frontend (SSE bleibt, ist Architektur-
  Entscheid).
- NICHT: Multi-Mandate-Sharing von Modulen.

## Betroffene Module

- Gateway:
  - `gateway/modules/features/teamsbot/datamodelTeamsbot.py` -- neue
    Klasse `TeamsbotMeetingModule`, FK `TeamsbotSession.moduleId`
    (nullable in Uebergangsphase).
  - `gateway/modules/features/teamsbot/interfaceFeatureTeamsbot.py` --
    CRUD fuer `MeetingModule`.
  - `gateway/modules/features/teamsbot/routeFeatureTeamsbot.py` --
    neue Routen `/modules/...`, `agentRun`-Event sauberer schicken,
    `stats`-Payload kontinuierlich anreichern.
  - `gateway/modules/features/teamsbot/mainTeamsbot.py` -- RBAC-Keys
    auf 5 Tabs, optional Default-MeetingModule-Templates.
- Frontend:
  - `frontend_nyla/src/types/mandate.ts` 244-252 -- TeamsBot-Sidebar
    3 -> 5 Eintraege.
  - `frontend_nyla/src/pages/FeatureView.tsx` 159-163 -- View-Mapping
    aktualisieren.
  - `frontend_nyla/src/pages/views/teamsbot/` -- vorhandene Komponenten
    aufteilen:
    - `TeamsbotDashboardView` -- KPIs erweitern (Modul-Aggregate +
      Gamification).
    - `TeamsbotAssistantView` (NEU) -- Wizard.
    - `TeamsbotModulesView` (NEU) -- Modul-CRUD + Sessions je Modul.
    - `TeamsbotSessionView` -- bleibt, jetzt nur Live-Session.
    - `TeamsbotSettingsView` -- bleibt.
  - `frontend_nyla/src/api/teamsbotApi.ts` -- Module-API + neuer
    Reconnect-Hook.
- DB-Migration: ja (additive Tabelle + nullable FK).

## Zieldatenmodell

```mermaid
flowchart LR
  Inst[FeatureInstance teamsbot] --> Mod[MeetingModule]
  Mod --> Sess[TeamsbotSession meetingLink]
  Sess --> Trans[Transcript]
  Sess --> Resp[BotResponse]
  Sess --> Dir[DirectorPrompt]
  Mod --> Kpi[ModuleKpi/Goals]
  Mod --> DefBot[Default Bot]
  Mod --> DefDir[Default Director Prompts]
```

`MeetingModule` Felder (Auszug):

| Feld | Typ | Bedeutung |
|------|-----|-----------|
| `id` | UUID | PK |
| `instanceId` | UUID | FeatureInstance-Scope |
| `mandateId` | UUID | Tenant |
| `ownerUserId` | UUID | Owner |
| `title` | text | "Weekly Standup", "Q3 Sales Review-Reihe" |
| `seriesType` | enum | `weekly` \| `biweekly` \| `monthly` \| `adhoc` \| `project` |
| `defaultBotId` | UUID? | `TeamsbotSystemBot` |
| `defaultDirectorPrompts` | jsonb | Liste vorausgefuellter Director-Prompts |
| `goals` | text | -- |
| `kpiTargets` | jsonb | -- |
| `status` | enum | `active` \| `archived` \| `completed` |

## IA: 5 Tabs (final)

| # | Tab | Zweck | Komponente |
|---|------|-------|-------------|
| 1 | Dashboard | Gamification (Talking-Time, Director-Trefferquote, beliebteste Prompts), aktive Module/Sessions, Quick-Action "Neues Meeting" | `TeamsbotDashboardView` |
| 2 | Assistent | Wizard: Modul waehlen oder neu -> Meeting-Link/Auto-Join -> Bot starten | `TeamsbotAssistantView` |
| 3 | Module | CRUD-Liste aller Meeting-Module, pro Modul aufklappbare Session-Liste | `TeamsbotModulesView` |
| 4 | Live-Session | aktive Sitzung: Regie-Panel, UDB-Sidebar, Transkript, Antworten, Bot-Status, MFA, Stats-Karten | `TeamsbotSessionView` (refactor) |
| 5 | Einstellungen | Bot-Account, Stimme, System-Bots (SysAdmin) | `TeamsbotSettingsView` |

## Use-Case-Mapping

| Use-Case | Tab(s) | Hauptaktion |
|----------|--------|-------------|
| 1 Gamification-Dashboard | Dashboard | Talking-Time + Modul-KPIs |
| 2 Assistent: neues Meeting | Assistent -> Live-Session | Wizard durchklicken |
| 3 Session-Operations | Live-Session | Stop, Director-Prompts, MFA, Stats |
| 4 Listen CRUD | Module | Module + Sessions je Modul pflegen |
| 5 Instanzen-Einstellungen | Einstellungen | Bot, Stimme, System-Bots |

## Live-Update-Fixes (parallel zur IA)

### F-fix-1: SSE-Reconnect-Hook

- Problem: `useEffect` `[instanceId, sessionId]`-only haengt nicht an
  `session.status` -> Reconnect bei legitimen Status-Wechseln nicht
  garantiert.
- Loesung: Eigener Hook `useTeamsbotSessionStream(instanceId, sessionId,
  isTerminal)` der intern reconnectet wenn `isTerminal` von `true` ->
  `false` flippt (z.B. nach manuellem Re-Start einer beendeten Session).
  Andere Status-Bits triggern KEINEN Reconnect.

### F-fix-2: agentRun-Event sichtbar

- Problem: `agentRun`-SSE-Events sind nur `_dlog`
  (`TeamsbotSessionView.tsx` 290-293).
- Loesung: Status-Bubble in der Live-View ("Agent denkt nach: <toolName>...")
  als kurzlebige animierte Komponente.

### F-fix-3: stats-Karten

- Problem: `getSession`-API liefert `stats` (Sprechminuten, Bot-
  Antworten, Latenz) -- Frontend ignoriert.
- Loesung: Header-Karten in `TeamsbotSessionView` gebunden an
  `session.stats`. Aktualisierung kommt automatisch via SSE
  `sessionState`-Events (Backend muss `stats` mitliefern -- ggf.
  Backend-Anpassung in `routeFeatureTeamsbot.py`).

### F-fix-4: Dashboard-Counts ohne 10s-Lag

- Problem: Dashboard pollt `listSessions` alle 10s.
- Option A (kleiner Eingriff): bei aktiver Session 3s-Polling, sonst
  30s.
- Option B (besser): SSE-Channel pro Mandate
  `/api/teamsbot/{instanceId}/dashboard/stream` mit "session-tick"-
  Events (Counter-Updates push, kein Polling).
- **Default:** Option A in Phase 4, Option B als Follow-up.

## Entscheidungen

| Datum | Entscheidung | Begruendung |
|-------|-------------|------------|
| 2026-04-29 | Neues `MeetingModule`-Entity additiv | Reihen-Konzept gewuenscht; bestehende Sessions in "Adhoc"-Modul |
| 2026-04-29 | 5 Tabs (statt 3) | Use-Cases brauchen klare Trennung Assistent/Module/Live |
| 2026-04-29 | SSE bleibt (kein WS) | Architektur stabil, Browser-Bot nutzt WS, Frontend nicht |
| 2026-04-29 | Dashboard-Counts: Adaptive Polling jetzt, SSE-Channel als Follow-up | Pragmatisch, schnell sichtbar |

## Umsetzungs-Checkliste

### Phase 1 -- Backend Datenmodell + Routes

- [ ] `datamodelTeamsbot.py`:
      - Neue Klasse `TeamsbotMeetingModule`.
      - `TeamsbotSession.moduleId Optional[UUID]` additiv.
- [ ] DB-Migration:
      `script_db_init_teamsbot_meeting_modules.py` -- legt Tabelle an,
      erzeugt pro `instanceId` ein Default-`Adhoc`-Modul, setzt
      bestehende Sessions auf dieses Modul.
- [ ] `interfaceFeatureTeamsbot.py` -- CRUD-Methoden fuer Module.
- [ ] `routeFeatureTeamsbot.py`:
      - Neue Routen `GET/POST/PUT/DELETE /modules/...`.
      - `getSession` liefert `stats` (existiert), `listSessions` 
        ergaenzt `moduleId` im Payload.
      - SSE: `sessionState`-Event traegt jetzt auch `stats`.
      - SSE: `agentRun`-Event sauberer schicken (toolName, status:
        `started`/`finished`/`failed`).

### Phase 2 -- Backend Live-Stats anreichern

- [ ] `_buildSessionStats(session) -> SessionStats` zentral, in
      jedem `sessionState`-SSE-Event aufrufen (nicht nur on-demand).

### Phase 3 -- Frontend Routing & Sidebar

- [ ] `frontend_nyla/src/types/mandate.ts` 244-252 TeamsBot-Eintraege
      auf 5 Eintraege.
- [ ] `frontend_nyla/src/App.tsx` Routes ergaenzen (`assistant`,
      `modules`).
- [ ] `frontend_nyla/src/pages/FeatureView.tsx` View-Mapping
      aktualisieren.

### Phase 4 -- Frontend Komponenten

- [ ] NEU `TeamsbotAssistantView` -- Wizard 3 Steps (Modul-
      Auswahl/Neu, Meeting-Link, Bot-Auswahl) -> "Bot starten" ->
      Navigation `live-session?sessionId=...`.
- [ ] NEU `TeamsbotModulesView` -- Liste, CRUD, aufklappbare Sessions.
- [ ] `TeamsbotSessionView` Refactor:
      - Reconnect-Hook (F-fix-1) integrieren.
      - Status-Bubble fuer agentRun (F-fix-2).
      - Stats-Karten im Header binden (F-fix-3).
- [ ] `TeamsbotDashboardView`:
      - Polling adaptiv (F-fix-4 Option A).
      - Modul-Aggregate-Sektion ergaenzen (Top-Module nach
        Session-Count, Talking-Time-Verteilung etc.).

### Phase 5 -- Doku

- [ ] `wiki/b-reference/teams-bot/architecture.md` Module-Sektion
      ergaenzen, Live-Update-Pfade dokumentieren.
- [ ] `wiki/TOPICS.md` ggf. Eintrag "TeamsBot Module".

## Akzeptanzkriterien

| # | Kriterium (Given-When-Then) | Prio |
|---|-----------------------------|------|
| 1 | Given Sidebar TeamsBot, When User es oeffnet, Then sieht er 5 Tabs (Dashboard, Assistent, Module, Live-Session, Einstellungen) | must |
| 2 | Given Tab Module, When User auf "Neues Modul" klickt, Then kann er Titel, Series-Typ, Default-Bot, Director-Prompts, KPIs setzen | must |
| 3 | Given Modul existiert, When User auf "Neue Session" klickt, Then wird eine `TeamsbotSession` mit `moduleId` angelegt und im Live-Tab geoeffnet | must |
| 4 | Given Live-Session laeuft, When der Backend-Agent ein Tool aufruft, Then erscheint im UI ein Status-Bubble "Agent denkt nach" mit Tool-Name | must |
| 5 | Given Live-Session laeuft, When sich Sprechminuten/Bot-Antworten/Latenz aendern, Then aktualisieren die Stats-Karten ohne Page-Reload | must |
| 6 | Given Session terminiert (z.B. Stop), When User auf gleicher Seite bleibt, Then schliesst die SSE sauber, kein Reconnect-Loop | must |
| 7 | Given Bestand-Sessions ohne Modul, When Migration laeuft, Then sind alle Sessions im Default-`Adhoc`-Modul je Instanz einsortiert | must |
| 8 | Given Dashboard offen, When eine aktive Session laeuft, Then aktualisieren die Counter spaetestens nach 3s | should |
| 9 | Given keine aktive Session, When Dashboard offen, Then aktualisiert es nur alle 30s | should |

## Testplan

| ID | AC | Art | Automatisiert | Repo-Pfad | Status |
|----|----|-----|--------------|-----------|--------|
| T1 | 1 | unit | ja | frontend_nyla/src/types/__tests__/mandate.test.ts | pending |
| T2 | 2,3 | e2e | ja | frontend_nyla/tests/e2e/teamsbot-modules-crud.spec.ts | pending |
| T3 | 4 | unit | ja | frontend_nyla/src/pages/views/teamsbot/__tests__/TeamsbotSessionView_agentRun.test.tsx | pending |
| T4 | 5 | integration | ja | frontend_nyla/tests/integration/teamsbot-stats-binding.spec.ts | pending |
| T5 | 6 | manual | nein | -- | pending |
| T6 | 7 | integration | ja | gateway/tests/features/teamsbot/test_migration_modules.py | pending |
| T7 | 8,9 | manual | nein | -- | pending |

## Links

- Audit-Quelle: Subagent-Report 2026-04-29.
- Aktueller Code: `gateway/modules/features/teamsbot/`,
  `frontend_nyla/src/pages/views/teamsbot/`.
- Wiki: `wiki/b-reference/teams-bot/architecture.md`,
  `wiki/c-work/4-done/2026-04-teamsbot-director-prompts.md`.

## Abschluss

- [ ] `wiki/b-reference/teams-bot/architecture.md` aktualisiert
- [ ] `wiki/TOPICS.md` ggf. neuer Eintrag
- [ ] Dieses Dokument -> `z-archive/` verschoben