CG-Feedback-Monitor/docs/FACHLICHE_ARCHITEKTUR.md

# Fachliche Architektur — Assignment Monitor

## Zweck und Kontext

Assignment Monitor ist eine Progressive Web App (PWA) zur **Live-Begleitung und Bewertung von Capgemini-Trainees** (Institutees) während ihrer Kunden-Assignments. Die App wird vom jeweiligen Lead (Führungskraft / Mentor) auf dem Smartphone genutzt, um:

- Kundentermine strukturiert zu protokollieren
- Beobachtungen und Bewertungen in Echtzeit zu erfassen
- Am Ende eines Assignments ein qualifiziertes Feedback vorzubereiten

**Nutzer:** Lars Stommer (Capgemini Management Consultant Trainee Program Lead)  
**Sprache der App:** Deutsch (Bedienoberfläche), Englisch (Rating-Labels)  
**Datenschutz:** Alle Daten bleiben lokal im Browser (IndexedDB). Kein Public Cloud Upload.

---

## Fachliche Entitätenhierarchie

```
AssignmentType                        ← Konfiguration (z.B. "Case Interview")
  └── PhaseTemplate[]                 ← Definierter Meeting-Flow des Typs
  └── criteriaIds: FeedbackCriterionItem[] ← Welche Kriterien gelten für diesen Typ

Assignment                            ← Ein konkretes Kundenprojekt
  └── AssignmentType                  ← Zugeordneter Typ
  └── Institutees: Consultant[]       ← Begleitete Berater (1–n)
  └── MeetingInstance[]               ← Durchgeführte Meetings je Phase

MeetingInstance                       ← Ein konkreter Termin (z.B. "Briefing Call #1")
  └── PhaseTemplate                   ← Welche Phase des Assignments
  └── ConversationEntry[]             ← Zeitleiste: wer spricht wann
  └── Assessment[]                    ← Gesamtbewertung pro Institutee am Ende

ConversationEntry                     ← Ein Gesprächsbeitrag eines Institutees
  └── ConversationSkillScore[]        ← Kategorie-Schnellbewertung (während des Beitrags)

FeedbackDimension                     ← Übergeordnete Dimension für das Assignment-Feedback
  └── FeedbackCategory[]              ← Kategorie (z.B. "Kommunikationsfähigkeit")
    └── FeedbackCriterionItem[]       ← Einzelnes Kriterium (z.B. "To the point")

AssignmentFeedback                    ← Strukturiertes Abschluss-Feedback pro Institutee
  └── FeedbackCategoryRating[]        ← Bewertung je Kategorie
  └── FeedbackDimensionText[]         ← Freitext Achievements + Development Needs je Dimension
```

---

## Meeting-Phasen

Jeder AssignmentTyp definiert einen geordneten Flow von PhaseTemplates. Die drei vordefinierten Typen haben folgende Phasen:

| Phase | Mit wem | Wdh. | Protokoll | Bewertung | Generisch | Case | Pitch |
|---|---|:-:|:-:|:-:|:-:|:-:|:-:|
| Pre-Briefing (Lead) | Lead | — | — | — | ✓ | ✓ | ✓ |
| Briefing (Kunde) | Kunde | — | ✓ | ✓ | ✓ | ✓ | ✓ |
| Alignment Call | Kunde | **✓** | ✓ | ✓ | ✓ | — | ✓ |
| Pre-Delivery (Lead) | Lead | — | — | — | ✓ | — | ✓ |
| Delivery / Pitch | Kunde | — | ✓ | ✓ | ✓ | ✓ | ✓ |
| Feedback Call (Kunde) | Kunde | — | ✓ | ✓ | ✓ | ✓ | ✓ |
| Feedback Call (Lead) | Lead | — | — | — | ✓ | ✓ | ✓ |

Wiederholbare Phasen (z.B. Alignment Calls) werden mit fortlaufendem `phaseIndex` und Dateinamen-Suffix `-#2`, `-#3` etc. gekennzeichnet.

---

## Bewertungssystem

### Skala

| Label | Kürzel | Farbe | Numerischer Wert |
|---|---|---|:-:|
| N/A | N/A | grau | 0 |
| Not Client Ready | Not | rot | 1 |
| Partially Client Ready | Partially | orange | 2 |
| Nearly Client Ready | Nearly | hellgrün | 3 |
| Client Ready | Fully | dunkelgrün | 4 |

`N/A` gilt als „nicht gesetzt" und wird aus allen Berechnungen ausgeschlossen.

### Aggregationslogik

**Gewichteter Durchschnitt** über alle Kriterien mit `weight`-Faktor (×1–×5):

```
avg = Σ(score_i × weight_i) / Σ(weight_i)
```

Mapping auf Rating:
- `avg < 1.5` → Not
- `avg < 2.5` → Partially
- `avg < 3.5` → Nearly
- `avg ≥ 3.5` → Fully

### Zwei Assessment-Ebenen

1. **Kategorie-Level (live, während Gesprächsbeitrag):** `ConversationSkillScore.criteriaId` → `FeedbackCategory.id`  
   Schnelle Bewertung während ein Institutee spricht. Optional, da im Hektik oft nicht machbar.

2. **Kriterium-Level (Gesamtbewertung am Ende des Meetings):** `Assessment.criteriaId` → `FeedbackCriterionItem.id`  
   Detaillierte Bewertung je Kriterium nach dem Meeting. Grundlage für die Kategorie-Farbkodierung im Gesamtbewertungs-Tab.

---

## Feedback-Struktur (Abschluss-Feedback)

Die Feedback-Struktur ist vollständig konfigurierbar und von der Meeting-Bewertungsstruktur **getrennt**. Sie spiegelt das Capgemini-Kompetenzmodell wider:

| Dimension | Kategorien (Beispiele) |
|---|---|
| Mindset, Commitment, Collaboration | Persönliche Einstellung, Professionalität, Commitment, Kommunikationsfähigkeit, Zusammenarbeit |
| Running Our Projects | Ergebnisverantwortung, Arbeitsstil, Kundenmanagement, Lieferzeiten |
| Growing our People | Networking, Learning und Development |
| Functional & Technical Skills | Qualität des Inhalts, Inhaltliche Vollständigkeit, Qualität der Unterlage, Prozesstreue |
| Innovation und Asset Development | Innovation |

Das Abschluss-Feedback (`AssignmentFeedbackPage`) erlaubt:
- Manuelle Bewertung je Kategorie (N/A bis Fully)
- KI-gestützten Textentwurf via OpenRouter API (GPT-4o, Claude, Gemini)
- Manuell editierbare Textfelder „Achievements" und „Development Needs" je Dimension
- Status-Toggle: Entwurf → Final

---

## Protokoll-Notation

Im Gesprächsprotokoll unterstützt die App eine Schnellnotations-Syntax, die farbig gerendert wird:

| Symbol | Bedeutung | Darstellung |
|---|---|---|
| `+` | Positiv | grün |
| `(+)` | Positiv mit Abstrichen | grün (gedimmt) |
| `!` | Negativ | rot |
| `(!)` | Negativ mit Abstrichen | rot (gedimmt) |
| `>` | Einwand / Kundeninput | blau |
| `[…]` | Slide-/Dokument-Referenz | grau |

---

## Export-Funktionen

### Meeting-Export
**Format:** `{AssignmentNummer}_{Datum}_{PhasenLabel}{-#Nr}.{md|json}`  
**Beispiel:** `CGI-2024-001_02-07-2026_Alignment Call-2.md`

- **Markdown:** Lesbare Dokumentation mit Protokoll, Bewertungen und Notizen
- **JSON:** Vollständige Datensicherung eines einzelnen Meetings

### Datenbank-Backup
Vollständiger Export aller Tabellen als JSON-Datei. Import löscht alle Daten und stellt den gesicherten Stand wieder her. Backup sollte nach jedem Meeting erstellt werden.

---

## Datenschutz und Datenhaltung

- Alle Daten bleiben im **lokalen Browser-IndexedDB** (Dexie.js)
- Kein Backend, kein Cloud-Sync
- Personenbezogene Daten: Namen von Institutees, Kundennamen, Gesprächsnotizen
- GDPR-relevant: Backup-Dateien müssen sicher (OneDrive, lokaler Ordner) aufbewahrt werden
- **Kein Public Cloud Storage** erlaubt (explizite Anforderung)
- Zukünftig geplant: SQLite WASM + OPFS für robustere lokale Speicherung ohne Installation