零件BOM处理（匹配 + 导入 一体）

把"匹配编码"和"生成导入模板"两个环节串成一条流水线，保留导入生成确认、金蝶确认后回填两道用户确认门禁（匹配写回免确认，仅 dry-run 预览），
绝不自动串跑导入（零件BOM / 电气 / 紧固件共用同一个 导入模板.xlsx，自动导入会互相覆盖）。

底层逻辑（列自动检测、M26009 互换、喷塑费、71 列格式、编码接续、单位映射、跨单去重等）
由引擎脚本承担，本 skill 不重复实现，仅做编排与安全确认。

前置条件

• Python 环境：C:\Users\mpqtc\.workbuddy\binaries\python\envs\default\Scripts\python.exe；依赖见 requirements.txt（openpyxl>=3.0,<4、xlrd>=1.2.0,<2.0）
• 执行方式：脚本调用一律用 Python 绝对路径
  （cd "<skill目录>" && PYTHONIOENCODING=utf-8 "<python绝对路径>" "scripts/match_bom.py" ...），
  文件操作（备份/拷贝/删除）优先交给 Python（shutil / ctypes 回收站）。
  > ⚠️ 2026-09-29 订正：此前记录的「本机 bash 工具残缺，ls/cp/mkdir/head/tail 等一律报
  > command not found」（2026-09-20 实测）已过时 —— 2026-09-29 实测这些命令均恢复正常可用，
  > 管道（| head）也正常。故 shell 内建命令与管道可以直接用，不必再一律绕行 Python；
  > 仅当命令确实报 command not found 时再改走 Python 绝对路径。
  > 自检口诀：命令报 command not found → 才改走 Python 绝对路径，别反复重试 shell。
• 申购单：零件BOM申购单 .xlsx（含 图名/图号/品牌/材质/表面处理/重量 列）
• 物料表：金蝶导出 物料_*.xlsx（用于匹配；不传则自动探测最新一份）
• 导入模板：D:\莫佩琪\msl\导入模板.xlsx（金蝶 71 列格式；由 _shared/paths.py 管理，可用 MSL_DIR 环境变量覆盖）
• 路径查找顺序：用户显式传入 → 桌面（Desktop / 桌面 / OneDrive 重定向）下最新 物料_*.xlsx → MSL_DIR 下最新，经 _shared.paths.get_material_path()
• 📖 各已知模板的逐列映射（M26012 / M26009 / M26007 / M26010 / M25012 / M26015 / M26011 / S24 等，含机台编号与工程代号所在行）见
  references/templates.md。match_bom.py 已内置全自动检测，一般无需手动指定列位；
  只有在匹配率异常低或报列位异常时，才来这里对照具体模板排查。

Phase 1 — 匹配（引擎：零件bom匹配 / match_bom.py）

✅ 备注栏合并自动取消（2026-08-11 起，脚本已内置，无需手动）

申购单常见「备注栏连续多行共用一个备注」的纵向合并（如采购链接、适用机号覆盖两行）。
match_bom.py 写回前已自动调用 unmerge_worksheet（_shared/unmerge_column.py 的模块入口）
取消备注列纵向合并并填充内容，无需再手动单独执行；已无合并则幂等跳过。
> 如需单独预览/执行（例如只做预处理不匹配）：PYTHONIOENCODING=utf-8 python "_shared/unmerge_column.py" "<申购单>" [--dry-run]
> （按表头自动定位「备注」列，只处理数据区合并，跳过表头/标题/页脚的横向或跨列合并；默认原地修改、不建 .bak）。
> 电气件/紧固件/零散物料 处理 skill 同样内置此步。

🔴🔴 备注列绝不做信息筛选（2026-09-12 用户两次明确要求，通用铁律）

申购单的「备注」列就是普通备注列。只按既有规则原样处理，不得对备注内容做任何筛选/判别/分流，更不得把备注内容写进模板其他列（尤其金蝶「表面处理」字段）。

• 备注列唯一处理规则 = _shared/normalize.build_remark()：重量 W + 原备注 + 表尾备注，单空格连接，剥离已有重量前缀。仅此而已。
• 禁止在 match_bom.py / generate.py / _shared/normalize.py 里为备注列添加
  --surface-col、strip_weight_prefix、looks_like_surface、clean_surface、_SURFACE_HINT_WORDS、_REMARK_ONLY_WORDS
  之类「从备注里挑出表面处理再填到别处」的逻辑。
• 申购单若只有备注列、无独立表面处理列 → 模板表面处理列留空，不猜、不推断、不搬运。
• 用户原话：「备注列的信息不加入表面处理」／「申购单上的信息都在备注，备注你只要按照你以前的规则处理就行，不用筛选填到模板的表面处理列或者别的列」。
• ⚠️ 注意区分：--surface-col N 作为声明哪一列是表面处理列的既有参数是合法的（M26012 模板 --surface-col 13 等）；被禁止的是从备注列推导表面处理。曾把备注列误当「表面处理＋备注」双语义列而做过分流逻辑，已全部 git 回滚，勿再重蹈。

PYTHONIOENCODING=utf-8 python "scripts/match_bom.py" "<申购单>" "<物料表>" "<申购单>(原地修改)" --dry-run

1. 先 --dry-run 预览，把匹配成功数 / 未匹配数汇报用户。
2. 匹配写回不需要用户确认（2026-07-20 用户明确，与电气件一致）：dry-run 预览后直接去掉 --dry-run 重跑，原地填回编码、机台编码、工程代号、重量，无需停下问确认。
   - 写入前提醒用户关闭 Excel，否则 PermissionError。
   - .xls 不支持原地改，需先另存为 .xlsx。
   - 重跑会覆盖已有编码（默认行为，用于修复假码/旧码）；若用户在两次运行之间手工填过编码且不希望被覆盖，加 --preserve-codes（v1.9.9：编码列已有值的行跳过不覆盖）。
   - 门禁只保留 Phase 2（是否生成导入模板）这一道，写回编码不再单独设门禁。

> 多 sheet 申购单（2026-09-21 起）：默认只处理第一张表，但工作簿含多 sheet 时会打印
> ⚠️ 警告并提示加 --all-sheets（不再静默跳过）。多 sheet 真清单加 --all-sheets 一次跑完，
> 或用 --sheet <表名> 定向；若其他表是「草稿/废弃/统计」页，不要加 --all-sheets。
> 4 个匹配脚本（本 skill / 电气件 / 紧固件 / 外购件）此参数行为已统一，见 tests/test_multisheet.py。

> 若脚本报列位异常或匹配率异常低，查 scripts/match_bom.py --help 或核对 name/spec 互换、乘号不统一（M26009 默认走互换列位）。

🔴🔴 插行必须用 insert_row_with_merges（2026-08-25 M26013 真实事故）

openpyxl 的 ws.insert_rows() 只下移单元格值、不移动下方合并区域。喷塑费插行时，
表尾「备注：」整行合并（A15:O16）的锚点被下移的序号 13 覆盖、合并区原地不动，
generate.py 展开后产生垃圾行「13|13|13|13|13」（所幸被表面处理护栏拦截，未流入金蝶）。
修复（match_bom.py v1.9.10）：插行处改用 _shared/io_utils.insert_row_with_merges()
（先解除插入点以下合并→插行→偏移位置重建并恢复锚点值）。回归测试：tests/test_insert_row_merges.py。
自检口诀：generate 报「未匹配行数」比 match_bom 的 Unmatched 多 → 先怀疑插行合并区错位。
（本单事故文件已手工修复：取消被污染的 A15:O16、备注标签恢复到 A16:O17。）

🔴🔴 C16 只要被正式列占用（备注/机型/修改说明）就走 OUTSIDE_MODE（v1.9.12 修复）

match_bom.py 判定编码列：C16 为空/是独立编码列 → 编码写 Col16（STANDARD）；
C16 已被正式列占用 → 编码写 Col17（OUTSIDE_MODE，后续列整体右移1）。

触发词（2026-09-14 起）= C16 表头含「备注」/「机型」/「修改说明」。

• 真实事故（2026-09-14 M26016-M02）：零件BOM 修改版在 C16 新增「修改说明」列，
  内含修订备注（如 数量改为24件）。旧触发词没有「修改说明」→ 编码写入 C16，
  静默覆盖该列修订备注，且列头仍叫「修改说明」、audit.py 报 NO_CODE_COL。
• 修复后：编码写 Col17，列序为 物料编码17 / 匹配详情18 / 类别19 / 机台编码20 / 工程代号21 / 重量22，
  修改说明列（含合并表头 P5:P6 与备注内容）原样保留。
• 自检口诀：dry-run 打印 Material-code placement: STANDARD(Col16)，但 C16 表头不是空、
  也不是「物料编码」→ 该列被别的正式列占了，先确认会不会覆盖数据，再补触发词升版本。
• 定位小抄：OUTSIDE_MODE 判定在 match_bom.py 约 L603-616；generate.py 侧对应分支为
  COL_22（Col17=物料编码）/ COL_MATCHED_STANDARD（Col16=物料编码），两者都已支持。

🔴 纵向合并单元格必须展开

Excel 合并区只有左上角存值，其余格子读出为 None。申购单常见「连续多行同材质/同表面处理/同品牌只写一次」的纵向合并，
不展开会静默丢值（真实事故：外购件清单 E8:F14 合并，品牌"亚德客"覆盖序号1~7，未展开只有首行拿到值）。

匹配前先探测，用 _shared/io_utils.py：

from io_utils import merged_cell_getter, warn_vertical_merges
warn_vertical_merges(ws, data_start_row=8, col_names={6:'材质', 12:'表面处理'}, label='零件清单')
get = merged_cell_getter(ws)   # 替代 ws.cell(r,c).value

匹配结果异常偏低、或某列成片为空时，优先怀疑纵向合并没展开。

🔴 横向合并 + 无「单位」列 → 品牌被误当单位（2026-09-23 外购件05 事故，v1.9.18 修复）

外购件清单（ZMSH001-外购件清单04/05）表头只有 序号/名称/规格/品牌/数量/注明/备注，没有「单位」列；
且 D7:F7（品牌）、G7:H7（数量）是横向合并。此时若沿用模板默认单位列（Col5=E），
Col5 恰好落在品牌横向合并区（D8:F8 展开后 Col5 也是「亚德客」）→ 品牌名被当成单位，
既打印假的「单位无对应组合」告警，又可能把品牌写进金蝶单位列。
> 已修：auto_detect_header_cols 检测不到单位列时显式置 COL['unit'] = None（不读），
> 读取端容忍 None。自检口诀：生成预览若出现「⚠️ 单位提醒：某个品牌名」→ 单位列又落进品牌合并区了。

🔴🔴 表头纵向合并泄漏（比"丢值"更隐蔽的坑）

> 📎 防护（统一到 _shared/header_utils，改表头词只改一处）见 _shared/common_rules.md「表头纵向合并泄漏」。

🔴 喷塑费行「批次」被表头合并泄漏（2026-09-17 M26009-M01 事故，v1.9.13 修复）

标准模板表头「区域/批次」（B5）与下一行纵向合并（B5:B6），merged_cell_getter 展开后
Row6 的 Col2 也读到表头词「区域/批次」。而 data_start_row 检测结果为 Row6（表头续行，非数据行），
旧的「取第一数据行批次」用 range(data_start_row, new_row) → 第一条命中的就是 Row6 的表头词
→ 写进喷塑费行 B 列（单据污染，肉眼可见）。

修复：① 扫描起点改为 max(data_start_row, header_row + 1)；② 值等于本行任一表头文本（去内部空白）时跳过。
回归测试：tests/test_spray_fee_batch_leak.py。
自检口诀：喷塑费行 B 列出现「区域/批次」等表头词 → 表头合并泄漏，升 v1.9.13 以上。

🔴 机台编号为空时表头词泄漏（2026-09-09 M26013 事故，v1.9.11 修复）

申购单「机台编号：」标签后无值（如设备铭牌单）时，detect_codes 旧逻辑会从标签下一行取值，
若下一行恰好是表头行（标准模板表头 Row5），会把表头词（如「单 位」）误当机台编号写回申购单。
修复：值行必须在表头行之前（r+1 < header_row）+ 与表头文本比对 + 主流程 fallback 加 header_row > 5 守卫
（S24 模板表头 Row7、标签 Row4 值 Row5 不受影响）。
自检口诀：dry-run 摘要 Fill JTDH (=xxx) 的值是表头词（单 位/序号…）→ 机台编号为空被表头泄漏，升 v1.9.11 以上。

Phase 2 — 停下确认导入（关键门禁）

汇总未匹配行数 N：
- N = 0（全部匹配）：主动告知用户「✅ 零件BOM 全部匹配，0 行未匹配，无需生成导入模板」，流程结束（仅完成匹配，不进入 Phase 3）。
- N > 0：停下来问用户：
> "零件BOM 有 N 行未匹配，是否生成金蝶导入模板？"
- 用户确认 → 进入 Phase 3
- 用户取消 → 流程结束（仅完成匹配，不生成导入模板）

Phase 3 — 导入（引擎：零件bom导入 / generate.py）

# 物料表可选（不传则自动探测最新 物料_*.xlsx）；多份合并时第一份正常、第二份起 + --append
PYTHONIOENCODING=utf-8 python "scripts/generate.py" "<申购单>" ["<物料表>"] ["--append"] ["--dry-run"]

• 输出固定写入 导入模板.xlsx（脚本内部 SRC_TEMPLATE，无需也不能通过位置参数传路径；如需覆盖用 --output <路径>）。
• 物料表可选：不传按 get_material_path 自动探测；显式传 物料_*.xlsx 优先。
• 脚本自动备份旧模板、接续 A 系列编号、跨单去重、写 71 列格式。
• 生成后用 present_files 投递 导入模板.xlsx。
• 若用户同时给了多份零件BOM申购单要合并：第一份正常生成（全新，只含新建部分），第二份起加 --append 并入同一文件。仅限本次批次内合并同类申购单，勿跨批次累积历史数据（详见 _shared/common_rules.md）。

🔴 同一批次绝不重复运行 generate（2026-09-07 事故，四类 generate 已加固）

同一批申购单的 generate 只能跑一次。若重复运行（如复检时顺手重跑），全局去重闸会把
上次已写入模板的物料判为「复用、不新建行」，而全新模式又会先清空重建 → 复用行既被清掉又不重写，
模板静默只剩空壳（本次 61 条零件BOM 全丢，靠备份才恢复）。

加固（2026-09-07）：四个 generate.py（零件BOM/电气/紧固/零散）均已加入护栏——
全新模式下检测到本次待建物料已有 N 项存在于模板 → 立即中止写入、模板不动，提示改用 --append 或人工确认。
看到 [ERROR] 全新模式下检测到…已中止 是护栏在保护数据，不是故障。

自检口诀：generate 报错「已存在于模板」= 别慌，数据没丢；真正危险的是它没报错还把模板写空了。

⚠️ 生成后必查（单位与编码）

> 📎 未知单位提醒 / ROL=roll / 钣金加工焊接件强制 Pcs / 金蝶单位编码勿改，详见 _shared/common_rules.md「单位规则」，此处不再重复。

🔴 新码分组必查（2026-09-14 修复，generate.py v1.9.12）

新物料的 A 系列分组由 generate.py 的 KEYWORD_GROUPS（关键词）+ 名称相似度兜底决定。
兜底容易被通用词吸走，导致新码落进与库中同类先例不同的分组：

• 实例：单排链轮06B-1-19T-15D 落到 A.032（输送机配件），而库中同类 06B 单排链轮全在 A.002；
  06B半目接头 落到 A.010（气动配件），而库中「半目接头」唯一先例在 A.020（链条）
  —— 因 A.010 有 218 条「管接头」类通用词，接头 子串命中兜底。
• 已补规则：单排链轮|双排链轮 → 002、半目接头|全目接头|链条接头 → 020。
• 自检口诀：生成预览的「类别分布」要和库里同类先例对齐。不确定时先查库：
  筛出名称含该关键词的物料 → 统计 A.xxx 分组分布 → 主簇在哪个组就归哪个组。
  分组不一致先补 KEYWORD_GROUPS 再生成，别直接导金蝶（分组错了后续改动成本高）。
• 注意次序：类别含「加工件/钣金件」→ A.001 的判定在 KEYWORD_GROUPS 之前，
  所以加工类链轮不受 单排链轮→002 影响。

🔴🔴 化学品/耗材行「类别留空」会 fallback 到 A.001（2026-09-18 M24005-M06 事故，generate.py v1.9.14 修复）

• 现象：除锈剂 WD-40、自喷漆 RAL7035、酒精 95度 三行被建成 A.001.14700~14702（加工件），用户直接指出「不可能是 A.001」。
• 根因：这三行类别列留空 → CATEGORY_C_GROUPS 不命中、KEYWORD_C_GROUPS（烙铁头/焊锡丝/泡棉/双面胶/胶带）也不含化学品 → 一路 fallback 到 DEFAULT_GROUP = A001。
• 修复：新增 CHEMICAL_C002_GROUPS（除锈剂|防锈剂|防锈油|自喷漆|喷漆|油漆|稀释剂|清洗剂|酒精|乙醇|润滑脂|砂纸|砂布|抹布|油漆笔|螺纹胶|密封胶 → 002），
  判定位置放在「类别含加工件/钣金件 → A.001」之后 —— 只收拾类别留空的化学品行，不抢走已明确标加工件的行。
• 判据（库中先例）：除锈剂/防锈油/油漆/稀释剂/清洗剂/砂纸/抹布/油漆笔/螺纹胶水 全在 C.002。
• 自检口诀：生成预览里出现「除锈剂/自喷漆/酒精…」却分到 A 系 → 化学品分组规则没生效，升 v1.9.14 以上。
• 注意：备注列不参与分组判定（备注列只按 _shared/normalize.build_remark() 处理，不做任何筛选分流）。

🔴 链轮/链条接头分组对齐库中先例（2026-09-21 M26016-M13 实测，generate.py v1.9.15 修复）

两处「相似度兜底被通用词带偏」，均已补规则：

• 根因 1：原规则只写 单排链轮|双排链轮，不带该前缀的链轮落到相似度兜底 → A.032。补 链轮→002。
  ⚠️ 次序关键：本条必须排在 电机|马达(→005) 与 滚筒|辊筒(→033)之后 —— 「电机链轮-12A-2-17Z」走 A.005（库 A.005.00083 同名先例正确）、「链轮式辊筒/链轮滚筒」走 A.033，都不被抢走。
• 根因 2：原规则只写 全目接头，申购单常写「全目链接头」→ 漏匹配 → 被 A.010 的 221 条「接头」通用词吸走。补 半目链接头|全目链接头。（「拖链接头」不受影响，走更前面的 拖链→019。）
• 自检口诀：生成预览里「链轮」出现在 032/005、或「链接头」出现在 010 → 规则没生效/次序错了，先查 KEYWORD_GROUPS 再生成。

🔴 成套外购组合件 → A.028 成品套件（2026-09-24 M26010-M01 实测，generate.py v1.9.20）

抗震支架斜撑（类别=市购件、无图号、规格「C型钢57米 铰连接72件 塑翼螺母72件 车修36件(含螺栓配件)」）
原先落 A.002「其他」（市购件兜底）→ 用户拍板改 A.028 成品套件，已补 (r'抗震支架|支架斜撑', '028')。

• 判据：规格里含多件配件清单、无图号、类别=市购件 → 是成套采购件，不是单个自制加工件。
• ⚠️ 库中「斜撑」33 条全在 A.001，但那些都带图号（自制加工件），语义完全不同 —— 再次印证「市购件看语义、别看库里怎么放」。
• 自检口诀：成套外购组合件（规格里带「N 件」配件清单、无图号）落到 A.002「其他」→ 先想 A.028 成品套件。

🔴 锥辊 → A.016 滚筒（2026-09-28 M26008M07 实测，generate.py v1.9.21 修复）

M26008M07「新制辊筒」料件BOM 的 多楔带无动力锥辊520L（类别=市购件）原被 多楔带→015 抢走，
落到 A.015 皮带/带轮；语义上锥辊是锥形辊筒，属滚筒类 → 用户拍板 A.016 滚筒。

• 新增 (r'锥辊', '016')，夹在 滚筒|辊筒(→033) 与 皮带|多楔带(→015) 之间。
• ⚠️ 同批「多楔带辊筒520L」用户拍板保持 A.033 电滚筒（含「辊筒」→ 先被上面的 033 规则命中），
  不要为了让锥辊落 016 而改动 滚筒|辊筒 的归属。
• 自检口诀：生成预览的「类别分布」里「锥辊」出现在 015 → 规则次序错了。

🔴 零件BOM 支持「两种格式」；申购类型来源列按表头名找、不绑列号（2026-09-28 match_bom.py v1.9.22）

本 skill 主要处理两种格式的申购单：老格式（原本就正确，别动） 与 新格式（后续新增支持）。
两者申购类型的来源列不同，但都按表头名检测定位，列位置可变、绝不写死列号：

• 不写死列号：来源列由 detect_header_col 按表头关键词包含匹配定位，列位置变了照样命中
  （老格式实测在 Col11、新格式在 Col9，代码均自适应；同批多份列位一致也无需硬编码假设）。
• 目标列同样按表头名 申购类型 优先定位，找不到才回退历史固定位 Col18+OFF；
  其后的「机台编码 / 工程代号 / 重量」以目标列为基准顺延。
• 新格式原逻辑找不到类别列 → 走「按文件名推断」分支，把「申购类型」列填成默认值「零件」，
  盖掉原表的「加工件」（用户 2026-09-28 发现）→ 现改为回退取「注明」列。
• 喷塑费行（F.001.00001）继承其上方数据行的申购类型（新格式 → 同为「加工件」）；
  老格式（「类别」来源）的喷塑费行维持留空不变。
• 手工指定列位仍可用 --category-col N（优先级最高）。
• 自检口诀：新格式（ZMSH001 类）处理完，「申购类型」列出现「零件」→ 来源列回退逻辑没生效。
• ⚠️ 兼容性（2026-09-28 实测）：老格式 4 份 + 新格式 2 份原样重跑 diff 全 0
  （唯一表象是公式单元格缓存被清，属 openpyxl 保存固有行为，fullCalcOnLoad 已置 True，Excel 打开自动重算）。

🔴 品名/规格「数据级」反向 → 导入模板名称被写成图号（2026-09-28 M26017-M02 实测，generate.py v1.9.21 修复）

申购单常有「表头标准、数据反向」的写法：表头 C3=品名 / C4=图号，但数据行把图号填在品名列、
品名填在图号列（M26009/M26017 常见）。match_bom.py 有数据级检测能纠正并正确匹配，
而 generate.py 原先只看表头文字判断列位 → 生成时把名称/规格写反进金蝶导入模板：

(物料)名称 = 26017M02P051A     ← 写成了图号
(物料)规格型号 = 侧封板护罩1      ← 写成了品名

• 修复：detect_name_spec_swap 提升为 _shared/header_utils.detect_name_spec_swap（单一真源），
  generate.py 在 resolve_bom_columns 之后按数据内容（前 5 行：名称列像零件代号 字母+数字、
  规格列含中文 → 判定互换）纠正列位，并打印 [auto] 检测到品名/规格列【数据反向】…。
• 同时 resolve_bom_columns 改为返回 COL 副本，防自动纠正污染模块级 COL_* 常量。
• 自检口诀：导入模板「(物料)名称」列出现 26017M02P051A 这类图号形态 → 反向没被纠正，回来查这里。

🔴🔴 分组判定优先级：「市购件」行以物料语义为主，库中同类先例仅作次要参考（2026-09-21 用户明确要求）

用户原话：「因为以前编码分组有很多错误，其实你可以主要看自己分类，次要看原有的类似分组」
→ 追问后补充限定：「我说的编码，它要是写着市购件的才主要按你的分析」。

适用范围（看申购单「类别」列）：

• 主判据看什么：品名 + 规格 + 材质 + 表面处理 + 有无图号，对照 _shared/classifications.py 的
  A_SERIES_MAP 分组定义（A.001 加工件 / A.002 其他 / A.003 紧固件 / A.004 小零件 / A.005 电机 /
  A.006 减速机 / A.007 轴承 / A.008 气缸 / A.009 阀类 / A.010 气动配件 / A.012 直线轴承 / A.013 直线导轨 /
  A.016 滚筒 / A.017 脚杯 / A.018 脚轮 / A.019 拖链 / A.020 链条 / A.024 电缸 / A.026 铝型材及配件 /
  A.027 门五金 / A.032 输送机配件 / A.033 电滚筒 …），自己判断它该归哪一组。
• 库是历史填写的，已知有大量错分（如「其他」A.002 被当兜底垃圾桶、直线轴承塞进 A.007、
  门把手塞进 A.002、链轮塞进 A.002/A.032）。不得因为"库里都这么放"就照抄。
• 典型语义归属速查（按物料性质，不按库中现状）：
  | 物料 | 应归 | 常见错分 |
  |------|------|---------|
  | 直线轴承（LMF/LMK/LM…UU） | A.012 直线轴承 | 错入 A.007 轴承（被「轴承」二字抢走） |
  | 直线滑轨 / 滑块（HGH/HGW…） | A.013 直线导轨 | 错入 A.002 其他 |
  | 门把手 / 门锁 / 合页 | A.027 门五金 | 错入 A.002 其他 |
  | 固定环 / 挡圈 / 卡簧 | A.004 小零件 | 错入 A.002 其他 |
  | 隔套 / 钢套 / 轴套 / 套管 | A.004 小零件 | 错入 A.007（被「轴承套管」的「轴承」抢走） |
  | 带座轴承 UCP/UCF | A.007 轴承 | — |
  | 接头 / 消声器 / 浮动接头 | A.010 气动配件 | — |
  | 调速阀 / 手阀 / 电磁阀 | A.009 阀类 | — |
  | 键 / 平键 / 销 | A.004 小零件 | — |
  | 链轮 | 待用户拍板（A.020 链条 / A.001 / A.002 三选，库中三种都有） | 错入 A.005「电机」（"电机链轮"含"电机"二字） |
• 自检口诀：这条物料的品名/规格放到 A_SERIES_MAP 里、"最像哪一组"就是哪一组；不要先问"库里怎么放的"。
• ⚠️ 已导入金蝶后才发现分组不妥：金蝶侧改分组需人工操作（禁用/改码 + 重建），成本高 →
  生成导入模板前的这次分组判断就是最后一道关口，务必按语义过一遍。

🔴 表面处理「措辞差异」会造成重复建码（2026-09-14 M26016-M02 事故）

同一图号在修订版/新增补料申购单里被重新列出时，常把工艺要求（如 膜厚：60μm~90μm）从备注挪进表面处理列。
五字段精确匹配因此落空 → generate.py 给它建新码 → 金蝶里同图号出现两个在用码。

• 实例：马达端板 | 26016M02P037A | Q235 在 9.7 批次已建 A.001.14003（表面处理=喷塑:RAL7047电视灰，膜厚写在备注）；
  9.14 新增补料把膜厚挪进表面处理 → 五字段未命中 → 又建 A.001.14640（表面处理含膜厚）。两码并存，需人工删除其一。
• 预防（生成前必做）：对每条拟新建物料，按「规格型号」反查物料库——若同规格已有编码（只是表面处理/品牌描述不同），
  立即停下人工确认，多半应复用旧码，不要建新码。
• 自检口诀：同图号（规格型号）在库里已有码 → 先问是不是措辞差异，先别建新码。
• 误建后的修法：金蝶里删除/禁用新码；申购单编码列改回旧码（注意 --backfill 只填空单元格，不会覆盖已填值，改码必须手工改单元格）。

🔴 喷塑费固定复用 F.001.00001（长期约定），不进导入模板

> 这是既有长期约定，不是新规则——spray_fee_code='F.001.00001' 硬编码在 match_bom.py 默认参数里，
> 2026-07-27 M26011-M04 等历史任务一直如此执行。

match_bom.py 自动添加的喷塑费行固定写 F.001.00001。该码是物料库里规格为空的全公司通用码，
跨工程复用，任何情况下都不新建第二个喷塑费编码。

因此 generate.py（只读空编码行）跳过喷塑费行是设计如此，不是 bug：

零件清单 23 行 → 导入模板只有 22 行加工件，没有喷塑费  ← 正确！

> ⛔ 反面教材（2026-08-01 真实事故）：误以为"喷塑费漏掉了"，把申购单编码列清成空字符串
> 再重跑 generate，结果新建出重复的 F.001.00005，而库里 F.001.00001 喷塑费 早就存在。
> 用户发现后才回滚。永远不要为了把喷塑费"塞进"模板而清空它的编码列。

判断口诀：
- 费用行编码已是 F.001.xxxxx → 已复用库里已有码，任务完成，不用管模板里没有它
- 只有当库里确实没有该费用物料时，才需要新建 F 系码
- 库里现有 F 系（截至 2026-08-01 共 4 个）：F.001.00001 喷塑费(规格空,通用) /
F.001.00002 90°弯圆加工费 / F.001.00003 150*40铝型材冲孔模具费 / F.001.00004 150*40铝型材冲孔费

🔴🔴 新物料场景喷塑费会漏加（2026-09-23 钣金清单02 实例）

喷塑费行只由 match_bom.py 在匹配阶段添加（信号：① 该行编码已以 A.001 开头；
② 类别列含「加工件/钣金件」）。generate.py 完全没有添加喷塑费的逻辑。

于是「新物料」链路会丢喷塑费：

① match_bom.py 匹配   → 该行未匹配（编码空）→ 两信号都不满足 → 不加喷塑费
② generate.py 建码    → 分配 A.001.14777（无喷塑费逻辑）
③ generate.py --backfill → 只写编码，不跑喷塑费判定 → 喷塑费永久丢失

所有「新物料 + 加工件/钣金件」场景都会踩到，且表里最后看不到任何报错。

表现：表里已有 A.001.xxxxx 编码，但没有喷塑费行（F.001.00001）。
补救：编码已在表里 → 重跑一次 match_bom.py 即触发信号①（但见下方列位陷阱）。
自检口诀：钣金/加工件清单处理完后，必查有无喷塑费行；没有就按上法补。

> ⚠️ 重跑前先验列位（2026-09-23 同时暴露）：match_bom.py 第 643-646 行只用
> Col16 表头判断 CODE_COL = 16 + OFF，从不检查表里是否已存在「物料编码」列。
> 若表被整理过（删掉空白列导致整体左移，如本实例编码列在 Col14），
> 重跑会把编码写到 Col16 → 表头重复、旧「匹配详情」不更新、申购类型被文件名值覆盖。
> 对策：重跑前先读表头确认「物料编码」列号；不一致时改用
> _shared/io_utils.insert_row_with_merges + unmerge_and_set 按实际列位手工插喷塑费行
> （名称列=喷塑费／数量列=PCS／编码列=F.001.00001／工程代号=原值／类型列沿用上一行）。

Phase 4 — 金蝶确认后回填

1. 用户把 导入模板.xlsx 上传金蝶。
2. 用户自行判断金蝶导入是否全部成功。
3. 用户确认全部成功 → 重跑导入脚本并加 --backfill（取导入模板里写入的真实编码，按 品名+规格 映射写回申购单空编码列；不重新分配）：

PYTHONIOENCODING=utf-8 python "scripts/generate.py" "<申购单>" ["<物料表>"] --backfill

• 澄清：--backfill 是读取已生成的导入模板里写入的真实编码映射回填申购单空编码列，不重新分配、不重新匹配物料表，与规则「回填不要重跑 generate 重新分配编码」完全一致，是幂等操作。
• ✅ --backfill 现已遵守 --dry-run（2026-09-21 修复 / 2026-09-29 复核）：
  本脚本把 dry_run 透传给 _shared/dedup_backfill.backfill()，其内部（if dry_run:，约 L221）
  只逐组打印「将写入 N 行」而不落盘，并有 tests/test_backfill_dry_run.py（文件逐字节不变）守护。
  → 现在可以用 --backfill --dry-run 安全预览回填。
  > 📌 历史（勿再照抄旧结论）：2026-09-20 曾实测 --backfill --dry-run 仍写源文件
  > （字节数 17330 → 17338、md5 改变）；该脚枪已于 2026-09-21 体检批次堵住
  > （4 个 generate 全部透传 dry_run）。回填终究是写源文件的操作，
  > 保持先备份的习惯依然稳妥，但不必再因此放弃 dry-run 预览。
• 回填后「匹配详情」列保持原值不变（仍为「未匹配」），只填编码列 —— 属既定行为，不是漏回填。
  4. 用户指出部分失败 → 不回填（或仅回填确认成功的部分）。
  5. 导入模板文件丢失/不可用时（如被清理、或 msl 路径被金蝶锁未生成成功）：只要用户已导出含新建编码的新物料表，可直接重跑匹配引擎回填——match_bom.py "<申购单>" "<新物料表>" "<申购单>"（去掉 --dry-run 写回）。匹配引擎只查已有编码、不重新分配，编码取自金蝶真实导出，与 --backfill 效果等价且更稳。前提：未匹配行的 品名+规格(+材质+表面处理+品牌) 五字段能精确命中新物料表（即该行确已成功导入金蝶）。dry-run 预览确认 Unmatched: 0 后再写回。

与「申购单分拣」的关系

• 单一零件BOM申购单 → 直接用本 skill 一键处理。
• 多种类型混在一个文件夹 → 用「申购单分拣」统一调度（它会对每类跑匹配、再统一把控导入门禁，避免共用模板互相覆盖）。本 skill 不要用于文件夹批量场景。