Deploymentcenter/public/docs/bugtracker.md

# Deployment Center — Agenten-Handbuch

Diese Seite beschreibt, wie ein Coding-Agent den Bugtracker und den
UpdateService des Deployment Centers benutzt.

**Maschinenlesbare Fassung:** `GET /api/openapi.json`

---

## 0. Was sich geändert hat

Wer eine ältere Integration betreibt, muss zwei Dinge anpassen:

| Änderung | Auswirkung |
|---|---|
| `POST /api/bugtracker/v1/report` verlangt jetzt zwingend ein Token | Aufrufe ohne Token liefern `401 unauthorized` |
| `GET /api/bugtracker/v1/projects` verlangt jetzt ein Token | dito |
| `POST` auf UpdateService-Publish verlangt `updateservice:publish` | Aufrufe ohne Token liefern `401` |
| Antwortformat vereinheitlicht | Erfolg: `{"status":"success",...}`, Fehler: `{"status":"error","error":{"code":"…","message":"…"}}` |

Der Feldname `error_hash` bleibt erhalten; zusätzlich gibt es `dedup_key`.

---

## 1. Authentifizierung

Alle Endpunkte akzeptieren das Token in einem dieser Header:

```
Authorization: Bearer dc_sub_xxxxxxxxxxxx
X-Agent-Token: dc_sub_xxxxxxxxxxxx
```

### Token-Hierarchie

* **Master-Token** (`dc_master_…`) — wird im WebUI unter *Token-Verwaltung* erzeugt.
  Langlebig, gehört auf den Rechner bzw. in die CI, nicht in ein Repository.
* **Sub-Token** (`dc_sub_…`) — erzeugt sich ein Agent selbst aus dem Master-Token.
  Rechte lassen sich dabei nur **einschränken**, nie erweitern.

### Sub-Token anfordern

```bash
curl -X POST https://dc.mhdf.de/api/tokens/v1/provision \
  -H "X-Master-Token: dc_master_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "client_name": "claude-code auf DEV-WORKSTATION-01",
        "instance_id": "DEV-WORKSTATION-01",
        "scopes": ["bugtracker:report", "bugtracker:read", "bugtracker:manage"],
        "environment": "development"
      }'
```

Das zurückgegebene `sub_token` wird **nur einmal** ausgeliefert.

### Rechte (Scopes)

| Scope | Erlaubt |
|---|---|
| `bugtracker:report` | Bugs, Feature Requests und Ideen melden |
| `bugtracker:read` | Items und Projekte lesen |
| `bugtracker:manage` | Übernehmen, kommentieren, Status setzen, schließen |
| `watchdog:ping` | Heartbeats senden |
| `updateservice:read` | Auf Updates prüfen |
| `updateservice:publish` | Releases veröffentlichen |
| `bugtracker:*` | alle Bugtracker-Rechte |
| `*` | alles |

Ist ein Token an ein Projekt gebunden, greifen alle Aufrufe automatisch nur
auf dieses Projekt zu — ein Zugriff auf ein anderes liefert `403 project_forbidden`.

---

## 2. Projekte finden

```bash
curl https://dc.mhdf.de/api/bugtracker/v1/projects \
  -H "Authorization: Bearer $DC_TOKEN"
```

```json
{
  "status": "success",
  "count": 4,
  "projects": [
    {
      "slug": "deploymentcenter",
      "name": "Deployment Center",
      "repo_url": "https://git.example.com/Richard/Deploymentcenter.git",
      "default_agent": null,
      "open_items": 3,
      "critical_items": 0
    }
  ]
}
```

> Findest du einen Fehler im Deployment Center selbst, melde ihn unter
> `project_slug: "deploymentcenter"`.

---

## 3. Etwas melden

```bash
curl -X POST https://dc.mhdf.de/api/bugtracker/v1/report \
  -H "Authorization: Bearer $DC_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-2026-08-07-42" \
  -d '{
        "project_slug": "myapp",
        "type": "bug",
        "title": "NullReferenceException in UserAuthService",
        "description": "Tritt beim Login ohne gesetzte Session auf.",
        "error_message": "Object reference not set to an instance of an object.",
        "stack_trace": "at MyApp.Core.UserAuthService.ValidateToken(String token)",
        "severity": "high",
        "environment": "production",
        "build_version": "v1.4.2",

        "repo_url": "https://git.example.com/me/myapp.git",
        "git_branch": "main",
        "commit_sha": "a21536f",
        "file_path": "src/Core/UserAuthService.cs",
        "line_no": 42
      }'
```

### Felder

| Feld | Pflicht | Bedeutung |
|---|---|---|
| `title` | ja | Kurze Beschreibung, max. 255 Zeichen |
| `project_slug` | empfohlen | Aus der Projektliste; Vorgabe `default` |
| `type` | nein | `bug` (Vorgabe) oder `feature_request` |
| `severity` | nein | `idea`, `wishlist`, `low`, `medium` (Vorgabe), `high`, `critical` |
| `environment` | nein | `production` (Vorgabe), `development`, `staging`, `testing` |
| `client_ref` | empfohlen | Idempotenz-Schlüssel, alternativ Header `Idempotency-Key` |
| `repo_url`, `git_branch`, `commit_sha`, `file_path`, `line_no` | empfohlen | Code-Kontext — spart dem nächsten Agenten das Parsen des Stacktrace |
| `context` | nein | Beliebiges JSON-Objekt für Zusatzinformationen |
| `push_id`, `target_agent`, `tags` | nein | Workflow-Zuordnung |

`created_by` wird aus dem Token abgeleitet und kann nicht gesetzt werden.

### Was der Server daraus macht

* **Deduplizierung** — gleiche Fehler werden zusammengefasst und
  `occurrence_count` erhöht. Zeilennummern, Speicheradressen, GUIDs und
  Zeitstempel werden dabei ausgeblendet, damit derselbe Fehler nicht als neu gilt.
  Feature Requests und Ideen werden über den Titel dedupliziert.
* **Eskalation** — wird ein offener Bug erneut mit höherem Schweregrad
  gemeldet, wird er hochgestuft (nie herabgestuft).
* **Regression** — tritt ein bereits gelöster Bug erneut auf, entsteht ein
  neues Item mit `regression_of` als Verweis auf das alte.
* **Idempotenz** — identische `client_ref` im selben Projekt legt kein Duplikat an.

### Antwort

```json
{
  "status": "success",
  "item_id": 42,
  "is_new": true,
  "idempotent_hit": false,
  "occurrence_count": 1,
  "dedup_key": "e2c918a514d89a42f...",
  "item_status": "open",
  "regression_of": null,
  "message": "Bug erfasst."
}
```

---

## 4. Die Agenten-Schleife

Basis: `https://dc.mhdf.de/api/bugtracker/v1/manage`

### 4.1 Arbeit holen und übernehmen

Ein Aufruf, der die nächsten offenen Items liefert **und** exklusiv für dich
reserviert — damit arbeiten nicht zwei Agenten am selben Bug:

```bash
curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/manage?action=next" \
  -H "Authorization: Bearer $DC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_slug": "myapp", "limit": 1, "severity": "critical,high"}'
```

Die Reservierung (Lease) läuft nach 30 Minuten automatisch ab. Brauchst du
länger, erneuere sie mit `action=claim` auf dieselbe ID.

### 4.2 Zwischenstand dokumentieren

```bash
curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/manage?action=comment&id=42" \
  -H "Authorization: Bearer $DC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "comment": "Ursache gefunden: Session wird vor dem Redirect nicht initialisiert.",
        "action_taken": "investigated"
      }'
```

Empfohlene Werte für `action_taken`: `investigated`, `fix_proposed`,
`pr_opened`, `needs_human`, `blocked`, `commented`.

### 4.3 Abschließen

```bash
curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/manage?action=resolve&id=42" \
  -H "Authorization: Bearer $DC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "resolved_in_build": "v1.4.3",
        "resolution_notes": "Session-Initialisierung in AuthController vorgezogen."
      }'
```

### 4.4 Wieder freigeben

Kommst du nicht weiter, gib das Item zurück, statt den Lease verfallen zu lassen:

```bash
curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/manage?action=release&id=42" \
  -H "Authorization: Bearer $DC_TOKEN" \
  -d '{"note": "Benötigt Zugriff auf Produktivlogs."}'
```

---

## 5. Lesen und Filtern

```bash
curl "https://dc.mhdf.de/api/bugtracker/v1/manage?action=list&project_slug=myapp&status=open,in_progress&order=severity&limit=20" \
  -H "Authorization: Bearer $DC_TOKEN"
```

| Parameter | Bedeutung |
|---|---|
| `status`, `severity` | Mehrere Werte kommagetrennt |
| `type`, `environment`, `project_slug` | Einzelwert oder `all` |
| `target_agent`, `claimed_by`, `push_id` | Exakte Übereinstimmung |
| `search` | Volltext über Titel, Beschreibung, Fehlermeldung, Tags, Dateipfad |
| `unclaimed_only` | `true` — nur Items, die kein Agent bearbeitet |
| `updated_since` | ISO-8601 — **Delta-Abfrage für effizientes Polling** |
| `order` | `newest`, `oldest`, `updated`, `severity`, `occurrences` |
| `limit`, `offset` | Pagination, max. 500 pro Seite |

Die Antwort enthält `total`, `limit`, `offset` und `has_more`.

### Polling-Muster

```bash
# Nur was sich seit dem letzten Durchlauf geändert hat
curl "…/manage?action=list&updated_since=2026-08-07T09:00:00Z&order=updated" \
  -H "Authorization: Bearer $DC_TOKEN"
```

---

## 6. Release veröffentlichen und Items automatisch schließen

Der Kreis schließt sich hier: Items, deren `resolved_in_build` der
veröffentlichten Version entspricht, werden beim Publish automatisch geschlossen.

```bash
curl -X POST https://dc.mhdf.de/api/updateservice/v1/publish \
  -H "Authorization: Bearer $DC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "product_slug": "myapp",
        "version": "1.4.3",
        "channel": "prod",
        "download_url": "https://dc.mhdf.de/downloads/myapp-1.4.3.zip",
        "sha256_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "git_commit": "a21536f",
        "release_notes": "Behebt den Login-Fehler."
      }'
```

```json
{
  "status": "success",
  "release_id": 12,
  "created": true,
  "auto_resolved": 3,
  "message": "Release 1.4.3 (prod) für \"myapp\" veröffentlicht. 3 Bugtracker-Item(s) automatisch geschlossen."
}
```

Der Versionsvergleich folgt der semantischen Versionsordnung — `1.10.0` gilt
korrekt als neuer als `1.9.0`.

---

## 7. Fehlerbehandlung

Fehler tragen einen stabilen, maschinenlesbaren Code. Reagiere auf `code`,
nicht auf `message`:

```json
{
  "status": "error",
  "error": { "code": "already_claimed", "message": "Item #42 ist bereits vergeben." }
}
```

| Code | HTTP | Bedeutung und Reaktion |
|---|---|---|
| `unauthorized` | 401 | Token fehlt, ist abgelaufen oder hat den Scope nicht |
| `project_forbidden` | 403 | Token ist an ein anderes Projekt gebunden |
| `already_claimed` | 409 | Anderer Agent arbeitet daran — nächstes Item nehmen |
| `not_claimed` | 409 | Freigabe eines Items, das dir nicht gehört |
| `not_found` | 404 | Item existiert nicht |
| `rate_limited` | 429 | Sendefrequenz senken, später erneut |
| `invalid_json` | 400 | Request-Body ist kein gültiges JSON |
| `missing_id`, `missing_status`, `missing_build` | 400 | Pflichtfeld fehlt |
| `invalid_status`, `invalid_version`, `invalid_hash` | 400 | Wert nicht zulässig |
| `internal_error` | 500 | Serverfehler — wird automatisch selbst im Bugtracker erfasst |

**Rate-Limit:** 60 Reports pro Minute und IP. Bei `429` das Intervall verdoppeln.

---

## 8. Vollständige Beispielschleife (Python)

```python
import os, requests

BASE = "https://dc.mhdf.de/api/bugtracker/v1/manage"
HEAD = {"Authorization": f"Bearer {os.environ['DC_TOKEN']}",
        "Content-Type": "application/json"}


def next_item(project):
    r = requests.post(f"{BASE}?action=next", headers=HEAD,
                      json={"project_slug": project, "limit": 1})
    r.raise_for_status()
    items = r.json().get("items", [])
    return items[0] if items else None


def comment(item_id, text, action="investigated"):
    requests.post(f"{BASE}?action=comment&id={item_id}", headers=HEAD,
                  json={"comment": text, "action_taken": action}).raise_for_status()


def resolve(item_id, build, notes):
    requests.post(f"{BASE}?action=resolve&id={item_id}", headers=HEAD,
                  json={"resolved_in_build": build,
                        "resolution_notes": notes}).raise_for_status()


def release(item_id, reason):
    requests.post(f"{BASE}?action=release&id={item_id}", headers=HEAD,
                  json={"note": reason}).raise_for_status()


item = next_item("myapp")
if item is None:
    print("Nichts zu tun.")
else:
    print(f"#{item['id']}: {item['title']}")
    if item.get("file_path"):
        print(f"  -> {item['file_path']}:{item.get('line_no', '?')}")

    comment(item["id"], "Analyse gestartet.")
    try:
        # ... hier die eigentliche Arbeit ...
        resolve(item["id"], "v1.4.3", "Fix in AuthController.")
    except Exception as exc:
        release(item["id"], f"Abbruch: {exc}")
```

---

## 8a. Fehler melden (Laufzeitfehler)

Für den globalen Exception-Handler einer Anwendung gibt es einen schlankeren
Eingang. Titel und Dringlichkeit leitet der Server ab:

```bash
curl -X POST https://dc.mhdf.de/api/errors/v1/report \
  -H "Authorization: Bearer $DC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "project_slug": "polytrader",
        "exception":    "PDOException",
        "message":      "SQLSTATE[23000]: Duplicate entry '\''MKT-88213'\'' for key '\''uq_market'\''",
        "stack_trace":  "at Importer.php:142",
        "level":        "error",
        "build":        "v2.0.1",
        "environment":  "production",
        "file":         "src/Market/Importer.php",
        "line":         142
      }'
```

`level` unterscheidet die technische Art des Ereignisses — unabhängig von der
geschäftlichen Dringlichkeit:

| Wert | Bedeutung |
|---|---|
| `fatal` | Der Prozess hat sich beendet |
| `error` | Ein Vorgang ist fehlgeschlagen, das Programm läuft weiter (Vorgabe) |
| `warning` | Auffälligkeit ohne Funktionsverlust |

### Gruppierung

Gleiche Fehler werden zu einer Gruppe zusammengefasst und hochgezählt.
Veränderliche Bestandteile werden dabei ausgeblendet — Werte in
Anführungszeichen, die Ziffern enthalten, Speicheradressen, GUIDs, Zeitstempel
und Zeilennummern. Diese drei Meldungen ergeben **eine** Gruppe:

```
Duplicate entry 'MKT-88213' for key 'uq_market'
Duplicate entry 'AA-1'      for key 'uq_market'
Duplicate entry 'X-99471'   for key 'uq_market'
```

Ein anderer Unique-Key (`uq_orders`) bleibt dagegen eine eigene Gruppe — der
Schlüsselname enthält keine Ziffern und zählt damit zur Identität des Fehlers.

### Bekannte, harmlose Fehler

Manche Fehler treten betriebsbedingt auf und sind belanglos. Dafür gibt es
Ignore-Regeln, die im WebUI unter **Bugtracker → Ignore-Regeln** gepflegt
werden. Greift eine Regel, wird der Fehler weiterhin erfasst und **hochgezählt**,
bleibt aber aus der Übersicht heraus und löst keine Benachrichtigung aus:

```json
{ "status": "success", "item_id": 42, "ignored": true,
  "ignore_rule_id": 3, "occurrence_count": 3841, "rate_alerted": false,
  "message": "Als bekannt eingestuft, gezaehlt, nicht gemeldet." }
```

Der Zähler ist dabei der eigentliche Zweck: Zu jeder Regel lässt sich eine
Alarmschwelle hinterlegen. Dass ein bekannter Fehler auftritt, ist normal —
dass er plötzlich hundertmal so oft auftritt, ist ein Signal. Wird die Schwelle
überschritten, meldet die Antwort `"rate_alerted": true` und ein Webhook
`error.rate_exceeded` wird ausgelöst.

---

## 9. Watchdog-Heartbeat

Läuft dein Agent als Dienst, melde dich regelmäßig:

```bash
curl -X POST https://dc.mhdf.de/api/watchdog/v1/ping \
  -H "Authorization: Bearer $DC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source": "agent-worker-01", "status": "ok", "interval": 60,
       "message": "Verarbeite Warteschlange", "metrics": {"queue": 3}}'
```

`interval` ist der erwartete Abstand in Sekunden. Bleibt der Heartbeat aus,
stuft der Evaluator den Monitor nach dem Doppelten auf `warning` und nach dem
Vierfachen auf `down`.

### Eigenen Gesundheitszustand mitsenden

Ein Heartbeat beweist nur, dass ein Thread läuft — nicht, dass die Anwendung
ihre Arbeit tut. Deshalb kann sie ihren Zustand selbst mitschicken:

```json
{ "source": "polytrader-worker",
  "status": "warning",
  "interval": 60,
  "checks": {
    "db":          { "ok": true },
    "market_feed": { "ok": false, "message": "Letzter Tick vor 14 min" },
    "queue":       { "ok": true, "value": 23 }
  },
  "metrics": { "cpu": 18, "ram": 42, "queue_depth": 23 } }
```

Das Deploymentcenter interpretiert die Namen der Prüfungen **nicht** — es liest
nur `ok` und `message`. Was „gesund" bedeutet, entscheidet jede Anwendung
selbst. Schlägt eine Prüfung fehl, wird ein als `ok` gemeldeter Heartbeat auf
`warning` herabgestuft.

Der Weg ist bewusst ausgehend: Es müssen keine Ports auf den Zielmaschinen
geöffnet werden.

### Metriken

Numerische Werte aus `metrics` landen im Verlauf und lassen sich abfragen:

```bash
# Welche Metriken liefert dieser Monitor?
curl "https://dc.mhdf.de/api/watchdog/v1/metrics?source=polytrader-worker" \
  -H "Authorization: Bearer $DC_TOKEN"

# Verlauf einer Metrik, auf 15-Minuten-Fenster verdichtet
curl "https://dc.mhdf.de/api/watchdog/v1/metrics?source=polytrader-worker&metric=queue_depth&hours=24" \
  -H "Authorization: Bearer $DC_TOKEN"
```

Die Antwort enthält zusätzlich `deviation` — den Vergleich des aktuellen Werts
mit dem Durchschnitt der letzten sieben Tage desselben Monitors. Damit lassen
sich Auffälligkeiten erkennen, ohne für jedes Projekt Schwellwerte zu pflegen.

Verschachtelte Werte werden flach abgelegt: `{"cpu":{"load":1.2}}` wird zu
`cpu.load`. Rohwerte werden 14 Tage aufbewahrt.

### Abhängigkeiten

Ist bei einem Monitor `parent_source` gesetzt und fällt der übergeordnete
Monitor aus, werden Alarme für die Kinder unterdrückt. Ihr Zustand bleibt im
Dashboard sichtbar — es entsteht nur nicht für jede VM eines ausgefallenen
Hypervisors eine eigene Meldung.

---

## 10. Verfügbarkeit prüfen

```bash
curl https://dc.mhdf.de/api/health -H "Authorization: Bearer $DC_TOKEN"
```

Meldet Datenbankzustand, ausstehende Migrationen, Bugtracker-Kennzahlen und
wann der Watchdog-Evaluator zuletzt lief.