Pre_Seg_Server/doc/11-frontend-interaction-state-machines.md

前端交互与状态机

本文档记录当前前端真实交互规则，重点覆盖那些不会直接体现在接口契约里的 UI 细节。测试以本文件、doc/07-current-requirements-freeze.md 和 doc/09-test-plan.md 为准。

全局状态

状态字段	所在文件	含义
activeModule	src/store/useStore.ts	当前页面模块；登录后默认 dashboard。
currentProject / frames / currentFrameIndex	src/store/useStore.ts	当前工作项目、帧序列和当前帧。
activeTool	src/store/useStore.ts	工作区当前工具。
selectedMaskIds	src/store/useStore.ts	当前选中的 mask id 列表；Canvas、本体面板和 AI 页共享。
activeTemplateId / projectActiveTemplateIds / activeClass	src/store/useStore.ts	当前项目的激活模板、各项目独立保存的激活模板映射，以及后续新建 mask 使用的语义类别。
maskHistory / maskFuture	src/store/useStore.ts	撤销/重做栈。

工作区工具自动机

状态	进入事件	可用动作	退出事件	测试
idle/no-selection	初始、Esc、左侧“取消选中”、删除 mask、切帧无对应传播结果	右侧语义树只设置后续新建类别；清空遮罩作用于当前帧全部 mask	点击 mask、AI 推送、创建新 mask	CanvasArea.test.tsx、OntologyInspector.test.tsx
mask-selected	move/edit_polygon 下点击 mask、新建 mask 完成、AI 候选选中	右侧语义树给已选 mask 换类；Delete/Backspace/DEL 删除；橡皮擦可扣除；顶点可编辑；创建工具的新几何会并入当前 mask	Esc、左侧“取消选中”、删除 mask、切帧无对应传播结果	CanvasArea.test.tsx
polygon-drawing	create_polygon 下点击画布	继续加点；三点后 Enter 或点击首点闭合	Enter/首点在有选中 mask 时并入选中 mask，无选中时创建新 mask 并显示边界点；Esc 放弃临时点并清选区	CanvasArea.test.tsx
shape-dragging	create_rectangle/create_circle 下按下鼠标	拖拽预览形状	鼠标释放时有选中 mask 则并入选中 mask，无选中时创建新 mask 并显示边界点；切工具取消临时状态	CanvasArea.test.tsx
brush-stroking	brush 且已有 activeClass 或当前选中 mask 时按下鼠标	采样图像范围内圆形笔触	鼠标释放时有选中 mask 则并入选中 mask，无选中时创建新的当前类别 mask；闭合成中空区域时保留内洞 ring；图外落笔不创建；Esc 取消笔触和选区	CanvasArea.test.tsx
eraser-stroking	eraser 且已有选中 mask 时按下鼠标	采样图像范围内圆形笔触	鼠标释放从选中 mask 扣除；扣空则删除该 mask；Esc 取消笔触和选区	CanvasArea.test.tsx
boolean-selecting	area_merge/area_remove	选择多个 mask；主区域黄色实线，参与区域红色虚线	当前帧执行、所有传播帧、按帧范围、取消、切换工具	CanvasArea.test.tsx、VideoWorkspace.test.tsx

细节规则

• Esc 是取消当前交互状态，不是删除：清空 selectedMaskIds、临时多边形点、矩形/圆拖拽状态、画笔/橡皮擦笔触和顶点选择；保留已有 mask、当前 activeClass 和当前工具。
• 切换到 create_polygon、create_rectangle、create_circle 会保留旧 mask 选区；用户若想新建独立 mask，需要先按 Esc 或点击“取消选中”。
• 多边形、矩形、圆和画笔创建完成后，有选中 mask 时会并入选中 mask，无选中 mask 时会自动选中新创建的 mask。
• 画笔和形状创建遵循同一规则：有选中 mask 时并入选中 mask，没有选中 mask 时才新建独立 mask。
• 橡皮擦只作用于当前选中 mask，不会在无选区时启动。
• 绘制类工具点击已有 mask 时继续绘制，不触发 mask 选择。

右侧语义分类树自动机

状态	点击分类结果	后续效果	测试
无选中 mask	仅更新 activeClass	后续新建 mask 使用该类别；已有 mask 不变	OntologyInspector.test.tsx
有选中 mask	更新已选 mask 的 class/label/color；同传播链对应 mask 同步更新	已保存 mask 标记为 dirty；已选 mask 移到前端渲染数组末尾	OntologyInspector.test.tsx
当前 mask 的类别被删除	工作区回显时降级为 maskid:0 “待分类”	保留几何并等待用户重新分类保存	VideoWorkspace.test.tsx
新增分类	打开新增表单时生成一个与当前模板已有颜色不同的默认色，并显示可见色块；保存后写入当前模板并设为当前 active class	新建/后续 mask 使用新增类别	OntologyInspector.test.tsx、classColors.test.ts

键盘交互

按键	前置状态	行为	测试
Esc / 左侧“取消选中”	任意 Canvas 工具	取消选中 mask 和临时绘制状态，不删除 mask，不清 active class	CanvasArea.test.tsx、ToolsPalette.test.tsx
Enter	多边形已有至少 3 点	闭合并创建新 mask	CanvasArea.test.tsx
Delete/Backspace	选中顶点	删除该顶点，保持 polygon 至少 3 点	CanvasArea.test.tsx
Delete/Backspace	选中整块 mask	删除 mask；传播链 mask 走范围确认；人工/AI 帧按确认策略处理	CanvasArea.test.tsx、VideoWorkspace.test.tsx
Ctrl/Cmd+Z	工作区且非输入控件聚焦	撤销 mask 历史	VideoWorkspace.test.tsx、keyboardShortcuts.test.ts
Ctrl/Cmd+Shift+Z / Ctrl/Cmd+Y	工作区且非输入控件聚焦	重做 mask 历史	VideoWorkspace.test.tsx、keyboardShortcuts.test.ts
左/右方向键	工作区时间轴	切换上一帧/下一帧	VideoWorkspace.test.tsx

工作区范围选择自动机

VideoWorkspace 用 rangeSelectionMode 区分四类范围选择：propagation、export、boolean、clear。

模式	进入事件	顶栏状态	时间轴行为	确认行为	测试
propagation	左侧“AI自动推理”	显示传播权重、向前/向后帧数和“开始传播”	拖拽/点击设置传播起止帧	先校验当前 SAM 2.1 权重状态；可用才保存参考帧 draft/dirty seed 并提交 Celery 传播任务	VideoWorkspace.test.tsx
export	打开导出菜单并选择“特定范围帧”	导出菜单保持打开	拖拽/点击设置导出起止帧	“开始导出”保存待归档 mask 后下载 ZIP	VideoWorkspace.test.tsx
boolean	区域合并/去除选择“按帧范围选择”	显示“确认区域合并/确认重叠区域去除”	拖拽/点击设置布尔操作范围	弹最终确认，只同步范围内对应传播帧，保留传播 metadata	CanvasArea.test.tsx、VideoWorkspace.test.tsx
clear	清空/DEL 选择“按帧范围选择”	显示“确认清空”	拖拽/点击设置清空范围	弹最终确认；如范围含人工/AI 帧，再询问是否删除这些帧	VideoWorkspace.test.tsx

取消规则：

• 关闭导出菜单会退出 export 范围选择。
• 在布尔范围确认前重新点击“合并选中/从主区域去除”，会取消旧的顶栏范围请求。
• 清空/删除传播链时选择“取消”不会删除任何 mask。

AI 智能分割自动机

状态	进入事件	主要行为	退出事件	测试
no-prompt	打开 AI 页或清空提示	等待正点/负点/框选	放置提示或框选	AISegmentation.test.tsx
box-prompt	框选完成	仅框选时发送 box prompt	加正/负点后转 interactive	AISegmentation.test.tsx
interactive-prompt	框选后加点或直接点选	发送累计正/负点；负点启用背景过滤	空结果移除旧候选	AISegmentation.test.tsx
candidate-selected	推理返回 mask 或点击候选	可通过语义树换标签；可删除候选	推送工作区、删除候选、重新推理	AISegmentation.test.tsx
send-blocked	候选缺少语义分类时点击推送	显示 error toast，不切模块、不改工具	选择语义分类	AISegmentation.test.tsx
model-unavailable	/api/ai/models/status 返回所选 SAM 2.1 变体不可用	禁用不可用模型按钮和执行按钮；不调用 /api/ai/predict	后端模型状态恢复可用或切换到可用变体	AISegmentation.test.tsx

模板与项目确认流

交互	状态机	测试
切换激活模板	无 mask 直接切换；有任意 mask 时弹确认；确认后删除项目所有本地/后端标注再切换；取消则保持原模板	OntologyInspector.test.tsx
切换项目	项目 ID 变化时清空临时帧、mask、选区和撤销栈，并按项目 ID 恢复该项目上次使用的激活模板；若本会话没有该项目模板记忆，则从已保存 mask 的 templateId 推断项目模板；同一项目对象刷新名称/封面时不清空工作区	useStore.test.ts、templateSelection.test.ts
删除模板	站内确认后删除；系统默认模板可由演示恢复出厂设置恢复	TemplateRegistry.test.tsx、后端模板/管理员测试
复制模板	鼠标点击复制入口，生成当前用户私有副本并保留分类颜色、maskid 和层级	TemplateRegistry.test.tsx
项目复制	项目删除按钮旁复制入口；可选“新项目重置”或“全内容复制”	ProjectLibrary.test.tsx
演示恢复出厂设置	管理员危险区二次确认并要求输入 RESET_DEMO_FACTORY；后端也校验 confirmation	UserAdmin.test.tsx、backend/tests/test_admin.py

文件与导入导出交互

交互	状态机	测试
视频/DICOM 上传	选择文件后显示上传进度；DICOM 显示有效文件数量；上传后继续轮询解析任务进度	ProjectLibrary.test.tsx
显式生成帧/重新生成帧	只对有源视频的视频项目显示；项目名称编辑状态不显示；DICOM 项目不显示；已有帧时显示“重新生成帧”并提示会清空旧帧、标注和 mask；入队后轮询解析任务，成功后刷新项目列表并立即显示新封面	ProjectLibrary.test.tsx
GT Mask 导入	选择文件后预览并选择未知 maskid 策略；非法格式返回错误；尺寸不一致最近邻拉伸；导入结果与普通 mask 同体验	VideoWorkspace.test.tsx、后端 AI 测试
分割结果导出	默认当前帧；可选整体/范围；范围可用时间轴；导出前保存待归档 mask；按钮带导出图标和绿色强调背景	VideoWorkspace.test.tsx、api.test.ts、后端导出测试

维护要求

新增或修改前端交互时，应同步做三件事：

1. 更新本文件中对应状态机或规则。
2. 在 doc/09-test-plan.md 的覆盖矩阵中写明测试归属。
3. 添加或更新组件测试，至少覆盖状态转移的进入条件、退出条件和副作用。