UI-SP2 — Download-manager Task Detail (4 additive read endpoints + redesigned page)

api/openapi.yaml

@@ -166,7 +166,7 @@
 
   # ========== Tasks ==========
   /tasks:
     get:
       tags: [tasks]
       summary: List tasks
       operationId: listTasks
@@ -194,7 +194,7 @@
               schema: {$ref: '#/components/schemas/RbacDenied'}
         '429': {$ref: '#/components/responses/RateLimited'}
 
     post:
       tags: [tasks]
       summary: Create download task
       operationId: createTask
@@ -296,7 +296,7 @@
     parameters:
       - $ref: '#/components/parameters/TaskId'
 
     get:
       tags: [tasks]
       summary: Get task by ID
       operationId: getTask
@@ -315,7 +315,7 @@
         '404':
           description: Task not found or cross-tenant ID (existence not leaked)
 
     patch:
       tags: [tasks]
       summary: Update task (priority only)
       operationId: updateTask
@@ -368,7 +368,7 @@
   /tasks/{taskId}/cancel:
     parameters:
       - $ref: '#/components/parameters/TaskId'
     post:
       tags: [tasks]
       summary: Cancel task (async)
       operationId: cancelTask
@@ -402,7 +402,7 @@
   /tasks/{taskId}/retry:
     parameters:
       - $ref: '#/components/parameters/TaskId'
     post:
       tags: [tasks]
       summary: Retry failed subtasks
       operationId: retrySubtasks
@@ -448,7 +448,7 @@
   /tasks/{taskId}/upgrade:
     parameters:
       - $ref: '#/components/parameters/TaskId'
     post:
       tags: [tasks]
       summary: Upgrade to new revision (incremental)
       operationId: upgradeTask
@@ -472,7 +472,7 @@
   /tasks/{taskId}/subtasks:
     parameters:
       - $ref: '#/components/parameters/TaskId'
     get:
       tags: [subtasks]
       summary: List subtasks of a task
       operationId: listSubtasks
@@ -495,7 +495,7 @@
   /tasks/{taskId}/source-allocation:
     parameters:
       - $ref: '#/components/parameters/TaskId'
     get:
       tags: [tasks]
       summary: View source allocation (multi-source visualization)
       operationId: getSourceAllocation
@@ -509,7 +509,7 @@
   /tasks/{taskId}/events:
     parameters:
       - $ref: '#/components/parameters/TaskId'
     get:
       tags: [tasks]
       summary: Task event log
       operationId: getTaskEvents
@@ -529,6 +529,34 @@
                     items: {$ref: '#/components/schemas/TaskEvent'}
                   next_cursor: {type: string, nullable: true}
 
+  /tasks/{taskId}/subtask-chunks:
+    parameters:
+      - $ref: '#/components/parameters/TaskId'
+    get:
+      tags: [tasks]
+      summary: Per-file chunk segments (download-manager visualization)
+      operationId: getSubtaskChunks
+      responses:
+        '200':
+          description: Subtask chunk report
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/SubtaskChunkReport'}
+
+  /tasks/{taskId}/participating-executors:
+    parameters:
+      - $ref: '#/components/parameters/TaskId'
+    get:
+      tags: [tasks]
+      summary: Executors participating in this task (swimlanes)
+      operationId: getParticipatingExecutors
+      responses:
+        '200':
+          description: Participating executors
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/ParticipatingExecutors'}
+
   # ========== Models ==========
   /models/search:
     get:
@@ -1867,6 +1895,55 @@
           type: object
           additionalProperties: true
 
+    SubtaskChunkReport:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items:
+            type: object
+            required: [subtask_id, filename, status, bytes_downloaded, is_chunked, chunks_completed, chunks]
+            properties:
+              subtask_id: {type: string, format: uuid}
+              filename: {type: string}
+              file_size: {type: integer, format: int64, nullable: true}
+              status: {type: string}
+              bytes_downloaded: {type: integer, format: int64}
+              is_chunked: {type: boolean}
+              chunks_total: {type: integer, nullable: true}
+              chunks_completed: {type: integer}
+              chunks:
+                type: array
+                items:
+                  type: object
+                  required: [chunk_index, byte_start, byte_end, source_id, status, bytes_done]
+                  properties:
+                    chunk_index: {type: integer}
+                    byte_start: {type: integer, format: int64}
+                    byte_end: {type: integer, format: int64}
+                    source_id: {type: string}
+                    status: {type: string}
+                    bytes_done: {type: integer, format: int64}
+
+    ParticipatingExecutors:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items:
+            type: object
+            required: [executor_id, assigned_subtasks, active_subtasks, bytes_downloaded]
+            properties:
+              executor_id: {type: string}
+              executor_status: {type: string, nullable: true}
+              health_score: {type: integer, nullable: true}
+              last_heartbeat_at: {type: string, format: date-time, nullable: true}
+              assigned_subtasks: {type: integer}
+              active_subtasks: {type: integer}
+              bytes_downloaded: {type: integer, format: int64}
+
     # ===== Models =====
     ModelSummary:
       type: object

docs/operator/web-ui.md

@@ -84,3 +84,25 @@ chip is read-only (no tenant switcher); list filtering is client-side
 (no server-side filter endpoint yet).
 
 Cross-ref: `docs/getting-started.md`, `docs/operator/cli-sdk.md`.
+
+## UI-SP2 — Download-manager Task Detail
+
+`/tasks/:id` is a full download-accelerator view backed by four additive
+read-only endpoints (zero migration):
+
+- `GET /api/v1/tasks/{id}/subtask-chunks` — per-file chunk segments
+- `GET /api/v1/tasks/{id}/source-allocation` — per-source contribution + chunk routing
+- `GET /api/v1/tasks/{id}/participating-executors` — executor swimlanes
+- `GET /api/v1/tasks/{id}/events` — audit-derived event log (cursor-paginated)
+
+The page has a header (basic info + aggregate progress ring + client-derived
+speed/ETA + cancel/delete) and four tabs (Files & chunks, Sources, Executors,
+Events). All polling flows through the single `useLiveResource` seam; only the
+active tab polls (others paused via the `enabled` option).
+
+Known limitations (intentional, deferred): speed/ETA are derived client-side
+from successive byte-count polls (no backend speed source); retry/pause/upgrade
+actions are not exposed (no endpoints); the file table uses a height-capped
+`el-table` (true `el-table-v2` windowing is a documented follow-up); the event
+log reads existing `audit_log` rows only; real-time push (SSE/WS) arrives in
+UI-SP5 with no view changes.