Pre_Seg_Server/工程分析/实现方案-20260430_222830.md

实现方案 — 模板系统与工作区联动改造

后端

1. Template 模型兼容 classes/rules

• schemas.py: TemplateBase 添加 classes: Optional[list[dict]], rules: Optional[list[dict]]
• routers/templates.py: create/update 时将 classes/rules 打包进 mapping_rules JSON；返回时解包
• main.py: lifespan 中种子默认模板（腹腔镜胆囊切除术）

2. 预置模板数据

腹腔镜胆囊切除术 35 个分类，RGB 颜色 + 名称数组，存入 mapping_rules.classes

前端

3. TemplateRegistry.tsx 修复

• addClass: 使用颜色轮算法（HSL 色相均匀分布）自动生成不同颜色
• handleSave: 将 editClasses 打包为 { classes: editClasses, rules: [] } 存入 mapping_rules
• z-index: 添加上下箭头按钮，点击后交换相邻项位置，自动重算 z-index
• 批量导入: 新增"批量导入"按钮，支持粘贴 JSON 数组格式 [colors[], names[]]

4. OntologyInspector.tsx 联动改造

• 从 Zustand store 读取 templates 和 activeTemplateId
• 显示当前激活模板的 classes（真实颜色、名称、z-index）
• 顶部添加模板选择下拉框
• 支持"从模板添加分类"和"自定义添加分类"两种模式
• 分类列表按 z-index 降序排列

5. useStore.ts + api.ts

• getTemplates / createTemplate / updateTemplate 做 mapping_rules ↔ classes/rules 映射

---

执行记录

2026-04-30 22:38 - 23:00

修改文件清单:

• backend/schemas.py: TemplateUpdate 添加 classes / rules 字段
• backend/models.py: Template 添加 description 列
• backend/main.py: 已含 _seed_default_templates_sync()（腹腔镜35分类模板种子）
• src/lib/api.ts:
  • _mapTemplate: 移除未在 Template 接口中定义的 color/z_index，避免 TS 编译错误
  • createTemplate: payload 签名增加 color/z_index 必填字段
  • updateTemplate: 改 PUT 为 PATCH，与后端 @router.patch 对齐；payload 类型增加 color/z_index
  • createProject: 签名增加 parse_fps?: number
• src/store/useStore.ts: 新增 activeTemplateId / setActiveTemplateId
• src/components/TemplateRegistry.tsx:
  • addClass: 已使用 generateColor()（HSL 轮盘）自动分配颜色
  • handleSave: 补齐 color 和 z_index，满足后端 TemplateBase 必填要求
  • 拖拽排序: 将上下箭头改为 HTML5 Drag & Drop（draggable + onDragStart/Drop/End），拖拽时高亮目标位置，释放后自动重算 z-index
  • 批量导入: 支持 [[colors], [names]] 和 {colors, names} 两种 JSON 格式
  • 预置模板: 一键载入腹腔镜胆囊切除术 35 分类
• src/components/OntologyInspector.tsx:
  • 完全重写，从 mock 数据改为读取 Zustand store 的 templates/activeTemplateId
  • 顶部模板选择下拉框，未选择时默认第一个模板
  • 显示模板 classes（颜色方块 + 名称 + z-index）
  • 支持添加项目级自定义分类（独立 state，不与模板冲突）
• src/components/VideoWorkspace.tsx:
  • 新增 getTemplates 调用，进入工作区时若 templates 为空则自动加载
• src/components/ProjectLibrary.tsx: 修复状态字符串比较（TS 严格类型检查报错）

关键 Bug 修复:

1. updateTemplate 前端调用 PUT 但后端只接受 PATCH → 405 Method Not Allowed
2. createTemplate payload 缺少 color/z_index → 后端 TemplateBase validation error
3. TemplateUpdate schema 缺少 classes/rules → update 时分类数据丢失
4. Template ORM 模型缺少 description 列 → seed 脚本抛 invalid keyword argument
5. _mapTemplate 返回 color/z_index 但 Template TS 接口未定义 → TS2353

验证结果:

• npx tsc --noEmit 0 errors
• npm run build 成功（dist 生成）
• 后端启动成功，自动 seed 腹腔镜胆囊切除术 35 分类模板
• GET /api/templates 返回 35 classes，PATCH update 能正确保存/解包 classes