admin
f020ff3b4f
后端能力： - 新增 Celery app、worker task、ProcessingTask 模型、/api/tasks 查询接口和 media_task_runner，将 /api/media/parse 改为创建后台任务并由 worker 执行 FFmpeg/OpenCV/pydicom 拆帧。 - 新增 Redis 进度事件模块和 FastAPI Redis pub/sub 订阅，将 worker 任务进度广播到 /ws/progress；Dashboard 后端概览接口改为聚合 projects/frames/annotations/templates/processing_tasks。 - 统一项目状态为 pending/parsing/ready/error，新增共享 status 常量，并让前端兼容归一化旧状态值。 - 扩展 AI 后端：新增 SAM registry、SAM2 真实运行状态、SAM3 状态检测与文本语义推理适配入口，以及 /api/ai/models/status GPU/模型状态接口。 - 补齐标注保存/更新/删除、COCO/PNG mask 导出相关后端契约和模板 mapping_rules 打包/解包行为。 前端能力： - 新增运行时 API/WS 地址推导配置，前端 API 封装对齐 FastAPI 路由、字段映射、任务轮询、标注归档、导出下载和 AI 预测响应转换。 - Dashboard 改为读取 /api/dashboard/overview，并订阅 WebSocket progress/complete/error/status 更新解析队列和实时流转记录。 - 项目库导入视频/DICOM 后创建项目、上传媒体、触发异步解析并刷新真实项目列表。 - 工作区加载真实帧、无帧时触发解析任务、回显已保存标注、保存未归档 mask、更新 dirty mask、清空当前帧后端标注、导出 COCO JSON。 - Canvas 支持当前帧点/框提示调用后端 AI、渲染推理/已保存 mask、应用模板分类并维护保存状态计数；时间轴按项目 fps 播放。 - AI 页面新增 SAM2/SAM3 模型选择，预测请求携带 model；侧边栏和工作区新增真实 GPU/SAM 状态徽标。 - 模板库和本体面板接入真实模板 CRUD、分类编辑、拖拽排序、JSON 导入、默认腹腔镜分类和本地自定义分类选择。 测试与文档： - 新增 Vitest 配置、前端测试 setup、API/config/websocket/store/组件测试，覆盖登录、项目库、Dashboard、Canvas、工作区、模型状态、时间轴、本体和模板库。 - 新增 pytest 后端测试夹具和 auth/projects/templates/media/AI/export/dashboard/tasks/progress 测试，使用 SQLite、fake MinIO、fake SAM registry 和 Redis monkeypatch 隔离外部服务。 - 新增 doc/ 文档结构，冻结当前需求、设计、接口契约、测试计划、前端逐元素审计、实现地图和后续实施计划，并同步更新 README 与 AGENTS。 验证： - conda run -n seg_server pytest backend/tests：27 passed。 - npm run test:run：54 passed。 - npm run lint、npm run build、compileall、git diff --check 均通过；Vite 仅提示大 chunk 警告。
6.5 KiB
6.5 KiB
当前需求冻结文档
冻结日期：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转成 KonvapathData、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后会发布 Redisseg: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://<host>:8000。
R13 文档与测试
doc/目录保存当前实现审计、接口契约、需求冻结、设计冻结和测试计划。- 测试应覆盖当前冻结需求中的真实功能、半可用行为和明确占位行为。
- 对外部服务依赖 PostgreSQL、MinIO、Redis、SAM 模型的测试应使用 mock 或测试替身，不依赖真实服务可用性。