Pre_Seg_Server/doc/08-current-design-freeze.md

当前设计冻结文档

冻结日期：2026-05-01

本文档描述当前代码结构、数据流、接口契约和测试边界。后续实现如果改变这些设计，应同步更新本文档和测试。

总体架构

当前系统由三层组成：

• React + TypeScript 前端 SPA。
• FastAPI 后端 API。
• PostgreSQL、MinIO、Redis、SAM 2 等外部基础设施。SAM 3 相关源码保留，但当前产品入口禁用。

开发时前端通过 server.ts 启动 Express + Vite middleware；后端通过 backend/main.py 启动 FastAPI。前端业务接口访问 FastAPI，server.ts 不再保留旧版 /api/* mock。

前端模块

模块	文件	设计职责
应用入口	src/App.tsx	根据登录状态和 activeModule 切换页面
全局状态	src/store/useStore.ts	Zustand store，保存项目、帧、模板、mask、当前选中 mask ids、工具状态和 mask 撤销/重做历史栈
API 封装	src/lib/api.ts	Axios 客户端、字段映射、AI 响应转换
配置	src/lib/config.ts	推导 API 和 WebSocket 地址
WebSocket	src/lib/websocket.ts	进度流连接、订阅、连接状态通知、心跳和重连
模型状态	src/components/ModelStatusBadge.tsx	展示 GPU 与当前 SAM 模型真实可用状态；工作区顶栏使用 compact 形态，只显示 GPU/CPU 状态，具体传播权重由旁边下拉负责
登录页	src/components/Login.tsx	调用登录 API，写入 store
Dashboard	src/components/Dashboard.tsx	展示统计、任务控制、失败详情和 WebSocket 进度消息
项目库	src/components/ProjectLibrary.tsx	项目列表、新建、删除、导入视频/DICOM、显式生成帧
工作区	src/components/VideoWorkspace.tsx	加载帧和模板，组织工具栏、Canvas、本体面板、时间轴
Canvas	src/components/CanvasArea.tsx	显示帧、缩放平移、点/框提示、渲染 mask
工具栏	src/components/ToolsPalette.tsx	切换工具、跳转 AI 页面、触发 mask 撤销/重做；紧凑垂直布局，高度不足时自身滚动；外层宽 56px，按钮列固定 48px，滚动条使用右侧外扩空间和低对比 seg-scrollbar
工作区顶栏	src/components/VideoWorkspace.tsx	保存/导出/传播/按起止帧批量清空遮罩/导入 GT、显式撤销/重做按钮和工作区快捷键
时间轴	src/components/FrameTimeline.tsx	帧导航、播放进度、视频处理进度条、自动传播历史片段、自动传播范围选择、左右方向键切帧、播放和当前/总时长显示
本体面板	src/components/OntologyInspector.tsx	模板选择、工作区 mask 透明度、分类树、后端自定义分类、mask 后端属性分析；内容过长时自身滚动，滚动条使用低对比 seg-scrollbar
AI 页面	src/components/AISegmentation.tsx	独立 AI 推理视图，使用当前项目帧
模板库	src/components/TemplateRegistry.tsx	模板 CRUD、分类编辑、导入、排序
短提示浮层	src/components/TransientNotice.tsx	项目库和模板库的非阻塞成功/失败提示，自动消失

后端模块

模块	文件	设计职责
应用入口	backend/main.py	FastAPI app、CORS、路由注册、健康检查、WebSocket
配置	backend/config.py	Pydantic settings
数据库	backend/database.py	SQLAlchemy engine、session、Base
模型	backend/models.py	Project、Frame、Template、Annotation、Mask、ProcessingTask
Schema	backend/schemas.py	Pydantic 请求/响应模型
Auth	backend/routers/auth.py	开发登录
Projects	backend/routers/projects.py	项目与帧 CRUD
Templates	backend/routers/templates.py	模板 CRUD 和 mapping_rules 打包/解包
Media	backend/routers/media.py	上传媒体和拆帧
AI	backend/routers/ai.py	当前启用 SAM 2 推理、视频传播、模型状态和标注保存
传播任务	backend/services/propagation_task_runner.py	Celery 中执行自动传播 steps，写任务进度并保存传播标注
Export	backend/routers/export.py	COCO 和 PNG mask 导出
SAM 2	backend/services/sam2_engine.py	SAM 2 懒加载、状态检测、点/框/自动推理和视频 mask 传播
SAM 3	backend/services/sam3_engine.py, backend/services/sam3_external_worker.py, backend/setup_sam3_env.sh	历史保留的 SAM 3 桥接源码和脚本；当前未接入 registry
SAM Registry	backend/services/sam_registry.py	当前暴露 SAM 2.1 四个变体、GPU 状态和推理分发

状态模型

前端 store 的核心对象：

• Project：项目基本信息、状态、帧数、fps、媒体路径。
• Frame：帧 ID、项目 ID、索引、图片 URL、宽高、序列时间戳和原视频源帧号。
• Template / TemplateClass：模板和分类定义。
• Mask：前端渲染用 mask，包含 pathData、segmentation、bbox、area。
• selectedMaskIds：Canvas 当前选中的 mask id 列表，供右侧本体面板对已选区域直接换标签。
• maskHistory / maskFuture：mask 编辑历史栈，用于撤销和重做。
• activeModule：当前页面。
• activeTool：当前工具。
• aiModel：当前启用的 AI 模型，取值为 sam2.1_hiera_tiny、sam2.1_hiera_small、sam2.1_hiera_base_plus 或 sam2.1_hiera_large，默认 sam2.1_hiera_tiny。

关键数据流

登录

1. Login 收集用户名和密码。
2. login() 调用 POST /api/auth/login。
3. 成功后 store 写入 token，App 渲染主界面。

项目导入与生成帧

1. ProjectLibrary 创建项目。
2. 导入视频时上传源视频到 /api/media/upload 并关联项目；该步骤不调用 /api/media/parse。
3. 用户在项目卡片点击“生成帧”，在弹窗中选择目标 FPS。
4. 前端调用 /api/media/parse 创建异步拆帧任务；可通过 parse_fps、max_frames 和 target_width 指定标准帧序列参数。
5. Celery worker 执行 FFmpeg/OpenCV/pydicom 拆帧，视频帧按 frame_%06d.jpg 从 frame_000000.jpg 连续命名，并按目标宽度缩放。
6. worker 写入 frames.timestamp_ms 和 frames.source_frame_number，并在任务 result.frame_sequence 中记录 FPS、帧数、时长、尺寸和对象存储前缀。
7. worker 持续更新 processing_tasks，并发布 Redis seg:progress。
8. 刷新项目列表；项目卡片右上角 FPS 徽标显示生成关键帧序列时选择的 parse_fps，原始视频 FPS 仅作为底部“原 xx fps”辅助信息显示。
9. 导入视频、生成帧、上传 DICOM 和失败反馈使用 TransientNotice，不再使用浏览器 alert() 阻塞操作；提示默认数秒后自动消失。

任务控制

1. Dashboard 从 GET /api/dashboard/overview 读取 queued/running/success/failed/cancelled 任务；queued/running 代表当前进度，success/failed/cancelled 代表最近任务状态。
2. 用户取消任务时，前端调用 POST /api/tasks/{task_id}/cancel；后端写入 cancelled、设置 finished_at，并尝试 celery_app.control.revoke(..., terminate=True)。
3. worker 在下载、解析、上传、写帧等关键阶段刷新任务状态；如果发现 cancelled，停止后续写入并发布 cancelled 事件。
4. 用户重试任务时，前端调用 POST /api/tasks/{task_id}/retry；后端基于原任务 payload 创建新任务，记录 retry_of 并重新投递 Celery。
5. 用户打开详情时，前端调用 GET /api/tasks/{task_id}，弹窗展示 error、payload、result、Celery ID 和时间。
6. Dashboard 通过 /ws/progress 接收 Redis seg:progress 转发事件；前端 WebSocket 客户端在 onopen/onclose/onerror 主动更新连接状态，并定时发送 ping 心跳，服务端返回 status 确认连接仍活跃。

工作区加载

1. VideoWorkspace 根据 currentProject.id 调用 getProjectFrames()。
2. 若无帧但项目有 video_path，显示“尚未生成帧”的状态提示，不自动触发 parseMedia()。
3. 帧数据映射为 store Frame[]，包含 timestampMs 和 sourceFrameNumber，供时间轴和后续视频传播使用。
4. 工作区调用 GET /api/ai/annotations 回显已保存标注时，会替换当前项目帧中的已保存 mask，但保留没有 annotationId 的未保存 draft mask；这保证 AI 页推送到工作区的候选 mask 不会被异步回显覆盖，并会在合并完成后恢复仍然存在的已选 mask id。
5. CanvasArea 会把全局 selectedMaskIds 中仍存在于当前帧的 id 同步回本地选区，避免帧初始化时的临时清空覆盖 AI 页推送过来的选中态。
6. CanvasArea 根据容器和帧尺寸按 86% 适配比例计算初始 scale/position，使底图默认居中且尽量大，但保留画布边距；滚轮缩放和拖拽平移仍由用户后续控制。
7. FrameTimeline 顶部播放进度条显示当前播放位置；其下方视频处理进度条根据 Mask.metadata.source / propagated_from_frame_id 计算自动传播帧并显示蓝色区段，对人工绘制或 AI 智能分割等非传播 mask 帧显示红色竖线。普通状态下，视频处理进度条可点击跳转到对应帧，红色人工/AI 标注帧和蓝色自动传播帧标识本身也可点击跳转。处理条未处理背景使用中性灰，和红色/蓝色标记保持明显区分。VideoWorkspace 会记录当前会话最近 8 次成功处理过的自动传播范围，并通过 propagationHistory 传给 FrameTimeline；时间轴会把这些片段叠加为不同色系的横向渐变条，片段内按视频时间从深到浅，较早片段降低透明度。底部缩略图导航轴对非当前帧使用红色边框标识人工/AI 标注帧，使用蓝色边框标识自动传播/推理帧；如果同一帧同时存在人工/AI 标注和自动传播结果，红色人工/AI 标注边框优先保留，自动传播状态只作为蓝色内描边。当前帧使用青色外框高亮优先，若当前帧同时是人工/AI 标注帧，则以青色外框加红色内描边同时表达两个状态，外层当前帧框和内层人工/AI 框的顺序固定。工作区进入自动传播或清空片段遮罩范围选择模式时，播放进度条和视频处理进度条显示 amber 覆盖层，并可点击/拖拽设置处理起止帧。
8. 当前帧传入 CanvasArea。
9. 工作区顶栏短状态文本会在空闲状态下自动消失；保存、导出、导入 GT 和传播任务运行中仍保留进度状态，无帧项目提示也会保留。
10. 左侧工具栏和右侧本体/语义分类面板使用 seg-scrollbar 定制纵向滚动条；默认滚动条 thumb 低透明度融入深色背景，hover/focus 时增强为青色提示，避免系统默认滚动条在工具区中过于突兀。左侧工具栏额外保留右侧滚动条槽位，按钮列仍按原 48px 布局，避免滚动条和图标抢空间。
11. 右侧面板不再显示“本体论与属性分类管理树”固定说明栏，直接展示实际可操作内容。
12. 右侧“遮罩透明度”滑杆写入 Zustand maskPreviewOpacity，CanvasArea 用该值计算 mask group opacity；选中 mask 在基础透明度上加亮，方便保留选中反馈。
13. Canvas 点击 mask 后，全局 selectedMaskIds 会同步到 OntologyInspector；本体面板按选中 mask 的 classId、className/label 和颜色匹配模板分类，自动设置 active class，并把分类按钮滚动/聚焦到可见区域。
14. 工作区顶栏“清空片段遮罩”和“自动传播”共用时间轴范围选择交互；第一次点击“清空片段遮罩”会进入范围选择模式，按钮变为“确认清空”，用户可在播放进度条或视频处理进度条上点击/拖拽选择起止帧；确认执行时对范围内已保存 mask 调用 DELETE /api/ai/annotations/{id}，同时移除范围内本地 draft mask 和被清空的选区，范围外 mask 保持不变。

AI 点/框推理

1. 用户在 Canvas 选择正向点、反向点或框选。
2. CanvasArea 读取当前帧 ID 和宽高。
3. SAM 2.1 框选会创建一个候选 mask，并记录原始框；后续正向点/反向点会累计到同一候选上。
4. predictMask() 归一化坐标并携带当前 model 调用 /api/ai/predict；同时有框和点时发送 interactive prompt。
5. SAM 2.1 请求中只要存在反向点，CanvasArea 会额外发送 options.auto_filter_background=true 和 options.min_score=0.05，让后端移除低分结果和包含负向点的 polygon。
6. 后端加载帧图片并通过 SAM registry 分发到所选 SAM 2.1 变体；model=sam2 会兼容归一化为 tiny，model=sam3 会被拒绝。
7. 前端把 polygons 转为 mask；交互式细化会替换同一个候选 mask，而不是新增多个 mask。
8. 若带反向点的 SAM 2.1 细化返回空结果，前端会删除当前旧候选 mask 并提示反向点已排除该区域。
9. AI 页面只按本页最新生成的候选 id 渲染 mask，不把工作区已有 mask 带入 AI 画布；每次 runInference() 都先过滤掉旧 aiMaskIds 对应候选，再写入本次最高分候选。
10. AI 页面候选 mask 的 Path 点击事件会先判断当前工具；正向/反向选点工具下点击 mask 会继续追加提示点，其他工具下才选中 mask。
11. 工作区 SAM 提示点由 CanvasArea 本地 points 状态维护；点击已渲染提示点会先 cancelBubble，再删除对应点并按剩余提示重新调用 runInference()，避免同一次点击继续触发 Stage 加点或 Path 选择。
12. AI 页面边界框选由 promptBox/boxStart/boxCurrent 维护；拖拽时渲染蓝色虚线框，鼠标释放后固化 promptBox 并清空旧提示点，避免旧点误绑定到新框。
13. AI 页面执行分割时，如果只有 promptBox 则发送 box prompt；如果 promptBox 和 points 同时存在，predictMask() 会发送 interactive prompt。
14. AI 页面提示点由本地 points 状态维护；点击已渲染提示点会按 index 删除对应点，“删除最近锚点”会删除数组最后一个点，不改动候选 mask 列表。
15. AI 页面候选 mask 删除只接受当前 aiMaskIds 范围内的已选 id；“删除选中候选”和 Delete/Backspace 都复用该范围过滤，避免删除工作区已有 mask。
16. AI 页面参数开关文案只做展示增强：“局部专注模式（自动裁剪无锚区域）”仍控制 cropMode/crop_to_prompt，“严格除杂模式（自动清理干涉点）”仍控制 autoDeleteBg/auto_filter_background/min_score。
17. AI 页面“遮罩清晰度”滑杆只调节候选 mask 的 Konva preview opacity，不写入 Mask.segmentation、分类元数据或后端 payload。
18. AI 画布左上角根据正向点、反向点、边界框选和视口控制显示上下文提示，说明点击/拖拽、删除提示点和执行推理的操作方式。
19. AI 画布根据容器和当前帧尺寸按 86% 适配比例计算初始 scale/position，使底图默认居中且尽量大，但保留画布边距。
20. Canvas 按当前帧过滤并渲染 mask。
21. 新 mask 会带上当前选择的模板分类元数据，包括 classId、className、classZIndex、metadata.source=ai_segmentation 和保存状态 draft。
22. 用户点击“结构化归档保存”后，前端将像素 segmentation 转成 normalized mask_data.polygons；未保存 mask 调用 POST /api/ai/annotate，dirty mask 调用 PATCH /api/ai/annotations/{annotation_id}；保存成功后本次提交的 draft mask id 会从本地保留列表中排除，并由后端 saved annotation 回显替换。
23. 工作区加载项目帧后通过 GET /api/ai/annotations 取回已保存标注并转成前端 mask。
24. 工作区“清空遮罩”删除当前帧已保存标注，并清除当前帧本地 mask。

视频片段传播

1. 用户在工作区打开一帧作为参考帧；该帧全部 mask 都会作为传播 seed，不再提供传播对象下拉。
2. 用户可以直接修改传播起始帧/结束帧数字框，并可通过工作区顶栏“传播权重”下拉独立选择本次传播使用的 SAM 2.1 tiny/small/base+/large 权重；该入口不提供 SAM2/SAM3 家族切换，默认跟随全局 AI 权重，用户手动选择后不再被 AI 页权重切换覆盖。
3. VideoWorkspace 以当前参考帧为 seed，将起止帧拆成 backward 和/或 forward 两段；只包含当前帧时不传播。
4. VideoWorkspace 在提交传播前会先调用现有归档保存链路保存当前项目中的 draft/dirty mask，并重新读取 store 中的回显结果；参考帧 seed 因此优先携带稳定的后端 source_annotation_id，避免用前端临时 mask id 生成传播结果后，二次传播无法找到旧结果。
5. VideoWorkspace 用 buildAnnotationPayload() 把每个 seed mask 转成 normalized polygon、bbox、label、color、class 元数据、source_mask_id 和可用时的 source_annotation_id；如果 seed mask 是未编辑的自动传播结果，会沿用其原始 source_annotation_id/source_mask_id/propagation_seed_signature，让后端把它识别为原传播链的同一个 seed；如果该传播结果被编辑并保存，更新 payload 只保留 lineage，不保留旧签名，使后端按“已修改”路径清理旧结果并重传。
6. 前端把传播权重 id、每个 seed、每个方向组装成 steps，一次调用 POST /api/ai/propagate/task，include_source=false、save_annotations=true；接口先规范化/校验 model 字段中的权重 id，再创建 processing_tasks.task_type=propagate_masks 并投递 Celery，避免长 HTTP 请求阻塞前端等待。
7. VideoWorkspace 记录返回的 task_id，轮询 GET /api/tasks/{task_id} 显示任务 message、步骤进度、已处理帧次和已保存区域数；任务运行期间提供取消传播按钮，调用通用 POST /api/tasks/{task_id}/cancel。
8. Celery worker 逐 step 顺序执行传播，避免多个视频 tracker 并发抢占 GPU；每个 step 开始/完成都会写入 processing_tasks.progress/result/message 并发布 Redis seg:progress，Dashboard 可同步显示。每个 step 开始前，worker 会在本次目标帧段内用 seed 来源 id、传播方向和 seed 签名查找旧传播标注：同权重、签名相同且目标帧都已有结果时跳过该 seed；签名不同、目标帧只部分覆盖或本次使用了其他 SAM 2.1 权重则先删除本次目标帧段内对应方向的旧自动传播标注，再执行新的 video predictor 传播。对旧版本只记录前端临时 source_mask_id 的传播标注，worker 会按 label/color/class 做兼容匹配，确保可被后续稳定 source_annotation_id 的传播替换。
9. 后端按项目帧序列截取片段，下载对应帧到临时目录，并写成 000000.jpg 这类纯数字文件名；这是 SAM2VideoPredictor 对视频帧排序的要求，和项目库中持久化的 frame_%06d.jpg 对象名无关。
10. model 为任一 SAM 2.1 权重变体时，sam2_engine 使用对应 checkpoint/config 加载 SAM2VideoPredictor.add_new_mask() 注入 seed mask，再用 propagate_in_video() 传播；model=sam2 会在入队时规范化为 tiny，任务 payload/result 会保留规范化后的权重 id；单个 SAM2 video predictor 调用内部暂不提供逐帧流式进度。
11. model=sam3 当前不支持；SAM 3 video tracker 代码保留但没有接入产品路径。
12. 后端把传播返回的 normalized polygon 保存为后续帧 Annotation，跳过源帧，mask_data.source 记录权重传播来源，同时写入 propagation_seed_key、propagation_seed_signature、propagation_direction、source_annotation_id 和 source_mask_id 供后续幂等传播判断。
13. 前端轮询到已创建区域后刷新 GET /api/ai/annotations 并回显新标注；任务结束后如果后端返回 0 个新区域，工作区会明确提示没有生成新的 mask，若是未改变 seed 被跳过则提示未改变 mask 已跳过。处理过帧次大于 0 的成功任务会追加一条本地传播历史片段，用于视频处理进度条显示最近传播范围；annotationToMask() 会保留传播来源 metadata，供时间轴视频处理进度条显示蓝色传播区段。

手工绘制与历史栈

1. 用户在 ToolsPalette 选择多边形、矩形、圆、点或线工具。
2. CanvasArea 将交互坐标转换成像素 polygon。
3. 多边形工具逐次记录节点，三点后点击首节点或按 Enter 时生成闭合 polygon。
4. Canvas 左上角根据当前工具和操作阶段显示上下文短提示；多边形提示会随已放置点数切换，明确 Enter 完成、Esc 取消和点击首节点闭合。提示会在工具或操作状态变化时出现，并在数秒后自动隐藏，避免长期遮挡底图。
5. mask path 只在 move、edit_polygon、area_merge 和 area_remove 工具下拦截点击；绘制和 AI prompt 工具点击已有 mask 时继续冒泡给 Stage。
6. 新 mask 写入 pathData、像素 segmentation、bbox、area 和当前模板分类元数据。
7. addMask()、setMasks()、updateMask()、clearMasks() 会维护 maskHistory/maskFuture。
8. 工具栏按钮、工作区顶栏按钮和 AI 页按钮调用 undoMasks() / redoMasks()；工作区由 VideoWorkspace 统一处理 Ctrl/Cmd+Z、Ctrl/Cmd+Shift+Z 和 Ctrl/Cmd+Y，并在输入框、下拉框和可编辑文本聚焦时跳过快捷键，避免影响帧范围输入。

Polygon 逐点编辑

1. 用户选择“调整多边形”或“拖拽/选择”后点击 Canvas 上的 mask path，CanvasArea 记录 selectedMaskId 并显示该 mask 第一条 polygon 的顶点控制点和边中点插入手柄。
2. 顶点 mousedown/dragstart 会立即设置当前顶点选择；拖动过程中通过 dragMove 实时重算 pathData、像素 segmentation、bbox、area，不需要先单击顶点再拖动。
3. Stage 的 onDragEnd 只处理 Stage 自身拖拽；polygon 顶点、GT seed point 等子节点拖拽结束事件会被忽略，避免子节点坐标误写入 Canvas position 导致视口跳动。
4. 点击边中点手柄会在该边中点插入新顶点；在“调整多边形”工具下双击 polygon path 会在最接近的线段上按双击位置插入新顶点。
5. 如果 mask 已有 annotationId，编辑会把 saveStatus 标成 dirty 且 saved=false。
6. 归档保存时复用现有 PATCH /api/ai/annotations/{annotation_id} 链路，把更新后的 normalized polygon 写回后端。
7. 选中顶点后 Delete/Backspace 可删除顶点；前端保持 polygon 至少三点。
8. 未选中具体顶点但选中了 mask 时，Delete/Backspace 从前端 store 删除该 mask；如果包含 annotationId，通过工作区回调调用后端删除接口。

区域合并与去除

1. 用户选择 area_merge 或 area_remove 后，点击多个当前帧 mask 组成选择集。
2. 合并/去除模式隐藏 polygon 顶点和边中点编辑手柄，并在右下角显示已选数量；少于两个 mask 时操作按钮禁用。
3. Canvas 左上角提示布尔选择顺序：第一个选中的是主区域，后续区域参与合并或扣除。
4. 布尔选择态按选择顺序区分角色：第一个选中的主区域使用黄色实线轮廓，后续参与合并/扣除的区域使用红色虚线轮廓；所有已选区域填充透明度保持一致，避免被误解为阴影模式异常。
5. CanvasArea 把 Mask.segmentation 转为 polygon-clipping 的 MultiPolygon。
6. area_merge 使用 union，更新第一个选中的主 mask，并从前端 store 移除后续被合并 mask；如果被移除 mask 已保存，会调用工作区传入的删除回调删除后端标注。
7. area_remove 使用 difference，从第一个选中的主 mask 中扣除后续选中 mask，扣除对象本身保留；如果 difference 产生内洞，segmentation 保留外圈和 hole ring，渲染时使用 even-odd fill。
8. 结果会重算 pathData、segmentation、bbox、area，已保存主 mask 会进入 dirty 状态并复用归档 PATCH 链路；带洞结果的面积按外圈减内洞计算。

GT Mask 导入

1. 工作区“导入 GT Mask”选择图片文件。
2. 前端 importGtMask() 以 multipart form-data 调用 POST /api/ai/import-gt-mask，携带 project_id 和 frame_id。
3. 后端验证项目、帧、模板后使用 OpenCV 读取灰度 mask。
4. 后端按非零像素值拆分多类别标签。
5. 后端对每个类别的前景做 contour 提取，每个连通域保存为一个 Annotation。
6. points 字段保存距离变换中心 seed point，mask_data.polygons 保存 normalized polygon，mask_data.gt_label_value 保存原始像素类别值。
7. 前端重新读取项目标注并回显。
8. annotationToMask() 会把 normalized seed point 转成像素坐标，Canvas 以可拖拽点显示；拖动后 buildAnnotationPayload() 会把点再归一化写回后端。

模板管理

1. TemplateRegistry 从后端读取模板。
2. 编辑态在组件本地维护分类列表。
3. 保存时调用 createTemplate() 或 updateTemplate()。
4. 后端把 classes、rules 打包进 mapping_rules。
5. 返回时再解包给前端。
6. CanvasArea 把当前选中的 mask id 同步到全局 selectedMaskIds；切换工具、切换帧或卸载 Canvas 时会清空选择。
7. AISegmentation 生成 mask 后会写入全局 masks 并把生成的 mask id 写入 selectedMaskIds；点击 AI 页预览 mask 也会更新 selectedMaskIds。
8. AI 页“推送至工作区编辑”会切换到工作区并把 activeTool 设为 edit_polygon；CanvasArea 初始读取全局 selectedMaskIds，让 AI 页选中的 mask 在工作区继续保持选中。
9. 工作区帧/标注异步加载完成后，hydrateSavedAnnotations() 会合并本地未保存 draft mask 和后端已保存 mask，不会用后端回显结果直接覆盖整个 masks store。
10. OntologyInspector 可以选择具体分类；选择结果进入全局 store，供 CanvasArea 和 AISegmentation 新建/更新 mask 时使用。
11. 如果 selectedMaskIds 中存在当前 store 的 mask，点击分类时会立即更新这些 mask 的 templateId、classId、className、classZIndex、label 和 color。
12. 同一次点击会把这些已选 mask 移动到前端 masks 数组末尾；CanvasArea 按数组顺序渲染，后渲染的 Path 显示在最上层，方便用户继续编辑刚换标签的区域。该显示置顶不改变模板 zIndex 或后端导出语义覆盖规则。
13. 已保存 mask 被重新分类后进入 dirty 且 saved=false，继续复用工作区归档保存的 PATCH 链路。
14. 模板保存、删除和 JSON 导入失败使用 TransientNotice 非阻塞提示，默认数秒后自动消失。

导出

1. 后端根据项目、帧、标注和模板生成 COCO JSON。
2. PNG mask 导出会把 normalized polygon 渲染为单标注二值 mask。
3. PNG mask 导出还会按 mask_data.class.zIndex 或模板 z_index 从低到高覆盖，生成每帧语义融合 mask。
4. ZIP 内写入 semantic_classes.json，记录语义值到类别、颜色和 zIndex 的映射。
5. 前端“导出 JSON 标注集”和“导出 PNG Mask ZIP”按钮都会在导出前保存待归档标注，然后下载对应文件。

接口契约

接口详情见 doc/04-api-contracts.md。测试中重点固定以下契约：

• updateProject() 使用 PATCH /api/projects/{id}。
• exportCoco() 使用 GET /api/export/{projectId}/coco。
• exportMasks() 使用 GET /api/export/{projectId}/masks。
• cancelTask() 使用 POST /api/tasks/{taskId}/cancel。
• retryTask() 使用 POST /api/tasks/{taskId}/retry。
• predictMask() 使用 POST /api/ai/predict，请求体为 image_id、prompt_type、prompt_data、model。
• propagateMasks() 使用 POST /api/ai/propagate，请求体为 project_id、frame_id、model、seed、direction、max_frames，作为单 seed 同步兼容接口保留。
• queuePropagationTask() 使用 POST /api/ai/propagate/task，请求体为 project_id、frame_id、model、steps、include_source、save_annotations，返回 ProcessingTask。
• saveAnnotation() 使用 POST /api/ai/annotate。
• importGtMask() 使用 POST /api/ai/import-gt-mask multipart form-data。
• getProjectAnnotations() 使用 GET /api/ai/annotations。
• updateAnnotation() 使用 PATCH /api/ai/annotations/{annotationId}。
• deleteAnnotation() 使用 DELETE /api/ai/annotations/{annotationId}。
• parseMedia() 使用 POST /api/media/parse?project_id=...，可选 parse_fps、max_frames、target_width，用于生成标准帧序列。
• getProjectFrames() 返回帧图像 URL、宽高、timestamp_ms 和 source_frame_number。
• 后端 /api/ai/predict 当前支持 SAM 2.1 的 point、box、interactive；semantic 文本提示禁用并返回 400。
• SAM 2.1 是点/框交互式分割模型，不做文本语义分割；AI 页面已经移除纯文本输入。
• SAM 2.1 点提示和 auto fallback 只返回一个最高分候选，避免同一提示产生多个重叠候选 mask。
• SAM 3 前端入口、后端 registry 入口和状态展示均已禁用；model=sam3 会返回不支持。
• 后端 /api/ai/predict 支持可选 options：crop_to_prompt 会对 point/box/interactive prompt 做局部裁剪推理并回映射 polygon，auto_filter_background 会按 min_score 和负向点过滤结果。
• 后端 /api/ai/propagate/task 当前支持所选 SAM 2.1 mask seed 视频传播后台任务；同步 /api/ai/propagate 仍保留为单 seed 兼容接口。
• 后端 /api/ai/models/status 返回 GPU 和四个 SAM 2.1 变体的真实运行状态。
• point prompt 支持旧数组形式和 { points, labels } 对象形式。

外部依赖边界

测试不直接依赖以下真实服务：

• PostgreSQL：后端测试使用内存 SQLite。
• MinIO：上传、下载、预签名 URL 使用 monkeypatch。
• Redis：单测使用 monkeypatch 验证进度事件发布，不依赖真实 Redis 服务。
• SAM：AI 推理测试使用 fake registry。
• 浏览器 Canvas/Konva 图片加载：前端测试 mock react-konva 和 use-image。

已知占位设计

以下能力属于当前冻结版本的占位或半可用功能：

• Dashboard 初始快照来自 GET /api/dashboard/overview；任务进度区由 processing_tasks queued/running/success/failed/cancelled 任务生成，处理中统计只计算 queued/running。
• 已保存标注支持通过“应用分类”、polygon 顶点拖动/删除、边中点插入、多 polygon 子区域编辑和区域合并/去除进入 dirty 状态并归档更新；选中整块 mask 可用 Delete/Backspace 删除并同步后端；复杂洞结构编辑尚未实现。
• SAM 3 文本语义分割已从当前产品路径中禁用；相关源码保留，恢复时需要重新接入前端入口、registry、状态接口和测试。
• 自定义分类通过 PATCH /api/templates/{id} 写入当前激活模板的 mapping_rules.classes。
• 选中 mask 后，本体面板调用 POST /api/ai/analyze-mask 显示后端模型置信度、拓扑锚点数量、面积等属性；“重新提取拓扑锚点”会带 extract_skeleton=true 重新请求后端分析。
• GT mask 导入已完成多类别像素值拆分、contour、distance transform seed point 和前端 seed point 拖拽编辑；骨架提取、HDBSCAN 聚类和模板自动映射尚未实现。