Kansho/docs/work_orders/debug_diagnostics_perfection.md

title	status	date	document_role	canonical_architecture
Kanshō – Arbeitsauftrag Debug-Diagnostik und Export	Arbeitsauftrag	2026-08-31	Cursor Implementation Brief	docs/architecture/technical/admin_diagnostics.md

Arbeitsauftrag: Debug-Diagnostik und Export konsolidieren

Arbeite im aktiven Repository C:\dev\Kansho.

Dieses Dokument ist ein Umsetzungsauftrag. Es ersetzt keine kanonische Fach- oder Technikdokumentation. Neue Entscheidungen und der tatsächliche Implementierungsstand sind additiv in den jeweils zuständigen Dateien unter docs/architecture/ zu dokumentieren.

Ausgangslage

Die bestehende Diagnostik enthält bereits viele wertvolle Informationen. Sie ist aber über verschiedene Seiten und Exportwege verteilt. Je nachdem, ob ein Export aus einem Dialog, einem Tag oder einer Generierung gestartet wird, entsteht ein anderer und teilweise sehr großer JSON-Export.

Dadurch ist oft unklar:

• welche Läufe im Export enthalten sind,
• welche Dialoge und Generierungen zu einem Tag gehören,
• warum ein Lauf fehlgeschlagen ist,
• welche Fassung tatsächlich angezeigt oder gespeichert wurde,
• und an welcher Stelle der passende Export ausgelöst werden muss.

Teilweise werden dieselben Daten mehrfach eingebettet. Das macht Exporte unnötig groß und ihre Analyse schwierig.

Die bereits ergänzte Speicherung fehlgeschlagener Detect- und Journal-Läufe muss erhalten bleiben.

Ziel

Baue eine zentrale, verständliche Admin-Diagnostik mit einem einheitlichen Exportverfahren.

Ein Administrator soll gezielt auswählen können:

1. welchen Reflection Space,
2. welchen Tag oder Zeitraum,
3. welche Dialoge,
4. welche Generierungsläufe – auch mehrere,
5. welche Laufarten und Status,
6. und welche Detailinformationen

der Export enthalten soll.

Die Diagnose soll sowohl für eine schnelle Sichtprüfung in der Oberfläche als auch für eine genaue externe Analyse des JSON geeignet sein.

Vor der Umsetzung

Lies zunächst:

• docs/architecture/functional/documentation_index.md,
• docs/architecture/technical/documentation_index.md,
• docs/architecture/technical/admin_diagnostics.md,
• docs/architecture/technical/privacy_gateway.md,
• die bestehenden Debug-Routen, Datenmodelle und Frontend-Komponenten.

Prüfe die tatsächliche Implementierung und beschreibe kurz:

• die aktuellen Exportwege,
• vorhandene Doppelungen,
• fehlende Beziehungen,
• und welche Informationen bei Fehlern noch verloren gehen.

Leite die konkrete technische Lösung daraus ab. Übernimm nicht ungeprüft Annahmen aus diesem Auftrag.

Anforderungen

Zentrale Auswahl

Unter /admin/debug soll es einen zentralen Exportdialog geben.

Filter:

• Reflection Space,
• einzelner Tag oder Zeitraum,
• Dialoge als Mehrfachauswahl,
• Laufart beziehungsweise Purpose,
• Status,
• einzelne Run-IDs,
• optional Generierungszeitraum.

Vor dem Export soll sichtbar sein, wie viele Dialoge und Läufe durch die Auswahl erfasst werden.

Auswählbare Inhalte

Der Administrator soll bestimmen können, welche Bereiche enthalten sind:

• kompakte Zusammenfassung,
• chronologische Ereignis- und Aufrufübersicht,
• Modell, Provider, Token, Kosten und Laufzeiten,
• Generierungsrichtlinien und wirksame Auswahl,
• wirksame Stilanwendung einschließlich tatsächlich eingebundener Profilbestandteile,
• verwendete Quellen,
• Privacy- und Detection-Diagnostik,
• Validierung und Fehlerursachen,
• Provideranfrage und Providerantwort,
• sichtbare und gespeicherte Ausgabe,
• vollständige Prompts und maskierter Provider-Egress.

Sensible Inhalte wie vollständige Prompts, Quellen und Rohantworten müssen ausdrücklich zugeschaltet werden. Zeige dabei einen klaren Warnhinweis.

Lokale Mappingtabellen, Secrets, Zugangsdaten und andere nicht benötigte Identitätsdaten dürfen niemals exportiert werden.

Einheitliches Datenmodell

Erzeuge ein versioniertes, kanonisches Exportformat, beispielsweise Version 3.

Eine Information soll nur einmal enthalten sein. Beziehungen werden über IDs dargestellt, nicht durch wiederholtes Einbetten desselben Laufes unter Tag, Dialog und Generierung.

Eine mögliche oberste Struktur ist:

• manifest,
• selection,
• entities,
• runs.

Die konkrete Struktur soll aus dem bestehenden Datenmodell abgeleitet werden.

Bestehende Exportwege dürfen entweder kompatibel weiterlaufen oder müssen kontrolliert auf das neue Format umgestellt werden. Dokumentiere die Entscheidung.

Vollständige Laufhistorie

Ein diagnostischer Lauf muss möglichst ab Beginn der Anfrage eine stabile Run-ID besitzen. Auch frühe Fehler sollen nachvollziehbar sein.

Unterscheide mindestens:

• laufend,
• erfolgreich,
• vor dem Provider fehlgeschlagen,
• Providerfehler,
• Detection fehlgeschlagen,
• Validierung fehlgeschlagen,
• Timeout,
• Clientabbruch,
• unvollständig beziehungsweise verwaist.

Vorhandene Statusbezeichnungen können weiterverwendet werden, wenn sie diese Fälle eindeutig abdecken.

Kosten oder Tokenwerte, die der Provider nicht geliefert hat, müssen als „nicht verfügbar“ beziehungsweise null erscheinen und dürfen nicht geschätzt als tatsächliche Werte ausgegeben werden.

Einheitliche Einstiegspunkte

Export-Schaltflächen auf Dialog-, Tages- oder Generierungsseiten sollen keine eigenen Exportlogiken mehr besitzen. Sie öffnen denselben zentralen Exportdialog mit sinnvoll vorbelegten Filtern.

Übersichtlichkeit

Die Adminoberfläche soll zuerst eine kompakte Übersicht zeigen. Technische Details werden erst bei Bedarf aufgeklappt.

Wichtig sind insbesondere:

• Status und Abbruchgrund,
• Dauer,
• Anzahl der Provideraufrufe,
• verwendetes Modell,
• Kosten und Token,
• Generate tatsächlich aufgerufen: ja/nein,
• Fallback verwendet: ja/nein,
• sichtbare und gespeicherte Fassung identisch: ja/nein.

Grenzen

• Keine Änderung an Journal-Prompts oder Generierungsrichtlinien.
• Keine Änderung der semantischen Detection.
• Keine Lockerung der Privacy-Regeln.
• Keine journal-spezifische Sonderarchitektur für allgemeine Runs.
• Keine zukünftige Memory-Architektur vorwegnehmen.
• Keine echten Provideraufrufe.
• Kein Commit und kein Tag.
• Bestehende uncommittete Änderungen erhalten.

Tests und Abnahme

Ergänze Regressionstests für mindestens:

1. Export eines einzelnen Dialogs.
2. Export eines Tages mit mehreren Dialogen.
3. Auswahl mehrerer Generierungsläufe.
4. Kombination erfolgreicher und fehlgeschlagener Läufe.
5. Persistenz eines Fehlers vor dem Generate-Aufruf.
6. Exakte Anwendung aller Filter.
7. Keine doppelte Einbettung eines Runs.
8. Sensible Inhalte nur nach ausdrücklicher Auswahl.
9. Niemals Secrets oder Identitäts-Mappingtabellen im Export.
10. Nicht-Admins erhalten keinen Zugriff.
11. Seitenspezifische Schaltflächen öffnen den zentralen Export mit korrekter Vorbelegung.
12. Bestehende MVP-Tests und Frontend-Build bleiben erfolgreich.

Dokumentiere die Änderung additiv in der bestehenden technischen Diagnostik-Dokumentation.

Abschlussbericht

Berichte anschließend:

1. bestätigte Ursachen,
2. fachliches Bedienkonzept,
3. neues Exportmodell und Versionsstrategie,
4. geänderte Dateien,
5. Behandlung erfolgreicher und fehlgeschlagener Läufe,
6. Datenschutzgrenzen,
7. ausgeführte Tests,
8. bewusst verbleibende MVP-Grenzen.

Nenne ausdrücklich, was nur durch Tests bewiesen wurde und was noch interaktiv im Browser geprüft werden sollte.