# Bugtracker-Integration

> **Dieser Leitfaden wurde zusammengeführt.**
>
> Die vollständige, gepflegte Beschreibung steht im
> **[Agenten-Handbuch](../public/docs/bugtracker.md)** — öffentlich erreichbar
> unter `https://dc.mhdf.de/docs/` und maschinenlesbar unter
> `https://dc.mhdf.de/api/openapi.json`.
>
> Zuvor existierten zwei Beschreibungen desselben Workflows nebeneinander. Sie
> waren bereits auseinandergelaufen: die hier stehenden Beispiele riefen die
> Endpunkte ohne Token auf, benutzten `report.php` und `manage/index.php` als
> Pfade und kannten weder Claim/Lease noch Idempotenz. Ein Agent, der diesem
> Dokument folgte, wäre seit Version 2.0 an `401 unauthorized` gescheitert.

---

## Was sich gegenüber der alten Fassung geändert hat

| Alt | Neu |
|---|---|
| `POST /api/bugtracker/v1/report.php` ohne Token | `POST /api/bugtracker/v1/report` **mit** Token (`bugtracker:report`) |
| `GET /api/bugtracker/v1/projects.php` ohne Token | `GET /api/bugtracker/v1/projects` **mit** Token (`bugtracker:read`) |
| `GET .../manage/index.php?project_slug=…` | `GET .../manage?action=list&project_slug=…` |
| `created_by` frei wählbar | Wird aus dem Token abgeleitet |
| Keine Reservierung — zwei Agenten konnten dasselbe Item bearbeiten | `?action=next` holt und reserviert exklusiv (Claim/Lease) |
| Wiederholte Sendung erzeugte Duplikate | `client_ref` bzw. Header `Idempotency-Key` |
| Fehler nur als Freitext | Stabiler `error.code` zum Auswerten |

## Kürzestmögliche Fassung

```bash
# 1. Arbeit holen und übernehmen
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}'

# 2. Zwischenstand festhalten
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.", "action_taken": "investigated"}'

# 3. Abschließen
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": "Fix in AuthController."}'
```

## Weiterführend

- **[Agenten-Handbuch](../public/docs/bugtracker.md)** — vollständige Referenz mit allen Feldern, Filtern, Fehlercodes und einem Python-Beispiel
- **[Agent-Prompt-Vorlage](./AGENT_PROMPT_TEMPLATE.md)** — Textbaustein für `CLAUDE.md` / `AGENTS.md`
- **[UPGRADE.md](./UPGRADE.md)** — Umstellungsschritte für bestehende Integrationen