158 lines
10 KiB
Markdown
158 lines
10 KiB
Markdown
# 数据维护说明书（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 列）：
|
||
|
||
```csv
|
||
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`**（否则中文乱码）
|