@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/invoice_lip_runner.py.bak-20260922-1710-freready

@@ -0,0 +1,1090 @@
+#!/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()
+DATA = HOME / ".dsh" / "argent"
+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
+
+# ── 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"]
+    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 里出现白名单外的键 ⇒ 直接拒绝执行（响亮失败），
+# 并落一条审计（谁、哪行、写了哪些字段），便于事后逐字段复核。
+WRITE_FIELDS = {"发票状态", "发票文件", "大货标签", "发票错误信息"}
+AUDIT_DIR = pathlib.Path(os.environ.get("ARGENT_DATA_DIR") or (pathlib.Path.home() / ".dsh" / "argent")) / "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_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 lip_upload_attachment(rid, field, path):
+    """上传附件（lark-cli 文件路径仅接受 cwd 相对 → 切到文件目录用文件名）。
+
+    upload-attachment 是追加语义——重复生成会累积重复附件；上传成功后用
+    patch 覆盖字段为单条（file_token 数组），保证字段恒为最新一份。
+    """
+    path = Path(path)
+    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("发票文件"), []))
+        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 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 ""
+
+
+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 = 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] = {"品名英文": 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 = (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 _label_wait_text(n):
+    if n >= LABEL_HUMAN_HINT_AT:
+        return (f"发票已上传；鑫中航暂无该大货订单/标签（已尝试 {n} 次，系统继续自动重试）"
+                f"——请运营确认鑫中航是否已生成该单")
+    return f"发票已上传；鑫中航暂无该大货订单/标签（第 {n} 次尝试，系统每轮自动重试）"
+
+
+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("缺中文材质（运营补）")
+    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": {
+            "品名英文": 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 的解释器（客户机为 /tmp/pw-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] = {"品名英文": 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：漏下载致大货标签字段空）
+        dl_out = _run_stageb(["--download-label", ship])
+        m2 = re.search(r"下载结果: (\S+)", dl_out)
+        label_path = m2.group(1) if m2 else ""
+        if label_path and os.path.exists(label_path):
+            lip_upload_attachment(rid, F_LABEL, label_path)
+            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] 补标签"
+    dl_out = _run_stageb(["--download-label", ship])
+    m = re.search(r"下载结果: (\S+)", dl_out)
+    label_path = m.group(1) if m else ""
+    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)
+    # 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:
+            if not dry:
+                # 文案按动作方区分（我方缺口明确「无需运营操作」）；同内容不重复写表
+                lip_update_if_changed(row, {F_ST: ST_PICK,
+                                            F_ERR: "需处理：" + "；".join(gaps) + gap_hint(gaps)})
+            ours, ops = split_gaps(gaps)
+            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:
+            lip_update([rid], {F_ST: ST_PICK,
+                               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)
+    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("--regenerate-only", action="store_true",
+                    help="按记录重生成发票文件（用于纠正历史错误，如 2026-09-19 的 PO 错写）——"
+                         "**只落本地 xlsx、不写表、不上传门户**；已完成的行也允许")
+    args = ap.parse_args()
+    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()