Design-Brief: Zeitgewichteter Bewertungs-Vorschlag (Auswertung & Abschluss-Feedback)

Status: Umgesetzt (2026-07-02). Design-Fragen mit Lars geklärt und implementiert — siehe CLAUDE.md (Abschnitt "zwei parallele Bewertungs-Strukturen", Erledigt-Liste) für den aktuellen Stand. Dieses Dokument bleibt als Kontext/Historie der Design-Entscheidungen erhalten.

Ausgangslage

Am 2026-07-02 wurde bei der Migration von Evaluation.tsx auf die neue Datenstruktur (feedbackCriterionItems) sichtbar, dass die App zwei komplett unabhängige, nicht synchronisierte Bewertungs-Strukturen hat:

Struktur	Tabelle	Wo gesetzt	Zweck
Meeting-Assessment	`assessments`	`MeetingView` (`pages/meeting/AssessmentTab.tsx`), pro Meeting, pro Kriterium	Live-Bewertung während/nach jedem Kundentermin
Abschluss-Feedback	`feedbackCategoryRatings`	`AssignmentFeedbackPage.tsx`, manuell pro Kategorie	Finales, für den Institutee bestimmtes Feedback am Assignment-Ende

Aktuell berechnet /evaluation (Evaluation.tsx) einen gleichgewichteten Durchschnitt aller assessments je Kriterium/Kategorie, gruppiert nach Assignment → Institutee. Das Abschluss-Feedback auf AssignmentFeedbackPage ist davon komplett entkoppelt — die Kategorie-Ratings dort werden per Klick frei gesetzt, nicht aus den Meeting-Daten abgeleitet. Der einzige bestehende Brückenschlag ist buildAiPrompt() in AssignmentFeedbackPage.tsx, der Assessment-Rohdaten in einen KI-Prompt packt (dieser Prompt hat aktuell noch einen offenen Bug: nutzt db.criteria, Legacy-Tabelle, sollte feedbackCriterionItems nutzen — siehe docs/STATUS_UND_OFFENE_PUNKTE.md, Punkt M2).

Fachlicher Wunsch (Lars, 2026-07-02, wörtlich sinngemäß)

Die Werte sollen aus den einzelnen Meetings berechnet werden — als Vorschlag. Dieser Vorschlag kann durch den Feedbackgeber überarbeitet werden. Eine parallele Ansicht ist daher möglicherweise sinnvoll. Bei der Berechnung der Vorschläge auf Kriteriumslevel über alle Meetings sollte auch die zeitliche Reihenfolge berücksichtigt werden. Es sollte honoriert werden, wenn sich der Berater über die Laufzeit des Assignments in bestimmten Kriterien verbessert hat. Verschlechterung über die Zeit sollte ebenfalls berücksichtigt werden (negative Lernkurve). Diese Entwicklung sollte dann auch im Kommentar an der richtigen Stelle berücksichtigt werden.

Kernpunkte:

Zeitgewichtung — spätere Meetings sollen stärker in den Kriterium-Durchschnitt einfließen als frühere (nicht der aktuelle gleichgewichtete Ansatz).
Trend-Erkennung — sowohl positive als auch negative Entwicklung über die Assignment-Laufzeit soll erkannt werden.
Automatische Kommentar-Integration — die erkannte Entwicklung soll an der "richtigen Stelle" im Feedback-Text auftauchen (vermutlich FeedbackDimensionText.achievements/developmentNeeds, evtl. über den bestehenden KI-Prompt-Mechanismus).
Vorschlag bleibt überschreibbar — die zwei Strukturen (Assessment vs. FeedbackCategoryRating) sollen bewusst getrennt bleiben; der berechnete Vorschlag ersetzt nicht die manuelle Entscheidung des Feedbackgebers.

Bereits vorhandene Bausteine (wiederverwendbar)

RATING_NUM_MAP in src/config/constants.ts — numerische Skala für Aggregation
weightedAvg() in src/pages/Evaluation.tsx — aktueller (ungewichteter nach Zeit) Aggregationsansatz auf Item-/Kategorie-Ebene, als Ausgangspunkt für die zeitgewichtete Variante
MeetingInstance.date — Zeitstempel pro Meeting, Basis für Zeitgewichtung
buildAiPrompt() in AssignmentFeedbackPage.tsx — bestehender Mechanismus, der Assessment-Daten in strukturierten Text für die KI übersetzt; möglicher Ort, um Trend-Informationen einzuspeisen
Bekannter Bug-Pattern, der bei jeder neuen Aggregationslogik zu beachten ist: score !== null schließt 'na' nicht aus — immer score !== null && score !== 'na' prüfen (siehe CLAUDE.md)

Offene Design-Fragen (in der Planungssession zu klären)

Gewichtungsformel: Linear nach Meeting-Reihenfolge? Exponentiell abfallend nach Alter? Feste Gewichte (z.B. letztes Meeting zählt doppelt)? Muss robust für Assignments mit 2 bis 7+ Meetings funktionieren.
Trend-Schwellenwert: Ab wann gilt eine Entwicklung als "signifikant" (z.B. mind. 1 Rating-Stufe Unterschied zwischen erstem und letztem gewerteten Meeting)? Wie viele Meetings mit Bewertung sind mindestens nötig, um überhaupt einen Trend zu behaupten?
Granularität: Wird der Trend auf Kriterium-Ebene, Kategorie-Ebene oder beidem berechnet?
UI-Darstellung des Vorschlags: Nebeneinander-Ansicht (Vorschlag vs. aktueller manueller Wert) mit "Übernehmen"-Button? Oder Vorschlag pre-fillt die Rating-Buttons direkt, überschreibbar wie jeder andere Wert?
Kommentar-Generierung: Deterministisch (Template-Satz wie "Zeigt über die Laufzeit eine Verbesserung in X") oder über den bestehenden KI-Prompt-Mechanismus? Wie wird das mit dem offenen AI-Prompt-Bug (M2) koordiniert?
Code-Ort: Soll die Trend-Berechnung eine gemeinsame Funktion sein, die sowohl Evaluation.tsx als auch AssignmentFeedbackPage.tsx nutzen (Vermeidung von Doppel-Logik)? Falls ja, wohin (src/db/queries/? neues src/utils/ratingTrend.ts?).
Naming/Labeling: Wie wird in der UI klar unterschieden zwischen "berechneter Vorschlag" und "final vom Feedbackgeber bestätigter Wert"?

Betroffene Dateien (voraussichtlich)

src/pages/Evaluation.tsx — zeigt den Vorschlag an
src/pages/AssignmentFeedbackPage.tsx — übernimmt/überschreibt den Vorschlag, generiert Kommentar
src/config/constants.ts — evtl. neue Konstanten für Gewichtungsparameter
Neue Datei denkbar: src/utils/ratingTrend.ts oder src/db/queries/ratingSuggestion.ts für die gemeinsame Berechnungslogik

5.8 KiB Raw Blame History