Deploymentcenter/docs/BUGTRACKER_INTEGRATION_GUIDE.md

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.

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:

{
  "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:

{
  "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)

{
  "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)

{
  "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

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}");
    }
}