# Deploymentcenter — Entwickler- und Agenten-Dokumentation

Zentrale Plattform für Lizenzverwaltung, Software-Updates, Infrastruktur-
Monitoring und einen Bugtracker, den Coding-Agenten selbständig bedienen.

---

## Zuerst lesen

| Dokument | Wofür |
|---|---|
| **[ROADMAP.md](./ROADMAP.md)** | **Der eine Ort für alles Geplante, Zurückgestellte und bewusst Verworfene.** Ab 2.7.0 gilt die Arbeitsteilung: Zustand im Deploymentcenter (WebUI → Roadmap, `dc_roadmap`), Begründung hier. |
| **[ROADMAP_MIGRATION.md](./ROADMAP_MIGRATION.md)** | **Eine vorhandene `ROADMAP.md` oder `TODO.md` ins Deploymentcenter überführen.** Einmalig je Projekt, sechs Schritte. Für die Agenten der angebundenen Projekte. |
| **[UPGRADE.md](./UPGRADE.md)** | **Ablaufplan für die Umstellung auf 2.0.** Enthält Pflichtschritte: Zugangsdaten wechseln, Migration, Evaluator-Cron. |
| **[Änderungen](../public/docs/changelog.json)** | Was sich je Fassung geändert hat und was zu tun ist. Öffentlich unter `/docs/changelog.php`, maschinenlesbar über `GET /api/updateservice/v1/changelog?since=X` |
| **[Release-Anleitung für Agenten](../public/docs/release.md)** | Ein Projekt veröffentlichungsfähig machen: Vorlage kopieren, konfigurieren, ausliefern |
| **[Linux-Testumgebung](./TESTUMGEBUNG.md)** | **Die geteilte Test-VM.** Wie ein Agent dort selbständig testet: DEV-Lizenz holen, Auslieferung prüfen, Befunde melden — mit `dc-testkit` |
| **[Testinstanz & automatisierter Testlauf](./TESTINSTANZ.md)** | **`dc-dev.mhdf.de` — die zweite Installation zum Kaputtmachen.** 124 Fälle gegen API, Rechte, Migrationen und Zugangssperre (`tests/e2e/run.py`). **`scripts/deploy.py` führt sie vor jedem Produktiv-Upload aus** und bricht bei Fehlschlägen ab (`--ohne-test` umgeht das) |
| [Agent-Prompt-Vorlage](./AGENT_PROMPT_TEMPLATE.md) | Textbaustein für `CLAUDE.md` / `AGENTS.md` eines Projekts |
| [Agenten-Handbuch](../public/docs/bugtracker.md) | Vollständige Beschreibung des Bugtracker-Workflows, öffentlich unter `/docs/` |

## Modul-Handbücher

- **[Lizenzsystem (Hardware-ID v2)](./LICENSE_INTEGRATION_GUIDE.md)** — Hardware-Anbindung, Schlüsselvalidierung, Offline-Cache, CLI, Windows und Linux/Docker
- **[Watchdog (Heartbeat & Telemetrie)](./WATCHDOG_INTEGRATION_GUIDE.md)** — Überwachung von Anwendungen, Diensten und Infrastruktur
- **[UpdateService](./UPDATESERVICE_INTEGRATION_GUIDE.md)** — Release-Verteilung und Update-Prüfung
- **[Erstinstallation](./SETUP_INTEGRATION_GUIDE.md)** — `setup.json`, Installationskonto, `update-agent --action install`
- **[Bugtracker](./BUGTRACKER_INTEGRATION_GUIDE.md)** — Anbindung aus Anwendungen heraus
- **[Supervisor](./SUPERVISOR_INTEGRATION_GUIDE.md)** — Befunde: was ist ungewöhnlich? Läuft serverseitig auf ohnehin eingehenden Daten, **ohne Einbau in die Anwendungen**. Enthält auch den Rückbau begonnener Vorbereitungen
- **[MCP-Adapter](../mcp/README.md)** — Claude Code und andere Werkzeuge direkt an Bugtracker, Roadmap und Supervisor anschließen

Hintergrund zu Supervisor und MCP, inklusive der Frage, warum der Client keinen
Quelltext sieht: **[archiv/SUPERVISOR_MCP_DESIGN.md](./archiv/SUPERVISOR_MCP_DESIGN.md)**
— archiviert, die Herleitung gilt weiter, der Stand steht in der
[Roadmap](./ROADMAP.md).

---

## Modulübersicht

| Modul | Aufgabe | Endpunkte | Authentifizierung |
|---|---|---|---|
| **Bugtracker** | Fehler, Feature Requests und Ideen; Agenten-Workflow mit Claim/Lease | `/api/bugtracker/v1/report`<br>`/api/bugtracker/v1/projects`<br>`/api/bugtracker/v1/manage` | Token mit `bugtracker:*` |
| **UpdateService** | Release-Verteilung, semantischer Versionsvergleich | `/api/updateservice/v1/check`<br>`/api/updateservice/v1/publish` | Lesen offen, Publish braucht `updateservice:publish` |
| **Watchdog** | Heartbeat-Monitoring, Zustandsbewertung, Alarmierung | `/api/watchdog/v1/ping`<br>`/api/watchdog/v1/evaluate` | Token mit `watchdog:ping` |
| **Supervisor** | Befunde: was ist ungewöhnlich? Fünf Detektoren laufen serverseitig im Tick und brauchen keine Client-Änderung | `/api/supervisor/v1/observe`<br>`/api/supervisor/v1/findings`<br>`/api/supervisor/v1/catalog` | Melden `supervisor:report`, Lesen `supervisor:read`, Einstufen `supervisor:manage` |
| **Lizenzen** | Lizenzprüfung, Hardware-ID v2, Offline-Cache, befristete DEV-Schlüssel zur Selbstbedienung | `/api/license/v1/validate`<br>`/api/license/v1/deactivate`<br>`/api/license/v1/dev-key` | Validierung offen, Deaktivierung authentifiziert, DEV-Schlüssel `license:dev` |
| **Tokens** | Selbst-Provisionierung von Sub-Tokens | `/api/tokens/v1/provision` | Master-Token |
| **Setup** | Erstinstallation: Anmeldung, Katalog, Anwendungstoken | `/api/setup/v1/login`<br>`/api/setup/v1/catalog`<br>`/api/setup/v1/token` | Login offen, Rest `setup:*` |
| **System** | Verfügbarkeit, Schema-Status, Schnittstellenbeschreibung | `/api/health`<br>`/api/openapi.json` | Health optional, OpenAPI offen |

---

## Schnittstelle maschinenlesbar

```
GET https://dc.mhdf.de/api/openapi.json
```

Ein Agent kann sich daran selbst orientieren — der früher fest im WebUI
hinterlegte Textblock entfällt damit.

---

## Drosselung

Je IP und Minute. Wird die Grenze überschritten, antwortet der Endpunkt mit
`429 rate_limited` — dann das Intervall verdoppeln und später erneut versuchen,
nicht sofort wiederholen.

| Endpunkt | Grenze | Einstellbar über |
|---|---|---|
| `/api/errors/v1/report` | **300** | `bugtracker.error_rate` |
| `/api/bugtracker/v1/report` | 60 | `bugtracker.report_rate` |
| `/api/supervisor/v1/observe` | 120 | `supervisor.observe_rate` |
| `/api/license/v1/*` | 120 | fest |
| `/api/license/v1/dev-key` | 10 | fest — ein Schlüssel je Testlauf, nicht je Sekunde |
| `/api/updateservice/v1/*` | 240 | fest |
| `/api/setup/v1/login` | 10 | fest — dort werden Passwörter geprüft |
| `/api/tokens/v1/provision` | 20 | fest |

---

## Antwortformat

Alle JSON-Endpunkte antworten einheitlich:

```json
{ "status": "success", "…": "…" }
```

```json
{ "status": "error", "error": { "code": "already_claimed", "message": "…" } }
```

Der `code` ist stabil und für Programme gedacht; die `message` richtet sich an
Menschen und kann sich ändern.

---

## Betrieb

| Aufgabe | Befehl |
|---|---|
| Deployment | `python scripts/deploy.py` |
| Migration | `php public/install_db.php` oder WebUI → System → DB-Migration |
| Evaluator (Cron, minütlich) | `curl -fsS -H "Authorization: Bearer <SHARED_KEY>" https://dc.mhdf.de/api/watchdog/v1/evaluate` |
| Zustand prüfen | `curl https://dc.mhdf.de/api/health` |
| Logs | `var/log/dc-<datum>.log` auf dem Server |

## Aufbau

```
config/    Zugangsdaten (nicht versioniert), Vorlage in config.example.php
src/       Anwendungscode, PSR-4 unter dem Namensraum Deploymentcenter\
  Core/      Bootstrap, Konfiguration, DB, Auth, CSRF, HTTP, Tokens, Migrator,
             ProjectLinks (welches Projekt nutzt welches, in welcher Fassung)
  Modules/   Bugtracker, License, Supervisor, UpdateService, Watchdog, Notify
public/    Webroot-Inhalte: WebUI, API-Endpunkte, öffentliche Dokumentation,
           testkit/dc-testkit.sh (das Werkzeug für die Linux-Test-VM)
sql/       Schema und Migrationen (fortlaufend nummeriert)
var/log/   Laufzeitprotokolle
scripts/   Deployment
mcp/       MCP-Adapter für Claude Code — eine Datei, keine Abhängigkeiten
client-dotnet/ Client-SDK: Lizenz, Update, Setup
```

Der Supervisor läuft ausschließlich hier — an den Detektoren in
`Modules/Supervisor/ServerDetectors.php`
im minütlichen Tick mit (gedrosselt auf zehn Minuten). Er arbeitet auf Daten,
die ohnehin hereinkommen — Fehlerberichte, Heartbeats, Kennzahlen — und
braucht dafür keine Änderung an den Anwendungen.

Neue Klassen werden automatisch geladen, sobald sie dem Namensraum-Pfad
entsprechen — eine `require`-Zeile ist nicht mehr nötig.