feat: integrate Bugtracker module, UpdateService enhancements & Token hierarchy

2026-08-06 12:45:58 +02:00
parent 70b35f7b8b
commit d71f90cdfc
28 changed files with 3494 additions and 32 deletions
@@ -0,0 +1,156 @@
+# Deploymentcenter — Bugtracker, Feature-Tracker & Token Provisioning Guide
+
+> **Zielgruppe**: KI-Agenten & Softwareentwickler  
+> **Zweck**: Anleitung zur automatisierten Registrierung, Fehlererfassung, Feature-Einreichung und Behebung über das Deployment Center.
+
+---
+
+## 1. Token-Architektur & Autonome Sub-Token-Erstellung
+
+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.
+
+### Sub-Token Anfordern (`POST /api/tokens/v1/provision`)
+Sendet einen HTTP POST Request mit dem Master-Token im `X-Master-Token` Header.
+
+```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
+
+{
+  "name": "Dev Workstation Agent #4",
+  "instance_id": "DEV-WORKSTATION-01",
+  "scopes": ["bugtracker:report", "bugtracker:manage"],
+  "environment": "development"
+}
+```
+
+#### JSON Antwort:
+```json
+{
+  "status": "success",
+  "sub_token": "dc_sub_5f8a2c1...",
+  "token_id": "tok_s_89a1b2c3",
+  "name": "Dev Workstation Agent #4",
+  "scopes": ["bugtracker:report", "bugtracker:manage"],
+  "environment": "development"
+}
+```
+
+---
+
+## 2. Bug & Feature Ingest API (`POST /api/bugtracker/v1/report`)
+
+Wird von Überwachungs-Agenten im laufenden Betrieb oder Entwickler-Agenten auf der Workstation genutzt.
+
+### Request Schema:
+```json
+{
+  "project_slug": "myapp",
+  "type": "bug", // "bug" oder "feature_request"
+  "environment": "development", // "production", "development", "staging", "testing"
+  "severity": "high", // "low", "medium", "high", "critical"
+  "title": "NullReferenceException in UserAuthService.cs line 42",
+  "description": "Beim Login ohne gesetzte Session ist ein Unerwarteter Nullpointer-Fehler aufgetreten.",
+  "error_message": "NullReferenceException: Object reference not set to an instance of an object.",
+  "stack_trace": "at MyApp.Core.UserAuthService.ValidateToken(String token)...",
+  "build_version": "v1.4.2-dev",
+  "created_by": "agent:dev-monitor-01"
+}
+```
+
+#### 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.
+
+---
+
+## 3. Geschützte Management & Resolution API (`/api/bugtracker/v1/manage`)
+
+Schnittstelle für KI-Behebungs-Agenten zum Abrufen offener Bugs, Schreiben von Diagnose-Notizen und Markieren als gelöst.
+
+**Header**: `Authorization: Bearer <dein_sub_token>` (Benötigt Scope `bugtracker:manage`).
+
+### 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`).
+
+### 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`)
+```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"
+}
+```
+
+### 3.4 Item als Gelöst / Umgesetzt Markieren (`POST /api/bugtracker/v1/manage/index.php?action=resolve&id=123`)
+```json
+{
+  "resolved_in_build": "v1.4.3",
+  "resolution_notes": "Null-Check für Session-Variable hinzugefügt.",
+  "author": "agent:code-fixer-01"
+}
+```
+
+---
+
+## 4. C# (.NET 8) Implementierungsbeispiel für KI-Agenten
+
+```csharp
+using System;
+using System.Net.Http;
+using System.Text;
+using System.Text.Json;
+using System.Threading.Tasks;
+
+public class DeploymentCenterBugtrackerClient
+{
+    private static readonly HttpClient HttpClient = new HttpClient();
+    private const string BaseUrl = "https://dc.mhdf.de";
+
+    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}");
+    }
+}
+```