Deploymentcenter BotandClaude Opus 5
1d5ac92051
Sammelcommit fuer den ueber mehrere Sitzungen gewachsenen, bisher nicht
eingecheckten Stand. Getrennte Commits waeren ehrlicher gewesen, sind es
nachtraeglich aber nicht mehr: BugRepo, changelog.json und die Doku tragen
Aenderungen aus allen Straengen gleichzeitig, und keine Zwischenstufe waere
lauffaehig.
ROADMAP IM DEPLOYMENTCENTER (2.7.0)
Planungsstand, Reihenfolge und Zustaendigkeit lagen in handgepflegten
Markdown-Dateien neben einem Bugtracker, der genau diese drei Dinge bereits
fuehrt. Zwei Pfleger fuer dasselbe Feld - Drift war eine Frage der Zeit.
Ab jetzt: Zustand im DC, Begruendung in der Datei. Kein Feld hat zwei Pfleger.
- Migration 016: epic, roadmap_rank, target_build, defer_trigger,
doc_anchor, Status "deferred", Tabelle roadmap_epics.
KEINE Roadmap-Tabelle - ein Eintrag ist ein bugtracker_item.
- Zugehoerigkeit ist ein Feld: Ein Item steht auf der Roadmap, wenn es ein
epic hat. Ein zweites Kennzeichen daneben koennte auseinanderlaufen.
- Kennung ist die Item-ID. Handvergebene Kuerzel ("A12") erzeugen die
schlimmste Fehlerart: Beide Seiten stimmig, Verschiedenes gemeint, weil
die Kennung nach einer Loeschung neu vergeben wurde.
- Zurueckstellen verlangt defer_trigger. Ohne benannten Anlass ist ein
Vorhaben nicht zurueckgestellt, sondern vergessen. Die Regel sitzt im
Repository, damit sie auf allen drei Schreibwegen gleich greift.
- Modules/Bugtracker/Roadmap.php, /api/bugtracker/v1/roadmap.php,
WebUI-Modul mit Filtern, cli/roadmap.php --write/--check,
dc_roadmap und dc_roadmap_set im MCP-Adapter.
- cli/roadmap.php --write ERZEUGT den Zustandsteil der Markdown-Datei;
--check prueft nur die Prosa. Was erzeugt wird, kann nicht driften.
- docs/ROADMAP_MIGRATION.md: Uebernahme fuer die anderen Projekte.
TESTINSTANZ UND TESTTOR
- dc-dev.mhdf.de: zweite Installation, eigene DB, eigene Schluessel,
Basic-Auth davor, Rocket.Chat aus.
- 124 Testfaelle in tests/e2e gegen API, Rechte, Migrationen, Sperre.
- scripts/deploy.py bringt vor jedem Upload erst den anstehenden Stand auf
die Testinstanz und laesst dann den Testlauf laufen. Erst bei
Rueckgabewert 0 geht etwas auf die Produktion (--ohne-test als Notausgang).
Andersherum prueft der Lauf aelteren Code als den, der gleich hochgeht.
- tests/ ist aus dem Produktiv-Deploy ausgeschlossen; testctl.php kann
nicht versehentlich auf dc.mhdf.de landen.
- Ein Lauf mit mehr uebersprungenen als geprueften Faellen endet mit
Rueckgabewert 2 statt 0. Nichts ist kaputt, geprueft wurde es aber auch
nicht - der Unterschied darf nicht am Rueckgabewert verschwinden.
SUPERVISOR, PROJEKTLANDSCHAFT, NACHPRUEFUNG (2.6.0/2.6.1)
- Migration 013: projektuebergreifend melden (dev_agent, evidence,
triage_external, affects).
- Migration 014: supervisor_findings, Katalog, fuenf serverseitige
Detektoren im Tick.
- Migration 015: Nachpruefung als Arbeitsschlange statt Benachrichtigung.
- DEV-Lizenzschluessel zur Selbstbedienung, dc-testkit fuer die Test-VM.
- MCP-Adapter: 15 Werkzeuge, ohne Fremdabhaengigkeiten, mit Abgrenzung
von Fremddaten gegen Prompt-Injektion.
BEHOBEN
- observe und status im Supervisor legten den Zustand des Befundes als
"status" in die Antwort. Http::ok() merged ['status' => 'success']
darunter, also gewann der Befundzustand - eine angenommene Meldung kam
als status="open" an. Heisst jetzt finding_status. War Item #59.
Migrationen 013-016 sind auf dem Produktivserver noch NICHT ausgefuehrt.
Ohne sie bricht das WebUI, weil die Roadmap-Ansicht bei jedem Seitenaufruf
gegen bugtracker_items.epic abfragt.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
136 lines
7.7 KiB
Markdown
136 lines
7.7 KiB
Markdown
# 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.
|