# 开发提示词：参数化选型引擎（一期：选型数据参数化）

> 交付对象：Claude Code。实现前请先通读本提示词 + 项目根 `项目总览.md`（需求定稿/踩坑清单）+ `docs\维护手册.md`。
> 实施命令以用户说"开工"为准；本文档只定义"做什么、边界在哪、怎么验收"。

## 1. 背景与目标

**问题**：直线气缸类别变种数量巨大。现状 CSV 已枚举 52,154 行（M 单系列 14,400 行），若把行程连续档、附件/磁性开关/杆端形式全枚举，将达到几十万行；且每个变种配一个 STEP 文件将导致发布包爆炸（几十万 × 1MB ≈ 数百 GB），参数表也无法浏览。Airtac 原系统用 CADENAS `.tab` 参数表 + `.3db` 参数化几何按需实例化，一个系列只有几个模板文件。

**目标（一期）**：把选型**数据层**参数化——

1. CSV 从"全枚举表"降级为"**标准档位网格**"（可控量级：每系列几百~几千行）
2. 系列规则包定义**参数域**（枚举 / 连续区间+步长）+ 组合约束 + **型号编码模板**
3. 选型时由规则引擎**实时生成**任意合法组合的参数行 + 型号编码（含非标准档位组合）
4. **两端一致**：同一份规则 JSON，C#（桌面）与 JS（网页）各写一个解释器，用同一份测试向量对拍
5. 非标准档位的 STEP 下载/3D 预览按一期降级策略处理（见 §6）

**二期（另行立项，不在本提示词范围）**：几何参数化——行程类变形引擎（OCP 切分/平移/融合），客户机按需生成非标 STEP。

## 2. 范围与边界

**做**：
- meta.json 增加参数化字段（mode/参数域/编码模板/步长等，见 §3）
- C# 与 JS 各一个规则解释器（共享语义，共享测试向量）
- 选型面板支持连续参数输入（标准档位快捷选 + 自定义值）
- 非标组合：参数行生成、编码生成、下载/预览降级（§6）
- 构建期校验 + selftest 新项 + 网页无头对拍（§8）
- 试点系列迁移：KC（2,628 行 → 网格化），验证后推广

**不做（一期明确排除）**：
- 几何变形引擎 / 按需生成 STEP（二期）
- 缸径类参数化变形（永远走标准档位，见二期边界）
- 删除现有 CSV 结构或重写搜索/平替/购物车主流程（它们继续以网格行为数据源）
- 维护向导的参数化规则可视化编辑器（一期手工编辑 meta.json，向导只做校验；编辑器列二期）

## 3. 数据模型（meta.json 扩展）

在现有 series.meta.json 的 `series` 块上扩展，**缺省字段 = 现行为，老系列零影响**：

```json
{
  "series": {
    "code": "KC",
    "mode": "parametric",              // 缺省/其他值 = 现有枚举模式，行为不变
    "modelCodeTemplate": "KC{type:pad2}{bore}-{stroke}{mount}",
    "stepNameTemplate": "KC-{type}-{bore}x{stroke}.step",
    "parameters": [
      { "code": "bore", "type": "enum",
        "values": [32, 40, 50, 63, 80, 100, 125] },
      { "code": "stroke", "type": "range",
        "min": 10, "max": 200, "step": 1, "unit": "mm",
        "gridValues": [10, 20, 30, 50, 75, 100] },
      { "code": "mount", "type": "enum", "values": ["", "FA", "FB"] }
    ],
    "rules": [ /* 现有 If/Then 规则，语义不变 */ ]
  }
}
```

**语义约定**：

1. **mode**：`parametric` 启动参数化引擎；缺失即现有枚举模式（CSV 行驱动选型），现有 11 个直线缸系列等全部老系列不受影响。
2. **参数域**：`enum`（现有）+ 新增 `range`（min/max/step，全部为整数，step≥1；min/max 必须满足 `max ≥ min`）。
3. **gridValues**：该参数的"标准档位"取值列表，仅用于 UI 快捷选择与网格判定辅助；**网格真源仍是 CSV**（见 §4 判定规则）。
4. **modelCodeTemplate**：型号编码模板。语法 `{字段[:padN]}`，padN = 前补零到 N 位；空枚举值（如 mount=""）输出空串。示例：`KC{type:pad2}{bore}-{stroke}{mount}` 对 type=00、bore=32、stroke=10、mount="" 生成 `KC0032-10`；mount=FA 生成 `KC0032-10FA`。
5. **stepNameTemplate**：同语法，生成网格内 STEP 文件名（与 `step\` 目录现有命名对齐）；非标组合无此文件。
6. **rules**：沿用现有 If/Then（Op: eq/ne/in/range…），解释器对 range 参数同样生效（Then 可把 range 参数修剪为子区间或枚举子集——实现时给出与现有枚举引擎等价的最小扩展）。
7. **组合合法性**：所有规则同时满足，且每个参数取值在其域内。网格判定见 §4。

**构建期校验（FullCatalogBuilder 新增）**：
- 模板中的每个 `{字段}` 必须存在于 parameters；padN 必须是正整数
- range 参数：min/max/step 合法；gridValues ⊆ [min,max] 且按 step 对齐
- parametric 系列的 CSV 中每个现有编码，必须能被模板重新生成且结果一致（**试点对拍门禁**，见 §8）

## 4. 网格判定与生成行语义

- **标准档位（isStandard=true）**：生成的型号编码命中本系列 CSV 行 → 该行数据即参数行，step_file 照常（网格行不动，搜索/平替/参数表/下载全部沿用老逻辑，**回归零差异**）
- **非标档位（isStandard=false）**：编码不在 CSV → 由引擎实时生成参数行：
  - model_code = 模板生成；各参数值 = 当前组合；step_file = null；isStandard = false
  - 数量类参数展示带单位（unit 字段）
- **非标编码不出现在任何静态表**：搜索只索引网格编码 + 系列关键词；crossref 的 our_model 只允许网格编码（构建校验）；非标组合的**唯一入口是选型面板**

## 5. 两端功能需求（桌面 / 网页逐项一致）

**选型面板**：
- enum 参数：现有下拉，不变
- range 参数：**可编辑下拉**（WPF ComboBox IsEditable / HTML input+datalist）——下拉列出 gridValues（标注"标准"），允许输入任意 [min,max] 内按 step 对齐的值；非法输入（越界/非整数/不齐 step）红框 + 统一文案，不生成型号
- 联动：任一参数变化 → 解释器重算其余参数可选集（枚举过滤 + range 修剪）；生成行实时刷新
- **组合上限保护**：合法组合数 > 2000 时，UI 不生成结果行，显示"可选组合过多，请先选择更多参数"（两端同阈值同文案）

**结果行**：显示生成型号编码 + 参数摘要 + isStandard 标记（非标显示"非标档位（无标准数模）"徽标，两端同样式）

**下载（STEP / PDF）**：
- 标准档位：现有逻辑不变
- 非标档位：下载按钮**置灰**，悬停/点击显示"非标档位暂不支持数模下载，请联系销售或选择标准档位"（PDF 照常可下）

**3D 预览**：
- 标准档位：现有四级链不变
- 非标档位：展示**最近标准档位**（按 gridValues 各维距离最近、平局取小）几何，视图顶部加提示条"当前为非标档位，展示最近标准档位 <编码> 的近似几何"

**参数表 / 搜索 / 平替 / 购物车**：全部以网格行为数据源，逻辑不变（回归项）：
- 参数表：仍浏览网格行；parametric 系列不新增行
- 购物车：非标组合可加入（参数摘要同标准行），条目标注"非标档位（打包时无 STEP）"；下载 zip 跳过其 STEP、清单.txt 中注明
- 平替：非标编码不参与对照（对照只认网格编码）

**维护向导**：parametric 系列仅做校验（域/模板/对拍门禁结果展示），编辑仍手工改 meta.json（同 UGP 手工规则先例）

## 6. 双端一致性架构（红线）

- **一份规则数据**：meta.json 即唯一规则源，随 .opc / web 数据发布
- **两个解释器**：C#（net48，桌面）+ JS（网页 app.js），只读同一份 JSON，语义以 §3 约定为准
- **同一份测试向量**：`onebot-data\catalog\parametric-vectors.json`（固定输入组合 → 期望编码/参数行/isStandard），C# selftest 读它断言；网页用 playwright 无头脚本读同一文件断言（沿用购物车 E2E 先例），发布门禁两端都要过
- 数值全部用整数；枚举值字符串两端统一 trim；空值语义统一（"" 显示"(无)"，不得出现 null/undefined 差异）

## 7. 试点与迁移

1. **试点 KC 系列**（type/bore/stroke/magnet/mount，2,628 行）：补 meta 参数化字段 + 模板，CSV 保持原样作为网格
2. **对拍门禁**：构建期对 KC.csv 全部 2,628 个编码执行"模板重生成"，任何一个不一致即构建失败——这是本功能最硬的门禁
3. 试点验收通过（§8）后，同法推广 KCB/KS/KSB/KSU/KCS → M/MS/MSC/MAL/MALC（action/rod/cap 多字段模板由用户确认补零与组合规则后再切换）
4. 规则细化：按真实产品手册补充规则（如 type=03 仅限大缸径），一期试点可先放通域+网格、规则渐进补

## 8. 验收标准（8 条，全部通过才可发布）

1. **对拍门禁**：KC 全部 2,628 个现有编码模板重生成 100% 一致（含 pad 规则），构建不通过即失败
2. **回归零差异**：KC 标准档位组合的选型行为、下载、预览、搜索、参数表与切换前完全一致
3. **非标档位**：输入 stroke=87 等非网格值 → 编码正确生成、参数行正确、下载置灰+统一文案、3D 预览降级最近标准档位+提示条（两端一致）
4. **双端向量对拍**：桌面 selftest 与网页无头脚本对同一向量表全通过，纳入发布门禁
5. **老系列零影响**：其余 16 个系列（enum 模式）全部行为不变；原 selftest 31 项全过 + 新增项通过
6. **存储与性能**：试点后 KC 数据规模仍 ≤ 2,628 行（网格未膨胀）；网页首屏、参数表打开、选型联动无明显卡顿
7. **组合爆炸保护**：构造 >2000 组合的域，两端均显示"可选组合过多"提示而非渲染
8. **发布三产物**：客户 exe / 增量包 / 网页站构建发布正常；老客户增量包替换 .opc 后软件正常启动且老系列可用

## 9. 陷阱清单（12 条，实现前先读）

1. **PowerShell 5.1 编码**：编辑含中文的 .ps1/.cs/.vb 后必须跑 `sample-data\tools\fix-bom.ps1` 再编译（GBK 乱码坑）
2. **两端解释器分歧**：JS 与 C# 对空值/类型/字符串处理不同（undefined vs null、NaN 比较）——全部收敛为整数 + trim 后字符串，向量表里放边界用例（空枚举值、pad 超长、min=max）
3. **补零/模板歧义**：pad 规则、空值拼接顺序必须靠对拍门禁锁死，不要靠人眼
4. **"网格"与"域"是两个概念**：gridValues 只是快捷选择，域才定义合法性——stroke=87 合法但非网格，勿混淆
5. **组合爆炸**：阈值两端一致（2000），且必须只算一次（解释器结果缓存）
6. **非标编码流入静态表**：搜索/crossref/参数表必须只认网格——构建期校验 crossref.our_model ∈ CSV 编码
7. **购物车打包静默丢文件**：非标条目跳过 STEP 时必须在清单.txt 显式注明，禁止静默
8. **老逻辑深度绑定 CSV 行**：选型面板现从行数据推选项，parametric 模式要改走 meta 域——改动集中在选型面板入口，其他模块不动
9. **发布被占用**：publish.ps1 前必须先关客户 exe 和 serve-web（老红线）
10. **增量包兼容**：老客户 exe 读到含新字段的 meta 必须忽略未知字段正常启动（发布前用旧 exe + 新 .opc 验证一次）
11. **无头对拍依赖**：playwright + Edge 路径（`C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`），纳入发布门禁脚本
12. **预览降级提示条**：两端同文案同位置（视图顶部），不弹窗打断

## 10. 两端统一文案表（zh / en 同源，走 _lang.T/t 双语文案）

| 场景 | 中文 | English |
|---|---|---|
| 非标档位徽标 | 非标档位（无标准数模） | Non-standard (no standard model) |
| 下载按钮置灰 | 非标档位暂不支持数模下载，请联系销售或选择标准档位 | STEP download unavailable for non-standard config. Contact sales or choose a standard config. |
| 3D 降级提示条 | 当前为非标档位，展示最近标准档位 {code} 的近似几何 | Non-standard config — showing nearest standard model {code} as approximation. |
| 输入非法 | 输入超出范围（{min}–{max} {unit}）或与步长 {step} 不符 | Out of range ({min}–{max} {unit}) or not aligned to step {step}. |
| 组合过多 | 可选组合过多，请先选择更多参数 | Too many combinations — please select more parameters first. |
| 购物车非标条目 | 非标档位（打包时无 STEP） | Non-standard (no STEP in package) |
| 快捷下拉"标准"标记 | 标准 | Std |

## 11. 交付物

1. C# 参数化解释器（构建期校验 + 运行时生成）+ meta.json 字段扩展
2. JS 解释器 + 网页选型面板 range 控件 + 降级提示条/徽标
3. `parametric-vectors.json` 测试向量 + 桌面 selftest 新项 + 网页无头对拍脚本
4. KC 系列试点 meta 更新（模板/域/规则初版）
5. `docs\维护手册.md` 增补"参数化选型引擎"章节 + `项目总览.md` 回写进展