feat: 完善视频传播、标注编辑和拆帧闭环

- 接入 SAM2 视频传播能力：新增 /api/ai/propagate，支持用当前帧 mask/polygon/bbox 作为 seed，通过 SAM2 video predictor 向前、向后或双向传播，并可保存为真实 annotation。
- 接入 SAM3 video tracker：通过独立 Python 3.12 external worker 调用 SAM3 video predictor/tracker，使用本地 checkpoint 与 bbox seed 执行视频级跟踪，并在模型状态中标记 video_track 能力。
- 完善 SAM 模型分发：sam_registry 按 model_id 明确区分 sam2 propagation 与 sam3 video_track，避免两个模型链路混用。
- 打通前端“传播片段”：VideoWorkspace 使用当前选中 mask 和当前 AI 模型调用后端传播接口，传播结果回写并刷新工作区已保存标注。
- 增强 SAM3 本地 checkpoint 配置：新增 sam3_checkpoint_path 配置和 .env.example 示例，状态检查改为基于本地 checkpoint/独立环境/模型包可用性。
- 完善视频拆帧参数：/api/media/parse 支持 parse_fps、max_frames、target_width，后端任务保存帧时间戳、源帧号和 frame_sequence 元数据。
- 增加运行时 schema 兼容处理：启动时为旧 frames 表补充 timestamp_ms 和 source_frame_number 列，避免旧库升级后缺字段。
- 强化 Canvas 标注编辑：补齐多边形闭合、点工具、顶点拖拽、边中点插入、Delete/Backspace 删除、区域合并和重叠去除等交互。
- 增强语义分类联动：选中 mask 后可通过右侧语义分类树更新标签、颜色和 class metadata，并同步到保存/导出链路。
- 增加关键帧时间轴体验：FrameTimeline 显示具体时间信息，并支持键盘左右方向键切换关键帧。
- 完善 AI 交互分割参数：前端保留正向点、反向点、框选和 interactive prompt 的调用状态，支持 SAM2 细化候选区域与 SAM3 bbox 入口。
- 扩展后端/前端 API 类型：新增 propagateMasks、传播请求/响应 schema，并补齐 annotation、导出、模型状态和任务接口的测试覆盖。
- 更新项目文档：同步 README、AGENTS、接口契约、需求冻结、设计冻结、前端元素审计、实施计划和测试计划，标明真实功能边界与剩余风险。
- 增加测试覆盖：补充 SAM2/SAM3 传播、SAM3 状态、媒体拆帧参数、Canvas 编辑、语义标签切换、时间轴、工作区传播和 API 合约测试。
- 加强仓库安全边界：将 sam3权重/ 加入 .gitignore，避免本地模型权重被误提交。

验证：npm run test:run；pytest backend/tests；npm run lint；npm run build；python -m py_compile；git diff --check。

doc/07-current-requirements-freeze.md

@@ -28,7 +28,11 @@
 - 未提供项目 ID 上传时，后端自动创建项目。
 - 提供项目 ID 上传时，后端把上传对象关联到该项目。
 - 拆帧接口根据项目 `source_type` 处理视频或 DICOM。
+- 拆帧接口支持 `parse_fps`、`max_frames` 和 `target_width` 参数，用于生成可被 SAM 2 / SAM 3 视频处理复用的标准帧序列。
+- 视频帧使用连续 `frame_%06d.jpg` 命名，默认从 `frame_000000.jpg` 开始，并按 `target_width` 缩放。
 - 拆帧完成后写入 `frames` 记录，并把项目状态设为 `ready`。
+- 每条帧记录包含 `frame_index`、`image_url`、`width`、`height`、`timestamp_ms` 和 `source_frame_number`。
+- 任务完成结果包含 `frame_sequence` 元数据：`original_fps`、`parse_fps`、`frame_count`、`duration_ms`、`target_width`、帧宽高和对象存储前缀。
 - 拆帧接口会创建 `processing_tasks` 记录并投递 Celery worker。
 - 前端可通过 `GET /api/tasks/{task_id}` 查询任务状态。
 - 后端支持 `POST /api/tasks/{task_id}/cancel` 取消 queued/running 任务，写入 `cancelled` 状态并尝试 revoke Celery。
@@ -41,8 +45,9 @@
 - 若项目有媒体但无帧，工作区会尝试触发拆帧后重新加载。
 - Canvas 显示当前帧图片。
 - Canvas 支持滚轮缩放、移动工具拖拽、鼠标坐标显示。
-- 时间轴支持缩略图点击切帧、range 拖动切帧、播放/暂停顺序推进帧。
+- 时间轴支持缩略图点击切帧、range 拖动切帧、键盘左右方向键切帧、播放/暂停顺序推进帧。
 - 播放帧率使用项目 `parse_fps` 或 `original_fps`，限制在 1 到 30 FPS。
+- 时间轴显示当前帧时间和总时长，时间基准使用项目 `parse_fps` 或 `original_fps`，格式为 `mm:ss.cc`。
 
 ## R5 工具栏
 
@@ -50,12 +55,16 @@
 - 正向点、反向点、框选工具会影响 Canvas 交互。
 - 魔法棒按钮切换到 AI 页面。
 - 多边形、矩形、圆、点、线工具会在 Canvas 上生成可保存的 polygon mask。
-- 多边形通过点击取点并按 Enter 完成；矩形、圆、线通过拖拽生成；点工具生成小点区域。
+- 多边形通过点击取点并按 Enter 完成，也支持三点后点击首节点闭合；矩形、圆、线通过拖拽生成；点工具生成小点区域。
+- 绘制工具点击已有 mask 时应继续执行当前绘制动作，不应被 mask 选择逻辑吞掉。
 - Canvas 支持点击 mask 进入 polygon 顶点编辑态；拖动顶点会更新 mask 几何并把已保存 mask 标记为 dirty。
 - 顶点编辑态下选中顶点后可用 Delete/Backspace 删除顶点，但不会让 polygon 少于三点。
+- 选中整个 mask 且未选中具体顶点时，Delete/Backspace 删除该 mask；已保存 mask 同步调用后端删除接口。
 - 撤销、重做绑定全局 `maskHistory/maskFuture`，支持工具栏按钮、AI 页按钮和 Canvas 快捷键。
 - 区域合并工具支持多选当前帧 mask，并使用 polygon union 生成合并后的主 mask。
 - 区域去除工具支持多选当前帧 mask，并从第一个选中的主 mask 中扣除后续选中 mask。
+- 区域合并/去除模式显示已选数量，并隐藏 polygon 编辑手柄以避免手柄抢占多选点击。
+- 区域去除结果包含内洞时，前端保留 hole ring 并用 even-odd 规则渲染。
 
 ## R6 AI 推理
 
@@ -65,7 +74,14 @@
 - 前端发送后端契约：`image_id`、`prompt_type`、`prompt_data`、`model`。
 - 点提示传 `{ points, labels }`，正向点 label 为 1，反向点 label 为 0。
 - 框选提示传归一化 `[x1, y1, x2, y2]`。
-- 语义文本提示传 `semantic`；选择 `sam3` 且独立 Python 3.12 环境、CUDA、官方包和 Hugging Face gated 权重访问均满足时走 SAM 3 文本语义推理，选择 `sam2` 时回退到自动分割。
+- 工作区 SAM 2 框选会建立一个候选 mask；后续正向点/反向点会携带原始框和累计点，以 `interactive` prompt 细化并替换同一个候选 mask。
+- 语义文本提示传 `semantic`；选择 `sam3` 且独立 Python 3.12 环境、CUDA、官方包和本地 checkpoint 均满足时走 SAM 3 文本语义推理，选择 `sam2` 时回退到自动分割。
+- SAM 3 支持工作区框选提示；后端把 normalized `[x1, y1, x2, y2]` 转成官方 `add_geometric_prompt()` 需要的 `[center_x, center_y, width, height]` 正框。
+- 当前 SAM 3 前端路径不支持正/反点修正；在工作区用 SAM 3 进行点交互时，前端会提示切回 SAM 2。
+- 工作区“传播片段”会把当前选中区域或当前帧第一个区域作为 seed，调用 `POST /api/ai/propagate`，默认从当前帧向后传播 30 帧并保存结果标注。
+- `POST /api/ai/propagate` 支持 `model=sam2` 或 `model=sam3`；SAM 2 使用官方 `SAM2VideoPredictor.add_new_mask()` 和 `propagate_in_video()`，SAM 3 通过独立 Python 3.12 helper 调用官方 `build_sam3_video_predictor()` video tracker。
+- 传播结果会写入后续帧 `annotations`，`mask_data.source` 分别标记为 `sam2_propagation` 或 `sam3_propagation`，并保留 label、color 和 class 元数据。
+- AI 页面会对 SAM 3 空文本、推理失败和返回 0 个 mask 的情况显示明确反馈。
 - AI 参数支持 `crop_to_prompt`、`auto_filter_background` 和 `min_score`；点/框 prompt 可以裁剪局部区域推理并回映射结果，背景过滤会移除低分结果和包含负向点的 polygon。
 - 后端返回 `polygons` 和 `scores`。
 - 前端把后端 `polygons` 转成 Konva `pathData`、`segmentation`、`bbox`、`area`。
@@ -98,6 +114,7 @@
 - 工作区右侧可以选择模板。
 - 面板显示模板分类和组件本地自定义分类。
 - 用户可以选择具体分类；新 AI mask 会记录 `classId`、`className`、`classZIndex`，并在保存时写入 `mask_data.class`。
+- 如果 Canvas 当前已经选中一个或多个 mask，点击语义分类树会把这些 mask 的 `label`、`color` 和 class 元数据改为该分类；已保存 mask 会进入 `dirty` 状态，归档保存时更新后端。
 - 添加自定义分类只存在组件本地状态，不保存到后端。
 - 置信度、拓扑锚点和重新提取骨架按钮当前为展示/占位。