# v2.1 更改说明

发布日期：2026-09-15
上一版：v2.0（4 分类真实数据替换 + 手册彩色重做 + 网页版改版）

本版聚焦两件事：**选型交互改为 DESTACO 风格**，以及**参数组合补全（缺组合也能出零件号）**。

---

## 一、选型界面：DESTACO 风格（网页版）

参照 DESTACO 配置器的交互做了改版。**只改网页版**，桌面版保持原样，后续再同步。

### 1. 零件号实时条（新增）

参数面板顶部新增一条零件号显示区，**边选边拼**：

- 已确定的片段用深青色实心显示，未确定的用浅灰虚化占位
- 底部进度条随选择推进
- 选满且唯一命中时，整条转为青色实心渐变（完成反馈）
- 浅色配色，与页面整体风格一致（初版曾用深色块，观感不协调，已改）

**技术说明**：40 个系列中只有 KC 有编码模板，无法靠模板拼号。改用**「当前候选型号的最长公共前缀」**——
选的越多候选越少、公共前缀越长，自然拼出完整零件号。已验证 40/40 系列前缀单调增长（不回退）。

### 2. 参数选择改为可视化选项块（替代下拉菜单）

- 每个维度显示为**选项块网格**，而不是 `<select>` 下拉
- 悬停抬升 + 青色投影；选中青色填充 + ✓ 角标
- **不可选的取值置灰**（虚线框 + 划线），而不是从列表消失——用户能看到"该选项存在但当前组合不适用"
- 再点一次可取消选择
- 有说明文字的（如传感器 `K` = 电子 PNP M12）显示代号大字 + 说明小字；纯数值显示紧凑文字块
- 连续域参数（range，如 KC 的行程）保留输入框 + 标准档位

**语义未变**：参数联动仍复用原有 `allowedOptions` 规则引擎，只改了渲染方式。

---

## 二、参数组合补全：库中缺的组合现在也能出零件号

### 背景

原逻辑是「**必须有真实数模才能生成型号**」：型号表由真实 STEP 文件扫描而来，构建器要求每个型号的数模必须存在。
结果是——**库里没有的组合，用户选不出来，也拿不到零件号**。

### 做法

**1. 从已有型号反推编码模板**

40 个系列里只有 1 个（KC）有现成模板。写了 `infer-sku-template.py` 从已有型号反推编码规则，
得到 **23 个系列 100% 可复现**的模板，例如：

```
ULP{size}{stroke:pad3}{rod}{orient}{sensor}0   →  ULP + 32 + 020 + A + E + K + 0
ULA{size}{stroke:pad3}{rod}{mount}{sensor}0
USSL{size}{pcmodel}{hook_pos}{pin_dia}{locating}{prog}{sensor}0
```

**并加了自检门禁**（`verify-templates.py`）：用模板重新渲染**每一个已有型号**，必须与库中编码逐字一致。
这道检查抓出了一处真实错误——ULM/ULP 的行程补零位数写错（2 位写成 3 位），
**若无此校验会生成 3,000 个不存在的零件号发给客户**。

**2. 补齐缺失组合**

只对模板验证通过的 23 个系列补全（其余 17 个系列因旧码/新码混用、编码结构特殊，未补）。

| 系列 | 补全前 | 补全后 |
|---|---|---|
| ULP | 168 | **2,970** |
| ULM | 70 | 200 |
| ULA | 19 | 192 |
| ULL | 14 | 40 |
| ULY / ULZ | 各 10 | 各 20 |
| USSL | 7 | 12 |
| ULT | 3 | 4 |
| **合计新增** | | **+3,157 个型号** |

全库型号数：**54,136 → 57,293**。构建通过（0 错误 0 警告）。

**3. 占位数模**

新增的 3,157 个型号共用 **1 个 `PLACEHOLDER.step`**（4.5KB 方块）。
构建器按路径打包，同一路径只存一份，因此**数据包仅从 2.10GB 增至 2.14GB**。

> 中途走过的弯路：先按"每型号一个硬链接文件"实现，但 NTFS 硬链接上限为 1024，
> 超出部分退化为真实拷贝，白占约 500MB。改为共享单文件后归零。

**4. 待补数模清单**

`onebot-data/catalog/_pending_models.csv` —— 3,157 行，列出每个待补型号及其参数，供 AI 补真实数模。
补完后把该行的 `step_file` 从 `PLACEHOLDER.step` 改为 `<型号>.step` 即可。

---

## 三、新增脚本

| 脚本 | 用途 |
|---|---|
| `infer-sku-template.py` | 从已有型号反推编码模板 |
| `verify-templates.py` | 校验模板能 100% 复现已有型号（生成新号前的门禁） |
| `quantify-combo-gap.py` | 统计参数组合缺口规模 |
| `gen-missing-combos.py` | 补全缺失组合（`--report` 只统计，`--write` 落盘） |
| `gen-placeholder-step.py` | 生成占位数模方块 |
| `check-combo-unique.py` | 检查"参数组合 ↔ 型号"是否一对一 |

---

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

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

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

共 **310 个型号**受影响。原因是这些型号的编码里有**参数之外的尾缀**（版本号/变体标记），
如 `UCBP25AK00` vs `UCBP25AK010`（差末尾版本号）、`UBP25010` vs `UCBP25BK0`（旧码/新码混用）。

**影响**：用户选完参数后仍无法唯一确定型号。界面已提示"该组合对应 N 个型号"，但需后续补维度或清理。

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

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

### 3. 未补全的 17 个系列

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

---

## 五、涉及文件

| 文件 | 改动 |
|---|---|
| `web/app.js` | 零件号实时条 + 选项块渲染（+148 行） |
| `web/style.css` | SKU 条与选项块样式（+111 行） |
| `web/index.html` | 新增 SKU 条容器 |
| `onebot-data/catalog/csv/*.csv` | 8 个系列追加 3,157 行 |
| `onebot-data/catalog/step/PLACEHOLDER.step` | 新增占位数模 |
| `onebot-data/catalog/_pending_models.csv` | 新增待补数模清单 |
| `onebot-data/tools/*.py` | 新增 6 个数据管线脚本 |

---

## 六、验证方式

1. **构建**：`bin\OnebotCatalog.exe --buildfull onebot-data\catalog sample\OnebotCatalog_2026.08.opc`
   → 应输出 `系列数: 40 | 变体数: 57293`，`校验: 0 错误, 0 警告`
2. **网页预览**：`tools\serve-web.ps1` → 打开 `http://localhost:8080`（Ctrl+F5 强刷）
   - 选定位销 PIN → ULP → 选一个原来选不到的组合（如 63 缸 / 110 行程）
   - 应能看到零件号实时拼出、可下载（下载到的是占位方块）
3. **模板门禁**：`PYTHONUTF8=1 python onebot-data\tools\verify-templates.py`
   → 应输出「所有模板对已有型号 100% 复现」