OnebotCatalog/交接-夹紧缸数据替换.md

夹紧缸模块数据替换 —— 工作交接

交接时间：2026-09-14 项目：D:\开发\OnebotCatalog（欧霓博气动元件电子目录软件） 本次任务：把 CLM 气动夹紧缸分类从 demo 占位数据替换为 Univer 真实数据

---

一、任务目标（用户原话）

"我这个是开发的对气缸的选型，你看下目前的夹紧缸名称种类，能否完善一下夹紧缸模块的分类选型及数模替换，原来的数据都是生产的 demo 数据不是真实数据，请你就 25/32/40/50/63/80 6 个系列的种类进行细化并将 demo 数据替换一下"

用户后续拍板的三个决策：

1. 系列划分：完整建官方全部系列（不是只建有数模的）
2. 旧命名处理：UBM/UBP 等无 UC 前缀的旧码 → 归一化到官方 UC 前缀
3. 参数维度：五维全拆（缸径/臂位置/臂类型/臂样式/传感器）
4. 停产老型号：UFL450/UHL463 → 单独建系列（不并入 UCBP）
5. 附图：用 X 盘官方图册 PDF 生成

---

二、已完成 ✅

2.1 数据成果

项	替换前（demo）	替换后（真实）
系列数	1 个（UCBM）	11 个
型号数	6 个占位	862 个真实
参数	仅"缸径"	5 维（缸径/臂位置/臂类型/臂样式/传感器）
STEP 数模	6 个占位	862 个真实（4GB）
附图	1 个占位	11 个系列（官方图册 p01.png + _manual.pdf）

2.2 11 个系列清单

系列	含义	缸径	型号数	官方图册 PDF
UCBP	标准气动夹紧缸	25/32/40/50/63/80	358	ucbp25/40/50/63/80
UCBM	带手杆	25/32/40/50/63/80	268	ucbm32/50/63/80
UCBH	Ø63/Ø22	40/63	61	ucbh63
UCBQ	带手杆+补偿	40/63	45	ucbq63
UFL	停产老型号（原 UFL450/UHL463）	50/63	38	无（停产）
UCIP	可互换	40	22	ucip40
UCIM	可互换带手杆	40	19	ucim40
UCBT	带中央手杆	40	19	主目录第42页
UCDP	双夹臂	40/63	17	ucdp40/63
UCNP	NAAMS 标准	50/63/80	10	ucnp50/63/80
UCNM	NAAMS 带手杆	50/63	5	ucnm50/63/80

2.3 官方订购码结构（从图册 CODIFICATION KEY 提取，权威依据）

UC - B - M - 0 - E - O - A - K - 63
│    │   │   │   │   │   │   │   └ 缸径 (25/32/40/50/63/80)
│    │   │   │   │   │   │   └ 传感器 N=无 K=电子PNP M12 Y=白LED D=气动
│    │   │   │   │   │   └ 臂样式 A=铝 S=钢 N=无
│    │   │   │   │   └ 臂类型 C=中央15mm D=右15mm S=左15mm E=中央45mm F=右45mm L=左45mm N=无
│    │   │   │   └ 臂位置 V=90° O=180° N=无臂
│    │   │   └ 产品版本 0
│    │   └ 子系列 P/M/T/Q/H/D/I/N
│    └ 标准 B=欧洲标准
└ UC = UNICLAMP

2.4 产物状态

• .opc 数据包：sample/OnebotCatalog_2026.08.opc（1210MB，2026-09-14 重建）
  • 27 系列 / 53,047 变体 / 校验 0 错误 0 警告
  • 体积主要来自 40缸 UCBM40 的装配体数模（单个 20~54MB），用户已确认保留原样
• 自测：sample/selftest.log —— 46 通过 0 失败
• 构建日志：sample/build.log

2.5 本次改动/新增文件

新增数据（onebot-data/catalog/）

• csv/ 下 11 个新 CSV：UCBP/UCBM/UCBT/UCBQ/UCBH/UCDP/UCIM/UCIP/UCNM/UCNP/UFL
• series/ 下 11 个新 meta.json（5 维参数定义）
• step/ 下 862 个真实 STEP（归一化命名 .step）
• manual/ 下 11 个系列目录（各含 p01.png + <系列>_manual.pdf）
• catalog.json：CLM 分类 series 数组更新为 11 系列顺序

新增工具（onebot-data/tools/）

• gen-clamp-series.py —— 数据清洗主脚本（扫描 X 盘数模 → 归一化 → 生成 CSV/meta/复制 STEP）
  • --dry-run 只分析打印
• copy-clamp-step.py —— 8 线程并行复制 STEP（复用上面脚本的 collect()）
• gen-clamp-manual.py —— 从官方图册 PDF 渲染 p01.png + 生成 _manual.pdf

代码改动

• src/CatalogCore/SelfTest.cs（第 111-127 行附近）：自测"可解析出完整选型"逻辑
  • 原：取各参数第一个允许值组合 Resolve
  • 改：取第一个真实变体的完整参数组合 Resolve（稀疏数据下前者必然落空）
  • 改后已跑 fix-bom.ps1 并重新编译

清理

• crossref.csv：移除 491 行失效的 UCBM 旧平替引用（引用的是 demo 型号 UCBM40/50/63/80，现已被细化型号取代），保留 12 行有效（KCS 4 + UAGP 8）
  • 备份：crossref.csv.bak_*

备份（可回退）

• onebot-data/catalog/_backup_clamp_20260913_222631/（原 catalog.json + UCBM.csv + UCBM.meta.json）

---

三、未完成 / 待办 ⚠️

3.0 【已修复】三个曾导致数据没进包的坑（务必记住）

这三个坑在 2026-09-14 后续排查中发现并修复，但极易复发：

1. catalog.json 的 CLM.series 必须列出全部系列

   • 构建器（FullCatalogBuilder.cs:49）只遍历 catalog.json 各分类的 series 数组来发现系列
   • 只写 series/*.meta.json 而不改 catalog.json → 构建"成功"但系列根本不在包里（build.log 报的系列数不会增加，极易漏看）
   • 自查方法：python -c "import zipfile,json; z=zipfile.ZipFile('sample/OnebotCatalog_2026.08.opc'); print([c['series'] for c in json.loads(z.read('catalog.json').decode('utf-8-sig'))['categories'] if c['code']=='CLM'])"

2. 参数值域为空的维度必须剔除

   • 若某系列数据里某参数（如 style）全为空，meta 里会生成 values: [] → 自测报"参数 X 初始可选值非空"失败 → UI 出现无值下拉
   • 处理：meta 里删掉该参数 + CSV 删对应列（gen-clamp-series.py 已内置 params = [p for p in params if p['values']]）
   • 本次涉及：UCBT / UCNM / UCNP / UFL 四个系列（都无 style 维度）

3. _step 副本后缀必须在去下划线之前剥离

   • gen-clamp-series.py 原先先 .replace('_','') 再 re.sub(r'_STEP$') → 永远匹配不到
   • 导致 UCBM40OESK0_step.stp 被归一化成假型号 UCBM40OESK0STEP（与真型号 UCBM40OESK0 重复）
   • 已修：改为先去后缀再去下划线

3.1 未发布（重要）

只重建了 .opc，没有跑 publish。也就是说：

• release/OnebotCatalog_2026.08/（客户版目录）
• release/update_2026.08/catalog.opc（增量包）
• release/web_2026.08/（网页站）

三份产物还是旧数据。发布前必须先关掉运行中的 exe 和 serve-web：

powershell -NoProfile -ExecutionPolicy Bypass -File tools\publish.ps1

3.2 附图状态（已完成，备注）

11 个系列共 84 张附图 + 11 个 datasheet，全部来自 X 盘官方图册，按内容标记（CHARACTERISTICS/DIMENSIONS/CLAMPING ARMS）排序，多缸径系列的页面合并。

• UCBT 无独立图册 → 从主目录 katalog-pneumatische-spanner-...pdf 提取第 41-43 页；datasheet 裁成 606KB（原整本 54MB）
• UFL/UHL 经核实就是官方 UCBL（Manual power clamps Ø50/Ø63，缸径编号 450→Ø50、463→Ø63），已用官方 ucbl450/463 图册，不再是占位图
• 生成工具：onebot-data/tools/gen-clamp-manual.py（支持 --clean）
• meta 附件引用更新工具：onebot-data/tools/update-clamp-meta-attach.py（按 manual 目录实际 png 数量重写 attachments）

注意：主目录 PDF 54MB 在网络盘上逐页取文本极慢（360 页），若需再处理，先 cp 到本地临时盘再操作。

3.3 已知数据特性（非 bug）

• 参数稀疏：并非所有 5 维组合都有真实数模（Univer 是离散有限型号清单）。例如 UCBM bore=25 只有 3 个型号。选型时靠级联过滤收敛，部分组合会落空——这是数据本身的特性。
• 型号数 859（归一化去重后），CSV 与 STEP 100% 对齐。
• 单文件体积大：40缸 UCBM40 系列有完整装配体导出（单个 20~54MB），这是源文件本身的体积，用户已确认保留原样。.opc 因此为 ~1.2GB。

3.4 其他系列未动

本次只处理夹紧缸（CLM 分类）。其他分类的空壳/样板系列（ULP 定位销、USP 勾销缸、UGP 夹爪缸、UAGP 翻转缸、LAE 电缸）仍是 demo 数据，未替换。用户可能后续要求同样的处理。

---

四、下个会话怎么接续

开场直接说：

读一下 D:\开发\OnebotCatalog\交接-夹紧缸数据替换.md，我们继续。

关键上下文：

• 源数据在 X:\新开发产品-Research and Development\1_产品3D数模(发客户仿真)\1-夹紧缸\（按缸径分 25缸/32缸/40缸/50缸/63缸/80缸）
• 官方图册在 X:\新开发产品-Research and Development\2_产品资料\Univer资料\官方图册\
• 项目文档：项目总览.md、数据维护说明书.md、README.md

环境陷阱（必读）

• X 盘是网络盘，读取极慢（单文件 5MB 约 6 秒）。批量复制务必多线程（参考 copy-clamp-step.py），并行数 8 合适。复制偶发 WinError 31/1006，重试即可成功。
• 编辑含中文的 .ps1/.cs/.vb 必须先跑 sample-data\tools\fix-bom.ps1 -Files @('路径') 再编译
• PowerShell 输出中文在 bash 里显示乱码（GBK），但文件内容正常
• 跑 python 脚本要加 PYTHONUTF8=1 前缀（避免 GBK 编码错误）

常用命令

# 重建全量目录（改数据后必跑）
./bin/OnebotCatalog.exe --buildfull onebot-data/catalog sample/OnebotCatalog_2026.08.opc

# 自测（结果看 sample/selftest.log）
./bin/OnebotCatalog.exe --selftest sample/OnebotCatalog_2026.08.opc

# 编译（改代码后）
powershell -NoProfile -ExecutionPolicy Bypass -File tools/build.ps1

# 发布三份产物（★先关 exe 和 serve-web★）
powershell -NoProfile -ExecutionPolicy Bypass -File tools/publish.ps1

---

五、给用户的建议下一步

按优先级：

1. 验收：打开 bin\OnebotCatalog.exe 加载新 .opc，检查夹紧缸 11 个系列的选型、3D、附图是否正常
2. 决定是否发布（发布后客户版/网页站才更新）
3. 补 UFL 正式图（当前是占位）
4. 决定是否对其他分类（定位销/勾销缸/夹爪缸/翻转缸/电缸）做同样的真实数据替换
5. （可选）更新 crossref.csv 里被移除的 491 行 UCBM 平替映射——现在型号细化了，可以重新建立更精确的竞品对照