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

## 后端

### 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