# M2 设计文档：维护入口（Builder 制作器）+ 搜索 + 批量下载

> **历史设计文档（2026-06 拟定）**。实施后的最终状态（统一路线/全量构建器等）、与设计的偏差、进度与踩坑以 **项目总览.md** 为准（同目录）。本文件仅作设计参考。

## 1. M2 目标与验收标准

维护人员在维护入口内用 Builder 从 STEP 模型库 + Excel 参数表生成 .opc 数据包；客户模式新增搜索与批量下载。

**验收标准：**
- 在维护入口内完成一个真实气缸系列的数据制作全流程（导入 → 定义 → 规则 → 附件 → 生成 .opc）
- 生成的 .opc 被运行时正确读取，选型/预览/下载全流程可用
- 全文搜索：输入型号片段（含拼音如 "acq"）或中文关键词命中正确结果；参数范围搜索（缸径 10~32、行程 ≤100）结果正确
- 多选零件批量下载 zip，包内文件命名正确
- 校验器能发现：STEP 缺失、编码重复、规则冲突、附件缺失，并输出报告

## 2. Builder 设计（维护入口内）

### 2.1 数据制作向导（5 步）

1. **导入参数表**：选择 Excel/CSV（约定模板：列 = 型号编码 + 各参数列 + STEP 文件名），预览前 100 行
2. **定义参数**：逐列设置参数定义——名称、类型（enum/number/text）、单位、是否必选；enum 自动提取该列唯一值
3. **编码规则**：定义/验证型号编码模板（如 `{SERIES}{bore}x{stroke}{MAG}`）；系统从 model_code 反解参数值，对不匹配的型号行给出警告
4. **选型规则**：表格式编辑器（条件参数/条件值 → 约束参数/允许值列表），一行一条规则，无需手写 DSL；可选组合条件（AND）
5. **附件与生成**：上传 2D 尺寸图/数据表 PDF（按语言分）；预览目录树 → 点击生成 → 后台任务执行网格转换 → 输出 .opc

### 2.2 网格转换（STEP → 预览网格）

- assimp（或 OCCT）命令行批处理，Builder 内以后台任务运行，带进度与失败清单
- 转换产物缓存（`build-cache/`），增量重建时跳过未变化的 STEP（按文件 hash）
- 转换失败的 STEP：列入校验报告，不阻断打包（预览用占位网格，下载仍给原 STEP）

### 2.3 目录树编辑

分类/系列的增删改与排序（拖拽），系列可绑定参数定义集。

## 3. 规则引擎 DSL（存储格式，用户不直接写）

```json
{
  "if": {"and": [{"param": "bore", "op": "eq", "value": 32},
                  {"param": "magnet", "op": "eq", "value": "S"}]},
  "then": {"param": "stroke", "op": "in", "value": [25, 50, 75, 100]}
}
```

- 操作符：`eq / ne / in / gt / ge / lt / le / between`
- 求值接口沿用 M1 的 `ConfiguratorEngine.GetAvailableOptions`；M2 补充 `Explain(selections)`——解释某个选项为什么被禁用（引用命中的规则），用于 UI 提示
- 规则冲突检测：同一"条件"给出矛盾"约束"时，校验器报错

## 4. 搜索设计

### 4.1 全文搜索

- SQLite FTS5 表 `fts_search(model_code, series_code, names, keywords, pinyin)`，**Builder 打包时生成索引**（M1 schema 增加该表）
- 拼音：打包时用拼音库（如 TinyPinyin）把中文系列名/关键字转全拼+首字母，一并入索引
- 查询策略：精确型号码命中排最前；前缀匹配（`acq*`）；中文词、拼音、英文关键词均可命中

### 4.2 参数范围搜索

- M1 的 `variants.param_values_json` 对范围查询不友好，M2 由 Builder 生成时**为数值型参数落冗余列**（动态 `ALTER TABLE variants ADD COLUMN bore REAL, stroke REAL ...`，列名按参数定义生成），范围查询走普通索引
- UI：选型面板增加"范围模式"（缸径 [10..32]、行程 ≤100），与枚举模式切换

## 5. 批量下载

- 客户模式：部件列表多选（勾选框）→ 下载所选 → 生成 zip
- zip 内结构：`系列名/型号.step`（命名模板 M1 已定义）+ `BOM.csv`（型号、参数值、数量列）
- 大量文件时后台打包 + 进度条；默认单文件下载仍走原有 ExportService

## 6. 校验器（对标 qacheck）

检查项与输出：

| 检查项 | 说明 |
|---|---|
| STEP 缺失 | 变体引用的 step_path 不存在 |
| 编码重复 | model_code 唯一性 |
| 编码不匹配 | 参数值无法由编码模板反解 |
| 规则冲突 | 同条件矛盾约束；规则引用了不存在的参数值 |
| 附件缺失 | 必需的尺寸图/数据表未提供（按语言） |
| 命名模板变量未定义 | step_name_template 引用不存在的参数 |
| 网格缺失 | 网格转换失败的清单 |

输出：UI 报告列表（按严重度过滤、点击定位到变体）+ 可导出 CSV。**校验不通过不允许编译发布**（M3 的硬门槛）。

## 7. UI 扩展

- 维护页扩展：数据包管理（新建/打开/备份）、Builder 向导、校验报告页、生成日志
- 客户模式：顶部搜索栏（全局）、部件列表多选与批量下载按钮、禁用选项的规则解释 tooltip
- 维护入口交互沿用 M1：`--admin` 启动参数 + 密码

## 8. 任务清单（建议实现顺序）

1. 规则引擎求值 + Explain + 单测（纯逻辑，先行）
2. FTS5 索引与拼音生成（Builder 侧）
3. variants 动态数值列 + 范围查询
4. Builder 向导 5 步（导入/参数/编码/规则/附件）
5. 网格转换后台任务 + 缓存
6. .opc 生成（zip 打包）
7. 校验器 + 报告 UI
8. 客户模式搜索栏 + 批量下载
9. 全流程集成测试（真实系列数据从零到可用）

## 9. 需要用户提供的输入

- 真实系列的 Excel 参数表（含 STEP 文件名对应列）
- 该系列全部型号的 STEP 模型文件
- 编码规则说明（各段含义、允许组合）
- 中/英尺寸图与数据表 PDF