@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/wenyao_fill_template.py

@@ -0,0 +1,568 @@
+#!/usr/bin/env python3
+"""wenyao_fill_template.py — 上海文鳐「发票模版」填报器（P0，2026-09-11）
+
+输入：① 运营版《上海文鳐发票模版.xlsx》 ② 一行飞书数据（JSON） ③ 列映射 scripts/wenyao-template-map.json
+输出：填好的 xlsx（顶部块 + 数据写**第 8 行**，说明行被覆盖）+ 一份「写了什么」的 JSON 摘要
+
+设计要点（对齐运营说明，逐条可测）：
+  · 数据行 = 第 8 行（用户 2026-09-11 明确："说明就是要你填入的行，删掉重填"）；9 行起清空
+  · 箱序 `1-<箱数>`；单箱数量 = 数量÷箱数；货箱总重 = 重量×箱数；方数 = 长×宽×高÷1e6；
+    申报总价 = 7×数量；材质 = `中文，english`；卖家ID 由店铺名（如"墨西哥-1店-子账号"）映射
+  · 产品图：lip 附件 → 下载到本地 → 以**浮动图片**锚定在 AA 列（openpyxl）
+  · **材质英文三级解析**（`resolve_material_en`，本文件是唯一实现）：
+    ① SKU 字典（<数据目录>/lip-sku-dict.json，键=SKU）→ ② 通用小词典（映射真源 `materialEn`）
+    → ③ 会话传入（`--material-en` / 行内 `材质英文`）。三级都没命中 ⇒ **阻断**（缺口文案指路）；
+    ③ 定音时把译文**写回 SKU 字典**（`confirmed:false` + 来源 "LLM 译 <日期>…"，运营可事后复核）。
+  · 只读输入、只写本地文件；**不碰飞书表、不开门户**（P0 边界）
+
+用法：
+  python3 scripts/wenyao_fill_template.py --template <模版.xlsx> --row <行.json> \
+      --out <输出.xlsx> [--english-name "..."] [--material-en "<材质英文>"] \
+      [--image <图片路径>] [--dry-run] [--today YYYY-MM-DD]
+--dry-run 只打印将要写入的单元格（JSON），不生成文件（供单测做金标断言）；**任何模式都不写表/不联网**。
+「阻断性缺口」（材质英文三级未解析 / 同名不同值冲突）⇒ 拒绝写文件并 exit 1；
+其余缺口（如图片缺失）照旧只报告，由编排器的 P3 统一拦。
+"""
+import argparse
+import json
+import os
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+MAP_FILE = HERE / "wenyao-template-map.json"
+
+# 唯一真源：ML 店铺 → 卖家 user_id（2026-09-19 起；见 scripts/ml_store_ids.py 顶部事故说明）
+sys.path.insert(0, str(HERE))
+import ml_store_ids  # noqa: E402
+
+
+def load_map():
+    return json.loads(MAP_FILE.read_text(encoding="utf-8"))
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# 材质英文：三级解析（**唯一实现**，勿在别处复制判据）
+# ───────────────────────────────────────────────────────────────────────────
+# 合同：`skills/ml-invoice/references/template-fill-contract.md`（真源 = 本目录的模板映射真源）
+# —— S 列 = `{材质}，{材质英文}`。2026-10-12 事故固化：
+# 该列的英文此前只查 8 条通用小词典（不含『铁』），而**已确认的 per-SKU 字典根本没被查**
+# ⇒ 答案现成却被拦下（两条票同日 blocked，闸门 exit 1）。现在三级：
+#   ① SKU 字典（<数据目录>/lip-sku-dict.json，键=SKU；优先 `confirmed:true` 的「材质英文」）
+#   ② 通用小词典（映射真源 `materialEn`）
+#   ③ 会话传入（`--material-en` / 行内 `材质英文`）——**政策A：LLM 译出的材质英文可以直接用**
+#      （写台账留痕 + 写回字典标 `confirmed:false`，运营事后可复核）
+# ⛔ HS 编码那条红线**完全不动**（人工维护、不预填、不写候选、不自动确认）：
+#    它是**只给 HS** 的，不许套到材质英文上（今天的误阻正是这么来的）。
+# ⛔ 同一份 SKU 字典的既有读写方是另一条发票链的 runner：键/形状/原子写口径一致，
+#    改路径或条目形状要两处一起改（本文件不复制它的键空间判据，只共用同一份文件）。
+MATERIAL_POLICY = "政策A：材质英文允许 LLM 译；HS 编码仍必须人工维护"
+MATERIAL_SKU_DICT_NAME = "lip-sku-dict.json"
+MATERIAL_AUDIT_REL = ("material-en", "audit.jsonl")
+MATERIAL_WRITEBACK_SOURCE = "LLM 译 {date}（政策A：材质英文可直接用，HS 不动）"
+MATERIAL_LEVEL_SKU = "①SKU字典"
+MATERIAL_LEVEL_SMALL = "②小词典"
+MATERIAL_LEVEL_SESSION = "③会话传入"
+
+
+def data_dir():
+    """数据目录：**唯一判据**在 `scripts/lib/argent_datadir.py`（延迟求值 ⇒ 隔离跑得动）。"""
+    sys.path.insert(0, str(HERE / "lib"))
+    from argent_datadir import resolve_data_dir  # noqa: PLC0415
+    return Path(resolve_data_dir()["dir"])
+
+
+def sku_dict_path():
+    return data_dir() / MATERIAL_SKU_DICT_NAME
+
+
+def load_sku_dict(path=None, strict=False):
+    """读 SKU 字典（**只读**）。文件不存在 ⇒ `{}`；
+    `strict=True` 时「存在但不可解析」**抛错**（别把坏字典当空字典写，否则会毁掉已确认条目）。"""
+    p = Path(path) if path else sku_dict_path()
+    if not p.exists():
+        return {}
+    d = json.loads(p.read_text(encoding="utf-8"))
+    return d if isinstance(d, dict) else {}
+
+
+def _norm_en(s):
+    return re.sub(r"\s+", " ", str(s or "").strip()).casefold()
+
+
+def material_gap_text(mat):
+    """三级都没命中时的**阻断文案**（指路，不复述 HS 那条红线）。"""
+    return (f"材质「{mat}」未能在 SKU 字典 / 小词典命中 ⇒ 请翻译成英文后用 --material-en 重跑"
+            f"（{MATERIAL_POLICY}）")
+
+
+def material_conflict_text(sku, kept, rejected):
+    return (f"材质英文冲突（SKU {sku or '?'}）：字典保留『{kept}』、拒绝本次传入『{rejected}』"
+            f"⇒ 未写回字典，请人工裁决后重跑（{MATERIAL_POLICY}）")
+
+
+def resolve_material_en(mat_zh, *, sku="", material_en="", small_dict=None,
+                        sku_dict=None, dict_path=None, today=""):
+    """材质英文**三级解析（唯一实现）** —— 纯计算，**不写任何文件**（写回见 `apply_material_writeback`）。
+
+    :returns: `{"中文","英文","命中","来源","备注":[],"冲突":[],"缺口","写回","字典","覆盖"}`
+      · 命中 = `①SKU字典` / `②小词典` / `③会话传入` / `""`（三级都没命中）；
+      · `缺口` 非空 ⇒ **闸门必须阻断**（编排器按 `plan["gaps"]` 拦，文案即此串）；
+      · `写回` 非空 ⇒ ③ 定音且字典里没有可用条目 ⇒ 应写回（`{"mode","sku","条目"}`）。
+
+    判据（与 `flow_case` 的「同名不同值不覆盖、记冲突交人」同一口径）：
+      · ① 命中 ⇒ 用字典值；③ 与它同名不同值 ⇒ **冲突**（保留字典值、不写回、交人）；
+      · ② 命中且 ③ 不同 ⇒ 用 ③（更具体）并留痕；⛔ **不写字典**（通用小词典无需 per-SKU 固化）；
+      · ①② 都没命中而 ③ 有值 ⇒ 用 ③ 并**写回**；字典里已有 `confirmed:true` 条目但缺材质英文
+        ⇒ 只留痕、**不写**（不许把已确认条目降级成 `confirmed:false`）。
+    """
+    out = {"中文": str(mat_zh or "").strip(), "英文": "", "命中": "", "来源": "",
+           "备注": [], "冲突": [], "缺口": "", "写回": None, "字典": None, "覆盖": False}
+    mat, sku = out["中文"], str(sku or "").strip()
+    today = str(today or "")[:10] or datetime.now().strftime("%Y-%m-%d")
+    entry = None
+    if sku and isinstance(sku_dict, dict):
+        e = sku_dict.get(sku)
+        entry = e if isinstance(e, dict) else None
+    out["字典"] = entry
+    dict_en = str((entry or {}).get("材质英文") or "").strip()
+    small_en = str((small_dict or {}).get(mat) or "").strip()
+    session_en = str(material_en or "").strip()
+
+    if dict_en:
+        out.update({"英文": dict_en, "命中": MATERIAL_LEVEL_SKU,
+                    "来源": str((entry or {}).get("来源") or "")})
+        if small_en and _norm_en(small_en) != _norm_en(dict_en):
+            # per-SKU 值与通用小词典不一致（多半是 SKU 材质变过或字典陈旧）：按 per-SKU 优先，
+            # 但**必须留痕**（这类不一致只看 S 列看不出来）—— 不阻断，交运营复核。
+            out["备注"].append(f"SKU 字典（{dict_en}）与通用小词典（{small_en}）不一致"
+                               f"⇒ 按 per-SKU 优先用字典值，请复核")
+        if session_en and _norm_en(session_en) != _norm_en(dict_en):
+            out["冲突"].append({
+                "field": f"材质英文[{sku or mat}]",
+                "kept": {"value": dict_en, "来源": out["来源"] or "(字典)",
+                         "confirmed": bool((entry or {}).get("confirmed"))},
+                "rejected": {"value": session_en, "来源": "会话传入（--material-en / 行内 材质英文）"}})
+            out["缺口"] = material_conflict_text(sku or mat, dict_en, session_en)
+        return out
+
+    if small_en:
+        out.update({"英文": small_en, "命中": MATERIAL_LEVEL_SMALL, "来源": "映射真源 materialEn"})
+        if session_en and _norm_en(session_en) != _norm_en(small_en):
+            out["备注"].append(f"会话传入覆盖小词典：{small_en} → {session_en}（未写回字典）")
+            out["英文"], out["覆盖"] = session_en, True
+        return out
+
+    if session_en:
+        out.update({"英文": session_en, "命中": MATERIAL_LEVEL_SESSION,
+                    "来源": "会话传入（--material-en / 行内 材质英文）"})
+        if entry is None:
+            out["写回"] = {"mode": "新增", "sku": sku, "条目": {
+                "材质英文": session_en, "confirmed": False,
+                "来源": MATERIAL_WRITEBACK_SOURCE.format(date=today), "备注": ""}}
+        elif entry.get("confirmed") is True:
+            out["备注"].append("字典已有 confirmed:true 条目但缺材质英文 ⇒ 只留痕、**不写回**"
+                               "（不把已确认条目降级为 confirmed:false）；请人工补录该 SKU 的材质英文")
+        else:
+            out["写回"] = {"mode": "合并", "sku": sku, "条目": {
+                "材质英文": session_en, "confirmed": False,
+                "来源": MATERIAL_WRITEBACK_SOURCE.format(date=today),
+                "备注": str(entry.get("备注") or "")}}
+        return out
+
+    if mat:
+        out["缺口"] = material_gap_text(mat)
+    return out
+
+
+def _material_audit(rec, dict_path=None):
+    """审计留痕（JSONL 追加）。落点：<数据目录>/material-en/audit.jsonl（与回写器的审计同族）。"""
+    base = Path(dict_path).parent if dict_path else data_dir()
+    f = base.joinpath(*MATERIAL_AUDIT_REL)
+    try:
+        f.parent.mkdir(parents=True, exist_ok=True)
+        with f.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(rec, ensure_ascii=False) + "\n")
+        return str(f)
+    except Exception:  # noqa: BLE001 —— 审计失败不该毁掉填报（但调用方会把动作如实报出）
+        return ""
+
+
+def record_material_audit(plan, *, dict_path=None):
+    """**冲突留痕**（唯一入口）：字典已有值 vs 本次传入不同 ⇒ 即使被闸门拦下（不写回）也要落审计。
+
+    为什么单独一个函数：冲突时**不会**走到 `apply_material_writeback`（闸门在写盘前就拦了），
+    若只在写回路径留痕，冲突就只剩异常串里的那句话 —— 交人之后无从复核。
+    """
+    m = dict((plan or {}).get("material") or {})
+    if not m.get("冲突"):
+        return {"written": False, "动作": "无需留痕（无冲突）"}
+    rec = {"at": datetime.now().astimezone().isoformat(timespec="seconds"),
+           "sku": str(((m.get("写回") or {}).get("sku")) or ""), "材质": m.get("中文", ""),
+           "材质英文": m.get("英文", ""), "命中": m.get("命中", ""),
+           "政策": MATERIAL_POLICY, "动作": "冲突 ⇒ 未写回（交人）", "冲突": m["冲突"]}
+    rec["审计"] = _material_audit(rec, dict_path)
+    return rec
+
+
+def apply_material_writeback(plan, *, audit=True, dict_path=None):
+    """执行 ③ 命中后的**字典写回**（唯一写入口）+ 审计留痕；返回动作回执（可直接进台账）。
+
+    ⛔ 不覆盖 `confirmed:true`（解析阶段就不会给出写回计划；写前**再查一次**，防计划过期）；
+    ⛔ 同 SKU 同值 ⇒ 幂等跳过（不重写、不动 mtime）；原子写（tmp + `os.replace`）。
+    """
+    m = dict((plan or {}).get("material") or {})
+    wb = m.get("写回") or None
+    rec = {"at": datetime.now().astimezone().isoformat(timespec="seconds"),
+           "sku": str((wb or {}).get("sku") or ""), "材质": m.get("中文", ""),
+           "材质英文": m.get("英文", ""), "命中": m.get("命中", ""),
+           "政策": MATERIAL_POLICY, "动作": ""}
+    if not wb:
+        rec["动作"] = ("冲突 ⇒ 未写回（交人）" if m.get("冲突")
+                       else ("无需写回（命中 " + m["命中"] + "）" if m.get("命中") else "未解析 ⇒ 不写"))
+        if audit and (m.get("冲突") or m.get("命中") == MATERIAL_LEVEL_SESSION):
+            rec["审计"] = _material_audit(rec, dict_path)
+        return {"written": False, "动作": rec["动作"], "sku": rec["sku"], "条目": None}
+
+    p = Path(dict_path) if dict_path else sku_dict_path()
+    try:
+        cur = load_sku_dict(p, strict=True)
+    except Exception as exc:  # noqa: BLE001 —— 坏字典 ⇒ 拒绝写（绝不覆盖成"只剩本条的字典"）
+        rec["动作"] = f"字典不可解析 ⇒ 拒绝写回（{type(exc).__name__}）"
+        if audit:
+            rec["审计"] = _material_audit(rec, dict_path)
+        return {"written": False, "动作": rec["动作"], "sku": rec["sku"], "条目": None}
+
+    merged = dict(wb.get("条目") or {})
+    if wb.get("mode") == "合并":
+        merged = {**(cur.get(wb["sku"]) or {}), **merged}
+    prev = cur.get(wb["sku"]) or {}
+    prev_en = str(prev.get("材质英文") or "").strip()
+    if prev_en and _norm_en(prev_en) != _norm_en(merged.get("材质英文")):
+        # 计划之后字典被别的进程改过（或缓存过期）⇒ 仍按"不覆盖 + 记冲突"办
+        rec["动作"] = "冲突 ⇒ 未写回（字典现值与本次不同，交人）"
+        rec["冲突"] = {"kept": prev_en, "rejected": merged.get("材质英文")}
+        if audit:
+            rec["审计"] = _material_audit(rec, dict_path)
+        return {"written": False, "动作": rec["动作"], "sku": wb["sku"], "条目": None}
+    if prev == merged:
+        rec["动作"] = "幂等跳过（同 SKU 同值，未重写字典）"
+        if audit:
+            rec["审计"] = _material_audit(rec, dict_path)
+        return {"written": False, "动作": rec["动作"], "sku": wb["sku"], "条目": merged}
+
+    new = dict(cur)
+    new[wb["sku"]] = merged
+    tmp = p.parent / ("." + p.name + ".tmp")
+    p.parent.mkdir(parents=True, exist_ok=True)
+    tmp.write_text(json.dumps(new, ensure_ascii=False, indent=2), encoding="utf-8")
+    os.replace(tmp, p)
+    rec.update({"动作": f"字典写回（{wb.get('mode')}，confirmed=false）", "条目": merged, "字典": str(p)})
+    if audit:
+        rec["审计"] = _material_audit(rec, dict_path)
+    return {"written": True, "动作": rec["动作"], "sku": wb["sku"], "条目": merged,
+            "path": str(p), "审计": rec.get("审计", "")}
+
+
+def num(v, default=None):
+    """把飞书里的数字（可能是 '17.7' / 17.7 / '[17.7]'）转 float"""
+    s = str(v if v is not None else "").strip()
+    s = s.strip("[]").strip()
+    if not s:
+        return default
+    m = re.search(r"-?\d+(?:\.\d+)?", s)
+    return float(m.group(0)) if m else default
+
+
+def pick(v, default=""):
+    """飞书 select/文本值归一：'["上海文鳐"]' → '上海文鳐'"""
+    s = str(v if v is not None else "").strip()
+    try:
+        arr = json.loads(s)
+        if isinstance(arr, list) and arr:
+            return str(arr[0]).strip()
+        if isinstance(arr, str):
+            return arr.strip()
+    except Exception:
+        pass
+    if len(s) >= 4 and s[0] == "[" and s[-1] == "]":
+        return s[1:-1].strip()
+    return s
+
+
+def fmt_num(x):
+    if x is None:
+        return ""
+    f = float(x)
+    return int(f) if abs(f - round(f)) < 1e-9 else round(f, 6)
+
+
+def store_id(store_name, ids=None):
+    """'墨西哥-1店-子账号' → ML 卖家 ID（唯一真源 `scripts/ml-store-ids.json`）。
+
+    2026-09-19：三份映射收敛到一处。此前本函数的键是裸 `1店`，与
+    `~/.dsh/argent/lip-po-mapping.json`（完整店名）、`invoice-mapping.json`（短名+后缀）
+    各写一份 —— 鑫中航那条线因键匹配不上而**静默回退成紫鸟 store_id**，6 张发票写错。
+    现在统一由 `ml_store_ids.resolve()` 解析（键 = `国家-店号`，主/子账号共用同一 ID）。
+
+    `ids` 仅为兼容旧调用/单测保留：显式传入时按旧口径查（键 `N店`），不传则读真源。
+    """
+    if ids is None:
+        return ml_store_ids.resolve(pick(store_name))
+    s = pick(store_name)
+    m = re.search(r"(\d+)店", s)
+    if m:
+        return ids.get(f"{m.group(1)}店", "")
+    for k, v in ids.items():
+        if k in s:
+            return v
+    return ""
+
+
+def plan_cells(row, m, today, english_name=None, material_en=None, sku_dict=None):
+    """纯计算：返回 {cell: value} 与诊断 —— 不碰文件（可单测）。
+
+    `material_en` = 会话传入的材质英文（三级解析的第③级；`--material-en` 或行内 `材质英文`）。
+    `sku_dict` = 只读注入的 SKU 字典快照（None ⇒ 读数据目录里的那份；**只读，不写**）。
+    返回额外带 `material`（三级解析结果）与 `blocking`（**阻断性**缺口；其余缺口只报告）。
+    """
+    cells, notes, gaps = {}, [], []
+    # 顶部块
+    for name, spec in m["topBlock"].items():
+        v = spec.get("value", "")
+        if v == "__TODAY__":
+            cells[spec["cell"]] = today
+        else:
+            cells[spec["cell"]] = v
+    # 数据行
+    r = m["dataRow"]
+    qty = num(row.get("数量") if row.get("数量") is not None else row.get("总产品数量"))
+    cart = num(row.get("箱数") if row.get("箱数") is not None else row.get("总箱数"))
+    wt = num(row.get("重量") if row.get("重量") is not None else row.get("单箱总重"))
+    L = num(row.get("长") if row.get("长") is not None else row.get("货箱长度"))
+    W = num(row.get("宽") if row.get("宽") is not None else row.get("货箱宽度"))
+    H = num(row.get("高") if row.get("高") is not None else row.get("货箱高度"))
+    mat = pick(row.get("材质"))
+    # 材质英文：**三级解析**（① SKU 字典 → ② 小词典 → ③ 会话传入）。
+    # 解析本身不写文件；③ 定音后的字典写回由 `apply_material_writeback(plan)` 单独做。
+    session_en = (str(material_en or "").strip()
+                  or pick(row.get("材质英文")) or pick(row.get("materialEn")))
+    mat_res = resolve_material_en(
+        mat, sku=pick(row.get("SKU")), material_en=session_en,
+        small_dict=m.get("materialEn") or {},
+        sku_dict=(load_sku_dict() if sku_dict is None else sku_dict), today=today)
+    mat_en = mat_res["英文"]
+    notes.extend(mat_res["备注"])
+
+    for spec in m["columns"]:
+        cell = f"{spec['col']}{r}"
+        src = spec["source"]
+        if src == "field":
+            raw = row.get(spec["field"])
+            if spec.get("numeric"):
+                # 数值列必须写**数字**（飞书里可能是文本，直接写会让门户当成文本数字）
+                v = num(raw)
+                if v is None:
+                    gaps.append(spec["header"])
+                    v = ""
+                else:
+                    v = fmt_num(v)
+            else:
+                # 文本列保持字符串：货件号/HS编码/SKU/卖家ID（防科学计数法、防丢前导零）
+                v = pick(raw, spec.get("default", ""))
+                if not v and spec.get("default"):
+                    v = spec["default"]
+                if not v:
+                    gaps.append(spec["header"])
+            cells[cell] = v
+        elif src == "const":
+            raw_v = spec.get("value", "")
+            if isinstance(raw_v, (int, float)) and not isinstance(raw_v, bool):
+                # 常数是数字就写数字（写成文本会导致门户不认，如申报单价）
+                cells[cell] = raw_v
+            else:
+                tpl = str(raw_v)
+                cells[cell] = tpl.replace("{材质}", mat or "").replace("{材质英文}", mat_en)
+        elif src == "calc":
+            expr = spec["expr"]
+            if expr == "1-{箱数}":
+                cells[cell] = f"1-{fmt_num(cart)}" if cart else ""
+            else:
+                try:
+                    val = eval(expr.format(数量=qty or 0, 箱数=cart or 0, 重量=wt or 0, 长=L or 0, 宽=W or 0, 高=H or 0), {"__builtins__": {}})
+                    cells[cell] = fmt_num(val)
+                except Exception as e:
+                    cells[cell] = ""
+                    notes.append(f"{spec['header']} 算式失败: {e}")
+            if cells[cell] == "":
+                gaps.append(spec["header"])
+        elif src == "storemap":
+            v = store_id(row.get(spec["field"]))   # 唯一真源 scripts/ml-store-ids.json
+            if not v:
+                # 把**原因**带进缺口文案（人看的是这句）：等账号 vs 认不出店铺名，动作完全不同
+                gaps.append(f"卖家ID：{ml_store_ids.missing_reason(pick(row.get(spec['field'])))}")
+            cells[cell] = v
+        elif src == "llm":
+            v = english_name or ""
+            if not v:
+                notes.append(f"{spec['header']} 待 LLM 翻译（中文：{pick(row.get(spec['field']))}）")
+            cells[cell] = v
+        elif src == "image":
+            has = str(row.get(spec["field"], "")).strip() not in ("", "[]")
+            if not has:
+                # 缺口文案与**另一条发票链统一**（用户口径 2026-10-13）：表内没有产品图时，
+                # 提示运营补图。此前这里写的是**表头名**（`产品图片`/`*产品图片 picture`），
+                # 对运营不构成行动指令；表头名仍留在 notes 里便于溯源。
+                gaps.append("缺产品图（运营补）")
+                notes.append(f"{spec['header']}：表内无附件")
+            # 关键：无论有没有图都要**清空**该格 —— 运营版的第 8 行本身写着说明文字，
+            # 不清就会被原样带进导入文件（2026-09-11 读回验证抓到）
+            cells[cell] = "@IMAGE@" if has else ""
+    # 闸门（**唯一判据**）：材质英文三级都解析不出来（或与字典同名不同值 ⇒ 冲突交人）⇒ 阻断。
+    # ⛔ 判据是「**三级都无法解析**」，不是「英文为空 ⇒ 按报关敏感字段拦」——后者是 HS 的口径，
+    #    套到材质英文上就是 2026-10-12 那两条票被误阻的成因。
+    blocking = []
+    if mat_res["缺口"]:
+        gaps.append(mat_res["缺口"])
+        blocking.append(mat_res["缺口"])
+    # 图片锚点：**以映射真源为准**（`imageAnchor`），不要按数据行硬编码。
+    # 2026-09-11 用户实测：锚在数据行 AA8 时飞书里显示位置不对，应为 **AA7**（「*产品图片 picture」表头格，
+    # 也落在冻结窗格 A8 的冻结区内）。回退顺序：imageAnchor → 图片列 spec.anchor → AA<数据行>。
+    anchor = (m.get("imageAnchor")
+              or next((c.get("anchor") for c in m["columns"] if c.get("source") == "image" and c.get("anchor")), None)
+              or f"AA{r}")
+    return {"cells": cells, "notes": notes, "gaps": gaps, "blocking": blocking,
+            "material": mat_res, "image_cell": anchor}
+
+
+def cell_pixel_box(ws, cell_ref, margin=0.96, default_col_width=8.43, default_row_height=15.0):
+    """单元格可用像素尺寸（Excel 换算规则：列宽→像素 = round(width*7)+5；行高 pt→像素 = pt*96/72）。
+
+    2026-09-11 用户实测：产品图**比单元格大、装不下**（原来写死 120px 宽，而 AA 列仅约 96px 宽、
+    第 8 行仅约 53px 高）⇒ 一律按单元格实际尺寸等比缩放。
+    """
+    import re as _re
+    m = _re.match(r"^([A-Z]+)(\d+)$", cell_ref.strip().upper())
+    if not m:
+        raise SystemExit(f"图片锚点格式不合法: {cell_ref!r}")
+    col, row = m.group(1), int(m.group(2))
+    # ⚠️ 必须用 `cd[col]` 取，**不能用 `cd.get(col)`**：openpyxl 的 DimensionHolder 对
+    # 未显式列出但存在于 <cols> 的列（实测 AA 列宽 13），`.get()` 返回 None（会退化成默认 8.43 ⇒ 算小），
+    # 而 `[]` 能拿到真值。取不到或 width 为空时才回落默认值。
+    try:
+        cd = ws.column_dimensions[col]
+        width = cd.width if (cd is not None and cd.width) else None
+    except (KeyError, AttributeError):
+        width = None
+    if width is None:
+        width = default_col_width
+    rd = ws.row_dimensions.get(row)
+    height_pt = rd.height if (rd is not None and rd.height) else default_row_height
+    px_w = int(round(float(width) * 7 + 5))
+    px_h = int(round(float(height_pt) * 96.0 / 72.0))
+    return max(1, int(px_w * margin)), max(1, int(px_h * margin))
+
+
+def fit_image_to_cell(img, ws, cell_ref, margin=0.96):
+    """把图片等比缩放到**装得进单元格**为止（只缩不放，避免糊）。返回尺寸信息。"""
+    box_w, box_h = cell_pixel_box(ws, cell_ref, margin=margin)
+    ow, oh = int(img.width), int(img.height)
+    scale = min(box_w / float(ow), box_h / float(oh), 1.0)
+    if scale < 1.0:
+        img.width = max(1, int(round(ow * scale)))
+        img.height = max(1, int(round(oh * scale)))
+    return {"original": [ow, oh], "box": [box_w, box_h], "size": [int(img.width), int(img.height)]}
+
+
+def fill_xlsx(template, plan, out, image_path=None):
+    import openpyxl
+    if image_path:
+        # 前置检查：openpyxl 插图片需要 Pillow；缺了就明确报错（别抛栈）
+        try:
+            from openpyxl.drawing.image import Image as XLImage  # noqa: F401
+            import PIL  # noqa: F401
+        except ImportError:
+            raise SystemExit("插入产品图需要 Pillow（openpyxl 依赖）：pip install Pillow（本机 venv：~/.dsh/argent/venv/bin/pip install Pillow）")
+    from openpyxl.drawing.image import Image as XLImage
+    wb = openpyxl.load_workbook(template)
+    ws = wb[plan.get("sheet") or "Sheet1"]
+    # ── 清底（用户 2026-09-11 明确）：门户模板**自带的值一律不用**，值全部来自运营版说明/飞书行/算式。
+    # 具体：先把顶部块 8 格（A2..H2）清空（模板里 E2/F2/G2/H2 预填了 CNYTN/USLGB/东莞集货仓/墨西哥），
+    #       再由 plan 写入我们的值（其中港前仓=华南仓，**覆盖**模板自带的东莞集货仓）。
+    # 注：不删 G2 的单元格下拉校验（用户："港前仓不用管校验，就填华南仓"）。
+    # 第 5-6 行是门户模板自带的填写示例、门户要求不删（用户 2026-09-11）⇒ 不动。
+    for col in ("A", "B", "C", "D", "E", "F", "G", "H"):
+        ws[col + "2"] = None
+    for cell, val in plan["cells"].items():
+        if val == "@IMAGE@":
+            # 有图也必须先把该格写空：运营版第 8 行原本是说明文字，不清就会被带进导入文件
+            ws[cell] = ""
+            continue
+        ws[cell] = val
+    # 清掉数据行以下的残留（避免示例/说明残值干扰导入）
+    if image_path and os.path.exists(image_path):
+        img = XLImage(image_path)
+        info = fit_image_to_cell(img, ws, plan["image_cell"])
+        ws.add_image(img, plan["image_cell"])
+        plan["image_size"] = info["size"]
+        plan["image_box"] = info["box"]
+        plan["image_original"] = info["original"]
+    out.parent.mkdir(parents=True, exist_ok=True)
+    wb.save(out)
+    os.chmod(out, 0o600)
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--template", required=True)
+    ap.add_argument("--row", required=True, help="一行飞书数据的 JSON 文件")
+    ap.add_argument("--out", default="")
+    ap.add_argument("--english-name", default="")
+    ap.add_argument("--material-en", default="",
+                    help="材质英文（三级解析的第③级：SKU 字典与小词典都没命中时由会话传入；"
+                         "政策A 允许 LLM 译；命中后会写回 SKU 字典并标 confirmed:false）")
+    ap.add_argument("--image", default="")
+    ap.add_argument("--today", default="")
+    ap.add_argument("--dry-run", action="store_true")
+    a = ap.parse_args()
+    from datetime import date
+    today = a.today or date.today().strftime("%Y-%m-%d")
+    m = load_map()
+    row = json.loads(Path(a.row).read_text(encoding="utf-8"))
+    plan = plan_cells(row, m, today, a.english_name, material_en=a.material_en)
+    summary = {"sheet": m["sheet"], "dataRow": m["dataRow"], "today": today,
+               "cells": plan["cells"], "notes": plan["notes"], "gaps": plan["gaps"],
+               "blocking": plan["blocking"], "material": plan["material"],
+               "image": bool(a.image), "image_cell": plan["image_cell"]}
+    if a.dry_run:
+        if a.image:
+            import openpyxl
+            from openpyxl.drawing.image import Image as XLImage
+            _ws = openpyxl.load_workbook(a.template)[m["sheet"]]
+            _info = fit_image_to_cell(XLImage(a.image), _ws, plan["image_cell"])
+            summary.update({"image_size": _info["size"], "image_box": _info["box"], "image_original": _info["original"]})
+        print(json.dumps(summary, ensure_ascii=False, indent=1))
+        return 0
+    if plan["blocking"]:
+        # 阻断性缺口（材质英文三级未解析 / 冲突）⇒ **不落盘**：宁可不出文件，也别出一张 S 列残缺的票
+        print("❌ 阻断，未生成文件：" + "；".join(plan["blocking"]), file=sys.stderr)
+        return 1
+    if not a.out:
+        print("需要 --out", file=sys.stderr)
+        return 2
+    out = fill_xlsx(a.template, plan, Path(a.out), a.image or None)
+    # ③ 命中 ⇒ 把译文写回 SKU 字典（政策A；confirmed:false）+ 审计留痕。⛔ ①/② 命中一律不写。
+    summary["writeback"] = apply_material_writeback(plan)
+    summary["out"] = str(out)
+    for k in ("image_size", "image_box", "image_original"):
+        if k in plan:
+            summary[k] = plan[k]
+    print(json.dumps(summary, ensure_ascii=False, indent=1))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())