# 工作总结 — OnebotCatalog 数据完善与界面改版

**时间范围**：2026-09-13 ~ 09-15
**版本**：v1.0 → v2.0 → v2.1（桌面版改动未提交，见文末）
**代码仓库**：https://git.ruiguo.wang/wangruiguo/OnebotCatalog

---

## 一、总体成果

| 指标 | 改动前 | 改动后 |
|---|---|---|
| 系列数 | 40 | 40 |
| **型号总数** | **54,136** | **57,293** |
| 真实数据分类 | 3 个（气缸/迷你缸）| **7 个**（+夹紧缸/定位销/勾销缸/翻转缸/电缸）|
| 手册附图 | 灰度、部分系列仅 1 页 | **彩色 346 页，覆盖全部 42 系列** |
| 网页版选型交互 | 下拉菜单 | **DESTACO 风格（选项块 + 零件号实时拼装）** |
| 数据包体积 | 1.21 GB | 2.14 GB |

各分类现状：

| 分类 | 系列 | 型号数 |
|---|---|---|
| AUT 汽车行业气缸 | 6 | 12,554 |
| MIN 不锈钢迷你缸 | 3 | 25,200 |
| ALU 铝合金迷你缸 | 2 | 14,400 |
| CLM 气动夹紧缸 | 11 | 860 |
| PIN 气动可伸缩定位销 | 9 | 3,455 |
| HOK 气动勾销缸 | 5 | 72 |
| ROT 气动翻转缸 | 2 | 741 |
| ELEC 电动气缸 | 1 | 9 |
| GRP 气动夹爪缸 | 1 | 2（仍为占位，X 盘无真实数模）|

---

## 二、按阶段的工作

### 阶段 1（v2.0）：4 个分类的真实数据替换

**背景**：定位销 / 勾销缸 / 翻转缸 / 电缸 4 个分类此前是 demo 占位数据（每类仅 1-3 个型号）。

**做法**：
1. 用 `pdftotext` 提取 **19 份 Univer 官方图册的 CODIFICATION KEY**，拿到每个系列的官方订购码结构（不靠推测）
2. 扫描 X 盘 3D 数模，按「官方值域校验 + 左对齐 DFS 填空」解析文件名
3. 生成 CSV / meta / 复制 STEP

**成果**：新增 19 系列 **1,124 个真实型号**（PIN 303 / HOK 73 / ROT 741 / ELEC 9）

**过程中解决的关键问题**：

| 问题 | 处理 |
|---|---|
| 解析器无法处理省略空位的型号（如 `ULP50040SK0`）| 改用官方值域 DFS 填空 |
| 参数组合可能一对多（选型会静默错配）| 加**唯一性门禁**，1124 型号全部通过 |
| 占位/测试文件（如 `USP50J_0___K0` 销径为空）| 解析阶段丢弃 |
| catalog.json 分类系列表未同步 → 10 个系列没进包 | 更新 `CLM.series` 数组 |
| 手册页全是灰度 | 脚本误写死 `colorspace=fitz.csGRAY`，去掉后重做**彩色 346 页** |
| UCBT 附图只有 1 页 | 筛选条件写死 `UCBT40` 且漏 `CLAMPING ARMS`，已修正为 3 页 |
| 重跑数据脚本会覆盖 meta 附件 | 改为**扫描 manual 目录自动生成**附件清单 |
| 数据包 2.25GB 超 MemoryStream 2GB 上限 | `OpcPackage` 超大包改走临时文件（保留原有句柄释放语义）|

### 阶段 2（v2.0）：网页版界面改版

- **首页**：全部产品缩略图网格，按大类分组
- **左树**：手风琴（一次展开一个），父级带 **9 个内置 SVG 图标**，悬停放大动画，可收起为图标窄条
- **缩略图**：40 张（27 张真实产品图从 `bom-viewer` 复用 + 13 张占位图）
- 修复分隔条被拖出容器后无法找回（**容器感知上限 + resize 重夹取 + 双击复位**）
- 修复搜索到型号后点结果内容区空白（`switchTab('dim')` 已失效）
- 购物车打包改取 `.step.gz` 副档（传输量降至约 1/4.5）

### 阶段 3（v2.1）：DESTACO 风格选型 + 参数组合补全

**3.1 零件号实时拼装**

DESTACO 配置器的核心体验。技术难点：**40 个系列中只有 KC 有编码模板**。

解法：用**「当前候选型号的最长公共前缀」** —— 选得越多候选越少、前缀越长，自然拼出完整零件号。
已验证 **40/40 系列前缀单调增长**（不回退）。

**3.2 参数选择改为选项块**

下拉菜单 → 可视化卡片：悬停抬升+青色投影、选中青色填充+✓、
**不可选取值置灰保留**（而非消失，让用户看到选项存在）、再点一次取消。

**3.3 参数组合补全（缺组合也能出零件号）**

原逻辑要求「必须有真实数模才能生成型号」，导致库里没有的组合选不出来、也出不了号。

1. **反推编码模板**：`infer-sku-template.py` 从已有型号反推出 **23 个系列 100% 可复现**的模板
2. **加自检门禁**：`verify-templates.py` 用模板重渲染每个已有型号必须逐字一致。
   **这道检查抓出了真实错误** —— ULM/ULP 行程补零位数写错（2 位写成 3 位），
   若无此校验会**生成 3,000 个不存在的零件号发给客户**
3. 补全 8 个系列共 **3,157 个型号**（全库 54,136 → 57,293）
4. **占位数模**：3157 个型号共用 1 个 `PLACEHOLDER.step`（4.5KB），
   数据包仅从 2.10GB 增至 2.14GB
5. 输出 `_pending_models.csv` 待补清单供 AI 补真实数模

### 阶段 4：桌面版同步（未提交）

将 3.1 / 3.2 同步到 C#/WPF 桌面版，保持两端语义一致：

- 新增 `OptionTile` 控件类（三态选项块）
- 零件号实时条（复用同一套最长公共前缀算法）
- range 参数保留可编辑下拉
- **编译首次通过**，算法对拍 **40/40 系列通过**

---

## 三、发现但未处理的问题

按优先级排列：

### 1. ULP 生成的候选有 56% 超出依据范围 ⚠️

补全时用的是**系列级值域**（整个 ULP 系列各维度取值的并集），而非**按缸径分级**。

| 缸径 | 真实型号数 | 真实行程 | 真实传感器 |
|---|---|---|---|
| ULP32 | 14 | 20, 40 | 只有 K |
| ULP50 | 83 | 15~110 | D, K |
| ULP63 | 71 | 15~60 | D, K |

结果：给 ULP32 生成了 9 种行程、传感器 D、杆样式 D/F/H/I/L/M —— 这些在该缸径的真实数据中**从未出现**。

**风险量化**（`assess-combo-risk.py`）：
```
低风险（取值在同缸径真实数据都出现过）  1,212  (43%)
高风险（含该缸径从未出现的取值）        1,590  (56%)
```

**建议**：收窄到低风险的 1,212 个；其余等 AI 补数模时先核对官方图册。

> 注：曾三次尝试从官方 PDF 提取分级值域，均因**图册双栏排版导致文本化后左右栏交错**而失败
> （把真实数据都判成越界 = 解析错误）。故改用「同缸径真实数据」作为可靠代理。

### 2. 夹紧缸 9 个系列：一组参数对应多个型号

| 系列 | 变体数 | 重复组数 | 一组最多 |
|---|---|---|---|
| UCBP | 358 | 46 组 | 18 个 |
| UCBM | 266 | 26 组 | 15 个 |
| UCBH / UCBQ / UCDP / UCIM / UCIP / UFL / UCBT | — | 2-7 组 | 2-6 个 |

共 **310 个型号**受影响。原因是编码含**参数之外的尾缀**（版本号/变体标记），
如 `UCBP25AK00` vs `UCBP25AK010`。界面已提示"该组合对应 N 个型号"，但无法唯一确定。

### 3. UAGP / LAGP 参数顺序与官方编码结构不符

官方订购码顺序为 `规格-台位-传感器-转角-制动-接口`，当前 meta 里传感器排在最后。
不影响选型正确性（参数按名索引），但**导致编码模板推不出来**，界面展示顺序也与官方不一致。

### 4. 17 个系列未补全组合

模板验证未通过的系列保持原状 —— 宁可少补，也不生成可能不存在的零件号。

### 5. 夹爪缸 UGP 仍为占位

X 盘无 UGP 系列真实数模（只有 GR8 抓手组装体），需确认 Univer 官方夹爪缸系列代号。

---

## 四、关键经验（避免重复踩坑）

| 坑 | 教训 |
|---|---|
| **模板必须先自检** | 用模板重渲染全部已有型号，逐字一致才能用于生成新号。省这道检查会造出不存在的零件号 |
| **PowerShell 变量名大小写不敏感** | `$root` 与 `$Root` 是同一变量，会互相覆盖（启动脚本因此指向错误目录）|
| **.ps1 必须带 UTF-8 BOM** | PS 5.1 对无 BOM 文件按 ANSI 读，中文注释会破坏解析（用 `tools/fix-bom.ps1`）|
| **脚本重跑会覆盖手工结果** | meta 附件清单改为扫描目录自动生成，而非硬编码 |
| **NTFS 硬链接上限 1024** | 超限部分退化为真实拷贝（曾白占 500MB）。改用共享单文件 |
| **Join-Path 不做路径归约** | 需再 `GetFullPath` 规范化 |
| **MemoryStream 上限 2GB** | 超大 .opc 改走临时文件副本 |

---

## 五、产出与交付

**新增脚本（11 个）**：`infer-sku-template` / `verify-templates` / `quantify-combo-gap` /
`gen-missing-combos` / `gen-placeholder-step` / `check-combo-unique` / `assess-combo-risk` /
`make-pending-list` / `gen-step-gz` / `gen-series-thumbs` / `serve-web-bg`

**新增文档**：`docs/更改说明-v2.1.md`、本文件

**发布产物（release/，未纳入 Git）**：
- `OnebotCatalog_2026.09/` — 客户版目录（catalog.opc 2.14GB）
- `update_2026.09/catalog.opc` — 增量更新包
- `web_2026.09/` — 网页站（含 3,285 个 gz 副档）

---

## 六、待办

1. **决定 ULP 高危候选如何处置**（收窄 / 维持 / 由 AI 核对官方图册）
2. **桌面版改动提交推送**（当前工作区有未提交改动，建议发 v2.2）
3. AI 补真实数模：按 `_pending_models.csv` 逐个核对后替换 `step_file`
4. 处理夹紧缸一对多问题（补维度或清理尾缀）
5. 确认 UGP 夹爪缸官方系列代号

---

*本总结由 Claude Code 生成于 2026-09-15*