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 中保留的旧 mock API。

前端模块

模块	文件	设计职责
应用入口	src/App.tsx	根据登录状态和 activeModule 切换页面
全局状态	src/store/useStore.ts	Zustand store，保存项目、帧、模板、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 模型真实可用状态
登录页	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 页面
时间轴	src/components/FrameTimeline.tsx	帧导航和播放
本体面板	src/components/OntologyInspector.tsx	模板选择、分类树、本地自定义分类
AI 页面	src/components/AISegmentation.tsx	独立 AI 推理视图，使用当前项目帧
模板库	src/components/TemplateRegistry.tsx	模板 CRUD、分类编辑、导入、排序

后端模块

模块	文件	设计职责
应用入口	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 / SAM 3 可选推理、模型状态和标注保存
Export	backend/routers/export.py	COCO 和 PNG mask 导出
SAM 2	backend/services/sam2_engine.py	SAM 2 懒加载、状态检测和点/框/自动推理
SAM 3	backend/services/sam3_engine.py	SAM 3 状态检测和文本语义推理适配
SAM Registry	backend/services/sam_registry.py	模型选择、GPU 状态和推理分发

状态模型

前端 store 的核心对象：

• Project：项目基本信息、状态、帧数、fps、媒体路径。
• Frame：帧 ID、项目 ID、索引、图片 URL、宽高。
• Template / TemplateClass：模板和分类定义。
• Mask：前端渲染用 mask，包含 pathData、segmentation、bbox、area。
• activeModule：当前页面。
• activeTool：当前工具。
• aiModel：当前选择的 AI 模型，取值为 sam2 或 sam3。

关键数据流

登录

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

项目导入

1. ProjectLibrary 创建项目。
2. 上传视频或 DICOM 到 /api/media/upload 或 /api/media/upload/dicom。
3. 调用 /api/media/parse 创建异步拆帧任务。
4. Celery worker 执行 FFmpeg/OpenCV/pydicom 拆帧，持续更新 processing_tasks，并发布 Redis seg:progress。
5. 刷新项目列表。

工作区加载

1. VideoWorkspace 根据 currentProject.id 调用 getProjectFrames()。
2. 若无帧但项目有 video_path，触发 parseMedia()，通过 getTask() 轮询任务完成后重新取帧。
3. 帧数据映射为 store Frame[]。
4. 当前帧传入 CanvasArea。

AI 点/框推理

1. 用户在 Canvas 选择正向点、反向点或框选。
2. CanvasArea 读取当前帧 ID 和宽高。
3. predictMask() 归一化坐标并携带当前 model 调用 /api/ai/predict。
4. 后端加载帧图片并通过 SAM registry 分发到 SAM 2 或 SAM 3。
5. 前端把 polygons 转为 mask，写入 store。
6. Canvas 按当前帧过滤并渲染 mask。
7. 新 mask 会带上当前选择的模板分类元数据，包括 classId、className、classZIndex 和保存状态 draft。
8. 用户点击“结构化归档保存”后，前端将像素 segmentation 转成 normalized mask_data.polygons；未保存 mask 调用 POST /api/ai/annotate，dirty mask 调用 PATCH /api/ai/annotations/{annotation_id}。
9. 工作区加载项目帧后通过 GET /api/ai/annotations 取回已保存标注并转成前端 mask。
10. 工作区“清空遮罩”删除当前帧已保存标注，并清除当前帧本地 mask。

模板管理

1. TemplateRegistry 从后端读取模板。
2. 编辑态在组件本地维护分类列表。
3. 保存时调用 createTemplate() 或 updateTemplate()。
4. 后端把 classes、rules 打包进 mapping_rules。
5. 返回时再解包给前端。
6. OntologyInspector 可以选择具体分类；选择结果进入全局 store，供 CanvasArea 和 AISegmentation 新建/更新 mask 时使用。

导出

1. 后端根据项目、帧、标注和模板生成 COCO JSON。
2. PNG mask 导出会把 normalized polygon 渲染为二值 mask 并打包 ZIP。
3. 前端“导出 JSON 标注集”按钮会在导出前保存待归档标注，然后下载 COCO JSON。

接口契约

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

• updateProject() 使用 PATCH /api/projects/{id}。
• exportCoco() 使用 GET /api/export/{projectId}/coco。
• predictMask() 使用 POST /api/ai/predict，请求体为 image_id、prompt_type、prompt_data、model。
• saveAnnotation() 使用 POST /api/ai/annotate。
• getProjectAnnotations() 使用 GET /api/ai/annotations。
• updateAnnotation() 使用 PATCH /api/ai/annotations/{annotationId}。
• deleteAnnotation() 使用 DELETE /api/ai/annotations/{annotationId}。
• 后端 /api/ai/predict 支持 point、box、semantic 三种 prompt_type，并通过 model 选择 SAM 2 或 SAM 3。
• 后端 /api/ai/models/status 返回 GPU、SAM 2、SAM 3 的真实运行状态。
• 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 任务生成。
• 多边形、矩形、圆、点、线手工绘制未实现。
• 合并、去除、撤销、重做未实现。
• 工作区导出 PNG mask ZIP 按钮尚未提供。
• 已保存标注支持通过“应用分类”进入 dirty 状态并归档更新；暂未提供逐点几何编辑器。
• SAM 3 文本语义分割取决于官方依赖和 GPU 运行环境；状态接口会暴露真实可用性。
• 自定义分类只存在本地组件状态。