OnebotCatalog/docs/维护手册.md

欧霓博气动元件电子目录 —— 维护手册 / 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

# 前提: 先关闭正在运行的目录软件 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. 网页版系列缩略图（2026-09-14）

• 首页为系列缩略图网格，按大类切换；点左树大类 → 网格切换，点卡片 → 进入选型，点【← 返回系列总览】回首页
• 缩略图目录：web\series\<系列码>.webp（40 个系列各一张）
• 换图/补图：把你的图按 web\series\<系列码>.webp 覆盖同名文件即可，无需改代码。 文件名只支持 .webp .png .jpg .jpeg .svg（前端按此顺序自动回退探测）
• 生成占位图：PYTHONUTF8=1 python onebot-data\tools\gen-series-thumbs.py （给 PLACEHOLDER 列表里的系列画统一风格的"图片待补"占位图）
• 视觉风格参照 D:\开发\bom-viewer（青/teal 主色、大圆角、柔和阴影、卡片悬停抬升动画）

12. 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.