Richard/Deploymentcenter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(clients, docs): Lizenz-Antwortformat wiederherstellen, Packager absichern

Browse Source 
Regression aus dem vorigen Commit
- /api/license/v1/validate lieferte die Antwort im neuen status/error-Umschlag.
  Der Vertrag dieses Endpunkts ist aber bereits ausgerollt: das Feld "status"
  auf oberster Ebene trägt den Lizenzzustand (valid, revoked, expired ...).
  LicenseClient las dadurch "success" statt "valid" — jeder ausgelieferte
  Client hätte seine Lizenz für ungültig gehalten. Die Lizenz-Endpunkte
  antworten jetzt wieder ohne Umschlag (Http::raw).
  Gefunden durch Ausführen der projekteigenen Test-Suite gegen den Server.

Packager
- FTP-Zugangsdaten standen als Standardwerte im Quelltext und zusätzlich in
  packager.config.json und in der Integrationsanleitung. Alle drei Fundstellen
  bereinigt; die Konfigurationsdatei ist nicht mehr versioniert. Zugangsdaten
  kommen aus Datei, Umgebungsvariablen oder CLI-Argument, sonst bricht das
  Programm mit einer klaren Meldung ab.
- Das Veröffentlichen sendet jetzt ein Token (updateservice:publish) und nutzt
  den Endpunkt /api/updateservice/v1/publish.
- Fehler wurden von einem leeren catch verschluckt, und ohne Erfolgsfall wurde
  gar nichts ausgegeben. Das Werkzeug meldete am Ende immer Erfolg und lieferte
  Rückgabewert 0, selbst wenn FTP-Upload und API-Aufruf fehlgeschlagen waren.
  Jetzt ehrliche Meldungen und Rückgabewerte 0/1/2.
- packager.config.json wurde vom csproj nie ins Ausgabeverzeichnis kopiert,
  weshalb sie dort nie gefunden wurde und stets die hartkodierten Werte griffen.

UpdateClient
- IsVersionNewer entfernte die Vorabkennung, aber kein führendes "v". Damit
  scheiterte Version.TryParse bei "v1.4.2" und es wurde auf einen
  alphabetischen Vergleich zurückgefallen, in dem "v1.9.0" als neuer gilt als
  "v1.10.0" — derselbe Fehler wie zuvor serverseitig im SQL. Ersetzt durch
  einen vollständigen semantischen Vergleich, verifiziert mit 16 Testfällen.
- Der Rückfall auf die API lag in einem catch-Block, aber GetAsync wirft bei
  einem 404 keine Exception. Fehlte die statische latest.json, brach die
  Prüfung ab, statt die API zu befragen.

Dokumentation
- BUGTRACKER_INTEGRATION_GUIDE.md beschrieb denselben Workflow ein zweites Mal
  und war bereits auseinandergelaufen: Aufrufe ohne Token, alte Pfade, weder
  Claim/Lease noch Idempotenz. Ersetzt durch einen Verweis auf das gepflegte
  Agenten-Handbuch samt Übersicht der Änderungen.
- UPDATESERVICE_INTEGRATION_GUIDE.md um Token, Umgebungsvariablen und
  Rückgabewerte ergänzt.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Deploymentcenter Bot
2026-08-07 16:27:02 +02:00
co-authored by Claude Opus 5
parent e7fbc85db4
commit a74c6fd990
10 changed files with 481 additions and 327 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/BUGTRACKER_INTEGRATION_GUIDE.md
+44 -254
View File
@@ -1,266 +1,56 @@
# 🤖 AI Agent Integration Guide: Deployment Center Bugtracker & Provisioning API
# Bugtracker-Integration
> **⚠️ Geändert in Version 2.0** — `POST /api/bugtracker/v1/report` und
> `GET /api/bugtracker/v1/projects` verlangen jetzt zwingend ein Token mit dem
> passenden Scope; Aufrufe ohne Token liefern `401 unauthorized`. Das
> Antwortformat wurde vereinheitlicht. Die aktuelle, vollständige Beschreibung
> steht im **[Agenten-Handbuch](../public/docs/bugtracker.md)** und unter
> `/api/openapi.json`. Umstellungsschritte: **[UPGRADE.md](./UPGRADE.md)**.
This guide defines the standardized protocol and API specifications for autonomous AI Developer Agents interacting with the **Deployment Center Bugtracker & Token Provisioning System**.
> **Dieser Leitfaden wurde zusammengeführt.**
>
> Die vollständige, gepflegte Beschreibung steht im
> **[Agenten-Handbuch](../public/docs/bugtracker.md)** — öffentlich erreichbar
> unter `https://dc.mhdf.de/docs/` und maschinenlesbar unter
> `https://dc.mhdf.de/api/openapi.json`.
>
> Zuvor existierten zwei Beschreibungen desselben Workflows nebeneinander. Sie
> waren bereits auseinandergelaufen: die hier stehenden Beispiele riefen die
> Endpunkte ohne Token auf, benutzten `report.php` und `manage/index.php` als
> Pfade und kannten weder Claim/Lease noch Idempotenz. Ein Agent, der diesem
> Dokument folgte, wäre seit Version 2.0 an `401 unauthorized` gescheitert.
---
## 📌 Executive Overview for AI Agents
## Was sich gegenüber der alten Fassung geändert hat
As an autonomous AI agent working on software repositories, you MUST actively track all runtime errors, stack traces, planned features, and backlog items in the central Deployment Center.
| Alt | Neu |
|---|---|
| `POST /api/bugtracker/v1/report.php` ohne Token | `POST /api/bugtracker/v1/report` **mit** Token (`bugtracker:report`) |
| `GET /api/bugtracker/v1/projects.php` ohne Token | `GET /api/bugtracker/v1/projects` **mit** Token (`bugtracker:read`) |
| `GET .../manage/index.php?project_slug=…` | `GET .../manage?action=list&project_slug=…` |
| `created_by` frei wählbar | Wird aus dem Token abgeleitet |
| Keine Reservierung — zwei Agenten konnten dasselbe Item bearbeiten | `?action=next` holt und reserviert exklusiv (Claim/Lease) |
| Wiederholte Sendung erzeugte Duplikate | `client_ref` bzw. Header `Idempotency-Key` |
| Fehler nur als Freitext | Stabiler `error.code` zum Auswerten |
### Core Capabilities:
1. **Sub-Token Auto-Provisioning**: Generate restricted sub-tokens for scoped agent tasks.
2. **Automated Error Ingestion**: Report unhandled exceptions with stack traces & automatic SHA-256 deduplication.
3. **Feature & Idea Backlog**: Submit roadmap ideas (`severity: "idea"`) or backlog items (`severity: "wishlist"`).
4. **Active Workflow Management**: Fetch active bugs assigned to your agent ID, update status (`in_progress`, `resolved`), and append diagnostic comments.
## Kürzestmögliche Fassung
---
## 🔑 1. Token Provisioning API
Agents authenticate using a **Master Token** or auto-provisioned **Sub-Token**.
### Endpoint: `POST /api/tokens/v1/provision`
Header: `Authorization: Bearer <MASTER_TOKEN>`
#### Request Payload:
```json
{
"parent_token": "dc_master_myapp_dev_agent_001",
"name": "Codebase Refactoring Agent Token",
"environment": "development",
"scopes": ["bugtracker:report", "bugtracker:manage"],
"expires_in_hours": 24
}
```
#### Response:
```json
{
"status": "success",
"token_id": "tok_s_8912ab",
"raw_token": "dc_sub_myapp_refactor_agent_991",
"scopes": ["bugtracker:report", "bugtracker:manage"],
"environment": "development",
"expires_at": "2026-08-07 21:00:00"
}
```
---
## 📂 1.5. Discovering Monitored Projects API
Before reporting a bug or feature request, an agent can dynamically query all registered projects monitored by the Deployment Center.
### Endpoint: `GET /api/bugtracker/v1/projects.php`
#### Response:
```json
{
"status": "success",
"count": 4,
"projects": [
{
"id": 1,
"slug": "myapp",
"name": "My Application Deluxe",
"notes": "Hauptanwendung für Desktop und Server"
},
{
"id": 2,
"slug": "polytrader",
"name": "PolyTrader Suite Pro",
"notes": "Trading- und Handelssystem Client"
},
{
"id": 3,
"slug": "predictalytics",
"name": "Predictalytics Engine",
"notes": "Datenanalyse und Vorhersage Dienst"
},
{
"id": 4,
"slug": "deploymentcenter",
"name": "Deployment Center",
"notes": "Zentrale Verwaltungs- & Update-Plattform"
}
]
}
```
If an agent discovers an issue or refactoring opportunity in any monitored system (including `deploymentcenter` itself or external dependencies), it can fetch this project list and map the issue to the appropriate `project_slug`.
---
## 🐛 2. Reporting Bugs, Features & Ideas
### Endpoint: `POST /api/bugtracker/v1/report.php`
Header: `Authorization: Bearer <AGENT_TOKEN>`
### A. Reporting an Unhandled Exception / Bug
```json
{
"project_slug": "myapp",
"type": "bug",
"title": "NullReferenceException in UserAuthService.cs line 42",
"description": "Triggered when user logs in without an active session object.",
"error_message": "NullReferenceException: Object reference not set to an instance of an object.",
"stack_trace": "at MyApp.Core.UserAuthService.ValidateToken(String token) in UserAuthService.cs:line 42\nat MyApp.Controllers.AuthController.Login() in AuthController.cs:line 18",
"build_version": "v1.4.2-dev",
"environment": "development",
"severity": "high",
"push_id": "push_wf_8912",
"target_agent": "agent:code-fixer-01",
"tags": "auth, security, csharp",
"created_by": "agent:watchdog-monitor"
}
```
### B. Submitting a Feature Request or Quick Reminder Idea (`severity: "idea"`)
```json
{
"project_slug": "myapp",
"type": "feature_request",
"title": "Automatische Datenbank-Backups vor FTP Deployments",
"description": "Gedanke für später: Vor jedem FTP-Deployment automatisch mysqldump ausführen und im Server-Archiv ablegen.",
"build_version": "v1.6.0-roadmap",
"environment": "development",
"severity": "idea",
"push_id": "push_wf_9910",
"target_agent": "agent:db-optimizer",
"tags": "database, automation, backup",
"created_by": "agent:planner"
}
```
#### Response:
```json
{
"status": "success",
"item_id": 4,
"is_new": true,
"occurrence_count": 1,
"error_hash": "e2c918a514d89a42f",
"type": "bug",
"environment": "development",
"push_id": "push_wf_8912",
"message": "New bug reported successfully."
}
```
---
## 📌 3. Managing Items (Fetching, Updating & Commenting)
### Base Endpoint: `/api/bugtracker/v1/manage/index.php`
Header: `Authorization: Bearer <AGENT_TOKEN>`
### A. Fetching Open Items Assigned to an Agent
```http
GET /api/bugtracker/v1/manage/index.php?project_slug=myapp&status=open&agent=agent:code-fixer-01
```
### B. Updating Status & Details (`POST ?action=update`)
```json
{
"id": 4,
"status": "in_progress",
"severity": "high",
"push_id": "push_wf_8912",
"target_agent": "agent:code-fixer-01",
"tags": "auth, fixed_pending_test",
"author": "agent:code-fixer-01"
}
```
### C. Appending Diagnostic Timeline Comments (`POST ?action=comment`)
```json
{
"id": 4,
"comment": "Ursache identifiziert: $_SESSION['user'] war Null in line 42. Null-Check und Safe Navigation Operator wurden hinzugefügt.",
"action_taken": "code_patched",
"author": "agent:code-fixer-01"
}
```
### D. Marking as Resolved (`POST ?action=resolve`)
```json
{
"id": 4,
"resolved_in_build": "v1.4.3-dev",
"resolution_notes": "Unit tests hinzugefügt und Null-Check in ValidateToken() integriert.",
"author": "agent:code-fixer-01"
}
```
---
## 💻 4. Code Implementation Examples for Agents
### Python Example: Automatic Error Reporter Decorator
```python
import requests
import traceback
import sys
DC_API_URL = "https://dc.mhdf.de/api/bugtracker/v1/report.php"
AGENT_TOKEN = "dc_sub_myapp_agent_live_001"
def report_exception_to_dc(project_slug: str, exc: Exception, env: str = "production", push_id: str = None):
payload = {
"project_slug": project_slug,
"type": "bug",
"title": f"{type(exc).__name__}: {str(exc)}",
"error_message": str(exc),
"stack_trace": traceback.format_exc(),
"build_version": "v1.4.2",
"environment": env,
"severity": "high",
"push_id": push_id,
"created_by": "agent:python-runner"
}
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {AGENT_TOKEN}"
}
try:
r = requests.post(DC_API_URL, json=payload, headers=headers, timeout=5)
return r.json()
except Exception as e:
print(f"Failed to report to Deployment Center: {e}", file=sys.stderr)
```
### cURL Example: Submit Feature Request / Idea
```bash
curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/report.php" \
-H "Authorization: Bearer dc_sub_myapp_agent_live_001" \
# 1. Arbeit holen und übernehmen
curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/manage?action=next" \
-H "Authorization: Bearer $DC_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project_slug": "myapp",
"type": "feature_request",
"title": "Erweiterte Filterung im WebUI Dashboard",
"severity": "idea",
"push_id": "push_task_1029",
"tags": "ui, dashboard",
"created_by": "agent:dev-assistant"
}'
-d '{"project_slug": "myapp", "limit": 1}'
# 2. Zwischenstand festhalten
curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/manage?action=comment&id=42" \
-H "Authorization: Bearer $DC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"comment": "Ursache gefunden.", "action_taken": "investigated"}'
# 3. Abschließen
curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/manage?action=resolve&id=42" \
-H "Authorization: Bearer $DC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"resolved_in_build": "v1.4.3", "resolution_notes": "Fix in AuthController."}'
```
---
## Weiterführend
## 🎯 Best Practices for Developer Agents
1. **Always set `push_id`**: When executing automated pipelines, pass a `push_id` so all updates can be traced back to the specific execution run.
2. **Use `severity: "idea"` for thoughts**: When noticing potential refactorings or future improvements during coding, log them immediately as ideas.
3. **Comment before resolving**: Before calling `action=resolve`, write a diagnostic comment explaining **why** and **how** the fix was performed.
- **[Agenten-Handbuch](../public/docs/bugtracker.md)** — vollständige Referenz mit allen Feldern, Filtern, Fehlercodes und einem Python-Beispiel
- **[Agent-Prompt-Vorlage](./AGENT_PROMPT_TEMPLATE.md)** — Textbaustein für `CLAUDE.md` / `AGENTS.md`
- **[UPGRADE.md](./UPGRADE.md)** — Umstellungsschritte für bestehende Integrationen
docs/UPDATESERVICE_INTEGRATION_GUIDE.md
+41 -5
View File
@@ -76,26 +76,62 @@ Das Packaging-Tool verpackt den `dotnet publish`-Output, berechnet Hashes, erzeu
pack-and-deploy --project myapp --version 1.4.0 --channel prod --publish-dir ./bin/Release/net8.0/publish --changelog "Fehlerbehebungen und Performance-Optimierung"
```
### Konfiguration (`packager.config.json`):
### Konfiguration (`packager.config.json`)
> Diese Datei enthält Zugangsdaten und ist per `.gitignore` von der
> Versionskontrolle ausgeschlossen. Vorlage: `packager.config.example.json`.
> In der vorherigen Fassung standen die echten FTP-Zugangsdaten sowohl hier in
> der Anleitung als auch als Standardwerte im Quelltext von `Program.cs`.
```json
{
"ftpHost": "www531.your-server.de",
"ftpHost": "ftp.example.com",
"ftpPort": 21,
"ftpUser": "bergisnu_4",
"ftpPass": "o2#M*NN^5EsT",
"ftpUser": "ftp-user",
"ftpPass": "ftp-password",
"ftpRemoteBaseDir": "/public_html/releases",
"apiBaseUrl": "https://dc.mhdf.de",
"apiToken": "dc_sub_...",
"excludePatterns": [
"*.pdb",
"*.xml",
"appsettings.Development.json",
"*.log",
"logs/*"
"logs/**"
]
}
```
`apiToken` braucht das Recht `updateservice:publish`. Ohne Token baut und lädt
der Packager das Paket zwar hoch, meldet es aber nicht beim Deploymentcenter an
und beendet sich mit Rückgabewert 2.
### Alternative: Umgebungsvariablen
Für CI-Läufe, in denen keine Datei abgelegt werden soll — sie haben Vorrang vor
der Konfigurationsdatei:
```bash
export DC_FTP_HOST=ftp.example.com
export DC_FTP_USER=ftp-user
export DC_FTP_PASS='...'
export DC_TOKEN='dc_sub_...'
pack-and-deploy --project myapp --version 1.4.0 --channel prod \
--publish-dir ./bin/Release/net8.0/publish
```
### Rückgabewerte
| Wert | Bedeutung |
|---|---|
| `0` | Paket gebaut, hochgeladen und im Deploymentcenter registriert |
| `1` | Konfiguration unvollständig oder Publish-Verzeichnis fehlt — nichts wurde ausgeführt |
| `2` | Teilweise fehlgeschlagen: FTP-Upload oder Registrierung ging schief |
Zuvor lieferte das Werkzeug in allen Fällen `0` und meldete „successfully
published", selbst wenn FTP-Upload und API-Aufruf beide fehlgeschlagen waren.
---
## 4. Standalone UpdateAgent (`update-agent`)