feat: 建立 SAM2 标注闭环基线

- 打通工作区真实标注闭环：支持手工多边形、矩形、圆形、点区域和线段生成 mask，并可保存、回显、更新和删除后端 annotation。 - 增强 polygon 编辑器：支持顶点拖动、顶点删除、边中点插入、多 polygon 子区域选择编辑，以及区域合并和区域去除。 - 接入 GT mask 导入：后端支持二值/多类别 mask 拆分、contour 转 polygon、distance transform seed point，前端支持导入、回显和 seed point 拖动编辑。 - 完善导出能力：COCO JSON 导出对齐前端，PNG mask ZIP 同时包含单标注 mask、按 zIndex 融合的 semantic_frame 和 semantic_classes.json。 - 打通异步任务管理：新增任务取消、重试、失败详情接口与 Dashboard 控件，worker 支持取消状态检查并通过 Redis/WebSocket 推送 cancelled 事件。 - 对接 Dashboard 后端数据：概览统计、解析队列和实时流转记录从 FastAPI 聚合接口与 WebSocket 更新。 - 增强 AI 推理参数：前端发送 crop_to_prompt、auto_filter_background 和 min_score，后端支持点/框 prompt 局部裁剪推理、结果回映射和负向点/低分过滤。 - 接入 SAM3 基础设施：新增独立 Python 3.12 sam3 环境安装脚本、外部 worker helper、后端桥接和真实 Python/CUDA/包/HF checkpoint access 状态检测。 - 保留 SAM3 授权边界：当前官方 facebook/sam3 gated 权重未授权时状态接口会返回不可用，不伪装成可推理。 - 增强前端状态管理：新增 mask undo/redo 历史栈、AI 模型选择状态、保存状态 dirty/draft/saved 流转和项目状态归一化。 - 更新前端 API 封装：补充 annotation CRUD、GT mask import、mask ZIP export、task cancel/retry/detail、AI runtime status 和 prediction options。 - 更新 UI 控件：ToolsPalette、AISegmentation、VideoWorkspace 和 CanvasArea 接入真实操作、导入导出、撤销重做、任务控制和模型状态。 - 新增 polygon-clipping 依赖，用于前端区域 union/difference 几何运算。 - 完善后端 schemas/status/progress：补充 AI 模型外部状态字段、任务 cancelled 状态和进度事件 payload。 - 补充测试覆盖：新增后端任务控制、SAM3 桥接、GT mask、导出融合、AI options 测试；补充前端 Canvas、Dashboard、VideoWorkspace、ToolsPalette、API 和 store 测试。 - 更新 README、AGENTS 和 doc 文档：冻结当前需求/设计/测试计划，标注真实功能、剩余 Mock、SAM3 授权边界和后续实施顺序。
2026-05-01 15:26:25 +08:00
parent f020ff3b4f
commit 689a9ba283
48 changed files with 3280 additions and 176 deletions
--- a/backend/tests/test_tasks.py
+++ b/backend/tests/test_tasks.py
@@ -0,0 +1,104 @@
+from models import ProcessingTask
+
+
+def test_cancel_task_revokes_celery_and_updates_project(client, db_session, monkeypatch):
+    project = client.post("/api/projects", json={
+        "name": "Cancelable",
+        "video_path": "uploads/1/clip.mp4",
+        "status": "parsing",
+    }).json()
+    task = ProcessingTask(
+        task_type="parse_video",
+        status="running",
+        progress=35,
+        message="正在使用 FFmpeg/OpenCV 拆帧",
+        project_id=project["id"],
+        celery_task_id="celery-1",
+        payload={"source_type": "video"},
+    )
+    db_session.add(task)
+    db_session.commit()
+    db_session.refresh(task)
+
+    revoked = []
+    published = []
+    monkeypatch.setattr(
+        "routers.tasks.celery_app.control.revoke",
+        lambda celery_id, terminate, signal: revoked.append((celery_id, terminate, signal)),
+    )
+    monkeypatch.setattr("routers.tasks.publish_task_progress_event", lambda event_task: published.append(event_task.status))
+
+    response = client.post(f"/api/tasks/{task.id}/cancel")
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["status"] == "cancelled"
+    assert body["progress"] == 100
+    assert body["message"] == "任务已取消"
+    assert body["error"] == "Cancelled by user"
+    assert revoked == [("celery-1", True, "SIGTERM")]
+    assert published == ["cancelled"]
+    assert client.get(f"/api/projects/{project['id']}").json()["status"] == "pending"
+
+
+def test_retry_task_creates_fresh_parse_task(client, db_session, monkeypatch):
+    project = client.post("/api/projects", json={
+        "name": "Retryable",
+        "video_path": "uploads/2/clip.mp4",
+        "source_type": "video",
+        "status": "error",
+    }).json()
+    task = ProcessingTask(
+        task_type="parse_video",
+        status="failed",
+        progress=100,
+        message="解析失败",
+        error="ffmpeg failed",
+        project_id=project["id"],
+        payload={"source_type": "video"},
+    )
+    db_session.add(task)
+    db_session.commit()
+    db_session.refresh(task)
+
+    class FakeAsyncResult:
+        id = "celery-retry"
+
+    queued = []
+    published = []
+    monkeypatch.setattr("routers.tasks.parse_project_media.delay", lambda task_id: queued.append(task_id) or FakeAsyncResult())
+    monkeypatch.setattr("routers.tasks.publish_task_progress_event", lambda event_task: published.append((event_task.id, event_task.status)))
+
+    response = client.post(f"/api/tasks/{task.id}/retry")
+
+    assert response.status_code == 202
+    body = response.json()
+    assert body["id"] != task.id
+    assert body["status"] == "queued"
+    assert body["progress"] == 0
+    assert body["celery_task_id"] == "celery-retry"
+    assert body["payload"]["retry_of"] == task.id
+    assert queued == [body["id"]]
+    assert published[0] == (body["id"], "queued")
+    assert published[-1] == (body["id"], "queued")
+    assert client.get(f"/api/projects/{project['id']}").json()["status"] == "parsing"
+
+
+def test_task_actions_reject_invalid_states(client, db_session):
+    project = client.post("/api/projects", json={
+        "name": "Done",
+        "video_path": "uploads/3/clip.mp4",
+    }).json()
+    task = ProcessingTask(
+        task_type="parse_video",
+        status="success",
+        progress=100,
+        project_id=project["id"],
+        payload={"source_type": "video"},
+    )
+    db_session.add(task)
+    db_session.commit()
+    db_session.refresh(task)
+
+    assert client.post(f"/api/tasks/{task.id}/cancel").status_code == 409
+    assert client.post(f"/api/tasks/{task.id}/retry").status_code == 409