admin
b5413066a0
- 新增 Seg_Server_Docker 自包含部署内容，包含前后端、FastAPI、Celery、PostgreSQL、Redis、MinIO、演示视频和 DICOM 数据。 - 保留 demo 数据以支持恢复演示出厂设置，排除 SAM 2.1 .pt 权重并在 README 中补充下载命令。 - 补充 GPU 部署、backend/worker 镜像复用、frpc/frps + NPM 公网域名反代部署说明。 - 在 .env/.env.example 中用 # XXXX 标注局域网和公网域名部署需要修改的配置项。 - 添加部署分支 .gitignore，忽略本地模型权重、构建产物、缓存和日志。
118 lines
8.9 KiB
Markdown
118 lines
8.9 KiB
Markdown
# 当前实现地图
|
||
|
||
## 运行入口
|
||
|
||
### 前端入口
|
||
|
||
- 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 默认模板。
|
||
- 如果存在 `demo/演视LC视频序列.mp4` 和 `demo/演视DICOM序列/`，创建名为“演视LC视频序列”的默认演示视频项目和名为“演视DICOM序列”的演示 DICOM 项目，视频和 DICOM 都会生成帧，DICOM 按文件名自然顺序读取；启动时会把旧显示名 `Data_MyVideo_1` / `演示DICOM序列` 迁移为新显示名。
|
||
|
||
## 前端模块切换
|
||
|
||
`App.tsx` 使用 Zustand 中的 `activeModule` 做模块切换，没有使用路由库。
|
||
`useStore` 默认 `activeModule` 为 `dashboard`，因此用户登录后默认进入“总体概况”页。
|
||
|
||
| 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`；`admin/annotator` 可调用写入类业务接口；`/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` 会阻止管理员删除、停用、改名或降级自己；项目库已共享，因此删除标注员不会删除或迁移项目；演示出厂重置会清空其它用户、项目帧、标注、任务和私有模板，直接从 `demo/` 重新创建名为“演视LC视频序列”的已生成帧演示视频项目和名为“演视DICOM序列”的已自然排序演示 DICOM 项目。
|
||
|
||
### 项目与拆帧
|
||
|
||
1. `ProjectLibrary.tsx` 调用 `getProjects()` 获取项目。
|
||
2. 上传视频时先 `createProject()`，再 `uploadMedia()`；导入视频不自动调用 `parseMedia()`。
|
||
3. 后端 `media.py` 把原始文件上传到 MinIO。
|
||
4. 用户在项目库点击“生成帧”或“重新生成帧”并选择 FPS 后，`parseMedia()` 创建 `processing_tasks` 记录并投递 Celery worker；已有帧的视频重新生成时，worker 会先删除旧帧、旧标注和旧 mask，再写入新的帧序列。
|
||
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 多类别导入、标注新增和 dirty 标注更新；导入 GT Mask 仅支持 8-bit 二值/灰度 maskid 图和 8-bit RGB 三通道完全相同的 `[X,X,X]` maskid 图，未知 maskid 可由用户选择舍弃或导入为黑色 `maskid:0` 的“待分类”，16-bit/uint16 GT_label 和普通彩色类别图会被拒绝，尺寸不同会自动最近邻拉伸到当前帧；GT 连通域会生成高精度 polygon，导入后和普通 mask 一样不显示黄色 seed point，并与普通 mask 共用拓扑统计、边缘平滑、编辑和保存链路。保存状态按钮会按待保存数量显示“保存 X 个改动”或“已全部保存”；统一导出可选择整体视频、特定范围帧或当前图片，并勾选分开 mask、GT_label 黑白图、Pro_label 彩色图和 Mix_label 原图叠加图；特定范围帧导出支持直接输入起止帧，也支持在播放进度条或视频处理进度条上点击/拖拽选择范围；Mix_label 支持默认 0.3 的透明度调节和首帧预览；后端统一导出 ZIP 固定包含 maskid/GT 像素值映射 JSON 与原始图片文件夹，GT_label 固定输出 8-bit uint8 PNG，像素值使用类别真实 maskid，其中 `maskid:0` 的“待分类”和背景同为 0，缺失 maskid 的旧标注才补下一个可用正整数，正整数 maskid 超出 1-255 会拒绝导出，并按客户命名规则输出分开 Mask、GT_label、Pro_label 和 Mix_label 文件夹；清空当前帧遮罩会删除对应后端标注，存在传播链时同一弹窗提供取消/当前帧/按帧范围选择/所有传播帧，按范围清空复用时间轴范围选择和最终确认；按范围或全部清空遇到人工/AI 标注帧时会二次确认，选择保留则整帧保留。手工绘制、polygon 顶点拖动/删除、区域合并/去除和撤销重做已经落到前端 mask 数据结构；多边形、矩形、圆和画笔创建遵循“有选中 mask 则并入选中 mask、无选中 mask 才新建”的规则，即使新几何和旧区域不重叠也会组成同一个多 polygon mask；无选中分类的新建多边形/矩形/圆会默认归入 `maskid:0` 的“待分类”，画笔无选中 mask 时仍要求右侧语义分类树有 active class；`Esc` 只取消选区和临时绘制状态，不删除已有 mask。
|
||
- Dashboard 初始统计、队列和活动日志来自后端聚合接口；解析队列来自 `processing_tasks`，worker 进度通过 Redis `seg:progress` 转发到 WebSocket。任务取消、重试和失败详情已接入前后端。
|
||
- 后端已接入 Bearer JWT 鉴权、共享项目库和角色权限；写入类业务接口要求 `admin/annotator`，管理员用户后台要求默认 `admin`。当前审计覆盖登录和用户管理操作，全业务级审计仍可继续扩展。
|