@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/invoice_lip_runner.py

@@ -0,0 +1,1508 @@
+#!/usr/bin/env python3
+"""lip 表发票流程编排（2026-09-08，两段式全自动 + 异常介入）
+
+复用 invoice_runner.py 已验证逻辑：generate_invoice（鑫中航模板填报）/
+template_addr / clean_hs / fix_drawing_xfrm / 上传鑫中航（阶段4接）。
+lip 专属层：字段映射 / 预检 / 自动补全（hsbianma HS 候选）/ 两段式状态机 /
+成功固化字典。dsh 表路径（invoice_runner）零侵入。
+
+流程（每轮 scan / 定向处理）：
+  FULL状态=已完成 的行：
+    ├ 货代 ≠ 鑫中航-美墨 → 发票状态=跳过 + 发票错误信息=货代未接入/未填
+    ├ 发票状态 ∈ {已完成, 跳过, 失败} → 不动
+    ├ 预检缺口：
+    │   1. SKU 字典缺（品名英文无候选）→ 待勾选+提示（我们补字典）
+    │   2. HS编码 列空：字典已确认 → 字典值回填列 → 继续；
+    │                 字典未确认 → hsbianma 查候选预填列 → 待勾选+提示核 HS
+    │   3. 材质列空 → 待勾选+提示补中文材质
+    │   4. 行字段缺（数量/箱数/重量/尺寸）→ 待勾选+提示
+    │   5. 材质英文：词表命中或用字典候选 → ok；都没有 → 待勾选+提示
+    ├ 字段齐 ∧ (发票状态=未开发票/空 或 待勾选∧发票就绪=true)
+    │   → 生成发票（generate_invoice）→ 回填「发票文件」→ 发票状态=填写中
+    │   （阶段4 接上传→已上传→标签已下载→已完成+固化）
+用法:
+  invoice_lip_runner.py --scan
+  invoice_lip_runner.py --record-id <rid> [--generate-only]
+      --generate-only 语义（2026-09-22 用户口径）：**生成产物并回写「发票相关字段」**
+      （发票状态/发票文件/发票错误信息/大货标签 —— 白名单外的字段一律拒绝写入），
+      只是**不继续**门户上传 → 标签 → 完成那一段。它写表是预期行为，不是缺陷。
+  invoice_lip_runner.py --record-id <rid> --dry-run-pick   # 预演：打印判定不写表
+配置: fulfillment.env（FULL_BASE_TOKEN/FULL_TABLE_ID=lip 表；LARK_PROFILE=主 Bot）
+"""
+import argparse
+import json
+import os
+import pathlib
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+import time
+from pathlib import Path
+
+HOME = Path.home()
+# 数据目录：**唯一判据**在 `scripts/lib/argent_datadir.py`（三级链 `ARGENT_DATA_DIR` →
+# `$DSH_HOME/argent` → `~/.dsh/argent`，与 JS 内核同语义）。此前本文件里**两种口径并存**
+# （模块级硬编码 + 函数内两级链）⇒ 隔离实例一半写隔离目录、一半写生产。
+sys.path.insert(0, str(Path(__file__).resolve().parent / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  —— 勿在别处复制判据
+DATA = Path(resolve_data_dir()['dir'])
+ENV_FILE = DATA / "fulfillment.env"
+
+# 唯一真源：ML 店铺 → 卖家 user_id（2026-09-19；事故说明见 scripts/ml_store_ids.py 顶部）
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import ml_store_ids  # noqa: E402
+
+try:
+    from flow_registry import consumer_doc as _registry_doc      # P2a：base + 业务线合并（唯一真源）
+except Exception:  # noqa: BLE001 —— 半坏机器上退回单文件（升级链路要能跑）
+    def _registry_doc(path=None):
+        _p = pathlib.Path(path) if path else (HERE / "flow-requirements.json")
+        return json.loads(_p.read_text(encoding="utf-8"))
+
+
+# ── env 装载（fulfillment.env：表源/身份/词表路径）──
+def _load_env():
+    if ENV_FILE.exists():
+        for line in ENV_FILE.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, _, v = line.partition("=")
+            os.environ.setdefault(k.strip(), v.strip())
+
+_load_env()
+# lark-cli shebang「/usr/bin/env node」需 node 在 PATH（launchd/ssh 最小 PATH 兼容）
+_EXTRA_PATH = [p for p in (f"{HOME}/.local/bin", f"{HOME}/node/bin",
+                           "/opt/homebrew/bin", "/usr/local/bin")
+               if p not in (os.environ.get("PATH") or "").split(":")]
+if _EXTRA_PATH:
+    os.environ["PATH"] = ":".join(_EXTRA_PATH + [os.environ.get("PATH", "")])
+
+BASE_TOKEN = os.environ.get("FULL_BASE_TOKEN", "")
+TABLE_ID = os.environ.get("FULL_TABLE_ID", "")
+PROFILE = os.environ.get("LARK_PROFILE", "cli_aaf7cafb66b85ccc")
+DICT_FILE = DATA / "lip-sku-dict.json"
+MAT_DICT_FILE = DATA / "lip-material-dict.json"
+OUTPUT_DIR = DATA / "invoice-output-lip"
+LOG_FILE = DATA / "invoice-lip.log"
+SHEET_NAME = "入仓预报"   # 鑫中航模板填报 sheet（与 invoice_runner 对齐）
+XINZHONGHANG_STORE = "鑫中航-美墨"   # lip 货代列匹配值（运营命名含 -美墨 后缀）
+
+# lip 发票字段映射（lip 物理字段集中定义，勿散落）
+F_ST = "发票状态"
+F_READY = "发票就绪"
+F_HS = "HS编码"
+F_MAT = "材质"
+F_FILE = "发票文件"
+F_LABEL = "大货标签"
+F_ERR = "发票错误信息"
+F_FULL_ST = "FULL状态"
+F_SKU = "SKU"
+F_NAME = "产品名称"
+F_QTY = "数量"
+F_BOX = "箱数"
+F_PER_BOX = "装箱数"
+F_WEIGHT = "重量"
+F_LEN = "长"
+F_WID = "宽"
+F_HGT = "高"
+F_ETA = "到货时间"
+F_SHIP = "货件号"
+F_STORE = "店铺"
+F_FREIGHT = "货代公司"
+F_IMG = "产品图"
+F_CHARGE = "是否带电"
+F_MAGNETIC = "是否带磁"
+
+
+def _yes_no(v):
+    """运营填值标准化：lip 单选字段返回 ['是']（数组）——先 _first 取首元素。
+    含 是/带/Y/1 → 是；空/否/0 → 否（默认否兜底）。"""
+    s = _first(v).lower()
+    return "是" if s and s in ("是", "带", "y", "yes", "1", "带电", "带磁") else "否"
+
+
+def lip_download_attachment(rid, file_token, out_dir):
+    """下载 lip 行附件（产品图）到本地，返回本地路径或 None。"""
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out = out_dir / f"{file_token}.img"
+    if out.exists():
+        return out
+    r = subprocess.run(
+        [LARK_CLI, "--profile", PROFILE, "base", "+record-download-attachment",
+         "--base-token", BASE_TOKEN, "--table-id", TABLE_ID,
+         "--record-id", rid, "--file-token", file_token,
+         "--output", out.name, "--format", "json"],
+        capture_output=True, text=True, timeout=120, cwd=str(out_dir))
+    return out if out.exists() else None
+
+ST_NOT = "未开发票"
+ST_PICK = "待勾选"
+ST_GEN = "待生成"
+ST_FILL = "填写中"
+ST_UPLOADED = "已上传"
+ST_LABEL = "标签已下载"
+ST_DONE = "已完成"
+ST_FAIL = "失败"
+ST_SKIP = "跳过"
+
+# ── lark-cli 封装（主 Bot 表读写）──
+def _resolve_lark_cli():
+    import shutil
+    for cand in (shutil.which("lark-cli") or "",
+                 f"{HOME}/.local/bin/lark-cli", f"{HOME}/node/bin/lark-cli",
+                 "/opt/homebrew/bin/lark-cli", "/usr/local/bin/lark-cli"):
+        if cand and os.path.isfile(cand) and os.access(cand, os.X_OK):
+            return cand
+    return "lark-cli"
+
+
+LARK_CLI = _resolve_lark_cli()
+
+
+def _cli(*args, timeout=90):
+    r = subprocess.run([LARK_CLI, "--profile", PROFILE, *args, "--format", "json"],
+                       capture_output=True, text=True, timeout=timeout)
+    try:
+        return json.loads(r.stdout[r.stdout.find("{"):])
+    except Exception:
+        raise RuntimeError(f"lark-cli 调用失败: {r.stderr[:300] or r.stdout[:300]}")
+
+
+def lip_list(filter_json=None):
+    cmd = ["base", "+record-list", "--base-token", BASE_TOKEN,
+           "--table-id", TABLE_ID, "--limit", "200"]   # ⚠️ json 上限就是 200；全表读取请用 lip_list_all()
+    if filter_json:
+        cmd += ["--filter-json", filter_json]
+    d = _cli(*cmd)
+    data = d.get("data", {})
+    fields = data.get("fields", [])
+    rows = data.get("data", [])
+    ids = data.get("record_id_list", [])
+    out = []
+    for i, row in enumerate(rows):
+        f = dict(zip(fields, row))
+        f["_id"] = ids[i] if i < len(ids) else ""
+        out.append(f)
+    return out
+
+
+# 允许写回的字段白名单（2026-09-22 用户口径）
+# 用户明确：**跑流程就是要写 lip 表对应行的发票相关字段**，这是设计而非缺陷。
+# 因此 `--generate-only` 的正确语义是：**生成产物 + 回写发票相关字段**（发票状态/发票文件/
+# 发票错误信息），只是**不继续**门户上传→标签→完成那一段；它写表是预期行为。
+# 守卫要防的是"写到无关字段"：patch 里出现白名单外的键 ⇒ 直接拒绝执行（响亮失败），
+# 并落一条审计（谁、哪行、写了哪些字段），便于事后逐字段复核。
+def _allowed_write_fields() -> set:
+    """写回白名单 = 能力的 `writeFields ∪ stateFields`（来自注册表，单一事实源）。
+
+    ⚠️ 2026-09-22 回归教训：第一版白名单只抄了 `writeFields`（4 个），**漏了 stateFields**，
+    而 `gapPolicy` 明确要求"运营缺口时**取消勾选「发票就绪」**" —— runner 在缺口路径写
+    `{发票状态: 待勾选, 发票就绪: False}`，于是**自己的合法写回被守卫拒绝**（SystemExit），
+    鑫中航连续两票（77635236 / 77642739）因此阻断，执行者只能把那两处写入删掉，
+    结果口径⑤的"取消勾选"动作被**静默移除**（比阻断更危险：错的行会被反复派发）。
+    ⇒ 白名单必须由注册表派生（含 stateFields），而不是手抄；注册表读不到时**兜底也要含
+    「发票就绪」**，绝不静默收窄。
+    """
+    cap = os.environ.get('ARGENT_CAPABILITY') or 'invoice'
+    for cand in (pathlib.Path(__file__).resolve().parent / 'flow-requirements.json',
+                 DATA / 'flow-requirements.json'):
+        try:
+            doc = json.loads(cand.read_text(encoding='utf-8'))
+            c = (doc.get('capabilities') or {}).get(cap) or {}
+            got = set(c.get('writeFields') or []) | set(c.get('stateFields') or [])
+            if got:
+                return got
+        except Exception:
+            continue
+    return {"发票状态", "发票文件", "大货标签", "发票错误信息", "发票就绪"}
+
+
+WRITE_FIELDS = _allowed_write_fields()
+
+# 大货标签的本地目录（stageb 下载落点）。可用 ARGENT_LABEL_DIRS（冒号分隔）覆盖。
+LABEL_DIRS = [pathlib.Path(x) for x in (os.environ.get("ARGENT_LABEL_DIRS") or "").split(":") if x] or \
+             [DATA / "invoice-labels"]
+# --label-from-local / ARGENT_LABEL_FROM_LOCAL=1：允许用本地标签跳过门户**下载**
+# （用户 2026-09-22 授权；**不做**页数=箱数校验 —— 运营暂无此要求）。
+LABEL_FROM_LOCAL = os.environ.get("ARGENT_LABEL_FROM_LOCAL") == "1"
+
+
+def _local_label_path(row) -> pathlib.Path:
+    """本票已有的本地大货标签（`运单-<货件号>.pdf`）→ Path 或 None。
+
+    守卫（2026-09-22 评审结论，只保留"能证明是**本票**产物"的那些）：
+      · 文件名必须精确等于 `运单-<货件号>.pdf`（本票唯一，防同名残留/串票）
+      · 非空且是 PDF（`%PDF-` 魔数）
+      · 目录可通过 ARGENT_LABEL_DIRS 收紧
+    不校验页数：运营明确暂无"页数=箱数"要求（且实测条件不成立）。
+    """
+    ship = _first(row.get(F_SHIP))
+    if not ship:
+        return None
+    name = f"运单-{ship}.pdf"
+    for d in LABEL_DIRS:
+        f = pathlib.Path(d) / name
+        try:
+            if not f.is_file() or f.stat().st_size <= 0:
+                continue
+            if f.read_bytes()[:5] != b"%PDF-":
+                continue
+            return f
+        except OSError:
+            continue
+    return None
+
+
+def _audit_note(rids, note: str) -> None:
+    """审计里记一条"非写表"的事实（例如：标签来源=本地）。"""
+    try:
+        AUDIT_DIR.mkdir(parents=True, exist_ok=True)
+        with (AUDIT_DIR / "audit.jsonl").open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps({"ts": time.strftime("%Y-%m-%dT%H:%M:%S"),
+                                 "flow": os.environ.get("ARGENT_FLOW", "xzh-invoice"),
+                                 "records": list(rids), "fields": [], "ok": True, "note": note},
+                                ensure_ascii=False) + "\n")
+    except Exception:
+        pass
+
+
+def _download_label_or_local(row, ship: str) -> tuple:
+    """取大货标签 → (本地路径 或 '', 输出文本, 是否来自本地)。
+
+    默认走门户下载（`--download-label`）；开了 `--label-from-local`（或环境变量）且本地已有
+    本票标签 ⇒ **跳过下载**直接复用，并在审计里记明来源（只跳过下载；**上传**那一段不受影响）。
+    """
+    if LABEL_FROM_LOCAL:
+        local = _local_label_path(row)
+        if local:
+            log(f"{row.get('_id')} 使用本地标签（跳过门户下载）：{local.name}")
+            _audit_note([row.get("_id")], f"大货标签来源=本地 {local}")
+            return str(local), f"下载结果: {local}（本地复用，未访问门户）", True
+    dl_out = _run_stageb(["--download-label", ship])
+    m = re.search(r"下载结果: (\S+)", dl_out)
+    return (m.group(1) if m else ""), dl_out, False
+AUDIT_DIR = DATA / "invoice-lip-writes"
+
+
+def _audit_write(rids, patch, ok, err=""):
+    try:
+        AUDIT_DIR.mkdir(parents=True, exist_ok=True)
+        rec = {"ts": time.strftime("%Y-%m-%dT%H:%M:%S"), "flow": os.environ.get("ARGENT_FLOW", "xzh-invoice"),
+               "records": list(rids), "fields": sorted(patch.keys()), "ok": bool(ok), "error": err[:200]}
+        with (AUDIT_DIR / "audit.jsonl").open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(rec, ensure_ascii=False) + "\n")
+    except Exception:
+        pass          # 审计失败不影响主流程（不因日志问题阻断业务）
+
+
+def lip_list_all(filter_json: str = "") -> list:
+    """**全表**读取（ndjson，上限 2000）→ 行列表；可选按 filter_json 的 conditions 在客户端过滤。
+
+    为什么单列一个函数（2026-09-23 事故）：`lip_list()` 用的 json 格式 `--limit` **上限 200**，
+    而表有 531 行 ⇒ 任何基于它的扫描都会**静默漏行**（用户指出的"就绪=true ∧ 待执行"6 条
+    就是因为只看了前 200 行而没被发现）。凡"对账/全表扫描"一律用本函数。
+    """
+    import lip_table as _lt
+    if filter_json:
+        try:                                     # 服务端过滤（全表 + 过滤，无 200 行截断）
+            return _lt.all_rows(profile=PROFILE, base=BASE_TOKEN, table=TABLE_ID, filter_json=filter_json)
+        except Exception:
+            pass                                 # 过滤语法不被接受时退回"全表 + 客户端过滤"
+    rows = _lt.all_rows(profile=PROFILE, base=BASE_TOKEN, table=TABLE_ID)
+    if not filter_json:
+        return rows
+    try:
+        doc = json.loads(filter_json)
+    except Exception:
+        return rows
+    conds = doc.get("conditions") or []
+
+    def _val(r, f):
+        v = r.get(f)
+        return v[0] if isinstance(v, list) and v else v
+
+    def _ok(r):
+        for f, op, want in conds:
+            got = _val(r, f)
+            if op in ("==", "is"):
+                if str(got).strip().lower() != str(want).strip().lower():
+                    return False
+            elif op in ("!=", "isNot"):
+                if str(got).strip().lower() == str(want).strip().lower():
+                    return False
+            elif op == "isEmpty":
+                if str(got or "").strip():
+                    return False
+            elif op == "isNotEmpty":
+                if not str(got or "").strip():
+                    return False
+        return True
+
+    return [r for r in rows if _ok(r)]
+
+
+def lip_update(rids, patch):
+    bad = sorted(set(patch.keys()) - WRITE_FIELDS)
+    if bad:
+        _audit_write(rids, patch, False, f"越界字段: {bad}")
+        raise SystemExit(f"❌ 拒绝写回：{bad} 不在发票字段白名单 {sorted(WRITE_FIELDS)} 内"
+                         f"（只允许改发票相关字段，其余字段由运营/其他流程负责）")
+    d = _cli("base", "+record-batch-update", "--base-token", BASE_TOKEN,
+             "--table-id", TABLE_ID,
+             "--json", json.dumps({"record_id_list": rids, "patch": patch}, ensure_ascii=False))
+    _audit_write(rids, patch, d.get("ok", False), "" if d.get("ok") else str(d)[:200])
+    return d.get("ok", False)
+
+
+def _fid(name: str) -> str:
+    """字段名 → 字段 id（运行时解析，见 scripts/lip_table.py；查不到则按名传）。"""
+    try:
+        import sys as _s, pathlib as _pl
+        _s.path.insert(0, str(_pl.Path(__file__).resolve().parent))
+        import lip_table as _lip
+        return _lip.field_id(name, {"flow": "xzh-invoice", "base": BASE_TOKEN,
+                                    "table": TABLE_ID, "profile": PROFILE})
+    except Exception:
+        return name
+
+
+def _attachments_of(row, field) -> list:
+    v = (row or {}).get(field)
+    return [a for a in v if isinstance(a, dict)] if isinstance(v, list) else []
+
+
+def _dedupe_choice(atts: list) -> tuple:
+    """附件去重策略 → (保留的下标 或 None, 原因)。
+
+    · 空/单条          ⇒ (None, '无需处理')
+    · 全部同名         ⇒ (最后一条, '同名重复：保留最新一份')   # 追加语义 ⇒ 新的在后
+    · 名字不一致       ⇒ (None, '存在不同名附件：交人工判断，不擅自丢件')
+    """
+    if not atts or len(atts) < 2:
+        return None, '无需处理'
+    names = {str(a.get('name') or '') for a in atts}
+    if len(names) > 1:
+        return None, '存在不同名附件：交人工判断，不擅自丢件'
+    return len(atts) - 1, '同名重复：保留最新一份'
+
+
+def _same_name_attachments(row, field, name) -> list:
+    return [a for a in _attachments_of(row, field) if str(a.get('name') or '') == name]
+
+
+def _needs_refresh(same: list, path) -> bool:
+    """同名附件是否需要"重传刷新" → True=重传，False=视为已存在（幂等跳过）。
+
+    判据（2026-09-22 角色提的加固点）：门户 PDF 每次导出会**重打时间戳** ⇒ 同名文件的字节数
+    可能不同。「同名+同大小」是弱代理，但**只看名字**又会永远留着旧件 ⇒ 采取折中：
+      · 有一份同名且**能取到大小且与本地不同** ⇒ 重传刷新（不是再挂一份）
+      · 大小一致 / 取不到大小 ⇒ 视为已存在（保守，不重复挂）
+    比内容哈希更轻（哈希要先把远端附件下载回来，每行多一次网络往返；而标签文件名
+    本身已按票号唯一化：运单-<货件号>.pdf ⇒ 同票不会有两个不同标签）。
+    """
+    local = _file_size(path)
+    if local < 0:
+        return False
+    for a in same:
+        asz = a.get('size')
+        if asz in (None, ''):
+            continue
+        try:
+            if int(asz) != local:
+                return True
+        except (TypeError, ValueError):
+            continue
+    return False
+
+
+def _file_size(path) -> int:
+    try:
+        return Path(path).stat().st_size
+    except OSError:
+        return -1
+
+
+def _already_attached(row, field, path) -> bool:
+    """同名（且大小一致时）已挂 ⇒ 视为已上传。**补跑幂等**的关键。
+
+    2026-09-22 实测事故：补跑时 `upload-attachment` 是**追加**语义 ⇒ 大货标签被挂了两份，
+    执行者被迫中止第二票的补跑。判据只用 name（大小能取到就一起比），不猜 file_token。
+    """
+    name = Path(path).name
+    try:
+        size = Path(path).stat().st_size
+    except OSError:
+        size = -1
+    for a in _attachments_of(row, field):
+        if str(a.get('name') or '') != name:
+            continue
+        asz = a.get('size')
+        if size < 0 or asz in (None, ''):
+            return True
+        try:
+            if int(asz) == size:
+                return True
+        except (TypeError, ValueError):
+            return True
+    return False
+
+
+def lip_upload_attachment(rid, field, path, row=None):
+    """上传附件（lark-cli 文件路径仅接受 cwd 相对 → 切到文件目录用文件名）。
+
+    upload-attachment 是**追加**语义——重复生成会累积重复附件。两道防线：
+      ① 上传前：同名（+同大小）已在格内 ⇒ **直接跳过**（补跑幂等，不产生第二份）；
+      ② 上传后：用**该字段自己**的 attachments 归一成单条（原实现写死查「发票文件」，
+         上传标签时查不到自己那条 ⇒ 归一失效、附件越挂越多）。
+    """
+    path = Path(path)
+    same = _same_name_attachments(row, field, path.name)
+    if row is not None and same and not _needs_refresh(same, path):
+        if len(same) > 1:
+            # 已经重复挂上了（2026-09-22 事故遗留）⇒ 就地归一为 1 份。
+            # 只在**全部同名**时才动；名字不同说明是新旧两版，交人工判断，不擅自丢件。
+            lip_update([rid], {field: [{"file_token": same[-1].get("file_token"),
+                                        "name": same[-1].get("name", path.name)}]})
+            log(f"{rid} {field} 有 {len(same)} 份同名附件 ⇒ 已去重为 1 份")
+        else:
+            log(f"{rid} {field} 已有同名附件（{path.name}）⇒ 跳过上传（幂等）")
+        return True
+    if row is not None and same:
+        # 同名但大小不同：门户每次导出会重打时间戳 ⇒ 同一张标签的字节数会变。
+        # 这时**不能**当作"新附件"再挂一份（那是重复），也不能当"已存在"跳过（那会永远留着旧件）；
+        # 正确做法是**重传刷新**，上传后由下面的归一把字段收敛成最新的一份。
+        log(f"{rid} {field} 同名但大小不同（{path.name}）⇒ 重传刷新（门户重打时间戳场景）")
+    r = subprocess.run(
+        [LARK_CLI, "--profile", PROFILE, "base", "+record-upload-attachment",
+         "--base-token", BASE_TOKEN, "--table-id", TABLE_ID,
+         "--record-id", rid, "--field-id", field, "--file", path.name,
+         "--format", "json"],
+        capture_output=True, text=True, timeout=120, cwd=str(path.parent))
+    try:
+        d = json.loads(r.stdout[r.stdout.find("{"):])
+        if not d.get("ok"):
+            return False
+        atts = (d.get("data", {}).get("attachments", {}).get(rid, {})
+                # 2026-09-20（迭代1-残留项）：字段 id 运行时解析（原写死 fldvmra3Rp ⇒ 表相关）
+                .get(_fid(field), []))
+        if atts:
+            last = atts[-1]
+            lip_update([rid], {field: [{"file_token": last.get("file_token"),
+                                        "name": last.get("name", path.name)}]})
+        return True
+    except Exception:
+        return False
+
+
+def _can_uncheck_ready(row: dict) -> tuple:
+    """终态行才允许补正「发票就绪」→ (是否允许, 原因)。
+
+    为什么需要：口径⑤要求完成即取消勾选，但**在最小修复版下完成的终态行**仍留着 true
+    （实测 77635236）。这类行**不能靠补跑修** —— runner 对终态行是**早退跳过**的
+    （`st in (已完成/跳过/失败) ⇒ 跳过`），补跑只会白跑一趟、还可能重复碰门户。
+    正确做法是**单字段补正**（不碰门户、不动产物）；且只允许对终态行做，
+    在飞行的行由流程自己管，绝不能被人为取消勾选。
+    """
+    st = str((row.get(F_ST) or [''])[0] if isinstance(row.get(F_ST), list) else (row.get(F_ST) or '')).strip()
+    if st not in (ST_DONE, ST_SKIP):
+        return False, f'状态={st or "空"} 不是终态（仅允许 已完成/跳过）'
+    if row.get(F_READY) is not True:
+        return False, '「发票就绪」本来就是未勾选，无需补正'
+    return True, '终态行且仍勾选就绪 ⇒ 可补正为未勾选'
+
+
+def uncheck_ready(rid, dash_yes=False) -> str:
+    """把终态行的「发票就绪」补正为未勾选（对齐口径⑤；不碰门户、不改产物）。"""
+    row = _read_row(rid)
+    ok, why = _can_uncheck_ready(row)
+    out = [f"  {rid}：{why}"]
+    if not ok:
+        return "\n".join(out)
+    if dash_yes:
+        lip_update([rid], {F_READY: False})
+        out.append("    ✅ 已写回「发票就绪」= 未勾选")
+    else:
+        out.append("    （dry-run；加 --yes 才写）")
+    return "\n".join(out)
+
+
+def _read_row(rid) -> dict:
+    """按 record id 取一行（字段名 → 值）。与 run_record 同一读取路径。"""
+    d = _cli("base", "+record-get", "--base-token", BASE_TOKEN,
+             "--table-id", TABLE_ID, "--record-id", rid)
+    if not d.get("ok"):
+        raise RuntimeError(f"记录 {rid} 读取失败: {(d.get('error') or {}).get('message', '')}")
+    data = d.get("data", {}) or {}
+    rows = data.get("data") or []
+    if not rows:
+        raise RuntimeError(f"记录 {rid} 无数据")
+    f = dict(zip(data.get("fields") or [], rows[0]))
+    f["_id"] = (data.get("record_id_list") or [rid])[0]
+    return f
+
+
+def dedupe_attachments(rid, dash_yes=False):
+    """把某行的「发票文件」「大货标签」归一为单条（同名重复才动）。
+
+    为什么需要它：附件是**追加**语义，历史补跑可能已留下重复（实测 77635236 的
+    大货标签有两份同名同大小）；这些行状态已是「已完成」⇒ 正常流程会跳过，
+    重复就永远留在表里。本命令是那类行的**修复入口**（默认 dry-run）。
+    """
+    row = _read_row(rid)
+    out = []
+    for field in ("发票文件", "大货标签"):
+        atts = _attachments_of(row, field)
+        keep, why = _dedupe_choice(atts)
+        out.append(f"  {field}: {len(atts)} 份 → {why}")
+        if keep is not None and dash_yes:
+            lip_update([rid], {field: [{"file_token": atts[keep].get("file_token"),
+                                        "name": atts[keep].get("name")}]})
+            out.append("    ✅ 已写回单条")
+    return "\n".join(out)
+
+
+def log(msg):
+    line = f"[{time.strftime('%F %T')}] {msg}"
+    print(line, file=sys.stderr, flush=True)
+    try:
+        with open(LOG_FILE, "a", encoding="utf-8") as f:
+            f.write(line + "\n")
+    except Exception:
+        pass
+
+
+# ── PM 手动接管（2026-09-10）：发票线三处改造 ──
+# 用户决定：① 不再发飞书通知（表格「发票错误信息」即唯一提示面）
+#           ② AI 补录用本地品名词表自愈，不阻塞拾取流程
+#           ③ 大货标签未就绪不再永久失败（落可续跑态「已上传」，每轮只补标签）
+PRODUCT_DICT_FILE = DATA / "lip-product-dict.json"
+# 全新品名实时翻译（PM 2026-09-10）：走 whyshu.com 兼容代理（客户机已有 apiKey），
+# 实测 deepseek-v4-flash + reasoning_effort=none ≈ 1.1s 出结构化 JSON；结果落词表缓存，重复品名零成本。
+LLM_BASE = os.environ.get("ARGENT_LLM_BASE", "") or "https://whyshu.com/api/argent/v1"
+LLM_MODEL = os.environ.get("ARGENT_LLM_MODEL", "") or "deepseek-v4-flash"
+LLM_TIMEOUT = int(os.environ.get("ARGENT_LLM_TIMEOUT", "120"))
+LABEL_RETRY_FILE = DATA / "invoice-lip-label-retry.jsonl"
+
+
+# ── A. 字典自愈：中文品名 → 英文品名（本地词表命中即补字典，本轮继续开票）──
+def load_product_dict():
+    try:
+        return json.loads(PRODUCT_DICT_FILE.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _write_dict_entry(sku, entry):
+    """原子写字典单条（tmp + rename），避免半写坏字典。"""
+    d = load_dict()
+    d[sku] = entry
+    tmp = DATA / ".lip-sku-dict.json.tmp"
+    try:
+        tmp.write_text(json.dumps(d, ensure_ascii=False, indent=2), encoding="utf-8")
+        os.replace(tmp, DATA / "lip-sku-dict.json")
+        return True
+    except Exception as exc:
+        log(f"字典写入失败 {sku}: {exc}")
+        return False
+
+
+def _norm_name(name):
+    """品名规范化（去掉 <br> 等抓取残留与多余空白），用于词表查找。"""
+    name = re.sub(r"<br\s*/?>", "", name or "", flags=re.I)
+    return re.sub(r"\s+", " ", name).strip()
+
+
+def _llm_key():
+    key = os.environ.get("WHYSHU_API_KEY", "")
+    if key:
+        return key
+    try:
+        return json.loads((DATA / "config.json").read_text(encoding="utf-8")).get("apiKey", "")
+    except Exception:
+        return ""
+
+
+# ── 产品英文名称：只留**直译名**（2026-10-13 用户现场纠正）──────────────────────
+# 现象：发票「产品英文名称」被写成 `150mm Digital Caliper (Zinc Alloy)` —— 括号里是材质/颜色/规格。
+# 用户口径：**只直译产品名**；材质另有 `材质中文`/`材质英文` 两列，不该在品名里重复。
+# 成因：① LLM 提示词曾要求"含关键规格/颜色/材质"；② 该值会被固化进字典并被后续复用。
+# ⇒ 在「读字典 / 收 LLM 结果 / 写 xlsx」三处都过一遍（幂等；⛔ 只动**尾部**括号）。
+_PAREN_TAIL_RE = re.compile(r"\s*[（(][^（()）]*[）)]\s*$")
+
+
+def strip_name_parens(name):
+    """去掉**尾部**括号注释（可连续多段）：`X (A) (B)` → `X`；`SSD (Black)` → `SSD`。
+    ⛔ 只动尾部（名称中间的括号保留）；清洗后为空 ⇒ 回退原值（宁可不改，也不把品名清空）。"""
+    s = str(name or "").strip()
+    if not s:
+        return s
+    out = s
+    while True:
+        nxt = _PAREN_TAIL_RE.sub("", out).strip()
+        if not nxt or nxt == out:
+            break
+        out = nxt
+    return out or s
+
+
+def llm_translate_product(name_zh, mat_zh="", hs_hint=""):
+    """中文品名 → 报关用英文品名/材质英文/HS 候选（实时 LLM，失败返回 None、不阻塞流程）。"""
+    name_zh = (name_zh or "").strip()
+    key = _llm_key()
+    if not name_zh or not key:
+        return None
+    prompt = (
+        "你是跨境电商报关资料助手。把中文品名**直译**成申报用英文品名："
+        "只译产品名本身，⛔ 不要带材质/颜色/规格/容量等括号注释（那些另有字段），"
+        "并给出材质英文与 10 位中国海关编码。只输出 JSON，无其他文字：\n"
+        '{"品名英文":"...","材质英文":"...","海关编码":"..."}\n'
+        f"中文品名：{name_zh}"
+        + (f"（材质：{mat_zh}）" if mat_zh else "")
+        + (f"\n参考HS：{hs_hint}" if hs_hint else "")
+    )
+    body = json.dumps({"model": LLM_MODEL, "temperature": 0, "max_tokens": 400,
+                       "reasoning_effort": "none",
+                       "messages": [{"role": "user", "content": prompt}]}).encode("utf-8")
+    req = urllib.request.Request(LLM_BASE.rstrip("/") + "/chat/completions", data=body,
+                                 headers={"Authorization": f"Bearer {key}",
+                                          "Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=LLM_TIMEOUT) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except Exception as exc:
+        log(f"LLM 翻译失败（{name_zh}）：{type(exc).__name__} {str(exc)[:120]}")
+        return None
+    content = ((data.get("choices") or [{}])[0].get("message") or {}).get("content") or ""
+    m = re.search(r"\{.*\}", content, re.S)
+    if not m:
+        log(f"LLM 翻译未返回 JSON（{name_zh}）：{content.strip()[:80]}")
+        return None
+    try:
+        d = json.loads(m.group(0))
+    except json.JSONDecodeError:
+        return None
+    en = strip_name_parens(str(d.get("品名英文") or "").strip())
+    if not en:
+        return None
+    cand = {"品名英文": en,
+            "材质英文": str(d.get("材质英文") or "").strip(),
+            "海关编码": re.sub(r"\D", "", str(d.get("海关编码") or ""))[:10],
+            "_源": "LLM 实时翻译"}
+    log(f"LLM 实时翻译：{name_zh} → {en}（HS候选 {cand['海关编码'] or '-'}）")
+    return cand
+
+
+def cache_product_dict(name_zh, cand):
+    """把翻译结果写入本地品名词表（原子写），后续同名品名零成本命中。"""
+    name_zh = _norm_name(name_zh)
+    if not name_zh or not cand.get("品名英文"):
+        return
+    d = load_product_dict()
+    d[name_zh] = {"品名英文": strip_name_parens(cand["品名英文"]), "海关编码": cand.get("海关编码", ""),
+                  "材质英文": cand.get("材质英文", ""), "confirmed": False,
+                  "来源": "LLM 实时翻译 " + time.strftime("%Y-%m-%d")}
+    tmp = DATA / ".lip-product-dict.json.tmp"
+    try:
+        tmp.write_text(json.dumps(d, ensure_ascii=False, indent=2), encoding="utf-8")
+        os.replace(tmp, PRODUCT_DICT_FILE)
+    except Exception as exc:
+        log(f"词表缓存写入失败（{name_zh}）：{exc}")
+
+
+def heal_dict_from_product(row, sku_dict):
+    """字典缺品名英文 → 用本地中英品名词表自愈（无需等 agent/人）。
+
+    命中：写字典条目（confirmed=False、来源标注）+ 更新内存 dict，返回英文品名；
+    未命中：返回 None（保持缺口文案，下一轮继续试）。
+    """
+    sku = _first(row.get(F_SKU))
+    if not sku or (sku_dict.get(sku) or {}).get("品名英文"):
+        return None
+    name_zh = _norm_name(_first(row.get(F_NAME)))
+    pdict = load_product_dict()
+    cand = pdict.get(name_zh) or {}
+    if not cand:  # 兜底：按规范化键再试一轮
+        cand = next((v for k, v in pdict.items() if _norm_name(k) == name_zh), {})
+    if not (cand.get("品名英文") or "").strip():
+        # 全新品名：实时 LLM 翻译（≈1s），结果落词表缓存
+        cand = llm_translate_product(name_zh, _first(row.get(F_MAT)), _first(row.get(F_HS))) or {}
+        if cand:
+            cache_product_dict(name_zh, cand)
+    en = strip_name_parens((cand.get("品名英文") or "").strip())
+    if not en:
+        return None
+    src = cand.get("_源") or ("LLM 实时翻译" if str(cand.get("来源", "")).startswith("LLM") else "本地品名词表自愈")
+    entry = {
+        "品名英文": en,
+        "海关编码": (cand.get("海关编码") or _first(row.get(F_HS)) or "").strip(),
+        "材质英文": (cand.get("材质英文") or translate_material(_first(row.get(F_MAT))) or "").strip(),
+        "confirmed": False,
+        "来源": f"{src} {time.strftime('%Y-%m-%d')}",
+        "备注": "PM 接管自愈；发票跑通后固化",
+    }
+    if _write_dict_entry(sku, entry):
+        sku_dict[sku] = entry
+        log(f"{row.get('_id', '')} 字典自愈：{sku}（{name_zh}）→ {en}（confirmed=false，跑通后固化）")
+        return en
+    return None
+
+
+# ── B. 不重复写表：值与当前一致时跳过写（减少无谓表写）──
+def lip_update_if_changed(row, patch):
+    rid = row.get("_id", "")
+    changed = {k: v for k, v in patch.items() if _first(row.get(k)) != v}
+    if not changed:
+        return False
+    lip_update([rid], changed)
+    return True
+
+
+# ── C. 大货标签「可续跑」：写表节流 + 失败可恢复 ──
+# 实测（2026-09-10 15:19）：刚上传的发票，鑫中航订单页搜不到该货件（数据行=0）
+# → 大货标签暂不可下载；原实现直接写「失败」而 handle_row 对「失败」一律跳过 ⇒ 永久卡死等人工。
+# 改为：发票状态=已上传（可续跑），每轮只补标签；写表按尝试次数节流（1/5 次，之后每 20 次）。
+LABEL_WRITE_AT = (1, 5)
+LABEL_WRITE_EVERY = 20
+LABEL_HUMAN_HINT_AT = 20
+
+
+def _label_attempt_count(rid):
+    n = 0
+    try:
+        for line in LABEL_RETRY_FILE.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                d = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if d.get("record_id") == rid:
+                n += 1
+    except Exception:
+        n = 0
+    return n
+
+
+def _append_label_attempt(rid, n, detail=""):
+    try:
+        LABEL_RETRY_FILE.parent.mkdir(parents=True, exist_ok=True)
+        with open(LABEL_RETRY_FILE, "a", encoding="utf-8") as f:
+            f.write(json.dumps({
+                "ts": time.strftime("%Y-%m-%d %H:%M:%S"),
+                "record_id": rid, "attempt": n, "detail": (detail or "")[-200:],
+            }, ensure_ascii=False) + "\n")
+    except Exception:
+        pass
+
+
+def _picks_of(spec):
+    """该流程 `source` 下的 `pick` 候选（**变体优先 + 顶层兜底**，与引擎 `_picks_of` 同口径）。"""
+    src = (spec or {}).get("source") or {}
+    variants = src.get("variants") or {}
+    out = [((variants.get(str(src.get("default") or "")) or {}).get("pick") or {})]
+    out += [((v or {}).get("pick") or {}) for v in variants.values()]
+    out.append(src.get("pick") or {})
+    return out
+
+
+def _external_cooldown_min(doc=None, flow=None):
+    """**外部时序**长冷却（分钟）—— 取自**声明面** `…releaseReDispatch.externalTiming.cooldownMin`。
+
+    ⛔ **不写死 120**（那是注册表声明的值，不是代码常量）；读不到/多条声明**不一致** ⇒ 返回 0
+    （文案就不编数字，但**仍然**给出"会自动再试 + 怎么人工接管"两要素）。
+    流程取 `ARGENT_FLOW`（未设 ⇒ 从声明面里找声明了该通道的那些流程；取值一致 ⇒ 用它，
+    不一致 ⇒ 0，⛔ 不猜）。读取链与引擎同源：合并注册表（`flow_registry.consumer_doc()`，
+    可用 `ARGENT_REGISTRY_ROOT` 隔离）。`doc` 可注入（夹具用，⛔ 不改判据）。
+    """
+    try:
+        d = doc if doc is not None else _registry_doc()
+        flows = d.get("flows") or {}
+        fid = flow or os.environ.get("ARGENT_FLOW") or ""
+        if fid:
+            canon_id = (d.get("aliases") or {}).get(fid, fid)
+            cands = [flows.get(canon_id) or flows.get(fid) or {}]
+        else:
+            cands = list(flows.values())
+        vals = set()
+        for spec in cands:
+            for pick in _picks_of(spec):
+                et = ((pick.get("releaseReDispatch") or {}).get("externalTiming") or {})
+                if et.get("enabled") is not False and et.get("cooldownMin"):
+                    vals.add(int(et["cooldownMin"]))
+        return vals.pop() if len(vals) == 1 else 0
+    except Exception:                                          # noqa: BLE001（读不到 ⇒ 不编数字）
+        return 0
+
+
+def _label_wait_text(n, cooldown_min=None, doc=None):
+    """"标签还没生成"的运营可见文案（**外部时序类**，措辞必须与机制一致）。
+
+    2026-10-13（放行额度与上游变化）：这类失败**不占运营放行额度** —— 引擎按 `externalTiming`
+    走独立通道（长冷却 + 独立上限）。旧文案写「系统**每轮**自动重试」是**兑现不了的话**
+    （实测：额度用满后该票再也不会被拾取，运营于是白补产品图 ⇒ 用户报的 BUG）。
+    2026-10-14（本批）：补上运营真正需要的两句 —— **自动再试节奏**（约 N 分钟，N 取自声明面
+    `externalTiming.cooldownMin`，⛔ 不写死）与**人工接管方式**（现在处理完就**取消勾选**
+    「发票就绪」⇒ 系统不再自动拾取）。两要素缺一即判红（回归
+    `scripts/tests/external-timing-ops-copy.test.py`）。
+    ⚠️ 卡片侧同一句见 `scripts/flow_triage.py#external_wait_copy`（那边是 markdown 加粗版；
+    表字段是纯文本 ⇒ 这里不写 `**`）。
+    """
+    n_min = _external_cooldown_min(doc=doc) if cooldown_min is None else int(cooldown_min or 0)
+    cadence = (f"系统将在约 {n_min} 分钟后自动再试；" if n_min > 0 else "系统会在冷却到期后自动再试；")
+    takeover = f"你也可以现在人工处理（处理完取消勾选「{F_READY}」，系统就不再自动拾取）"
+    tail = f"{cadence}{takeover}"
+    if n >= LABEL_HUMAN_HINT_AT:
+        return (f"发票已上传；鑫中航暂无该大货订单/标签（已尝试 {n} 次，不占运营放行额度）"
+                f"——{tail}｜请确认鑫中航是否已生成该单")
+    return f"发票已上传；鑫中航暂无该大货订单/标签（第 {n} 次尝试）——{tail}"
+
+
+def _first(v):
+    if v is None:
+        return ""
+    if isinstance(v, list):
+        return str(v[0]).strip() if v and v[0] is not None else ""
+    return str(v).strip()
+
+
+def _num(v):
+    s = _first(v)
+    try:
+        return float(s) if s else 0.0
+    except ValueError:
+        return 0.0
+
+
+def _num_ok(v):
+    return _num(v) > 0
+
+
+# ── 字典与词表 ──
+def load_dict():
+    if DICT_FILE.exists():
+        return json.loads(DICT_FILE.read_text(encoding="utf-8"))
+    return {}
+
+
+def save_dict(d):
+    DICT_FILE.write_text(json.dumps(d, ensure_ascii=False, indent=1), encoding="utf-8")
+
+
+def load_mat_dict():
+    if MAT_DICT_FILE.exists():
+        return json.loads(MAT_DICT_FILE.read_text(encoding="utf-8"))
+    return {}
+
+
+def translate_material(zh):
+    """中文材质 → 英文（词表）。多材质（含 '/' '、' '+'）分段翻译。"""
+    md = load_mat_dict()
+    zh = str(zh or "").strip()
+    if not zh:
+        return ""
+    parts = re.split(r"[\/、+]+", zh)
+    en = []
+    for p in parts:
+        p = p.strip()
+        if not p:
+            continue
+        if p in md:
+            en.append(md[p])
+        else:
+            return ""  # 未命中整段视为缺（由调用方提示）
+    return ", ".join(en)
+
+
+# ── hsbianma 自动查询（headless，复用批量脚本验证逻辑）──
+def _resolve_browser():
+    """浏览器路径探测：Chrome → Edge（国内环境常用，Chromium 同内核 playwright 兼容）。"""
+    cands = [
+        os.environ.get("INVOICE_BROWSER", ""),
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+    ]
+    for c in cands:
+        if c and os.path.exists(c):
+            return c
+    return ""
+
+
+CHROME = _resolve_browser()
+
+
+def hsbianma_query(name):
+    """按商品名查 hsbianma 返回候选编码列表（10 位）。失败/无结果返回 []。"""
+    if not CHROME:
+        log("浏览器缺失（Chrome/Edge 未安装），HS 自动查询不可用")
+        return []
+    from playwright.sync_api import sync_playwright
+    out = []
+    try:
+        with sync_playwright() as p:
+            b = p.chromium.launch(headless=True, executable_path=CHROME,
+                                  args=["--no-sandbox"])
+            pg = b.new_page()
+            pg.goto("https://www.hsbianma.com/", timeout=20000,
+                    wait_until="domcontentloaded")
+            pg.wait_for_timeout(1500)
+            box = pg.locator("input[type=text], input[placeholder*=搜索], "
+                             "input[placeholder*=编码]").first
+            box.fill(name)
+            box.press("Enter")
+            pg.wait_for_timeout(3500)
+            rows = pg.locator("table tr").all()[:6]
+            for r in rows:
+                cells = [c.strip() for c in r.locator("td").all_inner_texts()]
+                if cells and re.fullmatch(r"\d{8,12}", cells[0]):
+                    out.append(cells[0])
+            b.close()
+    except Exception as exc:
+        log(f"hsbianma 查询失败 {name}: {exc}")
+    return out
+
+
+# ── 预检与自动补全 ──
+def precheck(row, sku_dict):
+    """返回缺口列表 [] 或 [缺项,...]。sku_dict 值：None=字典无 / dict=候选。"""
+    gaps = []
+    sku = _first(row.get(F_SKU))
+    sd = sku_dict.get(sku)
+    if sd is None or not sd.get("品名英文"):
+        if _name_usable(row):
+            gaps.append("SKU字典缺品名英文（待AI补录）")
+        else:
+            # 产品名称=SKU 本身/空 → 属运营待办（用户 2026-09-10 口径），我方不自愈不编造
+            gaps.append(GAP_NEED_NAME)
+    if not _first(row.get(F_HS)):
+        if sd and sd.get("confirmed") and sd.get("海关编码"):
+            pass  # HS 列空但字典已确认 → 由补全步骤回填字典值
+        else:
+            gaps.append("HS编码待预填/核对")
+    if not _first(row.get(F_MAT)):
+        # 缺中文材质 → 运营待办（同族：缺产品图，见下）
+        gaps.append("缺中文材质（运营补）")
+    # 缺产品图 ⇒ **运营待办**（用户口径 2026-10-13：表里没有产品图时必须把缺口写进「发票错误信息」，
+    # 提示运营补图，⛔ 不许默默往下走 —— 现场 79408052 / 79406731 两行就是无图却没有任何提示）。
+    # ⚠️ 本 runner 的图源**只有**本表行内的 `产品图` 附件（见本文件下载函数）；其它 runner 可能有 SKU 主数据兜底，
+    #    那条路径不适用于本链 ⇒ 这里以"行内附件为空"为判据。
+    if not (row.get(F_IMG) or []):
+        gaps.append("缺产品图（运营补）")
+    if not _num_ok(row.get(F_QTY)):
+        gaps.append("缺数量")
+    if not _num_ok(row.get(F_BOX)):
+        gaps.append("缺箱数")
+    if not _num_ok(row.get(F_WEIGHT)):
+        gaps.append("缺重量")
+    if not (_num_ok(row.get(F_LEN)) and _num_ok(row.get(F_WID))
+            and _num_ok(row.get(F_HGT))):
+        gaps.append("缺尺寸")
+    return gaps
+
+
+# ── KB-125：缺口分型（我方动作 / 运营动作）──
+# 我方动作缺口（补字典 / 预填核对 HS）——运营勾「发票就绪」也无法推进，
+# 文案必须区别于运营动作缺口，避免再次出现「勾了就绪无反应」的困惑。
+GAP_NEED_NAME = "缺产品名称（表里填的是 SKU 本身，运营补）"
+
+OUR_GAPS = {
+    "SKU字典缺品名英文（待AI补录）",
+    "HS编码待预填/核对",
+    "HS自动查询无结果，请人工查填",
+}
+
+
+def _name_usable(row):
+    """产品名称是否可用于生成英文品名。
+
+    运营常见填法：留空、直接填 SKU（如 HW-MX-091）、填纯编码 → 均视为「需运营补真实品名」，
+    不做自愈（不编造品名）；只有真实中文/英文品名才走我方字典补录/自愈。
+    """
+    name = _norm_name(_first(row.get(F_NAME)))
+    if not name:
+        return False
+    sku = _norm_name(_first(row.get(F_SKU)))
+    if sku and name.upper().replace(" ", "") == sku.upper().replace(" ", ""):
+        return False
+    # 纯编码形态（无中文、无空格、像型号）：HW-MX-091 / HW-XXX-123-1 等
+    if re.fullmatch(r"[A-Za-z0-9._/-]+", name) and re.search(r"\d", name):
+        return False
+    return True
+
+
+def split_gaps(gaps):
+    """缺口按动作方拆分 → (我方缺口, 运营缺口)。"""
+    ours = [g for g in gaps if g in OUR_GAPS]
+    ops = [g for g in gaps if g not in OUR_GAPS]
+    return ours, ops
+
+
+def gap_hint(gaps):
+    """缺口尾部指引（KB-125 B-1）：我方动作 → 明确「无需运营操作」。"""
+    ours, ops = split_gaps(gaps)
+    if ours and ops:
+        return "（我方补录；运营补齐字段后勾选发票就绪）"
+    if ours:
+        return "（我方补录，无需运营操作）"
+    return "（处理完勾选发票就绪）"
+
+
+def fill_hs_candidate(row, sku_dict):
+    """HS编码 列空时自动补全：字典已确认→回填字典值；未确认→hsbianma 查候选预填。
+    返回 (动作文案, 是否已填候选)。"""
+    sku = _first(row.get(F_SKU))
+    sd = sku_dict.get(sku) or {}
+    name = _first(row.get(F_NAME)) or sku
+    if sd.get("confirmed") and sd.get("海关编码"):
+        lip_update([row["_id"]], {F_HS: sd["海关编码"]})
+        return f"HS已回填字典确认值 {sd['海关编码']}", True
+    cands = hsbianma_query(name.split("-")[0].split("(")[0].strip())
+    if cands:
+        lip_update([row["_id"]], {F_HS: cands[0]})
+        return f"HS候选已预填 {cands[0]}（共{len(cands)}条候选，请核对）", True
+    return "HS自动查询无结果，请人工查填", False
+
+
+# ── 生成发票（组装 record → 复用 invoice_runner.generate_invoice）──
+def generate_for_row(row):
+    import importlib.util
+    spec = importlib.util.spec_from_file_location(
+        "invoice_runner", str(Path(__file__).parent / "invoice_runner.py"))
+    ir = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(ir)
+    mapping = ir.load_mapping()
+    sku = _first(row.get(F_SKU))
+    sd = (load_dict().get(sku) or {})
+    hs = _first(row.get(F_HS)) or (sd.get("海关编码") if sd.get("confirmed") else "")
+    mat_zh = _first(row.get(F_MAT))
+    mat_en = translate_material(mat_zh) or (sd.get("材质英文") or "")
+    # 组装 generate_invoice 的 record dict（对齐 dsh 版消费字段）
+    store = _first(row.get(F_STORE))
+    # ⚠️ 这里**刻意不再读 stores.json 的紫鸟 store_id**：它是另一个 ID 体系
+    # （浏览器店铺 ID ≠ ML 卖家 ID），历史上正是它被当"兜底值"写进发票（见下方事故说明）。
+    # ── PO Number = ML 卖家 user_id（2026-09-19 收敛为唯一真源 + 响亮失败）──────────────
+    # 历史事故：这里曾按 `lip-po-mapping.json`（从未创建）→ 回退 `~/.dsh/argent/stores.json`
+    # 的**紫鸟 store_id**（浏览器店铺 ID，如 27494792824433）。那是另一个 ID 体系，
+    # 写进发票就是错的（应为 ML 卖家 ID，如 2475636269）—— 6 张发票因此写错且无人发现。
+    # 另一个失效源：invoice-mapping.json#storeId 的键是短名 `1店-子账号`，lip 的完整店名
+    # `墨西哥-1店-子账号` 根本匹配不上。
+    # 现在：**只认 scripts/ml-store-ids.json**（键=国家-店号，主/子账号共用同一 ID）；
+    # 解析不到 ⇒ **不发发票**（写「发票错误信息」，交人补配置），**绝不用别的 ID 顶上**。
+    store_ml = ml_store_ids.resolve(store)
+    if not store_ml:
+        # 原因写清楚（用户 2026-09-19 口径：「巴西-1店当前是没有给到账号的，写明原因即可」）：
+        # 这是**已知的等待态**（等运营给账号），不是系统故障 ⇒ 措辞是"陈述+下一步"。
+        msg = (f"{ml_store_ids.missing_reason(store)} ⇒ 本行**暂不自动开发票**"
+               f"（拿到账号 ID 后加入 scripts/ml-store-ids.json 即会自动跑；"
+               f"**不会**用紫鸟 store_id 顶替 PO）")
+        log(f"❌ {msg}")
+        try:
+            if row.get("_id"):
+                lip_update_if_changed(row, {F_ERR: msg})
+        except Exception as exc:
+            log(f"⚠️ 回填「发票错误信息」失败: {exc}")
+        return f"{_first(row.get('_id')) or '(未知记录)'} 缺 ML 卖家 ID（未生成发票）"
+    mapping.setdefault("storeId", {})[store] = store_ml
+
+    # B6/B7 带电/带磁：读 lip「是否带电/是否带磁」列（运营新增，默认否兜底），
+    # 覆盖 defaults 后 generate_invoice 填模板 R6/R7（B6 带电 / B7 带磁）。
+    mapping.setdefault("defaults", {})["带电"] = _yes_no(row.get(F_CHARGE))
+    mapping.setdefault("defaults", {})["带磁"] = _yes_no(row.get(F_MAGNETIC))
+    record = {
+        "货件号": _first(row.get(F_SHIP)),
+        "品名": _first(row.get(F_NAME)),
+        "数量": _first(row.get(F_QTY)),
+        "箱数": _first(row.get(F_BOX)),
+        "店铺名称": store,
+        "国内收货仓库": mapping.get("defaults", {}).get("国内收货仓库", "深圳仓"),
+        "到达时间": _first(row.get(F_ETA)) or "本周",
+        "备注": "",
+        "sku_data": {
+            "品名英文": strip_name_parens(sd.get("品名英文") or ""),
+            "海关编码": hs,
+            "材质中文": mat_zh,
+            "材质英文": mat_en,
+            "重量(kg/箱)": _first(row.get(F_WEIGHT)),
+            "长(cm)": _first(row.get(F_LEN)),
+            "宽(cm)": _first(row.get(F_WID)),
+            "高(cm)": _first(row.get(F_HGT)),
+            "产品图": [],
+        },
+    }
+    tpl = mapping.get("templates", {}).get("鑫中航", "")
+    if not tpl or not os.path.exists(tpl):
+        raise RuntimeError(f"鑫中航模板缺失: {tpl}")
+    import openpyxl
+    wb = openpyxl.load_workbook(tpl)
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    out = OUTPUT_DIR / f"{_first(row.get(F_SHIP))}-发票.xlsx"
+    ir.generate_invoice(record, mapping, wb, out)
+    # 产品图（lip「产品图」列附件）→ 插图（复用 dsh 版锚点逻辑；lip 附件从本表下载）
+    imgs = row.get(F_IMG) or []
+    if isinstance(imgs, list) and imgs and isinstance(imgs[0], dict):
+        ft = str(imgs[0].get("file_token", ""))
+        if ft:
+            local_img = lip_download_attachment(row["_id"], ft, DATA / "invoice-tmp-lip")
+            if local_img:
+                from openpyxl.drawing.image import Image as XLImage
+                from openpyxl.drawing.spreadsheet_drawing import TwoCellAnchor, AnchorMarker
+                wb2 = openpyxl.load_workbook(out)
+                ws2 = wb2[SHEET_NAME]
+                ws2._images.clear()
+                ws2.row_dimensions[22].height = 93
+                xl_img = XLImage(str(local_img))
+                xl_img.anchor = TwoCellAnchor(
+                    editAs="oneCell",
+                    _from=AnchorMarker(col=17, colOff=210185, row=21, rowOff=265430),
+                    to=AnchorMarker(col=17, colOff=1675765, row=21, rowOff=880745),
+                )
+                ws2.add_image(xl_img)
+                wb2.save(str(out))
+                try:
+                    ir.fix_drawing_xfrm(out, ws2, 0, 0, 0, 0, 0)
+                except Exception:
+                    pass
+    return out
+
+
+# ── 主流程 ──
+def _run_stageb(args):
+    """调 invoice_stageb.py（同目录，当前解释器）。返回 stdout（失败时附 stderr 末尾）。
+
+    注意：必须用带 playwright 的解释器（客户机为 ~/.dsh/argent/venv/bin/python3）运行本
+    脚本；KB-125 实测：用系统 python3 跑时 stageb 抛 ModuleNotFoundError → stdout
+    为空 → 下游误判为「标签下载失败」。故此处把 stderr 末尾一并回传（可诊断）。
+    """
+    stageb = str(Path(__file__).parent / "invoice_stageb.py")
+    r = subprocess.run([sys.executable, stageb, *args],
+                       capture_output=True, text=True, timeout=300)
+    out = r.stdout or ""
+    if r.returncode != 0 and (r.stderr or "").strip():
+        tail = (r.stderr or "").strip().splitlines()[-3:]
+        out = (out + "\n" + "\n".join(tail)).strip()
+        log(f"stageb {' '.join(args[:1])} 退出码={r.returncode}: {tail[-1][:200]}")
+    return out
+
+
+def _confirm_dict(sku, hs, mat_en, name_en=None):
+    """发票流程跑通后固化字典（confirmed=true，本次实际使用值）。"""
+    d = load_dict()
+    cur = d.get(sku) or {}
+    d[sku] = {"品名英文": strip_name_parens(name_en or cur.get("品名英文", "")),
+              "海关编码": hs or cur.get("海关编码", ""),
+              "材质英文": mat_en or cur.get("材质英文", ""),
+              "confirmed": True, "来源": "实际跑通固化 " + time.strftime("%Y-%m-%d"),
+              "备注": ""}
+    save_dict(d)
+    log(f"字典固化: {sku} confirmed=true (HS={hs})")
+
+
+def _upload_and_finish(row, out, generate_only=False, dry=False):
+    """上传鑫中航 → 下载大货标签 → 回填 → 已完成 + 固化。返回动作描述。
+
+    KB-125 修复（阻断性）：原先内部调 `_finish_with_label(row, dry=dry)` 但本函数
+    无 dry 形参 → `NameError: name 'dry' is not defined`，导致「新上传成功后」的路径
+    整行处理异常（实测 recvuIaAFow03Z 2026-09-10 15:36）。此处补形参并透传。
+    """
+    rid = row["_id"]
+    sku = _first(row.get(F_SKU))
+    ship = _first(row.get(F_SHIP))
+    # 1) 上传（CLI stdout 含「上传结果」dialogs；重复=鑫中航已有该单=幂等成功）
+    #    弹窗偶发未捕获（15s 等待不足）→ 判定缺失时重试一次再下结论。
+    up_out = _run_stageb(["--upload", str(out)])
+    if ("全部完成" not in up_out and "成功" not in up_out
+            and "重复" not in up_out and "参考单号" not in up_out):
+        log(f"{rid} 上传结果弹窗未捕获，重试一次…")
+        up_out = _run_stageb(["--upload", str(out)])
+    if "参考单号" in up_out and "重复" in up_out:
+        log(f"{rid} 上传: 鑫中航已有该单发票（幂等，视为已存在）")
+        # 已存在也补下载大货标签（2026-09-09：漏下载致大货标签字段空）
+        label_path, dl_out, _from_local = _download_label_or_local(row, ship)
+        if label_path and os.path.exists(label_path):
+            lip_upload_attachment(rid, F_LABEL, label_path, row=row)
+            # 完成即取消勾选「发票就绪」：留 true 会让"已完成"的行继续满足门条件
+            # （门 = FULL状态=已完成 ∧ 发票就绪=true）⇒ 每轮重复派发。口径⑤要求如此。
+            lip_update([rid], {F_ST: ST_DONE, F_READY: False, F_ERR: ""})
+        else:
+            # 标签仍未就绪 → 落可续跑态，下一轮只补标签（不重复生成/上传）
+            n = _label_attempt_count(rid) + 1
+            _append_label_attempt(rid, n, dl_out)
+            lip_update_if_changed(row, {F_ST: ST_UPLOADED, F_ERR: _label_wait_text(n)})
+            log(f"{rid} 已存在（鑫中航有单）但标签未就绪（第 {n} 次）→ 下一轮补")
+            return f"{rid} 已存在但标签未就绪(第{n}次)"
+        _confirm_dict(sku, _first(row.get(F_HS)),
+                      translate_material(_first(row.get(F_MAT))))
+        return f"{rid} 已存在（鑫中航有单）→ 已完成+固化"
+    if "全部完成" not in up_out and "成功" not in up_out and "完成 1/1" not in up_out:
+        lip_update([rid], {F_ST: ST_FAIL, F_ERR: f"上传失败（鑫中航）——请人工检查"})
+        log(f"{rid} 上传失败: {up_out[-300:]}")
+        return f"{rid} 上传失败"
+    log(f"{rid} 上传成功")
+    if generate_only:
+        lip_update([rid], {F_ST: ST_FILL, F_ERR: ""})
+        return f"{rid} 上传成功（generate-only 停在填写中）"
+    # 2) 下载大货标签 → 回填 → 已完成 + 固化（标签未就绪则落可续跑态，不永久失败）
+    return _finish_with_label(row, dry=dry)
+
+
+def _finish_with_label(row, dry=False):
+    """下载大货标签 → 回填「大货标签」→ 已完成 + 固化。
+
+    标签未就绪（实测：刚上传的发票在鑫中航订单页搜不到该货件）→ 发票状态=已上传（可续跑态），
+    每轮自动重试且只补标签；文案按尝试次数节流写入（避免每 5 分钟重复写表）。
+    """
+    rid = row["_id"]
+    sku = _first(row.get(F_SKU))
+    ship = _first(row.get(F_SHIP))
+    if dry:
+        return f"{rid} [dry] 补标签"
+    label_path, dl_out, _from_local = _download_label_or_local(row, ship)
+    if not label_path or not os.path.exists(label_path):
+        n = _label_attempt_count(rid) + 1
+        _append_label_attempt(rid, n, dl_out)
+        if n in LABEL_WRITE_AT or n % LABEL_WRITE_EVERY == 0:
+            lip_update_if_changed(row, {F_ST: ST_UPLOADED, F_ERR: _label_wait_text(n)})
+            log(f"{rid} 标签未就绪（第 {n} 次）→ 已上传态等待下一轮")
+        else:
+            log(f"{rid} 标签未就绪（第 {n} 次）→ 继续等待（不写表）")
+        return f"{rid} 标签未就绪(第{n}次)"
+    lip_upload_attachment(rid, F_LABEL, label_path, row=row)
+    # 3) 回填完成 + 固化（同样取消勾选「发票就绪」，见上）
+    lip_update([rid], {F_ST: ST_DONE, F_READY: False, F_ERR: ""})
+    _confirm_dict(sku, _first(row.get(F_HS)),
+                  translate_material(_first(row.get(F_MAT))))
+    log(f"{rid} 发票流程完成（上传+标签+固化）")
+    return f"{rid} 完成（上传+标签+固化）"
+
+
+def handle_row(row, generate_only=False, dry=False, stats=None):
+    """处理一行。返回动作描述。stats（可选）：缺口计数 {'our':n,'ops':m}（KB-125 B-3）。"""
+    rid = row["_id"]
+    sku = _first(row.get(F_SKU))
+    st = _first(row.get(F_ST))
+    freight = _first(row.get(F_FREIGHT))
+
+    # PM 接管：历史「大货标签下载失败」的失败行视为可续跑（发票已上传，只差标签）
+    if st == ST_FAIL and "大货标签" in (_first(row.get(F_ERR)) or ""):
+        st = ST_UPLOADED
+
+    if st in (ST_DONE, ST_SKIP, ST_FAIL):
+        return f"{rid} 状态={st} 跳过"
+    if freight != XINZHONGHANG_STORE:
+        if st == ST_NOT or st == "":
+            if not dry:
+                lip_update([rid], {F_ST: ST_SKIP,
+                                   F_ERR: f"货代{freight or '空'}未接入发票自动化（首期仅{XINZHONGHANG_STORE}）"})
+            return f"{rid} 货代={freight or '空'} → 跳过"
+        return f"{rid} 货代不符但状态={st} 不动"
+    # 发票已生成/已上传（填写中 / 已上传 / 标签已下载）= 只差大货标签 → 只补标签
+    # （幂等：不重复生成、不重复上传；避免每轮重复出票）
+    if st in (ST_FILL, ST_UPLOADED, ST_LABEL):
+        return _finish_with_label(row, dry=dry)
+    if st == ST_PICK and row.get(F_READY) is not True:
+        # 表格文案即行动指令（用户口径 2026-09-10）：就绪未勾时也保持缺口文案准确
+        # （只刷新文案，不做任何补全/生成；文案不变则不写表）
+        if not dry:
+            gaps0 = precheck(row, load_dict())
+            if gaps0:
+                lip_update_if_changed(row, {F_ERR: "需处理：" + "；".join(gaps0) + gap_hint(gaps0)})
+        return f"{rid} 待勾选未就绪 等待"
+
+    sku_dict = load_dict()
+    gaps = precheck(row, sku_dict)
+    # 字典缺品名英文 → 本地品名词表自愈（命中即补字典并本轮继续，不阻塞拾取）
+    if any(g.startswith("SKU字典缺品名英文") for g in gaps) and not dry and _name_usable(row):
+        if heal_dict_from_product(row, sku_dict):
+            gaps = precheck(row, sku_dict)
+    if gaps:
+        # 能自动补的（HS）先补（dry-run 只报告不查询不写）
+        if "HS编码待预填/核对" in gaps and not dry:
+            act, filled = fill_hs_candidate(row, sku_dict)
+            if filled:
+                gaps.remove("HS编码待预填/核对")
+                log(f"{rid} {act}")
+            else:
+                gaps[gaps.index("HS编码待预填/核对")] = "HS自动查询无结果，请人工查填"
+        elif "HS编码待预填/核对" in gaps and dry:
+            gaps[gaps.index("HS编码待预填/核对")] = "HS编码待预填（dry-run 不查询）"
+        if gaps:
+            ours, ops = split_gaps(gaps)          # 先分类：决定要不要动「发票就绪」
+            if not dry:
+                # 文案按动作方区分（我方缺口明确「无需运营操作」）；同内容不重复写表
+                patch = {F_ST: ST_PICK, F_ERR: "需处理：" + "；".join(gaps) + gap_hint(gaps)}
+                if ops:
+                    # 口径⑤（2026-09-22 用户授权实现）：**运营缺口** ⇒ 取消勾选「发票就绪」，
+                    # 运营补齐后需自己重勾（这就是放行勾的握手语义：不重勾 ⇒ 不会带着缺口被派发）。
+                    # 我方缺口**不动**它 —— 不该让运营为我们的问题重勾一遍。
+                    patch[F_READY] = False
+                lip_update_if_changed(row, patch)
+            if stats is not None:
+                if ours:
+                    stats["our"] = stats.get("our", 0) + 1
+                if ops:
+                    stats["ops"] = stats.get("ops", 0) + 1
+            return f"{rid} 缺口: {gaps}"
+        # HS 补完且无其他缺口 → 落待勾选（HS 候选需运营核）
+        if not dry:
+            # 同属"等运营核"的缺口（gaps 为空但 HS 只是候选）⇒ 同样取消勾选就绪（口径⑤）
+            lip_update([rid], {F_ST: ST_PICK, F_READY: False,
+                               F_ERR: "HS已补候选，请核对HS/材质后勾选发票就绪"})
+        return f"{rid} HS候选待核 → 待勾选"
+
+    # 字段齐：未开发票/空 → 字典已确认直接生成；待勾选+就绪 → 生成
+    sd = sku_dict.get(sku) or {}
+    if st == ST_PICK and row.get(F_READY) is not True:
+        return f"{rid} 待勾选未就绪"
+    if st == ST_PICK:
+        pass  # 就绪已确认，继续生成
+    elif st == ST_NOT or st == "":
+        if not (sd.get("confirmed")):
+            # 字典未确认但字段齐（运营核过 HS/材质+勾就绪才会到这）——若未就绪等待
+            if row.get(F_READY) is not True:
+                return f"{rid} 新品待运营勾就绪"
+        # confirmed 或已就绪 → 生成
+    if dry:
+        return f"{rid} [dry] 可生成"
+    try:
+        out = generate_for_row(row)
+    except Exception as exc:
+        if not dry:
+            lip_update([rid], {F_ST: ST_FAIL, F_ERR: f"生成失败：{exc}"})
+        return f"{rid} 生成失败: {exc}"
+    if not dry:
+        lip_update([rid], {F_ST: ST_FILL, F_ERR: ""})
+        lip_upload_attachment(rid, F_FILE, out, row=row)
+    log(f"{rid} 发票已生成: {out.name}")
+    # generate_only（试点核对）：停在填写中；否则自动继续 上传→标签→完成+固化
+    if not generate_only and not dry:
+        return _upload_and_finish(row, out, generate_only=False)
+    return f"{rid} 生成完成 → 填写中"
+
+
+def scan(generate_only=False, dry=False):
+    rows = lip_list(json.dumps({"logic": "and",
+                                "conditions": [[F_FULL_ST, "==", "已完成"]]}))
+    acted = 0
+    stats = {"our": 0, "ops": 0}   # KB-125 B-3：我方/运营待办计数
+    for row in rows:
+        try:
+            msg = handle_row(row, generate_only=generate_only, dry=dry, stats=stats)
+            if msg and "跳过" not in msg and "等待" not in msg and "不动" not in msg:
+                acted += 1
+            log(msg)
+        except Exception as exc:
+            log(f"{row.get('_id')} 处理异常: {exc}")
+    # KB-125 B-3：汇总行（只统计与提示，不写任何业务字段）
+    log(f"汇总：我方待办 {stats['our']} 行 / 运营待办 {stats['ops']} 行"
+        f"（扫描 {len(rows)} 行，本轮动作 {acted} 行）")
+    return acted
+
+
+def run_record(rid, generate_only=False, dry=False):
+    d = _cli("base", "+record-get", "--base-token", BASE_TOKEN,
+             "--table-id", TABLE_ID, "--record-id", rid)
+    if not d.get("ok"):
+        raise RuntimeError(f"记录 {rid} 读取失败: {d.get('error',{}).get('message','')}")
+    data = d.get("data", {})
+    fields = data.get("fields", [])
+    rows = data.get("data", [])
+    ids = data.get("record_id_list", [])
+    if not rows:
+        raise RuntimeError(f"记录 {rid} 无数据")
+    f = dict(zip(fields, rows[0]))
+    f["_id"] = ids[0] if ids else rid
+    return handle_row(f, generate_only=generate_only, dry=dry)
+
+
+def regenerate(record_id: str) -> int:
+    """按记录重生成发票 xlsx（**只落本地文件**），并核对 PO Number = 真源 ML 卖家 ID。
+
+    为什么需要它（2026-09-19）：6 张发票的 PO 曾静默写成紫鸟 store_id（另一个 ID 体系）。
+    正常的 run_record 对 `发票状态=已完成` 的行直接跳过（终态保护，正确），所以纠正历史
+    产物需要一条**明确只做本地生成**的通道 —— 不写表、不上传门户，避免把已完成的单
+    重新推进门户（那会产生重复发票）。
+    """
+    # 单条直取（不走 lip_list：它默认 limit 200，而表有 500+ 行 ⇒ 靠后的记录会"找不到"；
+    # 另外已完成的行若放行勾已释放，也不在候选筛选里）
+    try:
+        d = _cli("api", "GET",
+                 f"/open-apis/bitable/v1/apps/{BASE_TOKEN}/tables/{TABLE_ID}/records/{record_id}")
+        fields = ((d.get("data") or {}).get("record") or {}).get("fields") or {}
+    except Exception as exc:
+        print(f"❌ 读取记录 {record_id} 失败：{exc}")
+        return 2
+    if not fields:
+        print(f"❌ 未找到记录 {record_id}（或该记录无字段）")
+        return 2
+    row = dict(fields)
+    row["_id"] = record_id
+    store = _first(row.get(F_STORE))
+    want = ml_store_ids.resolve(store)
+    print(f"  记录 {record_id}｜店铺 {store}（键 {ml_store_ids.store_key(store) or '—'}）"
+          f"｜ML 卖家ID = {want or '❌ 未配置'}")
+    if not want:
+        print("  ❌ 真源里没有该店的 ML 卖家 ID ⇒ 拒绝生成（绝不用紫鸟 ID 顶替）")
+        return 2
+    out = generate_for_row(row)
+    if not out:
+        print("  ❌ 生成失败（见上方日志）")
+        return 1
+    print(f"  ✅ 已生成 {out}")
+    try:
+        import openpyxl
+        ws = openpyxl.load_workbook(out)[SHEET_NAME]
+        got = str(ws["B22"].value)
+        okp = got == want
+        print(f"  {'✅' if okp else '❌'} 核对 B22（PO Number）：{got}"
+              f"{'' if okp else f'（期望 {want}）'}")
+        return 0 if okp else 1
+    except Exception as exc:
+        print(f"  ⚠️ 未能自动核对 B22：{exc}")
+        return 0
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--scan", action="store_true")
+    ap.add_argument("--record-id", default="")
+    ap.add_argument("--generate-only", action="store_true",
+                    help="生成后停（不上传/不流转已完成）——试点核对用")
+    ap.add_argument("--dry-run-pick", action="store_true", help="预演：判定只打印不写表")
+    ap.add_argument("--dedupe-attachments", action="store_true",
+                    help="把该行的发票文件/大货标签附件归一到单条（默认 dry-run，配 --yes 才写）")
+    ap.add_argument("--yes", action="store_true", help="真正写回（默认只打印）")
+    ap.add_argument("--label-from-local", action="store_true",
+                    help="本地已有本票大货标签则跳过门户下载（默认关；仅跳过下载，上传不受影响）")
+    ap.add_argument("--uncheck-ready", action="store_true",
+                    help="终态行补正「发票就绪」=未勾选（对齐口径⑤；不碰门户，默认 dry-run）")
+    ap.add_argument("--regenerate-only", action="store_true",
+                    help="按记录重生成发票文件（用于纠正历史错误，如 2026-09-19 的 PO 错写）——"
+                         "**只落本地 xlsx、不写表、不上传门户**；已完成的行也允许")
+    args = ap.parse_args()
+    if getattr(args, "label_from_local", False):
+        globals()["LABEL_FROM_LOCAL"] = True
+    if args.record_id and args.uncheck_ready:
+        print(uncheck_ready(args.record_id, dash_yes=args.yes))
+        return 0
+    if args.record_id and args.dedupe_attachments:
+        print(dedupe_attachments(args.record_id, dash_yes=args.yes))
+        return 0
+    if args.record_id and args.regenerate_only:
+        rc = regenerate(args.record_id)
+        raise SystemExit(rc)
+    if args.record_id:
+        print(run_record(args.record_id, generate_only=args.generate_only,
+                         dry=args.dry_run_pick))
+    elif args.scan:
+        n = scan(generate_only=args.generate_only, dry=args.dry_run_pick)
+        print(f"scan 完成，处理 {n} 行")
+    else:
+        ap.print_help()
+
+
+if __name__ == "__main__":
+    main()