VianoBugAnalysis/docs/web-console.md

# Webübersicht

Die Betriebsübersicht wird durch die bestehende Übergabe-API ausgeliefert:

```powershell
.\.venv\Scripts\python.exe -m viano_bug_analysis.api serve --config config/api.local.toml
```

Anschließend `http://127.0.0.1:8080/` öffnen und mit **Benutzername und Passwort**
anmelden. Benutzer werden ausschließlich über privilegierte Konsolenbefehle
angelegt, geändert und gelöscht, siehe [Benutzerverwaltung](user-accounts.md).
Alle Webbenutzer haben dieselben Rechte für alle Projekte. Die unten beschriebenen
Client-/Projektberechtigungen gelten weiterhin für externe API-Integrationen.
Für entfernte Zugriffe HTTPS verwenden. Der Analyseworker läuft unabhängig davon wie unter
[Analyseworker](analysis-worker.md) beschrieben. Das Öffnen der Übersicht löst
keine Modellanfragen aus.

## Benutzeranleitung

Der Reiter **Benutzeranleitung** enthält die allgemeine Bedienung und
Funktionsweise sowie Anleitungen für Linux, Projekt-/DB-/Sourcekonfiguration,
Übergabe-API, Analyseworker, Nutzerkonten, Integrationsschlüssel, Weboberfläche
und Erfassungsworker. Dokumentauswahl, Inhaltsverzeichnis und interne Verweise
erlauben Navigation ohne Server-Dateizugriff. Markdown-Downloads sind ebenfalls
möglich. Der Reiter benötigt eine angemeldete Sitzung; sein Aufruf startet keine
Analyse. Tabellen, Codebeispiele und Überschriften werden als sichere DOM-Elemente
dargestellt, eingebettetes HTML wird nicht ausgeführt.

Für Dokumentationsänderungen die ursprünglichen Markdown-Dateien unter `docs/`
beziehungsweise `deploy/capture-worker/README.md` bearbeiten und danach
`python scripts/build_user_manual.py` ausführen. Die feste Auswahlliste steht im
Skript; tatsächliche lokale Konfigurationen oder Secrets werden nicht gebündelt.
`python scripts/build_user_manual.py --check` und die Tests erkennen veraltete
Webfassungen. Das erzeugte `web/user-manual.json` wird mit dem Python-Paket
ausgeliefert, sodass keine lokale Kopie des Dokumentationsordners nötig ist.

## Worker und Fortschritt

Die Startseite listet lebende Worker und darunter den jeweils bearbeiteten Fall
mit seinem Namen und einem Ladebalken. Der bestehende Dienst erlaubt einen Worker
je Workspace; die Darstellung ist bereits als Liste aufgebaut. Die Einführung
eines parallelen Worker-Pools ist damit nicht verbunden.

Der Balken folgt abgeschlossenen Arbeitsschritten, nicht vergangener Zeit. Seine
sieben Anteile entsprechen intern Aufnahme, Fallaufbau, Interpretation,
Hypothesenbildung, Untersuchung, Diagnose und Codingauftrag. Die Oberfläche führt
diese Stufen nicht einzeln auf. Der Codingauftrag ist die letzte Stufe, auch wenn
sein Dokument fachlich erklärt, dass kein Codingauftrag benötigt wird. Bei
gemeinsamer Interpretation/Hypothesengenerierung können zwei Anteile gleichzeitig
fertig werden. Eine lang laufende Untersuchung füllt den Balken nicht künstlich.

Der aktive Fall verschwindet bei `OUTPUT_READY`, `HANDED_OFF` oder
`FAILED_TO_ANALYZE` aus der Workeransicht und der Tabelle laufender Fälle. Er bleibt
in der Verbrauchsstatistik enthalten. Wartende Fälle bleiben in der Fallübersicht,
belegen aber keinen arbeitenden Worker. Ein alter Dienstsnapshot ohne lebenden
Telemetrie-Heartbeat wird nicht als aktiver Worker dargestellt.

## Verbrauch

- Kreisdiagramm: bekannte Eingabe- und Ausgabetokens je Phase; zusätzliche
  Korrektur-/Reparatur-/Wiederholungsaufrufe haben ein eigenes orangefarbenes Segment.
  Die Legende zeigt Fallaufbau, Fallplanung, Hypothesen, Untersuchung, Diagnose und
  Codingauftrag auch bei null gemessenen Tokens. Nullwerte erzeugen keinen
  künstlichen Tortenanteil. Gemeinsame Planungsaufrufe bleiben einmal gezählt.
- Balkendiagramm: Eingabe und Ausgabe einschließlich Denken je Kategorie.
- Der erste reguläre Aufruf bleibt bei seiner Phase, auch wenn sein Ergebnis später
  zurückgewiesen wurde. Seine Korrektur wird ausschließlich dem Korrektursegment
  zugeordnet. Abgeleitete, deterministisch reparierte Antwortdokumente sind keine
  zusätzlichen Anbieteraufrufe und werden nicht erneut gezählt.
- Denktokens sind bereits Bestandteil der Ausgabetokens. Sie werden weder zum
  Kreisdiagramm noch zum Gesamtverbrauch noch einmal hinzuaddiert.
- Neue LLM-Runden speichern ihre Verbrauchszuordnung deterministisch aus der
  Operationskennung. Das verändert keine Prompts, Modellparameter oder Budgets.
  Bereits gespeicherte Aufrufe bleiben unverändert. Bei älteren Akten wird nur
  eindeutig erkennbare Korrekturinformation übernommen; sonst erscheint der Anteil
  als „Nicht zugeordnet“.
- Fehlende Messwerte bleiben unbekannt. Die Diagramme summieren nur bekannte Werte
  und weisen unvollständige Aufrufe aus. Bei vollständig fehlender Tokennutzung
  lässt sich deren Größe nicht als Kreisanteil darstellen.

Der Messumfang umfasst **alle erhaltenen, für den Client freigegebenen Akten und
deren Revisionen** im konfigurierten Workspace. Er ist keine Google-Abrechnung und
keine lebenslange Statistik bereits gelöschter Akten. Dauerhafte Testbilanzen unter
`docs/test-results/token-usage/` bleiben davon unabhängig. Ein Projektfilter wendet
sich auf Fallliste, Worker und Diagramme gleichzeitig an. Gemeinsame Planungsaufrufe
werden einmal als Fallplanung gezählt, nicht zusätzlich als Hypothesengenerierung.

## Übergabe

Die Oberfläche bietet ein einfaches Formular für neue wowdiag-/wowsrc-Aufträge und
für abgeschlossene ZIP-Akten mit Testerfeedback. Es verwendet dieselbe Multipart-
API und denselben Idempotenzmechanismus wie externe Programme. Bei unveränderten
Eingaben verwendet eine Wiederholung denselben Schlüssel. Anhänge und Fallakten
werden nicht clientseitig bearbeitet. Betreiberaktionen stehen separat berechtigten
Clients zur Verfügung.

## Fallakte und Ergebnisse

Fallnamen verlinken auf eine lesbare Detailansicht mit Testerbeobachtungen,
Interpretation, Hypothesen, Confidence, stützenden und widersprechenden Befunden,
Diagnose sowie Coding- und Human-Dev-Auftrag. Befunde bleiben ausdrücklich
KI-Bewertungen mit Belegreferenzen. Das Belegverzeichnis zeigt Herkunft und
Abdeckungsinformationen; die vollständigen Recherchepayloads stehen im ZIP.
Ein expliziter Auftrag „Kein Auftrag“ wird von einem noch nicht erstellten Dokument
unterschieden. Die gemeinsame Liste **Bearbeitete Fälle** enthält Ergebnisse
(`OUTPUT_READY`, Ziel Outbox), bereits übergebene Fälle (`HANDED_OFF`), blockierte
Fälle (`BLOCKED`) und gescheiterte Analysen (`FAILED_TO_ANALYZE`, Ziel Review).
Blockierte Fälle bleiben ausdrücklich unvollständig und können weiterhin auch
in der Übersicht wartender Fälle erscheinen. Ein Sperrgrund wird angezeigt;
`AWAITING_TEST_FEEDBACK` erscheint als „Wartet auf Testerantwort“.

Projekt- und Kategoriefilter sowie Suche sind kombinierbar. Die Sortierung erlaubt
neueste/älteste Aktualisierung, Kategorie oder Projekt. Links in jeder Zeile lädt
ein beschrifteter Iconknopf die vollständige aktuelle Fallakte herunter, auch für
blockierte oder gescheiterte Analysen. Der Download ändert keinen Status und löst
keine Analyse aus. Die Ablagespalte zeigt das im Manifest gespeicherte Routingziel;
es ist keine unabhängige Bestandsprüfung des Outbox-Dateiverzeichnisses. Der Download
liest die verwaltete aktuelle Akte und funktioniert auch ohne separate Exportkopie.
Angezeigt wird der aktuelle Stand je Fall/Paket. Nach Wiedereröffnung erscheinen
aktive Fälle wieder in der laufenden Übersicht; ältere Revisionen bleiben in der
Detailansicht erhalten. Berechtigungen und Projektgrenzen gelten auch für Downloads.

Die Revisionsauswahl liest akzeptierte Artefakte aus der Checkpointhistorie der
aktuellen vollständigen Akte. Ergebnisse neuerer Revisionen erscheinen nicht in
älteren Ansichten. Über die Übergabe-API erfasste Patch-Rückmeldungen werden bis
zur gewählten Revision dargestellt. Bei gesperrten Fällen erscheinen Sperrgrund
und passende Betreiberhinweise. Für berechtigte Betreiber kann eine zulässige
Fortsetzung angefordert werden; Budgets werden dabei nicht zurückgesetzt.

## Betriebssteuerung

Alle angemeldeten Webbenutzer können die Betriebssteuerung verwenden. Externe
API-Clients erhalten standardmäßig keine Betreiberrechte. Ein eigener Client mit
eigenem Token und `operator = true` in der API-Konfiguration erhält Aktionen für
seine freigegebenen Projekte (Beispiel in `config/api.example.toml`). API nach einer
Rechteänderung neu starten. Der Gemini-Schlüssel ist dafür nicht geeignet.

- **Neue Fälle pausieren / wieder zulassen:** gilt je Projekt und bleibt nach
  Neustart erhalten. HTTP-Aufträge werden weiterhin dauerhaft angenommen. Der
  Worker lässt sie im Eingang bzw. wartet bei noch nicht begonnenen Fällen.
  Begonnene Analysen laufen weiter. Eine Pause unterbricht keinen Modellaufruf.
- **Fortsetzung nach Fehlerbehebung anfordern:** in der aktuellen Falldetailansicht
  bei passenden Schedulerfehlern bzw. `RESEARCH_UNAVAILABLE`. Die API bestätigt
  nur `QUEUED`, nicht bereits eine Freigabe. Der lebende Worker prüft den Auftrag
  zwischen Dispatches erneut; ein gestoppter Worker bearbeitet ihn nach Neustart.
- Veraltete Paketgeneration, geänderte Konfigurationsbindung, noch nicht fällige
  Research-Sperre und unzulässige fachliche Sperren werden abgewiesen. Keine
  Zurücksetzung von Hypothesenbudgets, Versuchszählern oder LLM-Operationen.
- Das Aktionsprotokoll dokumentiert Clientkennung, UTC-Zeit, Projekt, Aktion und
  Ergebnis. Fortsetzungen haben getrennte Eingangs- und Ausführungseinträge mit
  derselben Auftragskennung. Die Ansicht zeigt die letzten 100 berechtigten
  Einträge; das vollständige Protokoll bleibt unter `runtime/worker/control/`.
  Es enthält keine Tokens oder Konfigurationsinhalte. Erfolgreiche lokale
  CLI-Freigaben erscheinen als `local-cli`.
- Workerdetails zeigen Erreichbarkeit, letzten Zustand, Aktivität und Fehlercode.
  Ein alter Snapshot gilt nicht als lebender Worker. Globale Workerdetails sind
  nur Betreibern mit Zugriff auf alle konfigurierten Projekte zugänglich.

`GET /v1/operations` liefert Rechte, projektbezogenen Pausenzustand und für Betreiber
Protokoll/Workerzustand. `POST /v1/operations` benötigt Betreiberrechte und JSON:
`{"action":"pause","project_id":"viano-core"}` bzw. `resume`, oder
`{"action":"retry","key":"<Schlüssel aus der Übersicht>","package_generation":42}`.
Bei gleichzeitigem Zugriff kann `API_CONTROL_BUSY` auftreten; nach Aktualisierung
erneut versuchen. Der Worker muss nach diesem Softwareupdate neu gestartet werden.

## Menschliche Testanfragen

Die eigene Seite **Testanfragen** listet offene menschliche Rückfragen mit
Eingangszeit, Projekt, Bug-ID, Falltitel und Frage. Projektfilter sowie Sortierung
„Älteste zuerst“, „Neueste zuerst“ und „Projekt, dann älteste zuerst“ ermöglichen
chronologisches oder projektweises Abarbeiten. Die Liste aktualisiert sich mit der
Übersicht; eine noch offene Eingabe wird dabei nicht überschrieben.

„Ansehen / beantworten“ zeigt Umgebung, Voraussetzungen, Testschritte, benötigte
Beobachtungen und angefragten Termin. Die Antwort erfasst die tatsächliche Umgebung,
Beobachtungen und „Test durchgeführt“ oder „Nicht durchführbar“. Die ausdrückliche
Bestätigung ist erforderlich. Textdaten bleiben untrusted observations, keine
auszuführenden Befehle. Diese erste Oberfläche nimmt Text, keine Dateianhänge an.

Menschliche Antworten erfordern eine angemeldete Benutzersitzung und die exklusive
Übernahme über **Bearbeiten**, siehe [Benutzeranmeldung](user-accounts.md).
Es gibt keine gesonderten Testerrollen für Webbenutzer. Menschliche Zugänge
ausschließlich mit `create_user` anlegen.
Die bestätigende Identität und Zeit stammen vom Server, nicht aus frei editierbaren
Formularfeldern. `GET /v1/test-requests` liefert ausschließlich freigegebene Projekte;
`POST /v1/test-requests/{case-key}` bestätigt die konkrete Anfrage/Revision.
Kollisionen, veraltete Anfragen und widersprüchliche Wiederholungen werden abgewiesen.
Eine identische erneute Übermittlung derselben Sitzung bleibt ohne doppelte Wirkung.

Eine bestätigte Antwort setzt `AWAITING_TEST_FEEDBACK` über den vorhandenen
Coordinator auf `INVESTIGATING_HYPOTHESES` zurück. Revision, Budget und ursprüngliche
Belege bleiben erhalten. Der laufende Worker verarbeitet die Rückmeldung regulär;
eine besondere Betreiberfreigabe ist dafür nicht erforderlich. Der Termin führt
auch nach Ablauf zu keiner automatischen Fortsetzung und verwirft die Anfrage nicht.

Die Werkzeugfreigabe erfolgt über `budget_config = "budget.human-tests.toml"` in
den vertrauenswürdigen Projekteinstellungen. Die lokale Dienstkonfiguration wurde
entsprechend ergänzt. Diese Policy erlaubt `testing.request_human` für 40 fachliche
Einheiten, automatisierte Tests bleiben ohne Eintrag gesperrt. Bei Trial-Läufen
die Datei ausdrücklich mit `--budget-config config/budget.human-tests.toml` angeben.
Bestehende Revisionen behalten ihre eingefrorene Policy; sie werden nicht migriert.
Nach Konfigurationsänderung API und Worker neu starten. Keine Modellanfrage wird
allein durch Öffnen oder Beantworten der Seite gestartet; der Worker läuft separat.

`GET /v1/cases/{key}?revision=N` liefert diese projektgebundene Ansicht.
`GET /v1/cases/{key}/package` lädt die vollständige aktuelle Akte einschließlich
aller erhaltenen Revisionen herunter, auch als Zwischenstand eines laufenden Falls.
Beide Endpunkte benötigen denselben Bearer-Token und verwenden `no-store`.
Der Schlüssel stammt aus der Übersicht, nicht aus einem lokalen Dateipfad.
Große Anzeigeinhalte werden begrenzt und als gekürzt gekennzeichnet. Der Download
bleibt vollständig; die Anzeige verändert keine Paketgeneration und löst keine
LLM-Aufrufe aus.

## Datenschutz und Betrieb

`GET /v1/overview` benötigt eine Benutzersitzung oder einen Maschinen-Bearer-Token.
Webbenutzer sehen alle Projekte; Maschinenclients nur ihre freigegebenen Projekte.
Prompts, vollständige Modellantworten, lokale Pfade und Zugangsdaten werden nicht
an den Browser übergeben. Fallnamen werden als Text dargestellt. Die Seite lädt
keine externen Fonts, Chartbibliotheken oder Analysedienste; Diagramme werden lokal
mit Canvas/CSS gezeichnet. Eine Content Security Policy begrenzt Ressourcen auf
denselben Ursprung. Abmeldung entfernt dargestellte Daten und Formularinhalte;
verzögert eintreffende Antworten aus einer vorherigen Anmeldung werden ignoriert.

Die Ansicht aktualisiert sich alle vier Sekunden. Validierte Darstellungen werden
für unveränderte Paketgenerationen im API-Prozess zwischengespeichert; dies ist
eine Anzeigeoptimierung, kein fachlicher Zustand und kein Analysecache.

## Lokale Prüfung

```powershell
.\.venv\Scripts\python.exe -m pytest tests/test_dashboard.py -q
node tests/dashboard-smoke.mjs
```

Der Browser-Smoke-Test verwendet einen lokalen temporären API-Server, einen
unsichtbaren Edge-Browser und ausdrücklich künstliche Fall-/Verbrauchsdaten. Er
prüft Desktop, Mobilansicht, Projektfilter, Formularumschaltung, Abmeldung,
Tokenanzeige, Fortschritt, Ergebnisliste, Falldetails, Aufträge und Browserfehler.
Die API-Tests prüfen zusätzlich Projektzugriff, ZIP-Download und Revisionsisolation.
Unter Windows wird der installierte
Edge erwartet; über `BROWSER_PATH` lässt sich ein anderes Chromium angeben.
Die Testserver/-browser werden beendet, ihre erzeugten temporären Verzeichnisse
nach Pfadprüfung entfernt. Screenshots als Prüfergebnis liegen unter
`service-data/ui-preview/`. Es werden keine LLM- oder Datenbankanbieter aufgerufen.