feat: 打通全栈标注闭环、异步拆帧与模型状态

后端能力： - 新增 Celery app、worker task、ProcessingTask 模型、/api/tasks 查询接口和 media_task_runner，将 /api/media/parse 改为创建后台任务并由 worker 执行 FFmpeg/OpenCV/pydicom 拆帧。 - 新增 Redis 进度事件模块和 FastAPI Redis pub/sub 订阅，将 worker 任务进度广播到 /ws/progress；Dashboard 后端概览接口改为聚合 projects/frames/annotations/templates/processing_tasks。 - 统一项目状态为 pending/parsing/ready/error，新增共享 status 常量，并让前端兼容归一化旧状态值。 - 扩展 AI 后端：新增 SAM registry、SAM2 真实运行状态、SAM3 状态检测与文本语义推理适配入口，以及 /api/ai/models/status GPU/模型状态接口。 - 补齐标注保存/更新/删除、COCO/PNG mask 导出相关后端契约和模板 mapping_rules 打包/解包行为。前端能力： - 新增运行时 API/WS 地址推导配置，前端 API 封装对齐 FastAPI 路由、字段映射、任务轮询、标注归档、导出下载和 AI 预测响应转换。 - Dashboard 改为读取 /api/dashboard/overview，并订阅 WebSocket progress/complete/error/status 更新解析队列和实时流转记录。 - 项目库导入视频/DICOM 后创建项目、上传媒体、触发异步解析并刷新真实项目列表。 - 工作区加载真实帧、无帧时触发解析任务、回显已保存标注、保存未归档 mask、更新 dirty mask、清空当前帧后端标注、导出 COCO JSON。 - Canvas 支持当前帧点/框提示调用后端 AI、渲染推理/已保存 mask、应用模板分类并维护保存状态计数；时间轴按项目 fps 播放。 - AI 页面新增 SAM2/SAM3 模型选择，预测请求携带 model；侧边栏和工作区新增真实 GPU/SAM 状态徽标。 - 模板库和本体面板接入真实模板 CRUD、分类编辑、拖拽排序、JSON 导入、默认腹腔镜分类和本地自定义分类选择。测试与文档： - 新增 Vitest 配置、前端测试 setup、API/config/websocket/store/组件测试，覆盖登录、项目库、Dashboard、Canvas、工作区、模型状态、时间轴、本体和模板库。 - 新增 pytest 后端测试夹具和 auth/projects/templates/media/AI/export/dashboard/tasks/progress 测试，使用 SQLite、fake MinIO、fake SAM registry 和 Redis monkeypatch 隔离外部服务。 - 新增 doc/ 文档结构，冻结当前需求、设计、接口契约、测试计划、前端逐元素审计、实现地图和后续实施计划，并同步更新 README 与 AGENTS。验证： - conda run -n seg_server pytest backend/tests：27 passed。 - npm run test:run：54 passed。 - npm run lint、npm run build、compileall、git diff --check 均通过；Vite 仅提示大 chunk 警告。
2026-05-01 13:29:14 +08:00
parent 4d65c37c73
commit f020ff3b4f
78 changed files with 7089 additions and 456 deletions
--- a/doc/04-api-contracts.md
+++ b/doc/04-api-contracts.md
@@ -0,0 +1,193 @@
+# 接口契约清单
+
+## 前端 API 基础配置
+
+位置：`src/lib/config.ts`、`src/lib/api.ts`
+
+```ts
+API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://<current-browser-host>:8000'
+timeout: 30000
+```
+
+前端 request interceptor 会从 localStorage 读取 `token`，附加：
+
+```http
+Authorization: Bearer <token>
+```
+
+当前后端多数接口没有鉴权依赖，所以这个 header 主要是前端侧行为。
+
+## 前端封装的 API
+
+| 函数 | 方法与路径 | 状态 | 说明 |
+|------|------------|------|------|
+| `login(username, password)` | `POST /api/auth/login` | 对齐 | 后端返回 `{ token, username }`，前端只使用 token |
+| `getProjects()` | `GET /api/projects` | 对齐 | 前端映射 `frame_count`、`thumbnail_url` 等字段 |
+| `createProject(payload)` | `POST /api/projects` | 对齐 | 支持 `name`、`description`、`parse_fps` |
+| `updateProject(id, payload)` | `PATCH /api/projects/{id}` | 对齐 | 后端是 `PATCH /api/projects/{id}` |
+| `deleteProject(id)` | `DELETE /api/projects/{id}` | 对齐 | 当前 UI 未明显接入 |
+| `getTemplates()` | `GET /api/templates` | 对齐 | 前端从 `mapping_rules` 取 classes/rules |
+| `createTemplate(payload)` | `POST /api/templates` | 对齐 | 后端会打包 classes/rules 到 mapping_rules |
+| `updateTemplate(id, payload)` | `PATCH /api/templates/{id}` | 对齐 | 模板编辑页使用 |
+| `deleteTemplate(id)` | `DELETE /api/templates/{id}` | 对齐 | 模板编辑页使用 |
+| `uploadMedia(file, projectId)` | `POST /api/media/upload` | 对齐 | multipart form-data |
+| `uploadDicomBatch(files, projectId)` | `POST /api/media/upload/dicom` | 对齐 | multipart form-data |
+| `parseMedia(projectId)` | `POST /api/media/parse?project_id=...` | 对齐 | 创建异步拆帧任务并返回 task |
+| `getTask(taskId)` | `GET /api/tasks/{task_id}` | 对齐 | 查询异步任务状态 |
+| `getProjectFrames(projectId)` | `GET /api/projects/{id}/frames` | 对齐 | 后端返回预签名 image_url |
+| `predictMask(payload)` | `POST /api/ai/predict` | 对齐 | 前端发送 `image_id/prompt_type/prompt_data/model`，并把后端 `polygons` 转为 `masks[].pathData` |
+| `getAiModelStatus(selectedModel?)` | `GET /api/ai/models/status` | 对齐 | 返回 GPU、SAM 2、SAM 3 的真实运行状态 |
+| `getProjectAnnotations(projectId, frameId?)` | `GET /api/ai/annotations` | 对齐 | 前端加载工作区时用于回显已保存标注 |
+| `saveAnnotation(payload)` | `POST /api/ai/annotate` | 对齐 | 工作区归档保存当前项目未保存 mask |
+| `updateAnnotation(annotationId, payload)` | `PATCH /api/ai/annotations/{annotation_id}` | 对齐 | 工作区归档保存 dirty mask |
+| `deleteAnnotation(annotationId)` | `DELETE /api/ai/annotations/{annotation_id}` | 对齐 | 工作区清空当前帧已保存标注 |
+| `getDashboardOverview()` | `GET /api/dashboard/overview` | 对齐 | Dashboard 初始统计、队列和活动日志 |
+| `exportCoco(projectId)` | `GET /api/export/{projectId}/coco` | 对齐 | 后端实际是 `GET /api/export/{project_id}/coco` |
+
+## 后端 FastAPI 接口
+
+以下列表来自当前运行的 OpenAPI：
+
+| 方法 | 路径 | 用途 |
+|------|------|------|
+| POST | `/api/auth/login` | 登录 |
+| POST | `/api/projects` | 创建项目 |
+| GET | `/api/projects` | 项目列表 |
+| GET | `/api/projects/{project_id}` | 项目详情 |
+| PATCH | `/api/projects/{project_id}` | 更新项目 |
+| DELETE | `/api/projects/{project_id}` | 删除项目 |
+| POST | `/api/projects/{project_id}/frames` | 添加帧记录 |
+| GET | `/api/projects/{project_id}/frames` | 项目帧列表 |
+| GET | `/api/projects/{project_id}/frames/{frame_id}` | 单帧详情 |
+| POST | `/api/templates` | 创建模板 |
+| GET | `/api/templates` | 模板列表 |
+| GET | `/api/templates/{template_id}` | 模板详情 |
+| PATCH | `/api/templates/{template_id}` | 更新模板 |
+| DELETE | `/api/templates/{template_id}` | 删除模板 |
+| POST | `/api/media/upload` | 上传视频/图片/DICOM 单文件 |
+| POST | `/api/media/upload/dicom` | 批量上传 DICOM |
+| POST | `/api/media/parse` | 创建 Celery 拆帧任务 |
+| GET | `/api/tasks` | 查询后台任务列表 |
+| GET | `/api/tasks/{task_id}` | 查询单个后台任务 |
+| POST | `/api/ai/predict` | SAM 2 / SAM 3 可选推理 |
+| GET | `/api/ai/models/status` | GPU 和 SAM 模型状态 |
+| POST | `/api/ai/auto` | 自动分割 |
+| POST | `/api/ai/annotate` | 保存 AI 标注 |
+| GET | `/api/ai/annotations` | 查询项目标注，可选按帧过滤 |
+| PATCH | `/api/ai/annotations/{annotation_id}` | 更新已保存标注 |
+| DELETE | `/api/ai/annotations/{annotation_id}` | 删除已保存标注 |
+| GET | `/api/dashboard/overview` | Dashboard 聚合快照 |
+| GET | `/api/export/{project_id}/coco` | 导出 COCO JSON |
+| GET | `/api/export/{project_id}/masks` | 导出 PNG mask ZIP |
+| GET | `/health` | 健康检查 |
+| WS | `/ws/progress` | WebSocket 进度通道，未出现在 OpenAPI paths 中 |
+
+## 关键请求体
+
+### 登录
+
+```json
+{
+  "username": "admin",
+  "password": "123456"
+}
+```
+
+### 创建项目
+
+```json
+{
+  "name": "example.mp4",
+  "description": "导入说明",
+  "parse_fps": 30
+}
+```
+
+### 创建/更新模板
+
+```json
+{
+  "name": "腹腔镜胆囊切除术",
+  "color": "#06b6d4",
+  "z_index": 0,
+  "classes": [
+    {
+      "id": "cls-1",
+      "name": "胆囊",
+      "color": "#ffae00",
+      "zIndex": 280,
+      "category": "腹腔镜胆囊切除术"
+    }
+  ],
+  "rules": []
+}
+```
+
+### AI 推理请求体
+
+前端 `predictMask()` 当前已适配后端 `PredictRequest`：
+
+```json
+{
+  "image_id": 123,
+  "model": "sam2",
+  "prompt_type": "point",
+  "prompt_data": {
+    "points": [[0.5, 0.5]],
+    "labels": [1]
+  }
+}
+```
+
+`prompt_type` 支持：
+
+- `point`
+- `box`
+- `semantic`，选择 `sam3` 时进入 SAM 3 文本语义推理；选择 `sam2` 时仍回退到 auto segmentation
+
+后端响应：
+
+```json
+{
+  "polygons": [
+    [[0.25, 0.25], [0.75, 0.25], [0.75, 0.75], [0.25, 0.75]]
+  ],
+  "scores": [0.5]
+}
+```
+
+前端会把上面的 `polygons` 转成：
+
+```json
+{
+  "masks": [
+    {
+      "pathData": "M 160 90 L 480 90 L 480 270 L 160 270 Z",
+      "segmentation": [[160, 90, 480, 90, 480, 270, 160, 270]],
+      "bbox": [160, 90, 320, 180]
+    }
+  ]
+}
+```
+
+## 已完成的接口对齐
+
+- `updateProject()` 已从 `PUT` 改为 `PATCH`。
+- `exportCoco()` 已从 `/api/export/coco/{projectId}` 改为 `/api/export/{projectId}/coco`。
+- Canvas 已使用真实 `frame.id` 作为 `image_id`。
+- 点和框坐标已转成后端需要的归一化坐标。
+- 后端 `polygons` 已在前端转成 Konva 可渲染的 path。
+- `saveAnnotation()` 已接入 `POST /api/ai/annotate`。
+- `getProjectAnnotations()` 已接入 `GET /api/ai/annotations`。
+- `updateAnnotation()` 已接入 `PATCH /api/ai/annotations/{annotationId}`。
+- `deleteAnnotation()` 已接入 `DELETE /api/ai/annotations/{annotationId}`。
+- `parseMedia()` 已改为创建 Celery 后台任务，并返回 `ProcessingTask`。
+- `getTask()` 已接入 `GET /api/tasks/{taskId}`。
+- `getDashboardOverview()` 已从 `processing_tasks` 聚合解析队列。
+- 工作区导出按钮已调用 `exportCoco()`，并会先保存未归档 mask。
+
+## 仍需处理的接口问题
+
+- WebSocket 地址已从 `VITE_WS_PROGRESS_URL` 读取，未配置时从 `API_BASE_URL` 推导；部署时仍要确认浏览器能访问该地址。
+- Celery worker 进度会写 PostgreSQL 任务表，同时发布到 Redis `seg:progress`；FastAPI 订阅后广播到 `/ws/progress`。
+- 已保存标注目前支持分类级更新和整帧清空删除；逐点几何编辑器尚未实现。