CG-Feedback-Monitor/docs/HANDOVER.md

# Handover-Dokument — Assignment Monitor V2

Einstieg für neue Chat-/Dev-Sessions. **Produktiv** (`c:\dev\AssigmentMonitor`) niemals anfassen.

> **DEV-Isolation:** Repo `AssigmentMonitorV2` · Ports **5174 / 4001** · SQLite `assignment-monitor-v2-dev.sqlite3`  
> Details: [`DEV_ISOLATION.md`](./DEV_ISOLATION.md) · Team-Verteilung: [`TEAM_SETUP.md`](./TEAM_SETUP.md) · Offene Punkte: [`STATUS_UND_OFFENE_PUNKTE.md`](./STATUS_UND_OFFENE_PUNKTE.md)

---

## Stand (2026-08-16)

**Arbeitsverzeichnis:** `C:\dev\AssigmentMonitorV2`

### Zuletzt umgesetzt (Auswahl)

| Wann | Thema |
|---|---|
| 2026-08-16 | **Personen v2** E-Mail Pflicht · Gruppen umbenennen/löschen · Verschieben · Excel-Import · Archiv · Detail (Assignments/Feedbacks/Entwicklung) · Lösch-Kaskade |
| 2026-08-16 | **UX.3 Teil 1** Nav (Assignments/Feedbacks/Personen/Einstellungen) · Dashboard-Kachel-Grid · Plandaten · Typ-Farben · Filter/Überfällig |
| 2026-08-16 | **UX.1–UX.2** Design-Tokens + App-Chrome · **C0** Smoke · **C6/C7** Tagging/KI · **T2** Dexie entfernt |
| 2026-08 | Assignment-**Übergabe** Export/Import (Lead→Lead, inkl. Berater/Checklisten/Notizen) |
| 2026-08 | Team-**Starter-Paket** (`starter:export` / `bootstrap` / `setup` / `pack:zip`) |
| 2026-08 | Bewertungsskala **1–10**, Farbbänder, `meetingCategoryRatings` |
| 2026-08 | Feedback-Kaskade Stufe A (Kategorie) → B (Dimension), Benefits/Concerns |
| 2026-07 | Checklisten, selbstlernendes Kriterien-Tagging, PDF-Exporte, Papierkorb/Archiv, Meeting-Historie |
| 2026-07-04 | Lokaler Node/Express + `node:sqlite` statt IndexedDB als Primärspeicher |

**Laufende Arbeitsliste Feedback/KI:** [`FEEDBACK_CASCADE_PLAN.md`](./FEEDBACK_CASCADE_PLAN.md) — Pakete **0**, 1–3, 1b, **6, 7**, 8.3 erledigt; 4/5 Code weitgehend (manuelles Smoke/5.3 offen).

**Kanonischer Status + offene Punkte:** [`STATUS_UND_OFFENE_PUNKTE.md`](./STATUS_UND_OFFENE_PUNKTE.md) — als Nächstes **T4**.

---

## Worum geht es?

PWA für die Live-Bewertung von Capgemini-Trainees („Institutees“) während Kunden-Assignments: Meetings protokollieren, Kriterien taggen, einschätzen, Abschluss-Feedback (Benefits/Concerns) erzeugen.

---

## Tech-Stack

| | |
|---|---|
| Frontend | **React 19** + TypeScript + Vite (PWA) |
| Routing | **React Router 7** (`react-router-dom`) |
| CSS | Tailwind v4 — `@import "tailwindcss"`, Brand `brand` / `#0070AD` |
| Daten | Lokaler **Express** + **`node:sqlite`** (kein better-sqlite3), RPC `POST /api/rpc` |
| Ports (V2) | Frontend **5174**, API **4001** |
| DB-Datei | `server/data/assignment-monitor-v2-dev.sqlite3` (gitignored) |
| Tabellen | **26** — einzige Quelle: `server/db/tableRegistry.ts` |

```bash
npm run dev:all    # Vite :5174 + API :4001
npx tsc -b         # TypeScript — NICHT tsc --noEmit am Root
npm run setup      # Starter-Struktur einspielen
npm run pack:zip      # Team-ZIP nach dist-release/ (ohne DB)
npm run pack:laptop   # Umzug: Code + volle Dev-DB
```

---

## Bewertungsskala (1–10)

```typescript
type RatingScore = number  // 1–10 ganzzahlig; unset = null (kein N/A-String mehr)
```

- Farbbänder konfigurierbar: Config → **Skala** (`ratingColorBands` in `appSettings`)
- Notation in Protokollen: **führende Zahl** `1`–`10` am Zeilenanfang (`parseNotationPrefix`); `>` Zitat, `[…]` Abschnitte bleiben
- Meeting-Pflichtscore oft auf **Kategorie**-Ebene (`meetingCategoryRatings`); Kriterien bleiben Beobachtungs-/Detail-Ebene
- Aggregation: gewichtet `Σ(score×weight)/Σ(weight)`; `Σweight===0` → null; Details `docs/SCALE_1_TO_10.md`

**Legacy:** Alte Enum-Skala `not_client_ready` … und Notation `+`/`!` sind abgelöst — nicht neu einbauen.

---

## Datenmodell-Kern

### `criteriaId`-Semantiken (unverändert kritisch)

```
Assessment.criteriaId                 → FeedbackCriterionItem.id
ConversationSkillScore.criteriaId     → FeedbackCategory.id
ConversationLineTag.criterionItemId   → FeedbackCriterionItem.id
```

### Sichtbare Struktur je Assignment-Typ

`AssignmentType.criteriaIds` (leer = alle). Kanonisch:

`resolveVisibleStructure()` / `filterVisibleFeedbackStructure()` in `src/db/queries/feedbackStructure.ts` — nicht erneut inline.

### Checkliste

- `PhaseTemplate.hasChecklist` + `checklistItemDefs` / `checklistResponses`
- Effektives Kriterium: Antwort-Override oder Config-`linkedCriterionItemId` (`getEffectiveChecklistCriterionId`)
- UI im Gesprächsprotokoll-Tab (kein eigener Meeting-Tab)
- Tagging: eigener Prompt `checklistTaggingPromptTemplate` (`PUNKT n:`), getrennt vom Protokoll (`ZEILE n:`)

---

## Routing

```
/                                              Dashboard (+ Import Übergabe)
/assignment/new
/assignments/trash | /assignments/archive
/assignment/:id                                Detail (+ Export Übergabe, PDF)
/assignment/:id/edit
/assignment/:id/history                        Gesamtprotokoll
/assignment/:id/meeting/:meetingId             MeetingView  ← meetingId ≠ Assignment-ID
/assignment/:id/feedback/:instituteeId
/assignment/:id/feedback-draft/:instituteeId   Legacy
/evaluation | /consultants | /config
```

---

## Konfiguration (6 Tabs)

| Tab | Inhalt |
|---|---|
| Feedback | Dimensionen → Kategorien → Kriterien (Gewicht 0,0–2,0) |
| Ass.-Typen | Phasen, Checklisten, Kriterien-Sichtbarkeit, Standard-Zuordnung (KI) |
| Gewichtung | Zeitgewichtungs-Faktor Trend |
| Skala | Farbbänder 1–10 |
| KI-Prompts | Kategorie-/Dimension-Templates, Protokoll- + Checklisten-Tagging |
| Backup | Voll-Backup JSON (Wipe-Import) |

---

## Team & Übergabe

| Zweck | Wie |
|---|---|
| Frische Struktur ohne Personen | `docs/starter/starter-structure.json` · `npm run setup` |
| ZIP an Kollegen | `npm run pack:zip` → `dist-release/` · Anleitung `EINRICHTUNG.md` |
| Laptop-Umzug (Code + volle DB) | `npm run pack:laptop` → `dist-release/` · Anleitung `UMZUG.md` |
| Assignment an anderen Lead | Detail **↔ Übergabe** / Dashboard **↔ Import** (`assignmentTransfer`) |

Import prüft Berater per Vor-/Nachname (wiederverwenden oder anlegen); Feedback-Struktur muss auf dem Ziel (Starter) passen.

---

## Stil-Regeln

- Keine Kommentare außer nicht-offensichtlichen Invarianten
- Kein Auto-Resize-Textarea via `rows={1}` + JS
- Scores: `ScorePicker` / `resolveScoreStyle` / `RATING_SCORES` — keine alten `RATING_OPTIONS`-Enums neu erfinden
- Gewichtete Mittel: immer `weightedAverageScore` / `weightedAverageRating` in `ratingTrend.ts`
- Zeilen splitten: `splitNoteLines()` — nicht `note.split('\n')` inline
- Cross-Boundary: Dateien für Client+Server nur aus `src/db/types.ts` / `src/config/constants.ts` (in `tsconfig.server.json` include)

---

## Datenschutz

- Daten nur lokal unter V2-`server/data/` · kein Cloud-Upload
- GDPR: Institutee-/Kundennamen, Gesprächsnotizen
- KI-Key in `localStorage` — nie loggen
- Backup- und Übergabe-JSON = personenbezogen → vertraulich
- Produktiv-Backup nicht in V2-Experimente mischen

---

## Fallstricke

1. `MeetingInstance.generalNotes` → immer `?? ''`
2. `Assessment.criteriaId` ≠ Kategorie-ID
3. `npx tsc --noEmit` am Root prüft nichts — immer `npx tsc -b`
4. V2-Ports 5174/4001 — Start bricht bei 5173/4000 ab
5. Protokoll-Tagging-Prompt in DB darf kein `{{CHECKLISTEN_PUNKTE}}` mehr enthalten (Auto-Migration in `getOrSeedCriterionTaggingPromptTemplate`)
6. Dexie/IndexedDB-Legacy ist entfernt (2026-08-16) — nicht wieder einführen; Struktur über Starter/`npm run setup`