Predictalytics/CLAUDE.md

Predictalytics

Zuerst hier nachsehen:

• STATUS.md — wo das Projekt steht, was fertig ist.
• ROADMAP.md — was ansteht, in welcher Reihenfolge, und welche Konzepte bewusst zurückgestellt sind.

Die früheren Plandokumente liegen unter docs/archiv/ und werden nicht mehr gepflegt.

Betriebsdokumentation zur Anbindung an das Deployment Center (Lizenz, Watchdog, Updates, Fehler-Stream): 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

{
  "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