VianoBugAnalysis/docs/user-guide.md

# BugAnalysis verwenden

BugAnalysis untersucht gemeldete Softwarefehler und übergibt das Ergebnis an die
nächste zuständige Stelle. Das Programm erstellt selbst keinen fertigen Patch
und spielt keine Änderungen auf einen Server ein. Der aktuelle Erfassungsadapter
ist für WoW/Vcore eingerichtet.

## So arbeitet BugAnalysis

1. Eine Person oder ein Erfassungsprogramm übergibt Bugbeschreibung und
   Diagnosearchive. Die Übergabe-API erstellt daraus eine Fallakte.
2. Ein dauerhaft laufender Analyseworker übernimmt den Auftrag und lädt die
   Konfiguration des angegebenen Projekts.
3. Der Casebuilder wertet Beobachtungen und Telemetrie aus. Er kann relevante
   Identitäten mit den konfigurierten Recherchewerkzeugen auflösen.
4. Die LLM interpretiert den Fall und entwickelt Hypothesen. Im gemeinsamen
   Planungsmodus geschieht beides in einem Aufruf.
5. Die Untersuchung prüft Hypothesen mit Source- und DB-Werkzeugen. Eine knappe
   Untersuchungsschleife sammelt Ergebnisse; Prüfungen und Konsolidierungen
   übernehmen diese in den strukturierten Arbeitsstand. Werkzeuge lesen Daten;
   Zugangsdaten erhält die LLM nicht.
6. Die finale Diagnose bewertet die Befunde und kann einen Frühabschluss
   annehmen oder weitere Untersuchung verlangen. Fachliche Budgets begrenzen
   einzelne Untersuchungen. Ein bestimmter Erfolg ist nicht garantiert.
7. Das Ergebnis enthält Diagnose und Aufträge für Codingagent und menschlichen
   Entwickler. Ein Auftrag darf ausdrücklich erklären, dass keine Arbeit für
   den jeweiligen Empfänger vorliegt. Fehlende Daten zur Umsetzung können als
   menschlicher Auftrag übergeben werden, ohne die erfolgreiche Analyse zu sperren.

Ein Ergebnis bleibt eine begründete Analyse, keine Garantie für einen wirksamen
Fix. Nach Umsetzung und Tests können Rückmeldungen eine neue Analyserevision
derselben Akte auslösen. Behauptungen, Testerbeobachtungen und bestätigte Befunde
sollten bei der Bewertung auseinandergehalten werden.

## Anmeldung und Start

Die Webadresse im Browser öffnen und mit Benutzername und Passwort anmelden.
Benutzerkonten werden ausschließlich per privilegierter Konsole angelegt;
eine Selbstregistrierung gibt es nicht. Alle menschlichen Benutzer haben die
gleichen Rechte für alle Projekte. Externe Programme benutzen eigene
Integrationsschlüssel mit Projektfreigaben.

API und Analyseworker sind getrennte Dienste. Das Öffnen der Webseite startet
keinen Worker und sendet keine Modellanfrage. Der laufende Worker verarbeitet
Aufträge selbstständig; die Webseite ist die Übersicht und alternative Bedienung.

## Übersicht und laufende Fälle

Die Übersicht zeigt erreichbare Worker, den bearbeiteten Fall und dessen
Fortschrittsbalken. Der Balken folgt abgeschlossenen Phasen, nicht vergangener
Zeit. Während einer längeren Untersuchung kann er daher unverändert bleiben.
Abgeschlossene Fälle verschwinden aus der aktiven Workeransicht.

Die Diagramme zeigen gemessenen Tokenverbrauch. Korrektur- und Wiederholungsaufrufe
bilden eine eigene Kategorie. Denktokens sind bereits in den Ausgabetokens
enthalten und werden nicht doppelt addiert. Fehlende Messwerte werden als solche
ausgewiesen. Diese Zahlen sind keine verbindliche Cloud-Abrechnung und umfassen
nur die erhaltenen Akten im gewählten Messumfang.

Über Fallnummern lässt sich die Detailansicht öffnen: Beobachtungen, Einordnung,
Hypothesen, Befunde, Diagnose und Aufträge. Frühere Revisionen bleiben über die
Revisionsauswahl einsehbar. Die vollständigen Daten stehen im herunterladbaren ZIP.

## Neue Aufträge und Rückgaben

Unter **Auftrag übergeben** Projekt, Bug-ID, Fallname und Beobachtungen eingeben.
Für einen neuen Vcore-Fall das wowdiag-Archiv und möglichst das dazugehörige
wowsrc-Archiv derselben Erfassung auswählen. Die Bug-ID muss mit den Archiven
übereinstimmen. Zusätzliche Dateien lassen sich als Anhänge hinzufügen.

Nach dem Absenden bestätigt die API die Annahme. Das ist noch kein Analyseerfolg.
Bei einer unterbrochenen Übergabe verwendet das Formular bei unveränderten
Eingaben denselben Idempotenzschlüssel, damit kein doppelter Auftrag entsteht.

Für eine Rückgabe den Auftragstyp **Abgeschlossene Akte zurückgeben** wählen,
die aktuelle abgeschlossene Case-ZIP hochladen und Ergebnis sowie neue
Beobachtungen eintragen. Beispielsweise kann ein getesteter Patch den Fehler
nicht behoben haben. BugAnalysis ergänzt die Akte und öffnet eine neue Revision.
Blockierte oder noch laufende Akten sind keine Abschlussrückgaben.

Automatische Erfassung erfolgt über den wowdiag-Worker und dieselbe Übergabe-API.
Externe Programme erstellen keine internen Case-Manifeste selbst.

## Testanfragen beantworten

Die Seite **Testanfragen** listet offene menschliche Recherche- und Testfragen
mit Projekt. Nach Zeitpunkt oder Projekt sortieren, eine Anfrage auswählen und
zunächst **Bearbeiten** drücken. Erst dann wird das Antwortformular freigegeben.

Die Anfrage ist während der Session exklusiv gebunden. Andere Personen können
sie nicht gleichzeitig bearbeiten. Beobachtungen und verlangte Angaben sachlich
eintragen und absenden. Bei Sessionablauf oder Abmeldung wird die Bearbeitung
wieder freigegeben. Nach gültiger Antwort setzt der Worker die Analyse mit dem
vorhandenen Stand fort; fachliche Budgets werden nicht erneuert.

Eine Testanfrage während der Ursachenklärung ist etwas anderes als ein
Human-Dev-Auftrag im fertigen Ergebnis. Letzterer gehört zur weiteren Umsetzung.

## Bearbeitete Fälle und Downloads

Unter **Bearbeitete Fälle** stehen Ergebnisse, übergebene Fälle, blockierte Fälle
und gescheiterte Analysen in einer gemeinsamen Liste. Projekt, Kategorie und
Suchbegriff können kombiniert werden; die Sortierung ist separat wählbar.
Links lädt der Pfeilknopf die aktuelle vollständige Fallakte als ZIP herunter.
Ein Download ändert den Fallstatus nicht und bestätigt keine Übergabe.

| Zustand | Bedeutung |
| --- | --- |
| Ergebnis bereit / OUTPUT_READY | Analyseergebnis für die weitere Bearbeitung; Routingziel Outbox |
| Übergeben / HANDED_OFF | Die Akte wurde intern als übergeben markiert |
| Blockiert / BLOCKED | Analyse wartet, beispielsweise auf Testerantwort oder technische Behebung |
| Analyse gescheitert / FAILED_TO_ANALYZE | Analyse konnte nicht erfolgreich abschließen; Routingziel Review |

Blockiert bedeutet nicht abgeschlossen. Sperrgrund und Detailansicht erklären
die nächsten Schritte. Technische Fehler oder unzureichende Eingaben sind von
einem fachlichen Diagnoseergebnis zu unterscheiden. Die Ablagespalte zeigt das
Routingziel, keinen unabhängigen Verzeichnisbestand.

## Betrieb steuern

Die Betriebssteuerung in der Übersicht erlaubt das Pausieren neuer Fälle eines
Projekts. Bereits begonnene Fälle dürfen weiterlaufen. Geeignete technische
Fehlerfälle können über eine Fortsetzungsanforderung nach Behebung wieder
freigegeben werden. Diese Aktion ist kein beliebiger Neustart und setzt keine
Budgets zurück. Menschliche Testantworten werden auf ihrer eigenen Seite erfasst.

## Programme anbinden

Unter **API-Schlüssel** einen Programmnamen und die erlaubten Projekte auswählen.
Den erzeugten Schlüssel über **Anzeigen** oder **Kopieren** abrufen und im
aufrufenden Dienst geschützt hinterlegen. Schlüssel sind später erneut anzeigbar.
**Widerrufen** verhindert weitere authentifizierte Anfragen mit diesem Schlüssel.

Die Schlüssel dienen zur Auftragsübergabe und zum lesenden Projektzugriff;
Maschinenprogramme können darüber keine anderen Schlüssel verwalten oder
menschliche Testerantworten ausfüllen. Ein Integrationsschlüssel ist kein
Gemini- oder anderer Modellanbieter-Schlüssel.

## Einrichtung und Hilfe

- [Linux-Installation und Betrieb](linux-deployment.md)
- [Projekt-, Source-, DB- und Modellkonfiguration](project-configuration.md)
- [Übergabe-API und Rückgaben](intake-api.md)
- [Analyseworker und Wiederanlauf](analysis-worker.md)
- [Benutzerkonten](user-accounts.md)
- [Integrationsschlüssel und deren Sicherung](integration-keys.md)
- [Weboberfläche im Detail](web-console.md)
- [Erfassungsworker v0.4](capture-worker.md)

Vor dem ersten Feldbetrieb auf dem Zielserver Bereitschaftsprüfung, HTTPS,
Dienstneustart und Backups prüfen. Danach einen kontrollierten echten Auftrag
einschließlich Rückfrage und Ergebnisabholung durchführen. Die LLM-Zugriffe
erzeugen erst beim laufenden Analysebetrieb Kosten.