Predictalytics/CLAUDE.md

# Predictalytics

**Zuerst hier nachsehen:**
* [`STATUS.md`](STATUS.md) — wo das Projekt steht, was fertig ist.
* [`ROADMAP.md`](ROADMAP.md) — was ansteht, in welcher Reihenfolge, und welche Konzepte
  bewusst zurückgestellt sind.

Die früheren Plandokumente liegen unter [`docs/archiv/`](docs/archiv/) und werden nicht
mehr gepflegt.

Betriebsdokumentation zur Anbindung an das Deployment Center (Lizenz, Watchdog,
Updates, Fehler-Stream): [`docs/BETRIEB-Deploymentcenter.md`](docs/BETRIEB-Deploymentcenter.md).

## Zentraler Bugtracker — Deployment Center

Erfasse unbehandelte Fehler, geplante Verbesserungen und Ideen im zentralen
Deployment Center. Basis-URL: `https://dc.mhdf.de`

### Zugang
Token steht in der Umgebungsvariable `DC_TOKEN`.
Header: `Authorization: Bearer $DC_TOKEN`

Ist `DC_TOKEN` nicht gesetzt, melde nichts und weise stattdessen darauf hin —
die Endpunkte antworten sonst mit `401 unauthorized`.

Die vollständige Schnittstellenbeschreibung liegt maschinenlesbar unter
`GET /api/openapi.json`, das Handbuch unter `/docs/`.

### Projekt
Dieses Projekt ist `predictalytics`.
Repo: `http://192.168.178.10:8418/Richard/Predictalytics`
Fällt dir ein Fehler im Deployment Center selbst auf, melde ihn unter
`deploymentcenter`.

### Etwas melden
`POST /api/bugtracker/v1/report`

```json
{
  "project_slug": "predictalytics",
  "type": "bug",
  "title": "Kurze, aussagekräftige Zusammenfassung",
  "description": "Unter welchen Bedingungen tritt es auf?",
  "error_message": "Exakte Fehlermeldung",
  "stack_trace": "Vollständiger Stacktrace",
  "severity": "high",
  "environment": "production",
  "build_version": "v1.0.0",
  "repo_url": "http://192.168.178.10:8418/Richard/Predictalytics",
  "git_branch": "main",
  "commit_sha": "a21536f",
  "file_path": "src/Predictalytics.Worker/Services/TraderAnalyticsWorker.cs",
  "line_no": 152,
  "client_ref": "eindeutige-id-dieses-laufs"
}
```

**Setze immer `client_ref`** — ein wiederholter Aufruf mit demselben Wert legt
kein Duplikat an. Gib nach Möglichkeit `file_path` und `line_no` an; das spart
dem nächsten Agenten das Parsen des Stacktrace.

Schweregrade: `idea` (Gedanke für später), `wishlist` (Backlog),
`low`, `medium`, `high`, `critical`.

### Arbeit übernehmen
Bevor du an einem Item arbeitest, übernimm es — sonst arbeiten zwei Agenten
parallel am selben Problem:

```
POST /api/bugtracker/v1/manage?action=next
Body: {"project_slug": "predictalytics", "limit": 1}
```

Antwortet der Server mit `409 already_claimed`, nimm das nächste Item.
Die Reservierung läuft nach 30 Minuten ab; `action=claim` auf dieselbe ID
erneuert sie.

### Fortschritt festhalten
```
POST /api/bugtracker/v1/manage?action=comment&id=<ID>
Body: {"comment": "Was du herausgefunden hast", "action_taken": "investigated"}
```

`action_taken`: `investigated`, `fix_proposed`, `pr_opened`, `needs_human`,
`blocked`, `commented`.

### Abschließen
```
POST /api/bugtracker/v1/manage?action=resolve&id=<ID>
Body: {"resolved_in_build": "v1.0.1", "resolution_notes": "Was geändert wurde"}
```

Kommst du nicht weiter, gib das Item zurück statt es blockieren zu lassen:
```
POST /api/bugtracker/v1/manage?action=release&id=<ID>
Body: {"note": "Grund"}
```

### Laufzeitfehler
Die Anwendung meldet Error/Fatal selbst über `POST /api/errors/v1/report`
(`Services/DcErrorReporter.cs`) — dort nichts von Hand nachreichen.

### Release melden
Nach einem Release schließen sich Items mit passendem `resolved_in_build`
automatisch:
```
POST /api/updateservice/v1/publish
Body: {"product_slug": "predictalytics", "version": "1.0.1",
       "download_url": "...", "sha256_hash": "...", "git_commit": "..."}
```

Die Version in `Directory.Build.props` (`<Version>`) muss dazu passen — sie ist
es, die der Client als installierte Version meldet.

### Fehlerbehandlung
Antworten haben die Form `{"status":"error","error":{"code":"…"}}`.
Reagiere auf `code`, nicht auf den Text:
- `401 unauthorized` — Token prüfen, nicht wiederholen
- `409 already_claimed` — nächstes Item nehmen
- `429 rate_limited` — Intervall verdoppeln, später erneut