feat(bugtracker, tokens): Add project search, push_id, target_agent, tags, edit modal, extended severities (idea, wishlist), token actions (copy/toggle/delete), and agent integration guide

2026-08-06 21:53:30 +02:00
parent cb52298c7a
commit c437bdee6f
9 changed files with 682 additions and 177 deletions
@@ -1,156 +1,214 @@
-# Deploymentcenter — Bugtracker, Feature-Tracker & Token Provisioning Guide
+# 🤖 AI Agent Integration Guide: Deployment Center Bugtracker & Provisioning API

-> **Zielgruppe**: KI-Agenten & Softwareentwickler  
-> **Zweck**: Anleitung zur automatisierten Registrierung, Fehlererfassung, Feature-Einreichung und Behebung über das Deployment Center.
+This guide defines the standardized protocol and API specifications for autonomous AI Developer Agents interacting with the **Deployment Center Bugtracker & Token Provisioning System**.

 ---

-## 1. Token-Architektur & Autonome Sub-Token-Erstellung
+## 📌 Executive Overview for AI Agents

-Das Deployment Center nutzt eine hierarchische Token-Struktur:
- **Master-Token**: Wird im Deployment Center Admin-Dashboard pro Identität (z. B. Entwickler-Agent, Client-Anwendung, Host-Server) erstellt.
- **Sub-Token**: Wird von Anwendungen oder KI-Agenten autonom über die Provisioning-API angefordert und für API-Aufrufe genutzt.
+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.

-### Sub-Token Anfordern (`POST /api/tokens/v1/provision`)
-Sendet einen HTTP POST Request mit dem Master-Token im `X-Master-Token` Header.
+### 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.

-```http
-POST /api/tokens/v1/provision HTTP/1.1
-Host: dc.mhdf.de
-Content-Type: application/json
-X-Master-Token: dc_master_myapp_dev_agent_001
+---

+## 🔑 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
 {
-  "name": "Dev Workstation Agent #4",
-  "instance_id": "DEV-WORKSTATION-01",
+  "parent_token": "dc_master_myapp_dev_agent_001",
+  "name": "Codebase Refactoring Agent Token",
+  "environment": "development",
  "scopes": ["bugtracker:report", "bugtracker:manage"],
-  "environment": "development"
+  "expires_in_hours": 24
 }
 ```

-#### JSON Antwort:
+#### Response:
 ```json
 {
  "status": "success",
-  "sub_token": "dc_sub_5f8a2c1...",
-  "token_id": "tok_s_89a1b2c3",
-  "name": "Dev Workstation Agent #4",
+  "token_id": "tok_s_8912ab",
+  "raw_token": "dc_sub_myapp_refactor_agent_991",
  "scopes": ["bugtracker:report", "bugtracker:manage"],
-  "environment": "development"
+  "environment": "development",
+  "expires_at": "2026-08-07 21:00:00"
 }
 ```

 ---

-## 2. Bug & Feature Ingest API (`POST /api/bugtracker/v1/report`)
+## 🐛 2. Reporting Bugs, Features & Ideas

-Wird von Überwachungs-Agenten im laufenden Betrieb oder Entwickler-Agenten auf der Workstation genutzt.
+### Endpoint: `POST /api/bugtracker/v1/report.php`

-### Request Schema:
+Header: `Authorization: Bearer <AGENT_TOKEN>`
+
+### A. Reporting an Unhandled Exception / Bug
 ```json
 {
  "project_slug": "myapp",
-  "type": "bug", // "bug" oder "feature_request"
-  "environment": "development", // "production", "development", "staging", "testing"
-  "severity": "high", // "low", "medium", "high", "critical"
+  "type": "bug",
  "title": "NullReferenceException in UserAuthService.cs line 42",
-  "description": "Beim Login ohne gesetzte Session ist ein Unerwarteter Nullpointer-Fehler aufgetreten.",
+  "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)...",
+  "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",
-  "created_by": "agent:dev-monitor-01"
+  "environment": "development",
+  "severity": "high",
+  "push_id": "push_wf_8912",
+  "target_agent": "agent:code-fixer-01",
+  "tags": "auth, security, csharp",
+  "created_by": "agent:watchdog-monitor"
 }
 ```

-#### Besonderheiten:
- **Deduplizierung**: Bei Bugs berechnet das System automatisch einen Error-Hash. Tritt derselbe Fehler in derselben Umgebung erneut auf, wird kein neuer Bug angelegt, sondern `occurrence_count` hochgezählt.
+### 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. Geschützte Management & Resolution API (`/api/bugtracker/v1/manage`)
+## 📌 3. Managing Items (Fetching, Updating & Commenting)

-Schnittstelle für KI-Behebungs-Agenten zum Abrufen offener Bugs, Schreiben von Diagnose-Notizen und Markieren als gelöst.
+### Base Endpoint: `/api/bugtracker/v1/manage/index.php`

-**Header**: `Authorization: Bearer <dein_sub_token>` (Benötigt Scope `bugtracker:manage`).
+Header: `Authorization: Bearer <AGENT_TOKEN>`

-### 3.1 Offene Items Abfragen (`GET /api/bugtracker/v1/manage/index.php`)
-Filter-Parameter: `environment` (`development`/`production`), `type` (`bug`/`feature_request`), `status` (`open`/`in_progress`/`resolved`).
+### 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
+```

-### 3.2 Item-Details & Kommentar-Historie (`GET /api/bugtracker/v1/manage/index.php?id=123`)
-
-### 3.3 Ermittlungsschritt / Kommentar Hinzufügen (`POST /api/bugtracker/v1/manage/index.php?action=comment&id=123`)
+### B. Updating Status & Details (`POST ?action=update`)
 ```json
 {
-  "comment": "Log-Analyse gestartet. Der Fehler tritt auf, wenn $_SESSION['dc_user_id'] nicht gesetzt ist.",
-  "author": "agent:code-fixer-01",
-  "action_taken": "investigated"
+  "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"
 }
 ```

-### 3.4 Item als Gelöst / Umgesetzt Markieren (`POST /api/bugtracker/v1/manage/index.php?action=resolve&id=123`)
+### C. Appending Diagnostic Timeline Comments (`POST ?action=comment`)
 ```json
 {
-  "resolved_in_build": "v1.4.3",
-  "resolution_notes": "Null-Check für Session-Variable hinzugefügt.",
+  "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. C# (.NET 8) Implementierungsbeispiel für KI-Agenten
+## 💻 4. Code Implementation Examples for Agents

-```csharp
-using System;
-using System.Net.Http;
-using System.Text;
-using System.Text.Json;
-using System.Threading.Tasks;
+### Python Example: Automatic Error Reporter Decorator
+```python
+import requests
+import traceback
+import sys

-public class DeploymentCenterBugtrackerClient
-{
-    private static readonly HttpClient HttpClient = new HttpClient();
-    private const string BaseUrl = "https://dc.mhdf.de";
+DC_API_URL = "https://dc.mhdf.de/api/bugtracker/v1/report.php"
+AGENT_TOKEN = "dc_sub_myapp_agent_live_001"

-    public static async Task IngestDevBugAsync(string masterToken, string title, string errorMessage, string stackTrace)
-    {
-        // 1. Sub-Token anfordern
-        var provisionReq = new HttpRequestMessage(HttpMethod.Post, $"{BaseUrl}/api/tokens/v1/provision")
-        {
-            Content = new StringContent(JsonSerializer.Serialize(new
-            {
-                client_name = "Dev Agent Client",
-                scopes = new[] { "bugtracker:report" },
-                environment = "development"
-            }), Encoding.UTF8, "application/json")
-        };
-        provisionReq.Headers.Add("X-Master-Token", masterToken);
-
-        var provResponse = await HttpClient.SendAsync(provisionReq);
-        var provJson = await provResponse.Content.ReadAsStringAsync();
-        using var doc = JsonDocument.Parse(provJson);
-        string subToken = doc.RootElement.GetProperty("sub_token").GetString();
-
-        // 2. Bug melden
-        var reportReq = new HttpRequestMessage(HttpMethod.Post, $"{BaseUrl}/api/bugtracker/v1/report")
-        {
-            Content = new StringContent(JsonSerializer.Serialize(new
-            {
-                project_slug = "myapp",
-                type = "bug",
-                environment = "development",
-                severity = "high",
-                title = title,
-                error_message = errorMessage,
-                stack_trace = stackTrace,
-                build_version = "v1.4.2-dev",
-                created_by = "agent:dev-agent-01"
-            }), Encoding.UTF8, "application/json")
-        };
-        reportReq.Headers.Add("Authorization", $"Bearer {subToken}");
-
-        var reportResponse = await HttpClient.SendAsync(reportReq);
-        Console.WriteLine($"Report Response: {reportResponse.StatusCode}");
+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" \
+  -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"
+  }'
+```
+
+---
+
+## 🎯 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.