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 · Team-Verteilung: TEAM_SETUP.md · Offene Punkte: 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 — 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 — 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

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)

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