# 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 |
|---|---|
| **[UPGRADE.md](./UPGRADE.md)** | **Ablaufplan für die Umstellung auf 2.0.** Enthält Pflichtschritte: Zugangsdaten wechseln, Migration, Evaluator-Cron. |
| **[Release-Anleitung für Agenten](../public/docs/release.md)** | Ein Projekt veröffentlichungsfähig machen: Vorlage kopieren, konfigurieren, ausliefern |
| [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

---

## 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` |
| **Lizenzen** | Lizenzprüfung, Hardware-ID v2, Offline-Cache | `/api/license/v1/validate`<br>`/api/license/v1/deactivate` | Validierung offen, Deaktivierung authentifiziert |
| **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.

---

## 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
  Modules/   Bugtracker, License, UpdateService, Watchdog, Notify
public/    Webroot-Inhalte: WebUI, API-Endpunkte, öffentliche Dokumentation
sql/       Schema und Migrationen (fortlaufend nummeriert)
var/log/   Laufzeitprotokolle
scripts/   Deployment
```

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