wangruiguo/OnebotCatalog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
OnebotCatalog/开发提示词-参数化选型引擎.md

13 KiB
Raw Permalink Blame History

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

交付对象：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 块上扩展，缺省字段 = 现行为，老系列零影响：

{
  "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 回写进展