# 欧霓博气动元件电子目录 —— 维护手册 / Maintenance Manual

> 面向欧霓博目录维护人员。开发环境要求：Windows 10/11 + Visual Studio 2022 Build Tools（仅需其自带 csc 编译器）。
> 更完整的团队操作指南（数模替换/新增系列/打包/排查）见 `onebot-data\数据维护说明书.md`。

## 1. 数据源（统一路线）

**唯一数据源 = `onebot-data\catalog\`**：

| 文件 | 要求 |
|---|---|
| catalog.json | 目录级定义（版本/分类/系列列表），手工编辑系列列表 |
| series\*.meta.json | 每系列定义（参数/规则/显示名/附件），**由维护向导编辑** |
| csv\*.csv | 参数表：首列=型号编码（唯一），参数列名=参数代码（bore/stroke/magnet/mount...），**必须含 `step_file` 列**；UTF-8 |
| step\*.step | STEP 文件，文件名与 `step_file` 列一致（NX 母模批量导出后放这里；**.stp 后缀自动兼容**，同名即可无需改名） |
| crossref.csv | 平替对照表（可选）：brand,foreign_model,our_model,note；our_model 必须存在，构建自动校验 |
| manual\<系列>\ | 手册页 PNG（render-manual-pages.py 生成） |

## 2. 日常编辑与重建

1. 双击 `bin\维护入口.bat`（密码 `onebot888`）→ 顶栏【维护入口】按钮
2. 维护窗口：当前包系列清单 + 校验
3. 【目录制作器】：Step1 顶部【数据源目录】（默认已填 `onebot-data\catalog`）→ 下拉选系列 → 编辑参数/规则/显示名/附件 →【保存配置】（写回 series\*.meta.json）→ 点 **【重建全量目录】** → 全量 .opc 生成，可一键加载验证
   - 新系列：手动导入 CSV → 填系列信息 → 保存配置 → 把系列代码加进 catalog.json 的分类列表 → 放 STEP → 重建
   - 等价 CLI：`bin\OnebotCatalog.exe --buildfull onebot-data\catalog sample\OnebotCatalog_2026.08.opc`（结果看 `sample\build.log`）

## 3. 校验 / Validate

维护入口 →「校验 / Validate」检查：STEP 缺失、编码重复、规则引用/冲突、附件缺失。**有 ERROR 不允许发布**（发布门禁会拦）。

## 4. 一键编译发布 / Publish

```powershell
# 前提: 先关闭正在运行的目录软件 exe 和本地预览服务器 (占用文件会导致失败)
powershell -NoProfile -ExecutionPolicy Bypass -File tools\publish.ps1 -Opc sample\OnebotCatalog_2026.08.opc -Version 2026.08
```

自动执行：自测门禁（31 项）→ 编译客户版（数据内置、维护入口剔除、图标）→ 发布目录（含本机 3D 查看器组件 ~8MB）→ 增量包 → 网页站。

产出：
- `release\OnebotCatalog_2026.08\` —— 客户交付目录，压缩成 zip 即发（工作区根有现成 zip 示例）
- `release\update_2026.08\catalog.opc` —— 增量更新包，客户替换同名文件即升级
- `release\web_2026.08\` —— 网页站，整目录上传即上线

发布前建议在**纯净 Win10/11 虚拟机（断网）**上验收：双击运行、选型、下载 STEP 并在 CAD 中打开核对。

## 5. 日常命令 / Daily Commands

| 操作 | 命令 |
|---|---|
| 编译开发版 | `powershell -NoProfile -ExecutionPolicy Bypass -File tools\build.ps1` |
| 自测 | `bin\OnebotCatalog.exe --selftest sample\OnebotCatalog_2026.08.opc`（结果 `sample\selftest.log`） |
| 全量构建 | `bin\OnebotCatalog.exe --buildfull onebot-data\catalog sample\OnebotCatalog_2026.08.opc` |
| 本地网页预览 | `powershell -NoProfile -ExecutionPolicy Bypass -File tools\serve-web.ps1`（localhost:8080，16 并发） |
| 刷新源数据(占位几何) | `powershell -NoProfile -ExecutionPolicy Bypass -File onebot-data\tools\gen-onebot-source.ps1`（NX 真实 STEP 直接替换 catalog\step\ 同名文件即可，无需跑这个） |

**注意**：编辑任何含中文的 `.ps1`/`.cs`/`.vb` 后必须先运行 `sample-data\tools\fix-bom.ps1` 再编译/运行（PowerShell 5.1/csc 对无 BOM 文件按 GBK 读取会乱码报错）。

## 6. 修改维护密码 / Change Admin Password

编辑 `src\App\App.cs` 中 `PromptPassword()` 的 `"onebot888"`，重新编译开发版即可（客户版不含维护入口，无需处理）。

## 7. 桌面 3D 预览说明

- 占位简化几何 → 桌面内置 3D 直接渲染
- **真实 NX 数模 → 窗口内直渲，不弹浏览器**（2026-08-24 起），四级优先级：
  1. 有 STL 网格（`mesh\` 侧车目录，与 STEP 同名）→ 开源 Helix Toolkit 窗口内直渲
  2. 无网格 → **WebView2 内嵌新迪查看器**（窗口内嵌浏览器控件，真实 STEP 直接渲染；Win11 自带运行时，Win10 装 Edge 即有）
  3. WebView2 不可用 → 外部浏览器回退（程序内嵌本机微型服务器，完全离线；客户版发布目录已附带查看器组件）
  4. 占位几何 → 内置自绘
- 网格生成：NX journal 导出 STEP 时同步导出（`exportStl` 开关）；已有真实 STEP 用 `python onebot-data\tools\step-to-stl.py` + `simplify-stl.py` 批量转换压缩
- 网页端轻量化（glTF）待办 9，`nx-batch-export-glb.vb` 模板已备

## 8. 参数化选型引擎（一期，2026-08-25，两端一致）

- **模式开关**：series.meta.json 的 series 块加 `"mode": "parametric"` + `"modelCodeTemplate"`（语法 `{field}` 或 `{field:padN}` 前补零），参数可定义 range 域：`"type": "range", "min": 10, "max": 200, "step": 1, "gridValues": [10, 20, 30, 50, 75, 100]`。缺失字段 = 枚举模式，老系列零影响
- **语义**：CSV 仍是"标准档位网格"（搜索/平替/参数表/下载的数据源）；选型面板可输入网格外的**非标组合**（range 自由输入），引擎按模板实时生成型号编码
- **非标档位行为**：标题带徽标；STEP 下载按钮置灰（请联系销售或选择标准档位）；3D 展示最近标准档位近似几何 + 提示条；可加入清单但打包时跳过并注明
- **对拍门禁**：构建期强制校验——参数化系列的**全部 CSV 编码必须能被模板重新生成且一一对应**，任何一个不一致构建失败（build.log 显示"参数化对拍门禁通过: N 个编码全部一致"）
- **双端一致性**：一份规则 JSON + C#/JS 各一个解释器 + 同一份测试向量 `catalog\parametric-vectors.json`（随 .opc 发布）：桌面 selftest 自动对拍；网页无头 `node tools\e2e-parametric.js`（16 项）+ 购物车回归 `node tools\e2e-cart.js`
- **联动语义（重要）**：参数合法性按"域+规则"判定，**不按网格行存在性**；规则 Then 参数未选不判违背（避免选一半清空其他选项）
- **试点 KC** 已上线；推广新系列时：确认型号编码模板补零规则（对拍门禁会兜底）、按产品手册补规则、range 参数列出 gridValues

## 9. NX 按需生成服务（二期 A 版，2026-08-25，开发完成待 NX 联调/部署）

- **架构**：`bin\GenServer.exe`（csc 编译轻量后端：服务端二次校验（复用目录端同一规则引擎）→ 检索先行 → 文件任务队列 → 输出留存 → 限流/CORS）+ 常驻 NX worker（`sample-data\tools\worker_journal.vb`，每席位一个 `run_journal.exe` 进程：认领任务 → 拷母模副本 → 设表达式 → 更新 → 导出多格式 → 写结果；批量任务单会话顺序处理）
- **配置（服务器侧，`onebot-data\`）**：`genserver-config.json`（端口/API key/目录；apiKey 留空=匿名模式仅限流）、`masters.json`（母模+表达式映射+switchRules+exports）、`catalog-masters\<系列>\<母模>.prt`
- **部署三步**：① 管理员执行 `netsh http add urlacl url=http://+:8899/ user=Everyone`（否则仅本机）② 启动 GenServer ③ 每席位一个：`run_journal.exe worker_journal.vb <worker号> <genserver-config.json 路径>`（NXBIN 下，计划任务守护）
- **两端接入**：网页 `web\config.js` 的 api（空=非标下载维持置灰过渡态）；桌面 = 源目录 `catalog.json` 的 `genApi` 字段（重建+发布生效）
- **检索先行**：`output\<系列>\<型号编码>\` 留存不删（全格式齐全即命中复用，不再触发 NX）；任务私有工作副本任务后即删
- **多格式导出**：STEP(214)/Parasolid/IGES/STL，下载为全格式 zip；购物车含非标时打包前自动批量生成（型号子文件夹）
- **本地联调（无 NX）**：模拟 worker 的 PS 脚本 + 网页端 `tools\e2e-gen.js`（8 项）
- **NX 2506 实测 API（2026-08-26，反射探针核对，详见 `开发记录-NX2506批处理攻坚.md`）**：批处理打开部件用 **OpenBaseDisplay**（OpenBase 后 Work=NULL）；CloseAll 两参数；建表达式 `Expressions.CreateExpression("Number","名=值")`；改表达式 UF `EditExp`（只改已存在）；更新 `ufs.Modl.Update()`；导出器在 **Session.DexManager**（CreateStepCreator/CreateIgesCreator/CreateParasolidExporter/CreateStlCreator）；journal 环境无 JSON 库 → 任务文件为行式键值；母模/worker 副本**必须清只读属性**（否则保存被拒）
- **待用户确认（上线前）**：① `masters.json` 表达式名按 NX 母模实际命名填写 ② KC 母模放入 `catalog-masters\KC\` ③ run_journal 路径（随 NX 版本）④ **卡点**：批处理模式翻译器导出空几何——需交互式 NX 录制导出宏修正 worker 导出函数，或用真母模直接实测（开发记录 §5 两方案）⑤ 部署时 `netsh http add urlacl url=http://+:8899/ user=Everyone`

## 10. 购物车批量导出（2026-08-24，两端一致）

- 加入：参数面板【加入清单】（选型完成后）/ 参数表行尾"+"或勾选行【加入清单】；顶栏【清单 (N)】角标实时计数
- 清单面板：桌面独立窗口 / 网页右侧抽屉；数量可改（只在 BOM 数量列体现，zip 每型号一份）；支持删除/清空
- 一键打包：【下载全部 (zip + BOM)】→ `ONEBOT_清单_<时间戳>.zip` = 全部 STEP（型号命名）+ BOM.csv（UTF-8 BOM，Excel 直开）+ 清单.txt
- 购物车生命周期：网页刷新浏览器 / 桌面重启软件才清空；切系列/搜索/平替等操作不影响清单
- 桌面零新依赖（net48 ZipArchive）；网页用开源 JSZip 3.10.1（MIT，web\libs\jszip.min.js）前端打包

## 11. English Summary

- Data source: `onebot-data\catalog\` (catalog.json + per-series meta JSON + CSVs with a `step_file` column + STEP files + manual page PNGs).
- Edit: run `bin\维护入口.bat` (password `onebot888`) → Admin → Builder → pick series → save → 【重建全量目录】 (same engine as CLI `--buildfull`).
- Publish: `tools\publish.ps1` runs the selftest gate first, then compiles the customer exe (data embedded, no admin entry), assembles the release folder + incremental update package + static web site.
- Always run `sample-data\tools\fix-bom.ps1` after editing Chinese-containing .ps1/.cs/.vb files.