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}")
```

---

## 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`.

---

## 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.