@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/wenyao_run.py

@@ -0,0 +1,503 @@
+#!/usr/bin/env python3
+"""wenyao_run.py — 上海文鳐发票流程**编排器**（2026-09-11）
+
+把 ①→⑫ 串成带阶段号的单向流水线，供单票/批量调用，并把每阶段结果落成 JSONL 事件
+（`~/.dsh/argent/wenyao-logs/run-<货件号>-<时间>.jsonl`），便于上板/审计。
+
+两种模式
+--------
+· `--shadow`（**影子模式**）：只跑**本地无副作用**的阶段（读飞书行 → 取数 → 填报 → 自检），
+  并把后续会做什么**逐条打印成计划**；**不写飞书、不开浏览器、不导入不导出**。
+  用来把推演结果和真实链路比对，确认无误再切主。
+· `--yes`（真跑）：按阶段顺序执行，包含飞书回写与门户写操作。
+
+阶段
+----
+  P1 路由   读 lip 行，判定货代=上海文鳐，选门户模板
+  P2 取数   汇总填报输入 + 下载 lip 产品图（按需）
+  P3 填报   调 wenyao_fill_template 生成 xlsx（只写第 2、8 行）
+  P4 自检   锚点/装得下/G2/除 2、8 行外逐格一致
+  P5 回写①  发票文件 + 状态「填写中」
+  P6 登录   门户登录态（过期则人工过滑块）
+  P7 查重   按货件号查门户（0 条才继续）
+  P8 导入   导入订单（**对方生产系统写操作**）
+  P9 勾选   查回并勾选该货件号
+  P10 进仓单 导出进仓单（集货仓 - 东莞集货仓），只留本地
+  P11 唛头   导出唛头（异步任务）
+  P12 取件   下载 DDP 包 → 解压 → 按 `运单-<货件号>-<箱数>箱-<中文品名>.pdf` 改名
+  P13 回写②  大货标签
+  P14 收口   发票状态=已完成 + 清过时错误信息 + 释放「发票就绪」放行勾
+
+并发纪律（2026-10-12 事故固化 —— 三条票 `79212271 / 79298694 / 79210359` 同抢同一个标签页）
+--------------------------------------------------------------------------------------
+· **每条跑批一个自己的标签页**：门户模块 `connect()` 默认 `context.new_page()` 新建，
+  并在 `finally` 只关自己那个页（`sess.close()`）；⛔ 用户自己开着的门户页一个都不动。
+  旧实现三条执行者复用**同一个 page** ⇒ 导航/点击互相打断 ⇒ 死循环。
+· **门户阶段串行**：P6→P14 包在门户模块 `portal_lock()`（每门户一把 flock，
+  `<数据目录>/` 下的门户锁文件，有界等待 300s / `WENYAO_PORTAL_LOCK_TIMEOUT`，抢锁每 15s 打印一行）
+  ⇒ 超时**明确失败**（⛔ 绝不无限等待），且锁在**开浏览器之前**拿（超时连页都不开）。
+· **每票自己的下载目录**：`portal-<货件号>/`（在既有下载根目录下），下载行为尽量按 context 绑定，
+  下载后校验 `suggestedFilename` 与包内容归属，不符即报错（⛔ 不静默用错文件）。
+· 开始/结束各打一行：`[门户] 本次标签页=<targetId 前 8 位>｜锁=<获得/等待 Ns>｜票=<货件号>`
+  （与阶段日志**同源**：都走本文件的 `log()`，⛔ 不新造第二套日志）。
+
+用法
+----
+  # 影子模式（不产生任何副作用）
+  python3 scripts/wenyao_run.py --shipment 76637122 \
+      --english-name "42-Piece Professional Makeup Brush and Sponge Cosmetic Bag - Pink" --shadow
+
+  # 真跑
+  python3 scripts/wenyao_run.py --shipment 76637122 --english-name "…" --yes
+
+材质英文（S 列 `{材质}，{材质英文}`）走**三级解析**：① SKU 字典 → ② 通用小词典 →
+③ `--material-en`（会话传入，政策A 允许 LLM 译）。三级都没命中 ⇒ P3 **阻断**（不落盘）并
+指路「请翻译成英文后用 --material-en 重跑」；③ 命中时真跑会把译文写回字典（confirmed:false）。
+⛔ HS 编码那条人工红线**只管 HS**（不预填/不写候选/不自动确认），不适用于材质英文。
+"""
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+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  —— 勿在此复制判据
+ARG = Path(resolve_data_dir()['dir'])
+OUT_DIR = ARG / "wenyao-output"
+DOWN_DIR = ARG / "wenyao-downloads"
+FIX_DIR = ARG / "wenyao-fixtures"
+LOG_DIR = ARG / "wenyao-logs"
+
+# 2026-09-20（迭代1-残留项）：表/身份/字段 id **一律运行时解析**，不再写死。
+# 旧写法（BASE/TABLE/PROFILE + 21 条 fld id）的后果：换客户=改代码；客户另建同名字段的表时
+# id 全不同 ⇒ 写回/上传会打到错的列。解析入口见 scripts/lip_table.py（表走部署 env，字段 id 走
+# `+field-list` 运行时映射）；解析失败**响亮失败**，不猜表。
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import lip_table as _lip  # noqa: E402
+
+_TARGET = _lip.target("wenyao-invoice")
+BASE = _TARGET["base"]
+TABLE = _TARGET["table"]
+PROFILE = _TARGET["profile"]
+
+
+def FIELD_ID_OF(name: str) -> str:
+    """字段名 → 表内字段 id（运行时解析；查不到则原样按名传）。"""
+    return _lip.field_id(name, _TARGET)
+
+
+def log(phase: str, msg: str, **extra) -> None:
+    line = {"at": datetime.now().isoformat(timespec="seconds"), "phase": phase, "msg": msg, **extra}
+    print(f"[wenyao][{phase}] {msg}" + (f"  {json.dumps(extra, ensure_ascii=False)}" if extra else ""))
+    if _LOG is not None:
+        with _LOG.open("a") as f:
+            f.write(json.dumps(line, ensure_ascii=False) + "\n")
+
+
+_LOG = None
+
+
+# ───────────────────────── lip 读写 ─────────────────────────
+
+def _lark(args: list) -> dict:
+    out = subprocess.run(["lark-cli", "--profile", PROFILE, "base", *args, "--as", "bot", "--format", "json"],
+                         capture_output=True, text=True, check=True).stdout
+    j = json.loads(out)
+    if j.get("ok") is False:
+        raise RuntimeError(f"lark-cli: {j.get('error', {}).get('code')} {j.get('error', {}).get('message')}")
+    return j
+
+
+def read_row(record_id: str, names: list, batch: int = 7) -> dict:
+    """按**字段名**分批窄投影读（一次 ≤7 列，避免宽投影错位；按接口回显的 fields 名映射）。"""
+    out: dict = {}
+    for i in range(0, len(names), batch):
+        chunk = names[i:i + batch]
+        args = ["+record-get", "--base-token", BASE, "--table-id", TABLE, "--record-id", record_id]
+        for n in chunk:
+            args += ["--field-id", FIELD_ID_OF(n)]
+        d = _lark(args)["data"]
+        for n, v in zip(d["fields"], d["data"][0]):
+            out[n] = v
+    return out
+
+
+def find_record_id(shipment_no: str) -> str | None:
+    """按货件号找 record_id（只取两列，避免宽投影）。"""
+    out = subprocess.run(["lark-cli", "--profile", PROFILE, "base", "+record-list", "--base-token", BASE,
+                          "--table-id", TABLE, "--as", "bot", "--format", "ndjson", "--limit", "2000",
+                          "--field-id", "货件号"], capture_output=True, text=True, check=True).stdout
+    man = json.loads(out)
+    for line in open(man["record_file"]):
+        if not line.strip().startswith("{"):
+            continue
+        r = json.loads(line)
+        if str(r.get("货件号", "")).strip() == shipment_no:
+            return r["record_id"]
+    return None
+
+
+def pick(v):
+    if isinstance(v, list):
+        return pick(v[0]) if v else ""
+    return v if v is not None else ""
+
+
+# ───────────────────────── 阶段实现 ─────────────────────────
+
+def p1_route(shipment_no: str) -> dict:
+    rid = find_record_id(shipment_no)
+    if not rid:
+        raise SystemExit(f"❌ lip 表里找不到货件号 {shipment_no}")
+    row = read_row(rid, ["货件号", "货代公司", "发票状态", "FULL状态", "国家", "产品名称"])
+    carrier = pick(row.get("货代公司"))
+    status = pick(row.get("发票状态"))
+    log("P1", f"record_id={rid} 货代={carrier} 发票状态={status or '(空)'} FULL={pick(row.get('FULL状态'))}")
+    if carrier != "上海文鳐":
+        raise SystemExit(f"❌ 货代是「{carrier}」，本编排只处理上海文鳐")
+    if status in ("已完成",):
+        log("P1", f"⚠️ 该行已是「{status}」，重跑前请确认", level="warn")
+    return {"record_id": rid, "carrier": carrier, "status": status}
+
+
+def p2_fetch(record_id: str) -> dict:
+    names = ["产品名称", "货件号", "SKU", "店铺", "数量", "箱数", "装箱数",
+             "重量", "长", "宽", "高", "材质", "HS编码", "产品图"]
+    row = read_row(record_id, names)
+    data = {k: pick(v) for k, v in row.items()}
+    img = row.get("产品图")
+    img = img[0] if isinstance(img, list) and img else None
+    log("P2", f"取数完成：{data['产品名称']} / 数量{data['数量']} / 箱数{data['箱数']} / HS {data['HS编码']}"
+              f" / 图片 {'有' if img else '无'}")
+    local_img = None
+    if img:
+        local_img = DOWN_DIR / f"{data['货件号']}-产品图.png"
+        if local_img.exists() and local_img.stat().st_size == int(img.get("size") or 0):
+            log("P2", f"产品图已存在，跳过下载 → {local_img.name}")
+        else:
+            subprocess.run(["lark-cli", "--profile", PROFILE, "api", "GET",
+                            f"/open-apis/drive/v1/medias/{img['file_token']}/download",
+                            "--as", "bot", "--output", f"./{local_img.name}"],
+                           cwd=str(DOWN_DIR), capture_output=True, text=True, check=True)
+            log("P2", f"产品图已下载 → {local_img.name}（{local_img.stat().st_size} B）")
+    # 归一成填报器要的行结构
+    fixture = {"产品名称": data["产品名称"], "货件号": data["货件号"], "SKU": data["SKU"],
+               "店铺": data["店铺"], "数量": int(float(data["数量"])), "箱数": int(float(data["箱数"])),
+               "装箱数": int(float(data["装箱数"])), "重量": float(data["重量"]),
+               "长": float(data["长"]), "宽": float(data["宽"]), "高": float(data["高"]),
+               "材质": data["材质"], "HS编码": data["HS编码"],
+               "产品图": (img or {}).get("file_token", "")}
+    FIX_DIR.mkdir(parents=True, exist_ok=True)
+    fx = FIX_DIR / f"{data['货件号']}.json"
+    fx.write_text(json.dumps(fixture, ensure_ascii=False))
+    return {"fixture": fixture, "fixture_path": str(fx), "image": str(local_img) if local_img else None}
+
+
+def _load_filler():
+    spec = importlib.util.spec_from_file_location("wenyao_fill", ROOT / "scripts" / "wenyao_fill_template.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def p3_fill(fixture_path: str, english_name: str, today: str, image: str | None,
+            material_en: str = "", write_dict: bool = False) -> dict:
+    filler = _load_filler()
+    m = filler.load_map()
+    row = json.loads(Path(fixture_path).read_text())
+    plan = filler.plan_cells(row, m, today, english_name, material_en=material_en)
+    out = OUT_DIR / f"{row['货件号']}-上海文鳐发票-{row['产品名称']}.xlsx"
+    mat = plan["material"]
+    # ── 材质英文：三级解析（① SKU 字典 → ② 小词典 → ③ --material-en）────────────────
+    # ⛔ 闸门判据 = **三级都无法解析**（`plan['gaps']`，文案已指路：请翻译后用 --material-en 重跑），
+    #    **不是**「英文为空 ⇒ 按报关敏感字段拦」——「不预填/不写候选/不自动确认」那条人工红线
+    #    **只管 HS 编码**；把它套到材质英文上正是 2026-10-12 两条票被误阻的成因。
+    log("P3", f"材质英文：{mat['中文'] or '(空)'}，{mat['英文'] or '(空)'}"
+              f"（命中={mat['命中'] or '未命中'}）",
+        **({"来源": mat["来源"]} if mat.get("来源") else {}))
+    for _n in mat["备注"]:
+        log("P3", f"材质英文备注：{_n}")
+    if mat.get("冲突"):
+        log("P3", f"材质英文冲突（未写回，交人）：{mat['冲突']}")
+    # ⚠️ 缺口必须在**写盘之前**拦（2026-09-19 修）：原顺序是先 fill_xlsx 落盘、再 raise，
+    # 于是"缺卖家ID"这种票会在产物目录里留下一张**内容不全的 xlsx** —— 虽然不会被上传，
+    # 但放在那里迟早被人当成成品拿去导入（与本次"错 PO 静默顶替"同一类风险：错了还留在台面上）。
+    if plan["gaps"]:
+        # 冲突的审计要在这里落（写回路径走不到 ⇒ 不记的话交人后无从复核；无冲突时是 no-op）
+        filler.record_material_audit(plan)
+        raise SystemExit(f"❌ 填报存在缺口，**未生成文件**：{plan['gaps']}")
+    filler.fill_xlsx(ARG / "wenyao-downloads" / "跨境电商-下单模板.xlsx",
+                     plan, out, image or None)
+    # ③ 命中（会话传入定音）⇒ 写回 SKU 字典（confirmed:false，政策A）+ 审计留痕。
+    # 影子/预演**不写字典**（保持"零副作用"承诺），只把写回计划报出来。
+    if write_dict:
+        wb = filler.apply_material_writeback(plan)
+    else:
+        planned = mat.get("写回") or {}
+        wb = {"written": False, "动作": "预演：不写字典", "sku": planned.get("sku", ""),
+              "条目": planned.get("条目")}
+        if planned:
+            log("P3", f"材质英文写回计划（真跑 P3 会写字典）：{wb['sku']} → "
+                      f"{(wb['条目'] or {}).get('材质英文')}（confirmed=false）")
+    if wb.get("written"):
+        log("P3", f"材质英文写回字典：{wb['sku']} → {(wb.get('条目') or {}).get('材质英文')}"
+                  f"（confirmed=false；{wb.get('动作')}）", 字典=wb.get("path", ""), 审计=wb.get("审计", ""))
+    log("P3", f"已生成 {out.name}（{out.stat().st_size} B）锚点={plan['image_cell']} 缺口={plan['gaps']}")
+    return {"xlsx": str(out), "gaps": plan["gaps"], "image_cell": plan["image_cell"],
+            "material": {k: v for k, v in mat.items() if k != "字典"}, "writeback": wb}
+
+
+def p4_verify(xlsx: str, template: str) -> dict:
+    import openpyxl
+    a = openpyxl.load_workbook(xlsx)["Sheet1"]
+    b = openpyxl.load_workbook(template)["Sheet1"]
+    diffs = []
+    for r in range(1, max(a.max_row, b.max_row) + 1):
+        if r in (2, 8):
+            continue
+        for c in range(1, max(a.max_column, b.max_column) + 1):
+            if a.cell(r, c).value != b.cell(r, c).value:
+                diffs.append(f"{openpyxl.utils.get_column_letter(c)}{r}")
+    ws = a
+    anchor = None
+    for im in getattr(ws, "_images", []):
+        fr = im.anchor._from
+        anchor = f"{openpyxl.utils.get_column_letter(fr.col + 1)}{fr.row + 1}"
+    # ⚠️ 必须读 drawing XML 的 <ext>：openpyxl 的 im.width/im.height 是**原图像素**，不是显示尺寸
+    import re as _re, zipfile as _zip
+    w = h = 0
+    with _zip.ZipFile(xlsx) as z:
+        xml = z.read("xl/drawings/drawing1.xml").decode()
+    m2 = _re.search(r'<ext cx="(\d+)" cy="(\d+)"', xml)
+    if m2:
+        w, h = round(int(m2.group(1)) / 9525), round(int(m2.group(2)) / 9525)
+    box_w = round(ws.column_dimensions["AA"].width * 7 + 5)
+    box_h = round(ws.row_dimensions[8].height * 96 / 72)
+    res = {"only_rows_2_8_changed": not diffs, "diffs": diffs[:10], "anchor": anchor,
+           "g2": ws["G2"].value, "images": len(getattr(ws, "_images", [])),
+           "image_in_box": (0 < w <= box_w and 0 < h <= box_h)}
+    log("P4", f"自检：只改两行={res['only_rows_2_8_changed']} 差异={len(diffs)} 图={res['images']}张@{anchor} "
+              f"装得下={res['image_in_box']} G2={res['g2']}")
+    if diffs:
+        raise SystemExit(f"❌ 除第 2、8 行外有差异：{diffs[:6]}")
+    return res
+
+
+def _writeback(record_id: str, field: str, file: str, status: str, clear_error: bool,
+               real: bool, clear_ready: bool = False) -> dict:
+    cmd = ["node", str(ROOT / "scripts" / "wenyao-invoice-writeback.mjs"),
+           "--record-id", record_id, "--allow-record", record_id,
+           "--field", field, "--file", file, "--status", status]
+    if clear_error:
+        cmd.append("--clear-error")
+    if clear_ready:
+        # 2026-09-18：释放运营的放行勾（**单向**：只允许 false；勾选权永远归运营）。
+        # 漏这一步的后果：该行长期停在 `FULL状态=已完成 ∧ 发票就绪=true` ＝ 表上看着"还等着跑"；
+        # 且一旦台账那條 done 失效（身份漂移／台账轮转），开启闸门会重新放行 ⇒ 重复开票/重复上传。
+        # 鑫中航 runner 一直有这个动作，文鳐此前漏了（全表 38 条已完成行唯一一条残留即由此而来）。
+        cmd.append("--clear-ready")
+    cmd.append("--yes" if real else "--dry-run")
+    r = subprocess.run(cmd, capture_output=True, text=True)
+    print("\n".join("      " + l for l in r.stdout.strip().splitlines()))
+    return {"rc": r.returncode, "stdout": r.stdout[-1500:]}
+
+
+# ───────────────────────── 主流程 ─────────────────────────
+
+def main() -> int:
+    global _LOG
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--shipment", required=True, help="货件号，如 76637122")
+    ap.add_argument("--english-name", required=True, help="英文品名（LLM 产出，人工/上游提供）")
+    ap.add_argument("--today", default="")
+    ap.add_argument("--material-en", default="",
+                    help="材质英文（三级解析的第③级：SKU 字典与小词典都没命中时由会话传入；"
+                         "政策A 允许 LLM 译，命中后写回字典并标 confirmed=false）")
+    ap.add_argument("--shadow", action="store_true", help="影子模式：不产生任何副作用")
+    ap.add_argument("--yes", action="store_true", help="真跑")
+    ap.add_argument("--from", dest="from_phase", default="P1",
+                    help="从哪个阶段开始（断点续跑），如 --from P12")
+    a = ap.parse_args()
+    real = bool(a.yes) and not a.shadow
+    frm = int(str(a.from_phase).upper().lstrip("P") or 1)
+    if not (a.shadow or a.yes):
+        raise SystemExit("必须显式指定 --shadow（推演）或 --yes（真跑）")
+
+    today = a.today or datetime.now().strftime("%Y-%m-%d")
+    LOG_DIR.mkdir(parents=True, exist_ok=True)
+    _LOG = LOG_DIR / f"run-{a.shipment}-{datetime.now().strftime('%Y%m%d-%H%M%S')}.jsonl"
+    log("P0", f"模式={'影子(shadow)' if a.shadow else '真跑'} 货件号={a.shipment} 模板={today}", log=str(_LOG))
+
+    # ── 本地阶段（影子模式也执行）──
+    r1 = p1_route(a.shipment)
+    r2 = p2_fetch(r1["record_id"])
+    r3 = {"xlsx": str(OUT_DIR / f"{a.shipment}-上海文鳐发票-{r2['fixture']['产品名称']}.xlsx")}
+    if frm <= 4 and not a.shadow:
+        pass
+    if frm <= 3 or a.shadow:
+        # write_dict=真跑：③ 命中时把材质英文写回 SKU 字典（影子/预演只报写回计划，不写）
+        r3 = p3_fill(r2["fixture_path"], a.english_name, today, r2["image"],
+                     material_en=a.material_en, write_dict=real)
+    if frm <= 4 or a.shadow:
+        r4 = p4_verify(r3["xlsx"], str(DOWN_DIR / "跨境电商-下单模板.xlsx"))
+    else:
+        r4 = {"skipped": True}
+    if not Path(r3["xlsx"]).exists():
+        raise SystemExit(f"❌ 找不到填报件 {r3['xlsx']}（--from 续跑需要它已存在）")
+
+    if a.shadow:
+        fx = r2["fixture"]
+        log("SHADOW", "以下是**真跑**会做的动作（现在一条都不执行）：")
+        plan = [
+            ("P5  回写①", f"上传 `{Path(r3['xlsx']).name}` 到 `发票文件`，并置 `发票状态=填写中`"),
+            ("P6  登录  ", "连 CDP 9333 检查登录态；过期需人工过阿里云滑块"),
+            ("P7  查重  ", f"门户按货件号 {a.shipment} 查询，**0 条才继续**（避免重复单）"),
+            ("P8  导入  ", f"导入 {Path(r3['xlsx']).name}（写对方生产系统）"),
+            ("P9  勾选  ", f"查回 {a.shipment} 并勾选该行"),
+            ("P10 进仓单", "导出进仓单 → 集货仓 - 东莞集货仓（HNBD），产物只留本地"),
+            ("P11 唛头  ", "导出唛头（异步任务）"),
+            ("P12 取件  ", f"下载 DDP 包 → 解压 → 改名 `运单-{a.shipment}-{fx['箱数']}箱-{fx['产品名称']}.pdf`"),
+            ("P13 回写②", "上传该 PDF 到 `大货标签`"),
+            ("P14 收口  ", "发票状态=已完成 + 清空 `发票错误信息` + 释放「发票就绪」放行勾"),
+        ]
+        for k, v in plan:
+            print(f"      {k} │ {v}")
+        log("SHADOW", "影子模式结束：仅生成本地文件，未触碰飞书/门户",
+            xlsx=Path(r3["xlsx"]).name, fixture=Path(r2["fixture_path"]).name)
+        return 0
+
+    # ── 写操作阶段（真跑）──
+    if frm <= 5:
+        log("P5", "回写①：发票文件 + 状态=填写中")
+        _writeback(r1["record_id"], "发票文件", r3["xlsx"], "填写中", False, True)
+    else:
+        log("P5", f"跳过（--from P{frm}）")
+
+    sys.path.insert(0, str(ROOT / "scripts"))
+    import wenyao_portal as wp
+
+    # ── 门户阶段（P6→P12）与收口（P13/P14）：**每门户一把有界 flock** ──────────────────────
+    # 粒度 = **本门户**（默认 9333 那个 Chrome profile），⛔ 不是全局锁（不牵连 FULL / 其它流程）。
+    # 锁在**开浏览器之前**拿 ⇒ 超时连页都不开（"不进入门户阶段"）；⛔ 绝不无限等待
+    #   —— 无限等待正是 2026-10-12 三条票（79212271/79298694/79210359）死循环的形态。
+    try:
+        portal_timeout = wp.portal_lock_timeout()
+    except RuntimeError as e:                     # WENYAO_PORTAL_LOCK_TIMEOUT 非法 ⇒ fail-closed
+        log("门户", f"❌ {e}")
+        raise SystemExit(1)
+    try:
+        with wp.portal_lock(site=f"portal.{a.shipment}", timeout=portal_timeout,
+                            reporter=lambda m: log("门户", m)) as waited:
+            final = p6_p14_portal(a, r1, r2, r3, frm, wp, waited)
+    except (wp.PortalLockTimeout, wp.LockError) as e:
+        log("门户", f"❌ {e}")
+        raise SystemExit(1)
+
+    log("DONE", f"全链路完成：{a.shipment}", record_id=r1["record_id"], xlsx=Path(r3["xlsx"]).name,
+        mark=Path(final).name, log=str(_LOG))
+    return 0
+
+
+def _lock_desc(waited: float) -> str:
+    """锁的状态文案（日志口径：`锁=<获得/等待 Ns>`）。"""
+    return "获得" if waited < 0.5 else f"等待 {waited:.0f}s"
+
+
+def p6_p14_portal(a, r1, r2, r3, frm: int, wp, waited: float) -> str:
+    """门户阶段（P6 登录态 → P12 取件改名）+ 回写收口（P13/P14）。返回改名后的唛头 PDF 路径。
+
+    ⚠️ **调用方必须已持有门户锁**（`wp.portal_lock`）—— 本函数不再自己加锁。
+    ⚠️ 本次跑批用**自己的标签页**（`wp.connect` 隔离）与**自己的下载目录**，`finally` 只关自己那个页。
+    """
+    from playwright.sync_api import sync_playwright
+    dl_dir = DOWN_DIR / f"portal-{a.shipment}"     # 本次跑批**自己的**下载目录（下载事件不错配）
+    final = ""
+    with sync_playwright() as p:
+        sess = wp.connect(p)
+        tid = (sess.target_id or "?")[:8]
+        log("门户", f"本次标签页={tid}｜锁={_lock_desc(waited)}｜票={a.shipment}")
+        try:
+            page = sess.page
+            wp.install_hooks(page)
+            scope = wp.set_download_dir(sess.browser, page, dl_dir)
+            log("P6", f"自己的标签页 targetId={tid}｜下载目录={dl_dir.name}｜下载绑定={scope['scope']}")
+
+            st = wp.login_state(page)
+            log("P6", f"登录态：needLogin={st['needLogin']} onList={st['onList']}")
+            if st["needLogin"]:
+                raise SystemExit("❌ 门户未登录（需人工过滑块后再跑）")
+
+            q = wp.query_shipment(page, a.shipment)
+            log("P7", f"查重：共 {q['count']} 条")
+            if q["count"] != 0 and frm <= 7:
+                raise SystemExit(f"❌ 门户已有 {q['count']} 条 {a.shipment}，停止导入以免重复")
+            if q["count"] != 0:
+                log("P7", f"续跑（--from P{frm}）：已有 {q['count']} 条属预期，跳过导入与导出")
+
+            if frm > 8:
+                log("P8", f"跳过（--from P{frm}）")
+                imp = {"ok": True, "text": "(skipped)"}
+            else:
+                imp = wp.import_order(page, r3["xlsx"])
+            log("P8", f"导入结果：{imp['text'] or '(无 toast)'}")
+            if not imp["ok"]:
+                raise SystemExit("❌ 导入未报成功，停止后续")
+
+            if frm > 9:
+                log("P9", f"跳过勾选（--from P{frm}）")
+            else:
+                q2 = wp.query_shipment(page, a.shipment)
+                log("P9", f"查回：共 {q2['count']} 条 → {q2['rows'][0][:70] if q2['rows'] else '(无)'}")
+                sel = wp.select_shipment(page, a.shipment)
+                log("P9", f"勾选：{sel['summary']}")
+                if not sel["selected"]:
+                    raise SystemExit("❌ 未勾选成功")
+
+            rc = {"url": None} if frm > 10 else wp.export_receipt(page)
+            log("P10", f"进仓单地址：{'已生成' if rc['url'] else '未捕获'}", url=(rc["url"] or "")[:80])
+
+            mk = {"ok": True, "text": "(skipped)"} if frm > 11 else wp.export_marks(page)
+            log("P11", f"唛头导出：{mk['text']}")
+            if not mk["ok"]:
+                raise SystemExit("❌ 导出唛头未报成功")
+
+            # ⛔ 归属校验：下载文件名/包内容与本票不符 ⇒ 报错（绝不静默用错文件）
+            dl = wp.download_latest_ddp(page, dl_dir, expect_shipment=a.shipment)
+            log("P12", f"已下载 {dl['name']}（{dl['size']} B）",
+                归属=("文件名命中" if dl["owned"]["checked"] else f"包内容命中 {dl['inner'][:1]}"))
+            files = wp.unzip_marks(dl["path"], DOWN_DIR / f"ddp-{a.shipment}")
+            pdfs = [f for f in files if f.lower().endswith(".pdf")]
+            if not pdfs:
+                raise SystemExit(f"❌ DDP 包里没有 PDF：{files}")
+            final = wp.rename_mark(pdfs[0], a.shipment, r2["fixture"]["箱数"], r2["fixture"]["产品名称"])
+            log("P12", f"改名完成 → {Path(final).name}")
+        finally:
+            sess.close()          # ⛔ 只关自己这个页；别人/用户的页一个都不动
+            log("门户", f"本次标签页={tid}｜锁=释放（本次等待 {waited:.0f}s）｜票={a.shipment}")
+
+    if frm <= 13:
+        log("P13", "回写②：大货标签")
+        _writeback(r1["record_id"], "大货标签", final, "填写中", False, True)
+    else:
+        log("P13", f"跳过（--from P{frm}）")
+
+    if frm <= 14:
+        log("P14", "收口：发票状态=已完成 + 清空错误信息 + 释放「发票就绪」放行勾")
+        _writeback(r1["record_id"], "大货标签", final, "已完成", True, True, clear_ready=True)
+    else:
+        log("P14", f"跳过（--from P{frm}）")
+    return final
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/engine/scripts/wenyao_shadow_diff.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""文鳐「影子模式」对比器 —— 判断新票的影子产物能否**放行切主**。
+
+## 为什么需要
+
+门户 `my.ffl-tech.com` 是对方**生产系统**，登录/导入/导出都会留真实痕迹；生产 lip 表更不能试错。
+所以每票先跑 `wenyao_run.py --shadow`（只跑本地无副作用阶段）产出 xlsx，
+再与**已验收通过的票**（黄金样本）逐格比对：
+**只有"随行变化"的列允许不同，其余任何差异都说明模板/结构被动过 ⇒ 拒绝切主。**
+
+## 判据（默认从 `wenyao-template-map.json` 推导，无需手写名单）
+
+| source | 含义 | 允许不同？ |
+|---|---|---|
+| `const` | 固定值（关联单号/币种/是否带电…） | ❌ **必须完全相同** |
+| `field` / `llm` / `calc` / `storemap` / `image` | 随货件/行变化的值 | ✅ 允许不同 |
+| `const` + `perRow: true` | **常量模板，但取值随行变化**（如 S 产品材质 = `{材质}，{材质英文}`） | ✅ 允许不同 |
+
+⚠️ `perRow` 不是"这一列不用管"：该列的**判据在填报器**（材质英文三级解析：SKU 字典 → 小词典 →
+会话传入 `--material-en`），三级都解析不出来时填报器**直接阻断、不落盘**（文案指路）⇒ 走到本对比器
+的影子产物一定已带非空英文。本对比器只做"模板/结构有没有被动过"，不再把**每票都不同的材质文本**
+当成结构漂移（2026-10-12 实测：两条票因 S8 与黄金样本材质不同而被判"意外差异"⇒ 闸门 exit 1 误阻）。
+
+## 用法
+
+    python3 scripts/wenyao_shadow_diff.py --shadow <新票影子.xlsx> --golden <已验收票.xlsx>
+    python3 scripts/wenyao_shadow_diff.py ... --allow C,D --deny A         # 手工覆盖
+    python3 scripts/wenyao_shadow_diff.py ... --json                       # 机器可读
+
+退出码：0 = 可放行；1 = 有意外差异（**不要切主**）；2 = 参数/文件问题。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from openpyxl import load_workbook
+
+DEFAULT_MAP = Path(__file__).resolve().with_name("wenyao-template-map.json")
+PER_ROW_SOURCES = {"field", "llm", "calc", "storemap", "image"}
+
+
+def load_policy(map_path: Path) -> tuple[set[str], set[str], dict[str, str]]:
+    """返回 (允许不同的列, 必须相同的列, 列→表头)。
+
+    `perRow: true` 的列按**随行变化**处理（`const` 模板 + 行数据，如 S 产品材质）——
+    它的判据在填报器（三级解析 + 未命中即阻断），不在这里逐字比对。
+    """
+    data = json.loads(map_path.read_text(encoding="utf-8"))
+    allow: set[str] = set()
+    deny: set[str] = set()
+    headers: dict[str, str] = {}
+    for c in data.get("columns", []):
+        col = str(c.get("col", "")).strip().upper()
+        if not col:
+            continue
+        headers[col] = str(c.get("header", ""))
+        if c.get("source") in PER_ROW_SOURCES or c.get("perRow"):
+            allow.add(col)
+        else:
+            deny.add(col)
+    return allow, deny, headers
+
+
+def norm(v) -> str:
+    """None 与空串等价（模板清空行后两者混用），其余去首尾空白。"""
+    if v is None:
+        return ""
+    return str(v).strip()
+
+
+def column_letter(idx: int) -> str:
+    s = ""
+    while idx > 0:
+        idx, r = divmod(idx - 1, 26)
+        s = chr(65 + r) + s
+    return s
+
+
+def compare(shadow_path: Path, golden_path: Path, allow: set[str], deny: set[str]):
+    """逐格比对两张工作簿，返回 (意外差异列表, 允许差异列表, 统计)。"""
+    a = load_workbook(shadow_path, data_only=True)
+    b = load_workbook(golden_path, data_only=True)
+    unexpected, allowed, same = [], [], 0
+    for sheet in sorted(set(a.sheetnames) | set(b.sheetnames)):
+        if sheet not in a.sheetnames or sheet not in b.sheetnames:
+            unexpected.append({"sheet": sheet, "cell": "-", "col": "-", "reason": "工作表只存在于一侧",
+                               "shadow": sheet in a.sheetnames, "golden": sheet in b.sheetnames})
+            continue
+        wa, wb = a[sheet], b[sheet]
+        rows = max(wa.max_row, wb.max_row)
+        cols = max(wa.max_column, wb.max_column)
+        for r in range(1, rows + 1):
+            for c in range(1, cols + 1):
+                va, vb = norm(wa.cell(r, c).value), norm(wb.cell(r, c).value)
+                if va == vb:
+                    same += 1
+                    continue
+                col = column_letter(c)
+                item = {"sheet": sheet, "cell": f"{col}{r}", "col": col, "shadow": va, "golden": vb}
+                # 列在白名单里且**不在**必须相同名单里 → 允许
+                if col in allow and col not in deny:
+                    allowed.append(item)
+                else:
+                    unexpected.append(item)
+    return unexpected, allowed, {"相同单元格": same, "允许差异": len(allowed), "意外差异": len(unexpected)}
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="文鳐影子产物对比器（放行判据）")
+    ap.add_argument("--shadow", required=True, help="新票影子产物 xlsx")
+    ap.add_argument("--golden", required=True, help="已验收通过的票产物 xlsx（黄金样本）")
+    ap.add_argument("--map", default=str(DEFAULT_MAP), help="模板映射（默认 scripts/wenyao-template-map.json）")
+    ap.add_argument("--allow", default="", help="手工追加允许不同的列，逗号分隔（如 C,D）")
+    ap.add_argument("--deny", default="", help="手工追加必须相同的列，逗号分隔（如 A）")
+    ap.add_argument("--json", action="store_true", help="输出 JSON")
+    ap.add_argument("--show", type=int, default=20, help="文本模式最多打印多少条明细")
+    a = ap.parse_args(argv)
+
+    shadow, golden = Path(a.shadow), Path(a.golden)
+    for p in (shadow, golden):
+        if not p.exists():
+            print(f"文件不存在: {p}", file=sys.stderr)
+            return 2
+    try:
+        allow, deny, headers = load_policy(Path(a.map))
+    except Exception as exc:  # noqa: BLE001
+        print(f"读取映射失败: {exc}", file=sys.stderr)
+        return 2
+    allow |= {c.strip().upper() for c in a.allow.split(",") if c.strip()}
+    deny |= {c.strip().upper() for c in a.deny.split(",") if c.strip()}
+
+    unexpected, allowed, stats = compare(shadow, golden, allow, deny)
+    ok = not unexpected
+    if a.json:
+        print(json.dumps({"pass": ok, "stats": stats, "unexpected": unexpected, "allowed": allowed},
+                         ensure_ascii=False, indent=2))
+    else:
+        print(f"影子: {shadow.name}   黄金: {golden.name}")
+        print(f"允许不同的列（{len(allow)}）: {','.join(sorted(allow))}")
+        print(f"必须相同的列（{len(deny)}）: {','.join(sorted(deny))}")
+        print(f"统计: {stats}")
+        for tag, items in (("❌ 意外差异", unexpected), ("✅ 允许差异", allowed)):
+            if not items:
+                continue
+            print(f"\n{tag}（{len(items)}）:")
+            for it in items[: a.show]:
+                h = headers.get(it.get("col", ""), "")
+                print(f"  {it['sheet']}!{it['cell']:<6} {h:<22} 黄金={it['golden']!r} → 影子={it['shadow']!r}"
+                      if "reason" not in it else f"  {it['sheet']}: {it['reason']}")
+            if len(items) > a.show:
+                print(f"  …还有 {len(items) - a.show} 条")
+        print("\n" + ("✅ 可放行切主（无意外差异）" if ok else "❌ 拒绝切主：存在意外差异"))
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())