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

> 交接时间：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
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 编码错误）

**常用命令**
```bash
# 重建全量目录（改数据后必跑）
./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 平替映射——现在型号细化了，可以重新建立更精确的竞品对照