admin
29a1a87e52
- 后端 SAM2 引擎新增 sam2.1_hiera_tiny、sam2.1_hiera_small、sam2.1_hiera_base_plus、sam2.1_hiera_large 四个变体定义，并按变体维护 checkpoint/config、image predictor、video predictor、加载状态、错误信息和真实状态回报。 - 后端 SAM registry 仅暴露当前产品启用的 SAM2.1 变体，保留 sam2 作为 tiny 兼容别名，拒绝 sam3 产品入口，并把 point、box、interactive、auto、propagate 都分发到所选 SAM2.1 变体。 - 后端默认配置和下载脚本切换到 SAM2.1 checkpoint 命名，支持 legacy SAM2 checkpoint fallback，并在状态消息中标出 fallback 使用情况。 - 前端全局 AI 模型状态新增 SAM2.1 tiny/small/base+/large 类型和默认 tiny，API 请求默认携带 sam2.1_hiera_tiny，AI 页面提供模型变体选择和所选模型状态展示。 - AI 智能分割页移除当前产品不使用的 SAM3/文本提示入口，保留正向点、反向点、框选和参数开关；AI 页只展示本页生成的候选 mask，并支持遮罩清晰度调节、候选 mask 上继续加正/反点、清空本页候选、推送到工作区编辑。 - 工作区和 Canvas 补强 SAM2 交互式细化链路：框选后正/反点继续细化同一个候选 mask，反向点请求启用背景过滤，空结果会移除被否定候选；AI 推送到工作区后保留选中态和未保存 draft mask。 - 工作区标注保存闭环补强：未保存 mask 可归档保存，dirty saved mask 可更新，保存后用后端 saved annotation 替换已提交 draft，清空/删除已保存 mask 时同步后端删除。 - Dashboard 任务进度区改为展示 queued、running、success、failed、cancelled 最近任务，处理中统计只计算 queued/running，并保留近期完成记录。 - 时间轴在顶部时间进度条和底部缩略图导航轴之间新增已编辑帧标记带，基于当前项目帧内 masks 标出已有编辑/标注的帧，并支持点击标记跳转。 - 前端测试覆盖 SAM2.1 变体选择、模型状态徽标、AI 页候选隔离、遮罩透明度、候选上追加正/反点、推送工作区保留选择、Canvas 交互式细化、VideoWorkspace 传播/保存、Dashboard 进度和时间轴已编辑帧标记。 - 后端测试覆盖 SAM2.1 变体状态、sam2 alias 兼容、sam3 禁用、semantic 禁用、传播标注保存、Dashboard 最近任务状态和 SAM3 历史测试跳过说明。 - README、AGENTS 和 doc 文档同步当前真实进度，更新 SAM2.1 变体、SAM3 禁用、接口契约、设计冻结、需求冻结、前端元素审计、实施计划、FastAPI docs 说明和测试矩阵。
106 lines
4.8 KiB
Markdown
106 lines
4.8 KiB
Markdown
# 当前实现地图
|
||
|
||
## 运行入口
|
||
|
||
### 前端入口
|
||
|
||
- React 挂载：`src/main.tsx`
|
||
- 根组件：`src/App.tsx`
|
||
- 前端服务：`server.ts`
|
||
- 默认访问：`http://localhost:3000`
|
||
|
||
`server.ts` 的角色比较特殊：它既负责在开发模式下创建 Vite middleware，也在生产模式下服务 `dist/`。同时它还保留了旧版 mock API：`/api/login`、`/api/projects`、`/api/templates`。当前前端业务 API 主要不走这些 mock，而是走 `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。
|
||
|
||
## 数据流
|
||
|
||
### 登录
|
||
|
||
1. `Login.tsx` 调用 `login()`。
|
||
2. `src/lib/api.ts` 请求 `POST /api/auth/login`。
|
||
3. FastAPI `backend/routers/auth.py` 校验 `admin / 123456`。
|
||
4. 前端把返回 token 写入 localStorage。
|
||
|
||
### 项目与拆帧
|
||
|
||
1. `ProjectLibrary.tsx` 调用 `getProjects()` 获取项目。
|
||
2. 上传视频时先 `createProject()`，再 `uploadMedia()`；导入视频不自动调用 `parseMedia()`。
|
||
3. 后端 `media.py` 把原始文件上传到 MinIO。
|
||
4. 用户在项目库点击“生成帧”并选择 FPS 后，`parseMedia()` 创建 `processing_tasks` 记录并投递 Celery worker。
|
||
5. Celery worker 下载 MinIO 文件，调用 `frame_parser.py` 拆帧。
|
||
6. worker 把拆出的帧重新上传 MinIO，写入 `frames` 表，并更新任务状态。
|
||
7. 工作区只通过 `GET /api/projects/{id}/frames` 获取预签名图片 URL；若项目有源视频但无帧，会提示先回项目库生成帧。
|
||
8. Dashboard 可通过 `POST /api/tasks/{id}/cancel` 取消 queued/running 任务，通过 `POST /api/tasks/{id}/retry` 重试 failed/cancelled 任务，并用 `GET /api/tasks/{id}` 查看失败详情。
|
||
|
||
### 工作区浏览
|
||
|
||
1. `VideoWorkspace.tsx` 根据 `currentProject.id` 加载帧。
|
||
2. `CanvasArea.tsx` 用当前帧 URL 加载底图。
|
||
3. `FrameTimeline.tsx` 显示缩略图和当前帧索引。
|
||
4. 播放按钮会推进 `currentFrameIndex`，从而更新画布底图。
|
||
|
||
### 模板管理
|
||
|
||
1. `TemplateRegistry.tsx` 调用模板 API。
|
||
2. 后端 `templates.py` 把 `classes` 和 `rules` 打包进 `mapping_rules` JSON 字段。
|
||
3. `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。任务取消、重试和失败详情已接入前后端。
|
||
- 后端路由大多未做真实鉴权。
|