wangruiguo/OnebotCatalog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
acbf6f2db065f96f5c3f1df68a0cdb862e8f8ff9
OnebotCatalog/onebot-data/数据维护说明书.md

10 KiB
Raw Blame History

数据维护说明书（ONEBOT 目录）

适用：欧霓博目录维护人员（不用写代码）。所有改动都在唯一数据源 OnebotCatalog\onebot-data\catalog\ 里做， 然后"重建 → 发布"两步生效。全流程图形界面操作。

一、进入维护界面

方式 操作
快捷方式 工作区根目录双击ONEBOT目录-维护版
bat 双击OnebotCatalog\bin\维护入口.bat
密码 onebot888（输错不会进）

输完密码，顶栏出现 【维护入口】 按钮 → 点它打开维护窗口。

二、维护界面两个窗口

维护窗口（数据包总览）：

  • 系列清单表：当前包的系列/变体数/参数/规则/附件
  • 【校验】：检查 STEP 缺失、编码重复、规则冲突、附件缺失
  • 【加载数据包】：换用别的 .opc
  • 【目录制作器】：进入编辑（下面所有场景都在这里做）

目录制作器（编辑主战场）：

  • 顶部【数据源目录】：默认已填 onebot-data\catalog，不用动
  • 顶部【系列下拉】：选要编辑的系列（KC/KCB/KSB/…）
  • 5 个标签页：导入 / 参数 / 编码 / 规则 / 附件与生成
  • 【保存配置】：把修改写回 series\<系列>.meta.json
  • 【重建全量目录】：把源目录打包成新的 .opc（核心按钮）

三、日常维护场景（想做什么 → 怎么做）

1. 改系列定义（参数名/取值/规则/显示名）

目录制作器 → 系列下拉选系列 → 改「参数」/「规则」表格
→ 【保存配置】→ 【重建全量目录】
  • 显示名映射列格式：值:显示,值:显示（如 :基本型,M:附磁石）
  • 规则示例：条件 mount eq YB → 约束 bore in 32,40,50（即 YB 固定形式只有这几个缸径）

2. 改型号数据（增删型号/改编码/调参数值）

Excel 打开 OnebotCatalog\onebot-data\catalog\csv\<系列>.csv
→ 改完另存为 "CSV UTF-8(逗号分隔)"
→ 回到制作器 →【重建全量目录】
  • 第 1 列 model_code = 型号编码（必须唯一）
  • 最后一列 step_file = 该型号用的 STEP 文件名（多个型号可指向同一文件）
  • 数值列不带单位（如缸径写 32 不写 32mm）

3. 换/补数模（STEP 文件）

NX 批量导出 (nx-batch-export.vb) 输出到 onebot-data\catalog\step\
  或手动拷贝单个 STEP 进去
→【重建全量目录】(已存在的文件自动跳过, 可断点续跑; 想重导先删该文件)
  • 文件名（前缀）必须与 CSV 的 step_file 列一致；后缀 .step 和 .stp 都行（NX 导出的 .stp 直接放，构建自动识别，无需改名）
  • 新 6 个系列（UCBM/ULP/USP/UGP/UAGP/LAE）step_file 列已是 .stp：NX 导出的 .stp 拷进 step\ 同名覆盖占位即可；老 11 个系列列是 .step：换 .stp 时同前缀的 .step 占位优先被认，需先删掉占位 .step 文件
  • 只换一部分也行：没换到的档位继续显示占位模型
  • 窗口内 3D 预览网格：NX journal 导出 STEP 时同步导出同名 .stl 到 catalog\mesh\（exportStl 开关，默认开，公差 0.5mm）→ 发布时自动同步到软件旁的 mesh\ 目录 → 桌面 3D 标签页窗口内直渲（开源 Helix 渲染），无需浏览器；没有网格的型号自动回退浏览器预览
  • 已有真实 STEP 批量转网格（不等 NX）：python onebot-data\tools\step-to-stl.py（开源 OCP 内核，自动跳过占位、断点续跑）→ 网格 >5MB 会自动被 simplify-stl.py 压小（或手动跑：python onebot-data\tools\simplify-stl.py）→ 发布同步

4. 新增产品系列（以 ABC 为例，5 步）

💡 现成模板：6 个新分类（夹紧缸/可伸缩定位销/勾销缸/夹爪缸/翻转缸/电动气缸）里各已放好一个样板系列（UCBM/ULP/USP/UGP/UAGP/LAE，型号取自官网），直接照它的 csv\*.csv + series\*.meta.json 格式加型号就行；占位 STEP 已按型号命名，NX 导出真实数模同名替换后重建即可，CSV 不用动。

  1. CSV：新建 catalog\csv\ABC.csv（表头 model_code,参数列...,step_file）
  2. 系列定义：制作器 Step1【选择参数表 CSV】选它 → 顶部填系列代码 ABC、中英文名 → 补参数表 → 【保存配置】
  3. 挂分类：编辑 catalog\catalog.json，把 "ABC" 加进对应分类的 series 数组（系列显示顺序 = 数组顺序）
  4. 放 STEP：文件放 catalog\step\，文件名与 CSV 一致
  5. 重建 + 发布：制作器【重建全量目录】→ 校验通过 → publish

5. 增删分类

编辑 catalog\catalog.json 的 categories 数组（code/nameZh/nameEn/series 列表），重建即可。

6. 加附件（尺寸图/数据表/手册页）

  • 尺寸图/数据表：制作器 Step5【+添加附件】选文件（Kind 选 dimDrawing/datasheet）
  • 手册页：改 sample-data\tools\render-manual-pages.py 里 SERIES_PAGES 加新系列页码 → python render-manual-pages.py ABC → 重建

7. 改目录版本号/目录名

编辑 catalog\catalog.json 的 catalogVersion / catalogName → 重建 → 发布时用新版本号。

8. 平替对照表（竞品型号 → 我方型号）

数据表：catalog\crossref.csv（不存在则无平替功能；4 列）：

brand,foreign_model,our_model,note
SMC,CDJ2B16-100,KC0032-100MLB,近似平替
JELPC,SQ32-100,KCS0032-100,基础型平替(待核对)
  • brand = 竞品品牌（SMC/亚德客/FESTO/JELPC/...）
  • foreign_model = 竞品型号（客户搜这个）
  • our_model = 我方型号（必须存在于目录，构建自动校验，写错会报错拒绝打包）
  • note = 互换程度说明（完全互换/近似平替/需确认）
  • 改完 Excel 另存 CSV UTF-8 → 【重建全量目录】→ 发布
  • 客户使用：搜索框直接输竞品型号（如 SQ32-100）→ 命中平替结果 → 双击跳转到我方型号；或打开「平替对照」标签页按品牌筛选浏览
  • 佳尔灵对照自动生成工具：onebot-data\tools\jelpc-crossref.py（从英文目录 PDF 抽取基础型对照并校验存在性；完整订购码（含磁石/固定形式）需按各系列订购码页逐页解析，后续可扩展）

四、重建与校验

制作器【重建全量目录】 = CLI: bin\OnebotCatalog.exe --buildfull onebot-data\catalog sample\OnebotCatalog_2026.08.opc
  • 重建自动校验（缺 STEP/编码重复/参数不全会列出错误并拒绝打包）
  • 结果看 sample\build.log；发布门禁自测 31 项看 sample\selftest.log

五、发布三份产物

1. 关闭正在运行的目录软件 exe 和本地预览服务器 (占用文件会导致失败)
2. powershell -NoProfile -File OnebotCatalog\tools\publish.ps1

自动产出：

产物 位置 给谁
客户版目录 release\OnebotCatalog_2026.08\ 压缩成 zip 发给客户（双击 exe 即用）
增量更新包 release\update_2026.08\catalog.opc 老客户只发这一个文件替换
网页站 release\web_2026.08\ 整目录上传到网站服务器

六、客户怎么拿到更新

  • 新客户：发 OnebotCatalog_2026.08_客户版.zip（发布后重新压缩一次）
  • 老客户：发 update_2026.08\catalog.opc → 客户替换程序旁的 catalog.opc → 重启程序即升级

七、常见问题排查

现象 原因与处理
网页/桌面看不到新数模 ① 文件放错目录（只认onebot-data\catalog\step\）② 扩展名 .stp≠.step ③ 文件名与 CSV 不一致 ④ 忘了重建/发布 ⑤ 浏览器缓存（刷新即可，页面自动带版本号）⑥ 预览服务器没开（网页打不开/3D 报 Failed to fetch 或 ERR_CONNECTION_REFUSED——别关 serve-web 窗口）⑦ 网页 3D 直接从站点 step\ 取文件（绝对路径），换数模后必须重建并发布
打开系列失败"找不到 KC.meta.meta.json" 程序旧版 bug，已修复；更新程序或重启
重建报错 看sample\build.log，逐条列出缺文件/重复编码
发布失败 先关预览服务器（serve-web）和目录软件 exe 再发布
下载 STEP 慢 本地预览服务器已 16 并发；生产环境上传后无此问题
桌面 3D 显示提示按钮 该型号是真实数模，点【在浏览器中打开 3D 预览】（本机运行不联网）；窗口内直接渲染真实模型待 GLB 升级
忘记密码 改src\App\App.cs 里 "onebot888" → 重新编译（见维护手册 §6）

八、三条红线

  1. 业务文件（报价单/合同）不要放进 OnebotCatalog 目录——曾因此锁死文件夹、误删发布产物
  2. 发布前必须关程序（运行中的 exe 和预览服务器）
  3. 改完任何中文脚本/代码文件要先跑 fix-bom.ps1（否则中文乱码）