首次提交: OnebotCatalog 项目代码与文档（含 NX 按需生成服务二期、后台、一键启动）

欧霓博_目录软件_M2设计文档.md

@@ -0,0 +1,108 @@
+# 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