feat: board-first orchestration with Gateway Bridge, live-update, and flow-board

- GatewayBridgeController: MCP-artiger Kommando-Adapter für Agent-zu-Backend - TaskBridgeService + LiveUpdateService: SSE Live-Sync + Bridge-Kommandos - FlowBoard.vue: Board-first orchestration dashboard panel - live-sync.ts store + live.ts service: SSE-basierte Live-Updates - Nullability-Warnung in HealthController.cs gefixt - nginx.conf: SSE-Proxy + CORS für Bridge-Endpunkte - .gitignore: pnpm/corepack local caches ausgeschlossen - docs: architecture-board-first-orchestration.md hinzugefügt - README: Backend Bridge API dokumentiert
2026-06-22 19:56:45 +02:00
parent de1fc198cb
commit df94ed3cd4
34 changed files with 2115 additions and 118 deletions
@@ -0,0 +1,248 @@
+using Nexus.Api.Data;
+using Nexus.Api.DTOs;
+using Nexus.Api.Models;
+using Nexus.Api.Repositories;
+
+namespace Nexus.Api.Services;
+
+/// <summary>
+/// Concrete implementation of ITaskBridgeService.
+/// Wraps ITaskService, IActivityRepository, INotificationService, and ILiveUpdateService
+/// into structured, predictable commands for agent-facing usage.
+///
+/// All operations produce typed TaskBridgeResult<T> with explicit error codes,
+/// making agent consumption safe and debuggable.
+/// </summary>
+public sealed class TaskBridgeService(
+    ITaskService taskService,
+    IActivityRepository activityRepo,
+    INotificationService notificationService,
+    ILiveUpdateService liveUpdateService) : ITaskBridgeService
+{
+    private static readonly HashSet<string> ValidStates =
+        new(TaskStateHelper.AllStates, StringComparer.OrdinalIgnoreCase);
+
+    // ──────────────────────────────── Create Task ────────────────────────────────
+
+    public async Task<TaskBridgeResult<DashboardTaskDto>> CreateTaskAsync(
+        string title,
+        string? detail = null,
+        string? source = "iris",
+        string? priority = "Normal",
+        string? assignedTo = null,
+        Guid? projectId = null,
+        CancellationToken ct = default)
+    {
+        if (string.IsNullOrWhiteSpace(title))
+            return Error<DashboardTaskDto>(TaskBridgeOutcome.ValidationError, "Title is required.");
+
+        var normalizedSource = NormalizeSource(source);
+        var normalizedAssignee = NormalizeAssignedTo(assignedTo);
+
+        var task = await taskService.CreateDashboardTaskAsync(
+            title.Trim(), detail?.Trim(), normalizedSource, priority, normalizedAssignee, parentTaskId: null, ct);
+
+        var dto = MapToDto(task);
+        return Success(dto);
+    }
+
+    // ──────────────────────────────── Create Child Task ──────────────────────────
+
+    public async Task<TaskBridgeResult<DashboardTaskDto>> CreateChildTaskAsync(
+        Guid parentTaskId,
+        string title,
+        string? detail = null,
+        string? source = "iris",
+        string? priority = "Normal",
+        string? assignedTo = null,
+        string? expectedFrom = null,
+        CancellationToken ct = default)
+    {
+        if (string.IsNullOrWhiteSpace(title))
+            return Error<DashboardTaskDto>(TaskBridgeOutcome.ValidationError, "Title is required.");
+
+        // Verify parent exists
+        var parent = await taskService.GetByIdAsync(parentTaskId, ct);
+        if (parent is null)
+            return Error<DashboardTaskDto>(TaskBridgeOutcome.NotFound, $"Parent task {parentTaskId} not found.");
+
+        var normalizedAssignee = NormalizeAssignedTo(assignedTo);
+
+        var task = await taskService.CreateAgentTaskAsync(
+            title.Trim(), detail?.Trim(), NormalizeSource(source),
+            priority, normalizedAssignee, expectedFrom, parentTaskId, ct);
+
+        // If parent was in Backlog, move it to InProgress (coordination starts)
+        if (string.Equals(parent.State, "Backlog", StringComparison.OrdinalIgnoreCase))
+        {
+            await taskService.UpdateStatusAsync(parentTaskId, "In progress", ct);
+        }
+
+        var dto = MapToDto(task);
+        return Success(dto);
+    }
+
+    // ──────────────────────────────── Update Status ──────────────────────────────
+
+    public async Task<TaskBridgeResult<DashboardTaskDto>> UpdateStatusAsync(
+        Guid taskId,
+        string state,
+        string? callerAgent = null,
+        CancellationToken ct = default)
+    {
+        if (!ValidStates.Contains(state))
+            return Error<DashboardTaskDto>(TaskBridgeOutcome.ValidationError,
+                $"Invalid state '{state}'. Valid: {string.Join(", ", TaskStateHelper.AllStates)}");
+
+        var task = await taskService.GetByIdAsync(taskId, ct);
+        if (task is null)
+            return Error<DashboardTaskDto>(TaskBridgeOutcome.NotFound, $"Task {taskId} not found.");
+
+        // Check authorization
+        if (!TaskStateHelper.CanChangeState(callerAgent, task))
+            return Error<DashboardTaskDto>(TaskBridgeOutcome.Unauthorized,
+                $"Agent '{callerAgent}' is not authorized to change task state. Only iris and bao may move tasks.");
+
+        var result = await taskService.UpdateStatusAsync(taskId, state, ct);
+        if (result.Outcome != TaskOperationOutcome.Success)
+            return Error<DashboardTaskDto>(TaskBridgeOutcome.InvalidState, "Status update rejected.");
+
+        var dto = MapToDto(result.Task!);
+        return Success(dto);
+    }
+
+    // ──────────────────────────────── Append Activity ────────────────────────────
+
+    public async Task<TaskBridgeResult<ActivityEvent>> AppendActivityAsync(
+        Guid taskId,
+        string message,
+        string? type = "comment",
+        CancellationToken ct = default)
+    {
+        if (string.IsNullOrWhiteSpace(message))
+            return Error<ActivityEvent>(TaskBridgeOutcome.ValidationError, "Message is required.");
+
+        var task = await taskService.GetByIdAsync(taskId, ct);
+        if (task is null)
+            return Error<ActivityEvent>(TaskBridgeOutcome.NotFound, $"Task {taskId} not found.");
+
+        var ev = new ActivityEvent
+        {
+            Type = type ?? "comment",
+            Message = message.Trim(),
+            TaskId = taskId
+        };
+
+        await activityRepo.AddAsync(ev, ct);
+
+        // Trigger live update so the board refreshes
+        var board = await taskService.GetBoardAsync(ct);
+        liveUpdateService.Publish("tasks.board.snapshot", board);
+
+        return Success(ev);
+    }
+
+    // ──────────────────────────────── Handoff ────────────────────────────────────
+
+    public async Task<TaskBridgeResult<DashboardTaskDto>> HandoffAsync(
+        Guid taskId,
+        string targetAgent,
+        string? note = null,
+        CancellationToken ct = default)
+    {
+        if (string.IsNullOrWhiteSpace(targetAgent))
+            return Error<DashboardTaskDto>(TaskBridgeOutcome.ValidationError, "Target agent is required.");
+
+        var task = await taskService.GetByIdAsync(taskId, ct);
+        if (task is null)
+            return Error<DashboardTaskDto>(TaskBridgeOutcome.NotFound, $"Task {taskId} not found.");
+
+        var normalizedTarget = targetAgent.Trim().ToLowerInvariant();
+        var handoffNote = string.IsNullOrWhiteSpace(note)
+            ? $"Handoff → {normalizedTarget}"
+            : $"Handoff → {normalizedTarget}: {note.Trim()}";
+
+        // Update expected-from and optionally assigned-to
+        task.ExpectedFrom = normalizedTarget;
+
+        // If this is a child task (has parent), keep assigned-to on the child
+        // If standalone, set assigned-to to the target
+        if (!task.ParentTaskId.HasValue)
+            task.AssignedTo = normalizedTarget;
+
+        await taskService.UpdateDashboardTaskAsync(
+            taskId, title: null, detail: null, source: null,
+            priority: null, assignedTo: task.AssignedTo, dueDate: null, ct);
+
+        // Append handoff activity
+        await AppendActivityAsync(taskId, handoffNote, "handoff", ct);
+
+        // Notify the target
+        await notificationService.CreateAsync(
+            "task_assigned",
+            $"Handoff: {task.Title}",
+            handoffNote,
+            normalizedTarget,
+            task.Id,
+            ct);
+
+        var dto = MapToDto(task);
+        return Success(dto);
+    }
+
+    // ──────────────────────────────── Query ──────────────────────────────────────
+
+    public async Task<BoardResponse> GetBoardAsync(CancellationToken ct = default)
+        => await taskService.GetBoardAsync(ct);
+
+    public async Task<TaskBridgeResult<DashboardTaskDto>> GetTaskAsync(
+        Guid taskId, CancellationToken ct = default)
+    {
+        var dto = await taskService.GetDashboardTaskByIdAsync(taskId, ct);
+        return dto is null
+            ? Error<DashboardTaskDto>(TaskBridgeOutcome.NotFound, $"Task {taskId} not found.")
+            : Success(dto);
+    }
+
+    public async Task<IReadOnlyList<DashboardTaskDto>> GetChildTasksAsync(
+        Guid parentTaskId, CancellationToken ct = default)
+    {
+        var children = await taskService.GetChildTasksAsync(parentTaskId, ct);
+        return children.Select(MapToDto).ToList();
+    }
+
+    public async Task<List<ActivityEvent>> GetTaskActivityAsync(
+        Guid taskId, CancellationToken ct = default)
+        => await taskService.GetTaskActivityAsync(taskId, ct);
+
+    public async Task<AgentWorkflowOverview> GetAgentOverviewAsync(
+        TimeSpan? staleThreshold = null, CancellationToken ct = default)
+    {
+        var threshold = staleThreshold ?? TimeSpan.FromHours(2);
+        return await taskService.GetAgentWorkflowOverviewAsync(threshold, ct);
+    }
+
+    // ──────────────────────────────── Helpers ────────────────────────────────────
+
+    private static TaskBridgeResult<T> Success<T>(T data) =>
+        new(TaskBridgeOutcome.Success, data);
+
+    private static TaskBridgeResult<T> Error<T>(TaskBridgeOutcome outcome, string error) =>
+        new(outcome, Data: default, Error: error);
+
+    private static string NormalizeSource(string? source) =>
+        string.IsNullOrWhiteSpace(source) ? "iris" : source.Trim().ToLowerInvariant();
+
+    private static string? NormalizeAssignedTo(string? assignedTo)
+    {
+        if (string.IsNullOrWhiteSpace(assignedTo)) return null;
+        var valid = new HashSet<string> { "bao", "iris", "programmer", "reviewer", "architekt", "researcher", "executor" };
+        var lower = assignedTo.Trim().ToLowerInvariant();
+        return valid.Contains(lower) ? lower : null;
+    }
+
+    private static DashboardTaskDto MapToDto(WorkTask t) => new(
+        t.Id, t.Title, t.Detail, t.Source, t.State, t.Priority, t.AssignedTo,
+        t.ParentTaskId, t.DueDate, t.CreatedAt, t.UpdatedAt,
+        t.IsAgentTask, t.ExpectedFrom);
+}