# 当前需求冻结文档 冻结日期：2026-05-01 本文档描述当前仓库已经实现或明确保留为占位的需求。测试用例以本文档为准，不把早期设想或 Word 文档中的远期能力当作当前版本必须实现的功能。 ## R1 登录与会话 - 系统提供登录页。 - 默认开发凭证为 `admin / 123456`。 - 登录成功后前端保存 token，并进入主应用。 - 登录失败时显示错误信息。 - 当前 token 是开发用固定 token，不做真实 JWT 校验。 ## R2 项目管理 - 前端展示项目库，并从 `GET /api/projects` 获取项目列表。 - 用户可以新建项目，前端调用 `POST /api/projects`。 - 用户可以选择项目，进入工作区。 - 用户可以导入视频文件，前端创建项目、上传文件、触发拆帧、刷新项目列表。 - 用户可以导入 DICOM 序列，前端上传 DICOM、触发拆帧、刷新项目列表。 - 后端支持项目创建、列表、详情、局部更新和删除。 - 后端支持项目帧创建、列表和单帧查询。 ## R3 媒体上传与拆帧 - 后端允许上传视频、图片、DICOM 文件，其他扩展名返回 400。 - 未提供项目 ID 上传时，后端自动创建项目。 - 提供项目 ID 上传时，后端把上传对象关联到该项目。 - 拆帧接口根据项目 `source_type` 处理视频或 DICOM。 - 拆帧完成后写入 `frames` 记录，并把项目状态设为 `ready`。 - 拆帧接口会创建 `processing_tasks` 记录并投递 Celery worker。 - 前端可通过 `GET /api/tasks/{task_id}` 查询任务状态。 ## R4 工作区与帧浏览 - 工作区根据当前项目加载帧列表。 - 若项目有媒体但无帧，工作区会尝试触发拆帧后重新加载。 - Canvas 显示当前帧图片。 - Canvas 支持滚轮缩放、移动工具拖拽、鼠标坐标显示。 - 时间轴支持缩略图点击切帧、range 拖动切帧、播放/暂停顺序推进帧。 - 播放帧率使用项目 `parse_fps` 或 `original_fps`，限制在 1 到 30 FPS。 ## R5 工具栏 - 工具栏可以切换当前 active tool。 - 正向点、反向点、框选工具会影响 Canvas 交互。 - 魔法棒按钮切换到 AI 页面。 - 多边形、矩形、圆、点、线、合并、去除、撤销、重做当前只提供 UI 状态或占位按钮，不完成真实绘制/算法。 ## R6 AI 推理 - 前端可以在 AI 页面选择 `sam2` 或 `sam3`，选择结果存放在全局 store。 - 前端和工作区通过 `GET /api/ai/models/status` 展示 GPU、SAM 2 和 SAM 3 的真实运行状态。 - 前端 `predictMask()` 调用 `POST /api/ai/predict`。 - 前端发送后端契约：`image_id`、`prompt_type`、`prompt_data`、`model`。 - 点提示传 `{ points, labels }`，正向点 label 为 1，反向点 label 为 0。 - 框选提示传归一化 `[x1, y1, x2, y2]`。 - 语义文本提示传 `semantic`；选择 `sam3` 且环境满足依赖时走 SAM 3 文本语义推理，选择 `sam2` 时回退到自动分割。 - 后端返回 `polygons` 和 `scores`。 - 前端把后端 `polygons` 转成 Konva `pathData`、`segmentation`、`bbox`、`area`。 - AI 推理结果先存放在前端 store 的 `masks` 中，点击“结构化归档保存”后持久化到后端标注表。 ## R7 标注保存 - 后端提供 `POST /api/ai/annotate` 保存标注。 - 保存时必须存在项目；如果传入 `frame_id`，帧也必须存在。 - 后端提供 `GET /api/ai/annotations` 查询项目标注，可选按 `frame_id` 过滤。 - 后端提供 `PATCH /api/ai/annotations/{annotation_id}` 更新已保存标注的 `mask_data`、`points`、`bbox` 和 `template_id`。 - 后端提供 `DELETE /api/ai/annotations/{annotation_id}` 删除已保存标注。 - 当前前端“结构化归档保存”会保存当前项目未保存 mask，并会更新已标记为 dirty 的已保存 mask。 - 工作区“清空遮罩”会删除当前帧已保存标注，并清空当前帧未保存 mask。 - 工作区加载项目帧后会查询已保存标注并回显。 ## R8 模板库 - 前端展示模板列表，调用 `GET /api/templates`。 - 用户可以新建、编辑、删除模板。 - 模板分类存放在 `mapping_rules.classes`，规则存放在 `mapping_rules.rules`。 - 前端支持添加/删除分类、拖拽排序后重算 `zIndex`、JSON 批量导入、加载腹腔镜默认分类。 - 后端支持模板创建、列表、详情、局部更新和删除。 ## R9 本体检查面板 - 工作区右侧可以选择模板。 - 面板显示模板分类和组件本地自定义分类。 - 用户可以选择具体分类；新 AI mask 会记录 `classId`、`className`、`classZIndex`，并在保存时写入 `mask_data.class`。 - 添加自定义分类只存在组件本地状态，不保存到后端。 - 置信度、拓扑锚点和重新提取骨架按钮当前为展示/占位。 ## R10 Dashboard 与 WebSocket - Dashboard 显示基础统计、解析队列和活动日志。 - Dashboard 初始数据来自 `GET /api/dashboard/overview`。 - 后端聚合项目数、处理中任务数、标注数、帧数、模板数和主机 load average。 - 解析队列由 `processing_tasks` 中的 queued/running 任务生成；活动日志由最近任务、项目、标注和模板记录生成。 - Dashboard 会连接 `/ws/progress`。 - 收到 progress、complete、error、status 消息时，前端会更新队列或日志。 - Celery worker 每次更新 `processing_tasks` 后会发布 Redis `seg:progress` 事件，FastAPI 订阅并广播给 `/ws/progress` 客户端。 - 后端 WebSocket 接收到客户端消息后返回 status heartbeat。 ## R11 导出 - 后端支持 `GET /api/export/{project_id}/coco` 导出 COCO JSON。 - 后端支持 `GET /api/export/{project_id}/masks` 导出 PNG mask ZIP。 - 当前前端 `exportCoco()` API 封装已对齐后端路径。 - 工作区“导出 JSON 标注集”按钮已绑定下载事件；导出前会先保存当前未归档 mask。 ## R12 配置 - 前端 API 地址由 `src/lib/config.ts` 统一推导。 - `VITE_API_BASE_URL` 优先级高于自动推导。 - `VITE_WS_PROGRESS_URL` 优先级高于从 API 地址推导 WebSocket 地址。 - 未设置环境变量时，前端按当前浏览器 hostname 推导 `http://:8000`。 ## R13 文档与测试 - `doc/` 目录保存当前实现审计、接口契约、需求冻结、设计冻结和测试计划。 - 测试应覆盖当前冻结需求中的真实功能、半可用行为和明确占位行为。 - 对外部服务依赖 PostgreSQL、MinIO、Redis、SAM 模型的测试应使用 mock 或测试替身，不依赖真实服务可用性。