Files

admin b6a276cb8d feat: 完善工作区交互提示与后端属性分析

功能新增：
- 新增 POST /api/ai/analyze-mask 后端接口，基于 mask polygon、bbox、points 和 score 返回置信度来源、面积、拓扑锚点和后端分析提示。
- 前端新增 analyzeMask API 封装，并在本体检查面板读取选中 mask 的后端几何属性和重新提取拓扑锚点结果。
- 右侧语义分类树点击分类时，会给当前选中 mask 换标签、更新 class 元数据，并将选中 mask 移到前端渲染最上层，方便继续编辑。
- 分割工作区画布新增上下文操作提示，覆盖多边形 Enter 完成、Esc 取消、首节点闭合、拖拽图形、点区域、SAM 点/框提示、区域合并/去除选择顺序和多边形编辑。
- AI 智能分割画布新增正向点、反向点、边界框选和视口控制的上下文提示。
- 自动传播交互收敛为参考帧加起止帧范围加单个“自动传播”按钮，默认使用当前参考帧全部 mask 作为 seed。
- 时间轴改为用浅蓝色进度条区段标记自动传播生成的帧，而不是已编辑帧竖线提示。

Bugfix：
- AI 分割页无当前帧时移除外部演示背景图，改为明确空状态提示，避免误以为外部图片可参与真实推理。
- 工具栏魔法棒文案改为“打开 AI 智能分割”，避免误导为直接触发 SAM 推理。
- Canvas 底部当前图层信息改为显示真实选中 mask 标签和 annotation id，不再使用固定占位文本。
- 已保存标注回显时保留 mask metadata 中的传播来源、score 等字段，供时间轴和属性面板识别。
- 清理 server.ts 中遗留的 /api/login、/api/projects、/api/templates 内存 mock API，避免和 FastAPI 真实后端混淆。

测试：
- 补充 analyze-mask 后端测试，覆盖后端几何属性和锚点返回。
- 补充 api.analyzeMask 前端契约测试，覆盖 normalized polygon、bbox、points 和 extract_skeleton payload。
- 补充本体面板测试，覆盖后端属性读取、自定义分类写回后端模板、选中 mask 换标签和置顶显示。
- 补充 Canvas 测试，覆盖上下文提示、多边形完成提示、布尔选择顺序提示、当前图层真实显示和编辑优先级。
- 补充 AI 分割测试，覆盖无帧空状态和提示工具上下文提示。
- 更新 Konva 测试 mock，支持拖动过程、stroke/dash/fillRule 等渲染断言。

文档：
- 更新 README 和 AGENTS，说明 server.ts 不再保留业务 mock API。
- 更新 doc/02、doc/03、doc/04、doc/05、doc/07、doc/08、doc/09，记录后端属性分析、分类置顶显示、上下文提示、自动传播按钮、传播帧标记、测试覆盖和当前剩余限制。

2026-05-02 02:10:37 +08:00

4.8 KiB

Raw Blame History

当前实现地图

运行入口

前端入口

React 挂载：src/main.tsx
根组件：src/App.tsx
前端服务：server.ts
默认访问：http://localhost:3000

server.ts 的角色比较特殊：它既负责在开发模式下创建 Vite middleware，也在生产模式下服务 dist/。当前旧版 /api/login、/api/projects、/api/templates mock 已清理；前端业务 API 走 src/lib/api.ts 指向的 FastAPI。

后端入口

FastAPI 应用：backend/main.py
默认访问：http://localhost:8000
API 文档：http://localhost:8000/docs
健康检查：GET /health

后端启动时会通过 lifespan 执行：

创建数据库表。
检查 MinIO bucket。
测试 Redis。
Seed 默认模板。
如果存在 Data_MyVideo_1.mp4，创建默认项目并拆前 100 帧。

前端模块切换

App.tsx 使用 Zustand 中的 activeModule 做模块切换，没有使用路由库。

activeModule	组件	页面
`dashboard`	`Dashboard`	系统概况
`projects`	`ProjectLibrary`	项目库
`workspace`	`VideoWorkspace`	分割工作区
`ai`	`AISegmentation`	AI 智能分割页
`templates`	`TemplateRegistry`	模板库

未登录时，App.tsx 直接渲染 Login。

全局状态

全局状态在 src/store/useStore.ts 中，主要包括：

登录状态：isAuthenticated、token
项目：projects、currentProject
工作区：activeModule、activeTool、frames、currentFrameIndex
标注与 mask：annotations、masks
模板：templates、activeTemplateId
UI：isLoading、error

当前状态管理是前端内存状态，没有持久化到 localStorage，除了登录 token。

数据流

项目与拆帧

ProjectLibrary.tsx 调用 getProjects() 获取项目。
上传视频时先 createProject()，再 uploadMedia()；导入视频不自动调用 parseMedia()。
后端 media.py 把原始文件上传到 MinIO。
用户在项目库点击“生成帧”并选择 FPS 后，parseMedia() 创建 processing_tasks 记录并投递 Celery worker。
Celery worker 下载 MinIO 文件，调用 frame_parser.py 拆帧。
worker 把拆出的帧重新上传 MinIO，写入 frames 表，并更新任务状态。
工作区只通过 GET /api/projects/{id}/frames 获取预签名图片 URL；若项目有源视频但无帧，会提示先回项目库生成帧。
Dashboard 可通过 POST /api/tasks/{id}/cancel 取消 queued/running 任务，通过 POST /api/tasks/{id}/retry 重试 failed/cancelled 任务，并用 GET /api/tasks/{id} 查看失败详情。

工作区浏览

VideoWorkspace.tsx 根据 currentProject.id 加载帧。
CanvasArea.tsx 用当前帧 URL 加载底图。
FrameTimeline.tsx 显示缩略图和当前帧索引。
播放按钮会推进 currentFrameIndex，从而更新画布底图。

模板管理

TemplateRegistry.tsx 调用模板 API。
后端 templates.py 把 classes 和 rules 打包进 mapping_rules JSON 字段。
OntologyInspector.tsx 读取全局 templates 和 activeTemplateId 展示分类树。

后端数据模型

模型	表	用途
`Project`	`projects`	项目元数据，包含视频路径、缩略图、状态、fps
`Frame`	`frames`	拆帧后的图片记录
`Template`	`templates`	模板、本体类别、颜色、z-index、mapping_rules
`Annotation`	`annotations`	标注数据、点、bbox、mask_data
`Mask`	`masks`	mask 文件元数据

当前主要风险点

前端 API/WS 地址虽然已支持环境变量和 hostname 推导，但部署时仍需要确认浏览器可访问 :8000 后端。
AI 当前启用 SAM 2.1 tiny/small/base+/large 点/框/interactive 路径；语义文本提示和 SAM 3 产品入口已禁用，model=sam3 会被后端拒绝。SAM 3 源码保留但不计入当前可用功能。
工作区顶部“导出 JSON 标注集”“导出 PNG Mask ZIP”“导入 GT Mask”和“结构化归档保存”已接入导出、GT 多类别导入、seed point 回显/编辑、标注新增和 dirty 标注更新；清空当前帧遮罩会删除对应后端标注。手工绘制、polygon 顶点拖动/删除、区域合并/去除和撤销重做已经落到前端 mask 数据结构。
Dashboard 初始统计、队列和活动日志来自后端聚合接口；解析队列来自 processing_tasks，worker 进度通过 Redis seg:progress 转发到 WebSocket。任务取消、重试和失败详情已接入前后端。
后端路由大多未做真实鉴权。

4.8 KiB Raw Blame History Unescape Escape