@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/invoice_runner.py

@@ -0,0 +1,675 @@
+#!/usr/bin/env python3
+"""⚠️ **已作废（2026-09-17）—— 不要据本文件的判据改流程**。
+
+用户口径：文鳐与鑫中航**同属发票流程、同一张 lip 表**，开启前提是
+`货代公司=<自家> ∧ FULL状态=已完成 ∧ 发票就绪=true`（本文件原先用的
+「`状态=已完成 ∧ 发票状态=待生成`」+ 旧表 `TJrmbxuIyauNqrsJL9FclLfbnhc/tbl4vDxpCa71YLpe` 口径已废弃）。
+新链路：`flow_triage.py --flow xzh-invoice`（候选）→ 角色按 `scripts/flow-prompts/xzh-invoice.md` 执行
+→ 缺口回填走 `scripts/flow_return_to_ops.py`。保留本文件仅供历史追溯与旧部署回滚。
+"""
+"""Argent 发票填写/上传自动化 — invoice_runner
+M1 阶段 A：根据飞书 FULL任务表生成鑫中航入仓预报发票（openpyxl 填模板）
+M1 阶段 B：本机 Chrome 上传鑫中航 + 下载大货标签（已落地：scripts/invoice_stageb.py；见 docs/ml-invoice-automation.md）
+
+单表方案（2026-08-20）：发票字段挂在 FULL任务 同一行（发票状态/发票文件/大货标签/
+发票错误信息/国内收货仓库），运营只填 FULL任务 一张表；FULL 状态=已完成 且
+发票状态=待生成 的行自动进入发票流程。
+
+用法:
+  invoice_runner.py --test          用内置测试数据生成一张发票（验证模板映射）
+  invoice_runner.py --generate      处理 FULL任务表待开发票的行（阶段 A）
+  invoice_runner.py --record-id X   指定记录生成
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+import shutil
+from pathlib import Path
+
+# KB-090：launchd/cron 最小 PATH 兜底（同 poll-fulfillment.sh L87-90 与 daily-report.mjs
+# resolveLarkCli/LARK_ENV 机制）——本脚本由 poll-invoice.sh（LaunchAgent）调用，launchd
+# 环境 PATH 无 ~/.local/bin（npm 全局 lark-cli 实测位置）→ 裸 spawn lark-cli 报 ENOENT
+# 静默失败（2026-09-03 daily-report cron 同源事故，2026-09-02 poll launchd 事故）。
+# 1) 三链绝对路径解析 lark-cli（PATH → ~/.local/bin → ~/node/bin → /opt/homebrew/bin → /usr/local/bin）
+# 2) 注入 ~/.local/bin + ~/node/bin 到 os.environ["PATH"]（lark-cli shebang 为 /usr/bin/env
+#    node，最小 PATH 下即使绝对路径也会因 env node 找不到而失败；子进程默认继承 os.environ）
+_HOME = str(Path.home())
+
+
+# ── 产品英文名称：只留**直译名**（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 _resolve_lark_cli() -> str:
+    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"  # 最后兜底：依赖 PATH（SSH/交互环境通常可达）
+
+
+LARK_CLI = _resolve_lark_cli()
+# cron 最小 PATH（/usr/bin:/bin…）下 lark-cli shebang「/usr/bin/env node」找不到 node → stdout 空 →
+# json.loads('') JSONDecodeError（2026-09-06 本机 stageB 每 5 分钟失败根因；huangwei 机 node 在 ~/node/bin
+# 命中旧列表，本机 node 在 /opt/homebrew/bin（brew symlink）漏了）。brew/usr/local 一并注入。
+_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", "")])
+
+HOME = Path.home()
+# 数据目录：**唯一判据**在 `scripts/lib/argent_datadir.py`（三级链，与 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'])
+MAPPING_FILE = DATA / "invoice-mapping.json"
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import ml_store_ids  # noqa: E402  （店铺→卖家ID 唯一真源）
+OUTPUT_DIR = DATA / "invoice-output"
+CONFIG_FILE = DATA / "config.json"
+
+# ── 模板「入仓预报」sheet 填写位置（实测解析 2026-08-19）──
+# R2 国内收货仓库*（必填，选项1 下拉：深圳仓/义乌仓/广州仓）
+# R3 客户单号 | R4 服务类型 | R5 报关方式 | R6 带电 | R7 带磁 | R8 备注
+# R11-18 收件人(姓名/公司/地址一/城市/省/邮编/国家/电话) | R19 申报币种
+# R20 箱数 | R21 表头 | R22+ 数据行（18 列）
+DATA_START_ROW = 22
+SHEET_NAME = "入仓预报"
+ADDR_SHEET = "选项2"
+HEADER_COLS = 18
+
+
+def load_mapping():
+    m = json.load(open(MAPPING_FILE))
+    m["output"] = {k: Path(os.path.expanduser(v)) for k, v in m.get("output", {}).items()}
+    return m
+
+
+def load_creds():
+    try:
+        c = json.load(open(CONFIG_FILE))
+        return c.get("xhInvoiceUser", ""), c.get("xhInvoicePass", "")
+    except Exception:
+        return "", ""
+
+
+def norm(v):
+    """飞书字段值规范化：select 单选返回数组，取首元素。"""
+    if isinstance(v, list):
+        return v[0] if v else ""
+    return v
+
+
+def template_addr(mapping, wb, addr_code):
+    """从「选项2」地址库读取收件人信息（按地址库编码）。"""
+    ws = wb[ADDR_SHEET]
+    for r in range(2, ws.max_row + 1):
+        if str(ws.cell(row=r, column=2).value or "").strip() == addr_code:
+            return {
+                "公司": ws.cell(row=r, column=2).value,
+                "城市": ws.cell(row=r, column=3).value,
+                "地区": ws.cell(row=r, column=4).value,
+                "邮编": ws.cell(row=r, column=5).value,
+                "地址": ws.cell(row=r, column=6).value,
+                "电话": ws.cell(row=r, column=7).value,
+                "国家": ws.cell(row=r, column=8).value,
+            }
+    return {}
+
+
+def query_sku_images(sku, mapping):
+    """按 SKU 名称查 SKU 主数据表，返回 (附件列表, record_id)。
+
+    lookup 附件字段带出不可靠（FULL任务 表产品图 lookup 可能未配置/未带出），
+    统一直查 SKU 主数据表。lark-cli --format json 是列式数组（无字段名），
+    markdown 表格有表头 + _record_id 列，专表解析（SKU 主数据表值简单）。
+    """
+    src = mapping.get("skuSource", {})
+    base, table = src.get("base", ""), src.get("table", "")
+    if not base or not table or not sku:
+        return [], ""
+    try:
+        r = subprocess.run(
+            [LARK_CLI, "--profile", "ml-fulfillment", "base", "+record-list", "--base-token", base,
+             "--table-id", table, "--as", "bot", "--format", "markdown"],
+            capture_output=True, text=True, timeout=60)
+        lines = [l for l in (r.stdout or "").splitlines() if l.strip().startswith("|")]
+        if len(lines) < 2:
+            return [], ""
+        headers = [h.strip() for h in lines[0].strip("|").split("|")]
+        for line in lines[2:]:  # 表头后一行是分隔行，跳过
+            cells = [c.strip() for c in line.strip("|").split("|")]
+            if len(cells) != len(headers):
+                continue
+            row = dict(zip(headers, cells))
+            if str(row.get("SKU", "")).strip() == sku:
+                imgs_raw = row.get("产品图", "")
+                try:
+                    imgs = json.loads(imgs_raw) if imgs_raw else []
+                except Exception:
+                    imgs = []
+                return imgs, str(row.get("_record_id", ""))
+    except Exception:
+        pass
+    return [], ""
+
+
+def download_attachment(file_token, record_id, mapping):
+    """下载 SKU 主数据表附件到临时目录，返回本地路径或 None（幂等缓存）。"""
+    src = mapping.get("skuSource", {})
+    base, table = src.get("base", ""), src.get("table", "")
+    if not base or not table or not file_token or not record_id:
+        return None
+    tmp = DATA / "invoice-tmp"
+    tmp.mkdir(parents=True, exist_ok=True)
+    out = tmp / f"{file_token}.img"
+    if out.exists():
+        return out
+    try:
+        subprocess.run(
+            [LARK_CLI, "--profile", "ml-fulfillment", "base", "+record-download-attachment", "--base-token", base,
+             "--table-id", table, "--record-id", record_id, "--file-token", file_token,
+             "--output", f"./{file_token}.img", "--as", "bot"],
+            capture_output=True, text=True, timeout=120, cwd=str(tmp))
+    except Exception:
+        return None
+    return out if out.exists() else None
+
+
+def clean_hs(v):
+    """清洗海关编码：飞书 lookup 可能带出 markdown 链接（[3926909090](url)），提取纯数字。"""
+    s = str(v or "").strip()
+    if not s:
+        return ""
+    m = re.search(r"\[(\d{6,12})\]|(\d{6,12})", s)
+    return m.group(1) or m.group(2) if m else s
+
+
+def fix_drawing_xfrm(xlsx_path, ws, img_w, img_h, off_x, off_y, row_idx):
+    """修复 drawing1.xml：恢复官方模板的 drawing 结构（xdr 单锚点 + 相对路径 rels）。
+
+    两个问题（2026-08-29 实测鑫中航后端导入）：
+    1) 官方模板 drawing1.xml 自带 2 个示例图锚点（R22/R23 各一），openpyxl 保存时
+       可能原样保留模板 drawing（锚点成对残留），同一张产品图显示两次 → 取模板
+       drawing1.xml 并删除第二个锚点，只留 R22 的官方锚点（坐标/结构与后端认可一致）。
+    2) openpyxl 3.1.5 重写的 drawing/rels 使用绝对路径（/xl/media/image1.png），
+       鑫中航后端按相对路径解析 → 导入报「图片对象初始化时错误:[rId1] 图片位置错误」；
+       因此 drawing rels 用模板的相对路径（../media/image1.png），sheet rels 的
+       drawing Target 相对化（../drawings/drawing1.xml）。
+    """
+    import re
+    import zipfile
+    import shutil
+    mapping = load_mapping()
+    tpl_path = mapping["templates"].get("鑫中航", "")
+    tpl_dr = tpl_rels = None
+    if tpl_path and os.path.exists(tpl_path):
+        try:
+            with zipfile.ZipFile(tpl_path) as tz:
+                tpl_dr = tz.read("xl/drawings/drawing1.xml").decode()
+                tpl_rels = tz.read("xl/drawings/_rels/drawing1.xml.rels")
+        except KeyError:
+            tpl_dr = tpl_rels = None
+    if tpl_dr:
+        # 只保留第一个 twoCellAnchor（R22 产品图锚点），删除模板示例残留锚点
+        anchors = re.findall(r"<xdr:twoCellAnchor\b.*?</xdr:twoCellAnchor>", tpl_dr, re.S)
+        if len(anchors) > 1:
+            tpl_dr = tpl_dr.replace("".join(anchors[1:]), "")
+    tmp = xlsx_path.with_name(xlsx_path.name + ".tmp")
+    with zipfile.ZipFile(xlsx_path) as zin, zipfile.ZipFile(tmp, "w", zipfile.ZIP_DEFLATED) as zout:
+        for item in zin.namelist():
+            data = zin.read(item)
+            if item == "xl/drawings/drawing1.xml" and tpl_dr:
+                data = tpl_dr.encode()
+            elif item == "xl/drawings/_rels/drawing1.xml.rels" and tpl_rels:
+                data = tpl_rels
+            elif item.endswith("worksheets/_rels/sheet1.xml.rels"):
+                xml = data.decode()
+                xml = xml.replace('Target="/xl/drawings/drawing1.xml"', 'Target="../drawings/drawing1.xml"')
+                data = xml.encode()
+            zout.writestr(item, data)
+    shutil.move(tmp, xlsx_path)
+
+
+def generate_invoice(record, mapping, wb, out_path):
+    """用一条记录数据填模板 → 另存发票文件。
+    record 字段：货件号/店铺名称/品名/数量/箱数 + SKU 主数据（重量/尺寸/材质/编码/图）
+    """
+    import openpyxl
+    ws = wb[SHEET_NAME]
+    ws._images.clear()  # 清模板自带示例图（官方模板含 2 张示例产品图，避免后端多图解析异常）
+    d = mapping["defaults"]
+    # 2026-09-19：PO（ML 卖家 ID）改走唯一真源（scripts/ml-store-ids.json）。
+    # 本文件已作废，但它是"三份副本"之一（键=短名 '1店-子账号'，lip 完整店名匹配不上）；
+    # 留着副本只会让下一个人再踩一次"匹配不上就静默顶替"。
+    store_id = ml_store_ids.resolve(record.get("店铺名称"))
+
+    # 收件人（地址库）
+    addr = template_addr(mapping, wb, d.get("收件人地址库", "MXRC03"))
+
+    # 基础区：A 列为标题（模板已有），值填 B 列（column=2）
+    ws.cell(row=2, column=2).value = norm(record.get("国内收货仓库")) or d.get("国内收货仓库", "深圳仓")  # 国内收货仓库*（必填）
+    ws.cell(row=3, column=2).value = record.get("货件号", "")          # 客户单号
+    ws.cell(row=4, column=2).value = d.get("服务类型", "美转墨S1")
+    ws.cell(row=5, column=2).value = d.get("报关方式", "买单报关")
+    ws.cell(row=6, column=2).value = d.get("带电", "否")
+    ws.cell(row=7, column=2).value = d.get("带磁", "否")
+    remark = norm(record.get("备注")) or ""
+    if remark:
+        ws.cell(row=8, column=2).value = remark                     # 备注（可选，空则不填）
+    ws.cell(row=11, column=2).value = d.get("收件人姓名") or addr.get("公司", "") or "MXRC03"
+    ws.cell(row=12, column=2).value = addr.get("公司", "")
+    ws.cell(row=13, column=2).value = addr.get("地址", "")
+    ws.cell(row=14, column=2).value = addr.get("城市", "")
+    ws.cell(row=15, column=2).value = addr.get("地区", "")
+    ws.cell(row=16, column=2).value = addr.get("邮编", "")
+    ws.cell(row=17, column=2).value = addr.get("国家", "")
+    ws.cell(row=18, column=2).value = addr.get("电话", "")
+    ws.cell(row=19, column=2).value = d.get("申报币种", "USD")
+    # R20 官方模板为「到达时间*」：飞书 FULL任务 表「到达时间」字段（运营填写），无值默认"本周"
+    ws.cell(row=20, column=2).value = norm(record.get("到达时间")) or "本周"
+
+    # 数据行（R22+，每行=每箱一个商品；箱数重复即多行同箱号）
+    sku = record.get("sku_data", {})
+    boxes = int(record.get("箱数") or 1)
+    qty_per_box = 0
+    try:
+        qty_per_box = int(record.get("数量") or 0) // max(boxes, 1)
+    except Exception:
+        qty_per_box = 0
+
+    row = DATA_START_ROW
+    # 数据行统一行高（模板数据行高 93pt，避免图片溢出/错位）
+    data_row_height = 93
+    # R 列（18）像素换算：列宽 25 字符 ≈ 180px；行高 93pt ≈ 124px
+    r_col_px = int((ws.column_dimensions.get("R").width if ws.column_dimensions.get("R") else 8.43) * 7 + 5)
+    r_row_px = int(data_row_height * 4 / 3)
+    # 一行 = 一个商品（SKU），不按箱数拆行（箱数体现在"货箱编号 1-N / 总箱数"列；
+    # 模板说明：一箱货有多个商品，箱号重复即可——一条 FULL 记录一个 SKU → 一行）
+    ws.row_dimensions[row].height = data_row_height
+    ws.cell(row=row, column=18).value = None  # 清模板 R 列提示文字（如 R22"提取飞书中的图片..."）
+    ws.cell(row=row, column=1).value = f"1-{boxes}"                # 货箱编号：固定前缀"1-" + 箱数（如 1-12）
+    ws.cell(row=row, column=2).value = int(store_id) if str(store_id).isdigit() else store_id  # PO Number（数字）
+    ws.cell(row=row, column=3).value = boxes                        # 总箱数
+    ws.cell(row=row, column=4).value = strip_name_parens(sku.get("品名英文"))
+    ws.cell(row=row, column=5).value = norm(record.get("品名")) or ""
+    hs = clean_hs(sku.get("海关编码"))
+    ws.cell(row=row, column=6).value = int(hs) if str(hs).isdigit() else hs  # 目的国海关编码（数字）
+    ws.cell(row=row, column=7).value = sku.get("材质英文") or ""
+    ws.cell(row=row, column=8).value = sku.get("材质中文") or ""
+    ws.cell(row=row, column=9).value = d.get("用途", "家用")
+    ws.cell(row=row, column=10).value = qty_per_box
+    try:
+        ws.cell(row=row, column=11).value = float(d.get("申报价值USD", "10") or 0)  # 单个申报价值（数字）
+    except Exception:
+        ws.cell(row=row, column=11).value = d.get("申报价值USD", "10")
+
+    def num(v):
+        try:
+            return float(v)
+        except Exception:
+            return v
+
+    ws.cell(row=row, column=12).value = num(sku.get("重量(kg/箱)", ""))
+    ws.cell(row=row, column=13).value = num(sku.get("长(cm)", ""))
+    ws.cell(row=row, column=14).value = num(sku.get("宽(cm)", ""))
+    ws.cell(row=row, column=15).value = num(sku.get("高(cm)", ""))
+    ws.cell(row=row, column=16).value = d.get("brand", "无")
+    ws.cell(row=row, column=17).value = d.get("model", "无")
+    # 列 18 产品图片：SKU 主数据附件 → 下载 → OneCellAnchor 精确锚定 R 列该行
+    # （固定 from 单元格 + ext 像素，不依赖 TwoCellAnchor 的 to 扩散计算）
+    imgs = sku.get("产品图") or []
+    if imgs and sku.get("产品图记录"):
+        ft = imgs[0].get("file_token") if isinstance(imgs[0], dict) else str(imgs[0])
+        local_img = download_attachment(ft, sku.get("产品图记录"), mapping)
+        if local_img:
+            from openpyxl.drawing.image import Image as XLImage
+            from openpyxl.drawing.spreadsheet_drawing import TwoCellAnchor, AnchorMarker
+            # 用原始附件图片（不做 PIL 处理——鑫中航后端对处理过的图片识别异常）
+            xl_img = XLImage(str(local_img))
+            # 锚点完全复用官方模板示例图1（R22 位置，后端认可的坐标）
+            xl_img.anchor = TwoCellAnchor(
+                editAs="oneCell",
+                _from=AnchorMarker(col=17, colOff=210185, row=row - 1, rowOff=265430),
+                to=AnchorMarker(col=17, colOff=1675765, row=row - 1, rowOff=880745),
+            )
+            ws.add_image(xl_img)
+    row += 1
+
+    # 清理旧数据行残留（模板自带示例行 R23 含 B 列 2555555、示例商品等；
+    # 显式清固定范围，不依赖 max_row——模板示例行/历史残留必须全部抹掉）
+    for rr in range(row, DATA_START_ROW + 50):
+        for cc in range(1, HEADER_COLS + 1):
+            ws.cell(row=rr, column=cc).value = None
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    wb.save(str(out_path))
+    # 补图片 xfrm（鑫中航后端要求；无图时跳过）。坐标固定用官方示例图1（R22）
+    try:
+        if imgs:
+            fix_drawing_xfrm(out_path, ws, 0, 0, 0, 0, 0)
+    except Exception:
+        pass
+    return out_path
+
+
+def run_feishu_generate():
+    """处理 FULL任务表「已完成 + 发票状态=待生成」的行：生成发票 → 回写附件/状态。
+
+    单表方案 v2（2026-08-20）：FULL任务 表重建——SKU 为双向关联，品名/编码/材质/重量/
+    尺寸/产品图全部 lookup 自动带出（无 join、无主字段回填），运营只填 数量/箱数/店铺/
+    货代/国内收货仓库/SKU/就绪。"""
+    import openpyxl
+    import subprocess
+
+    import json as _json
+    mapping = load_mapping()
+    template_path = mapping["templates"].get("鑫中航", "")
+    if not template_path or not os.path.exists(template_path):
+        print(f"✗ 模板不存在: {template_path}")
+        return 1
+
+    base_token = mapping.get("fullSource", {}).get("base", "")
+    full_tbl = mapping.get("fullSource", {}).get("table", "")
+    if not full_tbl:
+        print("✗ 未配置 FULL 源表（invoice-mapping.json fullSource.table）")
+        return 1
+
+    # 待开发票任务：FULL 已完成 + 发票状态=待生成
+    out = subprocess.run(
+        [LARK_CLI, "--profile", "ml-fulfillment", "base", "+record-list", "--base-token", base_token, "--table-id", full_tbl,
+         "--filter-json", '{"logic":"and","conditions":[["状态","==","已完成"],["发票状态","==","待生成"]]}',
+         "--as", "bot", "--format", "json", "--limit", "10"],
+        capture_output=True, text=True, timeout=30,
+    ).stdout
+    data = json.loads(out)
+    records = data.get("data", {}).get("data", [])
+    fields = data.get("data", {}).get("fields", [])
+    ids = data.get("data", {}).get("record_id_list", [])
+    if not records:
+        print("无待开发票的已完成货件（状态=已完成 且 发票状态=待生成）")
+        return 0
+    print(f"发现 {len(records)} 条已完成货件待开发票")
+
+    # AI 翻译：英文申报字段（品名英文/材质英文）缺失时自动翻译并回填 SKU 主数据
+    translated = {}
+    try:
+        import sku_translate
+        translated = sku_translate.translate_and_backfill(sku_translate.load_api_key())
+    except Exception as e:
+        print(f"⚠ 自动翻译失败（继续处理）: {e}")
+
+    def mark_fail(rid, reason):
+        upd = _json.dumps({"update_records": {rid: {"发票状态": ["失败"], "发票错误信息": reason}}}, ensure_ascii=False)
+        subprocess.run(
+            [LARK_CLI, "--profile", "ml-fulfillment", "base", "+record-batch-update", "--base-token", base_token,
+             "--table-id", full_tbl, "--json", upd, "--as", "bot", "--format", "json"],
+            capture_output=True, text=True, timeout=30,
+        )
+
+    for i, row in enumerate(records):
+        rec = {k: norm(v) for k, v in zip(fields, row)}
+        rid = str(ids[i]) if i < len(ids) else ""
+        # SKU 关联方案：lookup 字段已自动带出字典数据，直接组装 sku_data（无 join）
+        sku = str(norm(rec.get("SKU名称")) or "").strip()
+        # 产品图：统一直查 SKU 主数据表（lookup 附件带出不可靠），拿附件 + record_id
+        sku_imgs, sku_rid = query_sku_images(sku, mapping)
+        rec["sku_data"] = {
+            "品名英文": strip_name_parens(norm(rec.get("品名英文")) or translated.get((sku, "品名英文"), "")),
+            "海关编码": norm(rec.get("海关编码")),
+            "材质英文": norm(rec.get("材质英文")) or translated.get((sku, "材质英文"), ""),
+            "材质中文": norm(rec.get("材质中文")),
+            "重量(kg/箱)": norm(rec.get("重量(kg/箱)")),
+            "长(cm)": norm(rec.get("长(cm)")),
+            "宽(cm)": norm(rec.get("宽(cm)")),
+            "高(cm)": norm(rec.get("高(cm)")),
+            "产品图": sku_imgs,
+            "产品图记录": sku_rid,
+        }
+        # 防呆校验：lookup 关键字段缺失 → 标记失败（SKU 未选或字典未维护）
+        missing = [k for k in ("海关编码", "材质中文", "重量(kg/箱)", "长(cm)", "宽(cm)", "高(cm)")
+                   if not rec["sku_data"].get(k)]
+        if not sku:
+            missing.insert(0, "SKU")
+        if missing:
+            mark_fail(rid, "SKU 主数据缺: " + ", ".join(missing))
+            print(f"✗ {rec.get('货件号','')}: SKU 主数据缺失（{', '.join(missing)}），已标记失败待补")
+            continue
+        name = str(norm(rec.get("品名")) or "").replace("/", "-").strip() or "发票"
+        out_path = mapping["output"]["invoice"] / f"运单-{rec.get('货件号','')}-{rec.get('箱数','')}-{name}.xlsx"
+        try:
+            wb = openpyxl.load_workbook(template_path)
+            generate_invoice(rec, mapping, wb, out_path)
+            # 回写 FULL 行状态 + 附件
+            upd = _json.dumps({"update_records": {rid: {"发票状态": ["填写中"], "当前步骤": "发票已生成: " + out_path.name}}}, ensure_ascii=False)
+            subprocess.run(
+                [LARK_CLI, "--profile", "ml-fulfillment", "base", "+record-batch-update", "--base-token", base_token,
+                 "--table-id", full_tbl, "--json", upd,
+                 "--as", "bot", "--format", "json"],
+                capture_output=True, text=True, timeout=30,
+            )
+            up = subprocess.run(
+                [LARK_CLI, "--profile", "ml-fulfillment", "base", "+record-upload-attachment", "--base-token", base_token,
+                 "--table-id", full_tbl, "--record-id", rid, "--field-id", "发票文件",
+                 "--file", out_path.name, "--as", "bot", "--format", "json"],
+                capture_output=True, text=True, timeout=60, cwd=str(out_path.parent),
+            )
+            print(f"✓ {rec.get('货件号','')}: 发票已生成并回写 {out_path.name}" + ("" if up.returncode == 0 else "（附件上传失败）"))
+        except Exception as e:
+            print(f"✗ {rec.get('货件号','')}: {e}")
+            mark_fail(rid, str(e)[:100])
+    return 0
+
+
+def run_test():
+    mapping = load_mapping()
+    template_path = mapping["templates"].get("鑫中航", "")
+    if not template_path or not os.path.exists(template_path):
+        print(f"✗ 模板不存在: {template_path}")
+        sys.exit(1)
+    import openpyxl
+    wb = openpyxl.load_workbook(template_path)
+    record = {
+        "货件号": "73699999",
+        "店铺名称": "3店-主账号",
+        "品名": "外卖背包",
+        "数量": 240,
+        "箱数": 12,
+        "国内收货仓库": "深圳仓",
+        "备注": "测试生成",
+        "sku_data": {
+            "品名英文": "Takeout Backpack",
+            "海关编码": "4202929100",
+            "材质中文": "尼龙",
+            "材质英文": "Nylon",
+            "重量(kg/箱)": 4.5,
+            "长(cm)": 60, "宽(cm)": 40, "高(cm)": 30,
+        },
+    }
+    out = OUTPUT_DIR / "运单-73699999-12-外卖背包.xlsx"
+    generate_invoice(record, mapping, wb, out)
+    print(f"✓ 测试发票已生成: {out}")
+    # 回读验证
+    wb2 = openpyxl.load_workbook(out)
+    ws2 = wb2[SHEET_NAME]
+    print("  国内收货仓库:", ws2.cell(row=2, column=2).value)
+    print("  客户单号:", ws2.cell(row=3, column=1).value)
+    print("  收件人公司:", ws2.cell(row=12, column=1).value)
+    print("  箱数:", ws2.cell(row=20, column=1).value)
+    print("  首行数据:", [ws2.cell(row=22, column=c).value for c in (2, 4, 5, 10)])
+
+
+# ── 阶段 B：上传鑫中航 + 下载大货标签 + 飞书状态流转（KB-045）──
+# 状态机：待生成 → 填写中 → 已上传 → 标签已下载 → 已完成；失败 → 失败 + 发票错误信息
+# SOP（用户要求）：上传鑫中航之前必须先回写飞书 FULL任务表「发票文件」字段（顺序固化）
+def run_feishu_stageb(record_id=None, skip_upload=False):
+    """处理 FULL任务表「发票状态=填写中」的行（发票已生成待上传/下载标签）。
+
+    顺序固化（每行）：
+      1) 确认发票文件已生成并回写飞书「发票文件」附件（阶段 A 已做，此处补校验/重写）
+      2) upload_invoice() 上传鑫中航 → 成功回写「已上传」+ 状态字段
+      3) download_label() 按订单号下载大货标签 → 回写「大货标签」附件 → 「标签已下载」→「已完成」
+    失败任一步 → 「失败」+「发票错误信息」。
+    """
+    import openpyxl
+    import subprocess
+
+    import json as _json
+    import invoice_stageb as sb
+    mapping = load_mapping()
+    base_token = mapping.get("fullSource", {}).get("base", "")
+    full_tbl = mapping.get("fullSource", {}).get("table", "")
+    if not base_token or not full_tbl:
+        print("✗ 未配置 FULL 源表（invoice-mapping.json fullSource）")
+        return 1
+
+    def lark_list(filter_json, limit=10):
+        r = subprocess.run(
+            [LARK_CLI, "--profile", "ml-fulfillment", "base", "+record-list", "--base-token", base_token, "--table-id", full_tbl,
+             "--filter-json", filter_json, "--as", "bot", "--format", "json", "--limit", str(limit)],
+            capture_output=True, text=True, timeout=30,
+        )
+        out = (r.stdout or "").strip()
+        # 诊断增强：无 JSON 输出时把 rc/stderr 带进错误（此前裸 JSONDecodeError 无法定位
+        # cron 环境下 env node 失败这类根因）
+        if not out.startswith("{"):
+            raise RuntimeError(
+                f"lark-cli 查询无 JSON 输出（rc={r.returncode}）stderr: {((r.stderr or '').strip() or '（空）')[:300]}"
+            )
+        data = json.loads(out)
+        return (data.get("data", {}).get("data", []),
+                data.get("data", {}).get("fields", []),
+                data.get("data", {}).get("record_id_list", []))
+
+    def lark_update(rid, patch):
+        upd = _json.dumps({"update_records": {rid: patch}}, ensure_ascii=False)
+        subprocess.run(
+            [LARK_CLI, "--profile", "ml-fulfillment", "base", "+record-batch-update", "--base-token", base_token,
+             "--table-id", full_tbl, "--json", upd, "--as", "bot", "--format", "json"],
+            capture_output=True, text=True, timeout=30,
+        )
+
+    def mark_state(rid, state, step=""):
+        patch = {"发票状态": [state]}
+        if step:
+            patch["当前步骤"] = step
+        lark_update(rid, patch)
+
+    def mark_fail(rid, reason):
+        lark_update(rid, {"发票状态": ["失败"], "发票错误信息": reason})
+        print(f"  ✗ 标记失败: {reason}", flush=True)
+
+    # 待上传/下载标签：发票状态=填写中（阶段 A 已生成回写）
+    if record_id:
+        rows, fields, ids = lark_list('{"logic":"and","conditions":[["发票状态","==","填写中"]]}')
+        target = None
+        for i, row in enumerate(rows):
+            if str(ids[i]) == record_id:
+                target = (row, fields, str(ids[i]))
+                break
+        if not target:
+            print(f"✗ 未找到 record_id={record_id}（发票状态=填写中）")
+            return 1
+        rows, fields, ids = [target[0]], target[1], [target[2]]
+    else:
+        rows, fields, ids = lark_list('{"logic":"and","conditions":[["发票状态","==","填写中"]]}')
+    if not rows:
+        print("无待上传/下载标签的发票（发票状态=填写中）")
+        return 0
+    print(f"发现 {len(rows)} 条待阶段 B 的发票")
+
+    for i, row in enumerate(rows):
+        rec = {k: norm(v) for k, v in zip(fields, row)}
+        rid = str(ids[i]) if i < len(ids) else ""
+        order_no = str(norm(rec.get("订单号码")) or "").strip()
+        full_no = str(norm(rec.get("货件号")) or "").strip()
+        if not order_no:
+            mark_fail(rid, "缺订单号码（鑫中航订单号），无法上传/下载标签")
+            continue
+        # 找阶段 A 生成的发票文件（~/.dsh/argent/invoice-output/运单-货件号-*.xlsx）
+        invoice_file = None
+        if full_no:
+            cands = sorted((OUTPUT_DIR / "").glob(f"运单-{full_no}-*.xlsx")) if OUTPUT_DIR.exists() else []
+            if cands:
+                invoice_file = str(cands[-1])
+        if not invoice_file:
+            mark_fail(rid, f"未找到发票文件（invoice-output/运单-{full_no}-*.xlsx）")
+            continue
+        # SOP：上传前必须先回写飞书发票文件字段（顺序固化——即使阶段 A 已回写，这里显式重写保证）
+        print(f"✓ [{full_no}] 发票文件: {invoice_file}", flush=True)
+        try:
+            up = subprocess.run(
+                [LARK_CLI, "--profile", "ml-fulfillment", "base", "+record-upload-attachment", "--base-token", base_token,
+                 "--table-id", full_tbl, "--record-id", rid, "--field-id", "发票文件",
+                 "--file", os.path.basename(invoice_file), "--as", "bot", "--format", "json"],
+                capture_output=True, text=True, timeout=60, cwd=str(OUTPUT_DIR),
+            )
+            print(f"  回写飞书发票文件: {'OK' if up.returncode == 0 else '附件上传失败'}（SOP：先回写再上传）", flush=True)
+        except Exception as e:
+            print(f"  ⚠ 回写发票文件异常（继续上传）: {e}", flush=True)
+        # 上传鑫中航（SOP：已先回写飞书）
+        if skip_upload:
+            print(f"  [--skip-upload] 跳过上传（干跑）", flush=True)
+        else:
+            ok_up = sb.upload_invoice(invoice_file, order_no)
+            if not ok_up:
+                mark_fail(rid, f"鑫中航上传失败（{invoice_file}）")
+                continue
+            mark_state(rid, "已上传", f"已上传鑫中航: {invoice_file}")
+        # 下载大货标签
+        save_name = f"运单-{full_no}-{norm(rec.get('箱数'))}-{norm(rec.get('品名'))}.pdf".replace("/", "-") if full_no else None
+        ok_dl = sb.download_label(order_no, save_name)
+        if not ok_dl:
+            mark_fail(rid, "大货标签下载失败（订单页未就绪/单行未命中/PDF 未捕获）")
+            continue
+        # 回写大货标签附件 + 完成
+        try:
+            subprocess.run(
+                [LARK_CLI, "--profile", "ml-fulfillment", "base", "+record-upload-attachment", "--base-token", base_token,
+                 "--table-id", full_tbl, "--record-id", rid, "--field-id", "大货标签",
+                 "--file", os.path.basename(ok_dl), "--as", "bot", "--format", "json"],
+                capture_output=True, text=True, timeout=60, cwd=str(sb.LABELS_DIR),
+            )
+        except Exception as e:
+            print(f"  ⚠ 回写大货标签异常: {e}", flush=True)
+        mark_state(rid, "已完成", f"标签已下载: {os.path.basename(ok_dl)}")
+        print(f"✓ [{full_no}] 发票流程完成（上传→标签→状态流转）", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    if "--test" in sys.argv:
+        run_test()
+    elif "--stageb" in sys.argv:
+        rid = None
+        if "--record-id" in sys.argv:
+            rid = sys.argv[sys.argv.index("--record-id") + 1]
+        skip = "--skip-upload" in sys.argv
+        sys.exit(run_feishu_stageb(record_id=rid, skip_upload=skip))
+    else:
+        sys.exit(run_feishu_generate())