Pre_Seg_Server/doc/02-current-implementation-map.md

当前实现地图

运行入口

前端入口

• 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	模板库
admin	UserAdmin	管理员用户后台，仅 role=admin 可见

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

全局状态

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

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

当前状态管理主要是前端内存状态；登录 token 会持久化到 localStorage，刷新后再通过 /api/auth/me 恢复当前用户。

数据流

登录

1. Login.tsx 调用 login()。
2. src/lib/api.ts 请求 POST /api/auth/login。
3. FastAPI backend/routers/auth.py 查询 users 表并校验密码哈希。
4. 前端把返回 JWT 写入 localStorage，并把用户资料写入 store。
5. 后续业务请求带 Authorization: Bearer <token>，后端按当前用户过滤项目资源。
6. admin/annotator 可调用写入类业务接口，viewer 只能读取；/api/admin/* 仅允许 admin。

管理员用户管理

1. Sidebar.tsx 仅对 currentUser.role === 'admin' 显示“用户管理”。
2. UserAdmin.tsx 调用 GET/POST/PATCH/DELETE /api/admin/users 完成用户新增、停用/启用、角色修改、改密码和删除无项目用户。
3. UserAdmin.tsx 调用 GET /api/admin/audit-logs 展示登录成功/失败以及用户管理操作审计。
4. UserAdmin.tsx 危险区“恢复演示出厂设置”需要浏览器确认和输入 RESET_DEMO_FACTORY，随后调用 POST /api/admin/demo-factory-reset。
5. 后端 backend/routers/admin.py 会阻止管理员删除、停用或降级自己，并阻止删除仍拥有项目的用户；演示出厂重置会清空其它用户、项目帧、标注、任务和私有模板，重新创建一个尚未生成帧的 Data_MyVideo_1 视频项目。

项目与拆帧

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 源码保留但不计入当前可用功能。
• 工作区顶部“分割结果导出”和保存状态按钮、左侧工具栏“导入 GT Mask”已接入统一导出、GT 多类别导入、seed point 回显/编辑、标注新增和 dirty 标注更新；导入 GT Mask 支持二值 mask、低数值/16-bit GT_label 图和 RGB 三通道完全相同的 [X,X,X] maskid 图，未知 maskid 可由用户选择舍弃或导入为未定义类别，普通彩色类别图会被拒绝，尺寸不同会自动最近邻拉伸到当前帧。保存状态按钮会按待保存数量显示“保存 X 个改动”或“已全部保存”；统一导出可选择整体视频、特定范围帧或当前图片，并勾选分开 mask、GT_label 黑白图、Pro_label 彩色图和 Mix_label 原图叠加图；特定范围帧导出支持直接输入起止帧，也支持在播放进度条或视频处理进度条上点击/拖拽选择范围；Mix_label 支持默认 0.3 的透明度调节和首帧预览；后端统一导出 ZIP 固定包含 maskid/GT 像素值映射 JSON 与原始图片文件夹，GT_label 像素值使用类别真实 maskid，缺失 maskid 的旧标注才补下一个可用正整数，并按客户命名规则输出分开 Mask、GT_label、Pro_label 和 Mix_label 文件夹；清空当前帧遮罩会删除对应后端标注。手工绘制、polygon 顶点拖动/删除、区域合并/去除和撤销重做已经落到前端 mask 数据结构。
• Dashboard 初始统计、队列和活动日志来自后端聚合接口；解析队列来自 processing_tasks，worker 进度通过 Redis seg:progress 转发到 WebSocket。任务取消、重试和失败详情已接入前后端。
• 后端已接入 Bearer JWT 鉴权、当前用户项目隔离和角色权限；写入类业务接口要求 admin/annotator，管理员用户后台要求 admin。当前审计覆盖登录和用户管理操作，全业务级审计仍可继续扩展。