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