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,133 @@
+using Nexus.Api.Data;
+using Nexus.Api.DTOs;
+using Nexus.Api.Models;
+
+namespace Nexus.Api.Services;
+
+/// <summary>
+/// Structured backend bridge for agent/task commands.
+/// Provides a clean, typed API for agents (Iris and sub-agents) to interact
+/// with the task board, activity log, and delegation workflow.
+///
+/// This is the internal service layer — never exposed directly to the browser.
+/// The GatewayBridgeController wraps this for agent-facing HTTP access.
+/// </summary>
+public interface ITaskBridgeService
+{
+    // ── Task CRUD (Agent-Commands) ──
+
+    /// <summary>
+    /// Creates a new top-level task (parent or standalone).
+    /// Returns the created task DTO.
+    /// </summary>
+    Task<TaskBridgeResult<DashboardTaskDto>> CreateTaskAsync(
+        string title,
+        string? detail = null,
+        string? source = "iris",
+        string? priority = "Normal",
+        string? assignedTo = null,
+        Guid? projectId = null,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Creates a child task linked to an existing parent.
+    /// This is the primary delegation command: iris creates a child task,
+    /// assigns it to a sub-agent, and tracks it on the board.
+    /// </summary>
+    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);
+
+    /// <summary>
+    /// Updates the status/state of a task.
+    /// Enforces CanChangeState rules (only iris/bao/nexus-system may change state).
+    /// </summary>
+    Task<TaskBridgeResult<DashboardTaskDto>> UpdateStatusAsync(
+        Guid taskId,
+        string state,
+        string? callerAgent = null,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Appends an activity entry to a task (comment, status note, agent note).
+    /// Used by agents to annotate their progress on the board.
+    /// </summary>
+    Task<TaskBridgeResult<ActivityEvent>> AppendActivityAsync(
+        Guid taskId,
+        string message,
+        string? type = "comment",
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Handles a task handoff: sets ExpectedFrom to the target agent,
+    /// appends a handoff activity entry, and optionally updates assigned-to.
+    /// </summary>
+    Task<TaskBridgeResult<DashboardTaskDto>> HandoffAsync(
+        Guid taskId,
+        string targetAgent,
+        string? note = null,
+        CancellationToken ct = default);
+
+    // ── Query (Read) ──
+
+    /// <summary>
+    /// Returns the full task board state (grouped by status column).
+    /// </summary>
+    Task<BoardResponse> GetBoardAsync(CancellationToken ct = default);
+
+    /// <summary>
+    /// Returns a single task by ID.
+    /// </summary>
+    Task<TaskBridgeResult<DashboardTaskDto>> GetTaskAsync(
+        Guid taskId,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Returns all child tasks for a given parent task.
+    /// </summary>
+    Task<IReadOnlyList<DashboardTaskDto>> GetChildTasksAsync(
+        Guid parentTaskId,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Returns task activity history.
+    /// </summary>
+    Task<List<ActivityEvent>> GetTaskActivityAsync(
+        Guid taskId,
+        CancellationToken ct = default);
+
+    // ── Agent Workflow ──
+
+    /// <summary>
+    /// Returns the agent-workflow overview: who is expected to respond,
+    /// stale tasks, workload distribution.
+    /// </summary>
+    Task<AgentWorkflowOverview> GetAgentOverviewAsync(
+        TimeSpan? staleThreshold = null,
+        CancellationToken ct = default);
+}
+
+/// <summary>
+/// Result pattern for task-bridge operations.
+/// WorkTask? is null on NotFound; state is stored in the Outcome.
+/// </summary>
+public sealed record TaskBridgeResult<T>(
+    TaskBridgeOutcome Outcome,
+    T? Data = default,
+    string? Error = null
+);
+
+public enum TaskBridgeOutcome
+{
+    Success,
+    NotFound,
+    InvalidState,
+    Unauthorized,
+    ValidationError
+}