型号/原产国/品牌回填 (Model / Brand / Country of Origin Backfill)

把报关资料 xlsx 中 CT合同 sheet 的 Model / Brand / Country of Origin 三字段，从同文件 PL清单 sheet 匹配取值回填。

快速开始

python scripts/backfill.py "<xlsx路径>" [--json 明细.json]

脚本自动完成：定位 sheet 与表头 → 四字段分组匹配 → ZIP-edit 写入 → 输出 <原名>-已回填.xlsx（源文件被 Excel/WPS 占用时自动 _v2）。控制台只打 ascii 摘要；完整结果（含 problems 明细）写入 <输出名>-backfill-report.txt（UTF-8，用 Read 工具读取）。

判定 STATUS=OK 后才算成功：matched == ct_rows、total_pass=True、problems=0。任一不满足时读报告文件排查，勿交付。

匹配口径（核心，不可改动）

PL清单按 料号 + Model + Brand + 产地 四字段分组，组内数量求和。
CT合同每行按 料号 + 数量 与分组对位：一行或多行合并后的数量之和 恰好等于 某分组数量，才把该组的三个字段回填给这些行（子集和精确求解，无近似）。
对不上（数量不等、料号缺失）→ 计入 problems，该行不回填，绝不猜值。

两种模式（自动识别）

| CT合同表头 | 模式 | 行为 | |---|---|---| | 已含 Model/Brand/Country of Origin 三列（数据区空） | fill | 空单元格 inlineStr 回填，保留原样式 id | | 缺这三列 | insert | 在 China HS Code 后插入三列：表头沿用同行样式、列宽与 HS 列同宽（区间 max+3）、原 Unit/Quantity/Price/Amount 及合计公式/共享公式 ref/合并单元格/spans/dimension 全部右移重编号 |

硬性规则

必须 ZIP-edit：此类文件普遍含外部链接（xl/externalLinks/），openpyxl save() 会剥掉公式缓存值导致外链丢失、重算报 #NAME?。脚本已内置；不要改用 openpyxl 写回。
回读校验：交付前用 openpyxl 重开输出文件，逐行比对 F/G/H 与 --json 明细、确认其他 sheet 与源文件字节一致、合计公式引用正确（如 =SUM(J22:J71)）。
列定位按表头文字，勿假设固定列字母（用户会手动改列位）。
sheet 名可能带尾随空格（'CT合同 '），用子串匹配后以 wb.sheetnames 精确名访问。
源文件在 Desktop 且被 WPS 打开时读没问题，写会 PermissionError → 脚本自动落 _v2。
文件名可能含 NBSP（\xa0）或越南文，构造路径前用 os.listdir 前缀匹配定位。

可选：HTML 匹配核对报告

用户要"核对报告/留档"时，用 --json 的明细走 data-report skill 生成（KPI 卡 + 品牌占比饼图 + Top10 料号 + 逐行明细表）。注意 ECharts formatter 用单花括号 {b}/{d}，Python 模板拼接时避免 f-string/.format 转义成 {{b}}。

常见问题

| 现象 | 原因/处理 | |---|---| | problems: 无法分配 | CT 与 PL 数量对不上，读报告确认差异行，向用户反馈而不是强行回填 | | PL 有而 CT 无: <料号> | PL 多出料号（CT 没有此行），核对是否漏行 | | 输出打不开/白图 | 检查是否误用 openpyxl 重存（破坏外链） |

详细原理（XML 变换清单、坑清单、实测记录）见 reference.md。