@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/wenyao_portal.py

@@ -0,0 +1,633 @@
+#!/usr/bin/env python3
+"""wenyao_portal.py — 上海文鳐门户（my.ffl-tech.com）操作模块（2026-09-11）
+
+把 ⑥→⑨ 的门户动作封成可复用函数，供 `wenyao_run.py` 编排调用。
+所有选择器/接口都来自 2026-09-11 首票 WY535082 的**实测**（见 skills/ml-invoice/references/portal-flow.md）。
+
+设计约束
+--------
+· **只连已登录的长驻 Chrome**（CDP 9333，profile 持久化）；本模块**不做登录**——
+  登录要过阿里云滑块，属人工介入点。
+· 导出/导入等**写操作**都返回结构化结果，由调用方决定是否执行（编排层负责 shadow/真跑）。
+· 下载用**浏览器级 CDP** 设下载目录 + `expect_download()` 捕获，并 `copy(download.path(), dest)`
+  （实测 `save_as()` 会存成 0 字节）。
+
+并发隔离（2026-10-12 事故固化 —— 三条票 `79212271 / 79298694 / 79210359` 同抢**同一个 page**）
+--------------------------------------------------------------------------------------
+· **每条跑批一个自己的标签页**：`connect()` 默认在门户所在 context 里 `context.new_page()`
+  新建一个**只属于本次跑批**的页，并返回可解包的 `PortalSession`；调用方**必须**
+  `finally: sess.close()`（只关自己那个页，⛔ 不关别人/用户自己开着的页）。
+  死因回顾：旧实现三条并发执行者都复用**同一个既有 page** ⇒ 导航/点击互相打断 ⇒ 看起来"永远跑不完"。
+· **每门户一把 flock**（数据目录下的门户锁文件，与 `scripts/lib/argent_filelock.py` 同源）：
+  覆盖**会改门户状态或产出文件**的阶段（P7 查重 → P14 收口）；**有界等待**（默认 300s，`WENYAO_PORTAL_LOCK_TIMEOUT`），
+  抢锁期间每 15s 打印一行，超时 ⇒ `PortalLockTimeout`（⛔ **绝不无限等待** —— 那正是本次死循环的形态）。
+  粒度 = **本门户/本 CDP profile**，⛔ 不是全局锁（不牵连 FULL 与其它流程）。
+· **下载目录**：在**持锁**前提下设置，并尽量把 `Browser.setDownloadBehavior` 收到**本次跑批自己的 context**
+  （`browserContextId`）；只能浏览器级时由锁保证串行，且下载后按 `suggestedFilename` + 包内容
+  校验归属，不符即报错（⛔ 不静默用错文件）。
+
+CLI（供手工排障；脚本路径 = 本文件）：
+  --state                 # 登录态/列表概况
+  --query 76636923        # 按货件号查（只读）
+  --warehouse-menu        # 开导出进仓单菜单看选项（只读，不点选）
+  --lock-probe            # 门户锁体检（先有界拿锁，再开一个自己的隔离页）
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import sys
+import time
+import zipfile
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Callable, Iterator, Optional
+from urllib.parse import urlparse
+
+DEFAULT_CDP = "http://127.0.0.1:9333"
+CDP = os.environ.get("WENYAO_CDP", DEFAULT_CDP)
+LIST_URL = "https://my.ffl-tech.com/my/trailer-center#/trailer-center"
+# 数据目录：**唯一判据**在 `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  —— 勿在此复制判据
+from argent_filelock import FileLock, LockError, read_lock_holder  # noqa: E402  —— 锁的唯一真源
+DEFAULT_DOWNLOAD_DIR = Path(resolve_data_dir()['dir']) / "wenyao-downloads"
+RECEIPT_MENU_LABEL = "集货仓 - 东莞集货仓"      # SOP：导出进仓单选「东莞集货仓」（= HNBD）
+
+# ── 门户锁 ──────────────────────────────────────────────────────────────────
+LOCK_NAME = "wenyao-portal.lock"
+LOCK_TIMEOUT_ENV = "WENYAO_PORTAL_LOCK_TIMEOUT"
+DEFAULT_LOCK_TIMEOUT = 300.0        # 秒；有界等待，⛔ 绝不无限等
+LOCK_HINT_SEC = 15.0                # 抢锁期间每隔多久打印一行"⏳ 等待…"
+LOCK_HINT_TEXT = "⏳ 等待其他发票跑批释放门户（已等 {n}s）"
+#: 货件号形态 = **恰好 8 位**数字（`79212271`）。用前后不看数字来排除 14 位时间戳（`唛头20260911180600.zip`）。
+TICKET_RE = re.compile(r"(?<!\d)(\d{8})(?!\d)")
+
+
+class PortalLockTimeout(RuntimeError):
+    """门户锁**有界等待**超时（⛔ 绝不无限等待；这正是 2026-10-12 死循环的形态）。"""
+
+
+def data_dir() -> Path:
+    """数据目录（**延迟求值**：`--home`/隔离 home 场景下不能在 import 期定死）。"""
+    return Path(resolve_data_dir()['dir'])
+
+
+def portal_lock_path() -> Path:
+    """每门户一把锁的路径。粒度 = **本门户 profile**（默认 9333 那个 Chrome）；
+    换了 `WENYAO_CDP`（另一个 Chrome profile）就换一把锁 —— ⛔ 不是全局锁。"""
+    if CDP != DEFAULT_CDP:
+        port = ""
+        try:
+            port = str(urlparse(CDP).port or "")
+        except Exception:                                            # noqa: BLE001
+            port = ""
+        return data_dir() / (LOCK_NAME.replace(".lock", f"-{port or 'custom'}.lock"))
+    return data_dir() / LOCK_NAME
+
+
+def portal_lock_timeout() -> float:
+    """有界等待上限（秒）：`WENYAO_PORTAL_LOCK_TIMEOUT` > 默认 300s。
+
+    ⛔ 非法值**响亮失败**（fail-closed）：静默回落到某个值 = 又一次"降级路径产出错值"。
+    """
+    raw = (os.environ.get(LOCK_TIMEOUT_ENV) or "").strip()
+    if not raw:
+        return DEFAULT_LOCK_TIMEOUT
+    try:
+        return max(0.0, float(raw))
+    except ValueError as exc:
+        raise RuntimeError(
+            f"{LOCK_TIMEOUT_ENV}={raw!r} 不是数字（秒）—— 拒绝静默回落；请改正或删掉该环境变量"
+        ) from exc
+
+
+@contextmanager
+def portal_lock(site: str = "", *, timeout: Optional[float] = None, hint_sec: float = LOCK_HINT_SEC,
+                reporter: Optional[Callable[[str], None]] = None, path: Optional[Path] = None,
+                ) -> Iterator[float]:
+    """**每门户一把 flock**，覆盖会改门户状态/产出文件的阶段（P7 查重 → P14 收口）。
+
+    · 有界等待：`timeout`（缺省 `WENYAO_PORTAL_LOCK_TIMEOUT` / 300s）；
+    · 抢锁期间每 `hint_sec` 秒打印一行 `⏳ 等待其他发票跑批释放门户（已等 Ns）`；
+    · 超时 ⇒ 抛 `PortalLockTimeout`（文案含「门户被占用/等待超时，避免并发踩踏；请稍后重跑或提高超时」）；
+    · 锁不可用（无后端 / 建不出锁文件）⇒ 抛 `LockError`（fail-closed，⛔ 绝不无锁继续）；
+    · yield **实际等待秒数**（0 = 立刻拿到）；退出时**释放并关掉自己的 fd**（锁文件可留，fd 必须释放）。
+    """
+    lim = portal_lock_timeout() if timeout is None else max(0.0, float(timeout))
+    lock_path = Path(path) if path else portal_lock_path()
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    say = reporter or (lambda m: print(m, flush=True))
+    t0 = time.monotonic()
+    lk = FileLock(str(lock_path), site=site or "portal.lock")
+    nxt_hint = t0 + max(0.01, float(hint_sec))
+    try:
+        while not lk.acquire(timeout=0.0):                # 非阻塞试一次；拿到就零等待（单跑路径不变）
+            waited = time.monotonic() - t0
+            if waited >= lim:
+                holder = read_lock_holder(lock_path)
+                raise PortalLockTimeout(
+                    f"门户被占用/等待超时（已等 {waited:.0f}s，上限 {lim:.0f}s）：避免并发踩踏；"
+                    f"请稍后重跑或提高超时（{LOCK_TIMEOUT_ENV}=<秒>）"
+                    + (f"；持锁者：{holder[:200]}" if holder else "")
+                )
+            now = time.monotonic()
+            if now >= nxt_hint:
+                say(LOCK_HINT_TEXT.format(n=round(now - t0)))
+                nxt_hint = now + max(0.01, float(hint_sec))
+            time.sleep(max(0.01, min(0.5, lim - waited, max(0.0, nxt_hint - now) or 0.5)))
+        yield time.monotonic() - t0
+    finally:
+        lk.release()                                      # 路径模式：连自己的 fd 一起关
+
+
+# ───────────────────────────── 连接 ─────────────────────────────
+
+def _page_target_info(page) -> dict:
+    """该 page 的 CDP target 信息（`targetId` / `browserContextId`）。取不到 ⇒ `{}`（⛔ 不因此失败）。"""
+    try:
+        info = page.context.new_cdp_session(page).send("Target.getTargetInfo") or {}
+        return dict(info.get("targetInfo") or {})
+    except Exception:                                                # noqa: BLE001
+        return {}
+
+
+class PortalSession:
+    """一次跑批**自己的**门户标签页（隔离）。
+
+    可解包成 `(browser, page, close_fn)`；调用方**必须** `finally: sess.close()`。
+    `browser` 是共享的 CDP 连接（⛔ 不要 close —— 那是用户的长驻 Chrome）；`close()` **只关自己这个 page**，
+    失败只告警不上抛（别人的页/用户的页一个都不动）。
+    """
+
+    def __init__(self, browser: Any, page: Any, target_id: str = "", *, owns_page: bool = True) -> None:
+        self.browser = browser
+        self.page = page
+        self.target_id = target_id or ""
+        self.owns_page = bool(owns_page)
+        self.closed = False
+        self.last_error: Optional[BaseException] = None
+
+    def __iter__(self):
+        return iter((self.browser, self.page, self.close))
+
+    def __repr__(self) -> str:                                       # pragma: no cover - 诊断用
+        return "<PortalSession target=%s owns_page=%s closed=%s>" % (
+            self.target_id[:8] or "-", self.owns_page, self.closed)
+
+    def close(self) -> None:
+        """只关**自己**那个 page；幂等；失败**只告警**（⛔ 不上抛，别把真正的错盖掉）。"""
+        if self.closed or not self.owns_page or self.page is None:
+            self.closed = True
+            return
+        try:
+            self.page.close()
+        except Exception as exc:                                     # noqa: BLE001
+            self.last_error = exc
+            print(f"[门户] ⚠️ 关闭自己的标签页失败（{type(exc).__name__}: {exc}）—— 不入库、不影响结论",
+                  file=sys.stderr)
+        self.closed = True
+
+
+def connect(pw, *, isolated: bool = True) -> PortalSession:
+    """连门户 Chrome，返回 `PortalSession`（可解包成 `(browser, page, close_fn)`）。
+
+    **默认即隔离**（`isolated=True`）：在门户所在 context 里 `context.new_page()` 新建一个
+    **只属于本次跑批**的标签页并导航到跨境电商订单列表页 —— 并发跑批各用各的页，互相不打断。
+    `isolated=False` 复用既有门户 page（旧行为，`close()` 是 no-op）—— ⛔ 只给只读排障用。
+
+    ⛔ 保留既有语义：**找不到门户 Chrome ⇒ 明确报错并提示先跑门户启动脚本**（文案见下）；
+    ⛔ **不动用户自己开着的门户页**（那是人的页面）。
+    """
+    browser = pw.chromium.connect_over_cdp(CDP, timeout=8000)
+    pages = [pg for c in browser.contexts for pg in c.pages if "ffl-tech" in (pg.url or "")]
+    if not pages:
+        raise RuntimeError("没找到门户标签页；先跑 bash scripts/wenyao-browser.sh start")
+    host = next((pg for pg in pages if (pg.url or "").endswith("#/trailer-center")), pages[0])
+    if not isolated:
+        page = host
+        if not (page.url or "").endswith("#/trailer-center"):
+            page.goto(LIST_URL)
+            page.wait_for_timeout(3000)
+        return PortalSession(browser, page, _page_target_info(page).get("targetId", ""), owns_page=False)
+    try:
+        page = host.context.new_page()
+    except Exception as exc:                                         # noqa: BLE001
+        raise RuntimeError(
+            f"打不开门户新标签页（{type(exc).__name__}: {exc}）；"
+            "先跑 bash scripts/wenyao-browser.sh start 再重试"
+        ) from exc
+    try:
+        page.goto(LIST_URL)
+        page.wait_for_timeout(3000)
+    except Exception as exc:                                         # noqa: BLE001
+        PortalSession(browser, page, "").close()                     # 导航失败也别把自己的页留下
+        raise RuntimeError(
+            f"门户新标签页导航失败（{type(exc).__name__}: {exc}）；"
+            "多半是门户未登录 —— 请人工在门户过一次滑块后重试"
+        ) from exc
+    return PortalSession(browser, page, _page_target_info(page).get("targetId", ""), owns_page=True)
+
+
+def set_download_dir(browser, page, download_dir: Path, *, browser_context_id: str = "") -> dict:
+    """设下载目录，**尽量绑定到本次跑批自己的 context**。
+
+    ⚠️ 必须设在**浏览器级** CDP session（设在 page 级实测不生效，2026-09-11）。但浏览器级是**全局**的 ⇒
+    并发跑批会互相覆盖下载目录（2026-10-12 次生竞争）⇒ 带上 `browserContextId` 把范围收窄到我们自己的
+    context；拿不到 contextId 时退回全局设置，由**门户锁**保证串行（调用方持有锁）。
+    返回 `{"scope": "context"|"browser"|"page", "browserContextId": …}`。
+    """
+    download_dir.mkdir(parents=True, exist_ok=True)
+    bid = browser_context_id or str(_page_target_info(page).get("browserContextId") or "")
+    base = {"behavior": "allow", "downloadPath": str(download_dir), "eventsEnabled": True}
+    tried: list = []
+    if bid:
+        tried.append(("context", dict(base, browserContextId=bid)))
+    tried.append(("browser", dict(base)))
+    last: Optional[BaseException] = None
+    for scope, params in tried:
+        try:
+            browser.new_browser_cdp_session().send("Browser.setDownloadBehavior", params)
+            return {"scope": scope, "browserContextId": params.get("browserContextId", "")}
+        except Exception as exc:                                     # noqa: BLE001
+            last = exc
+    page.context.new_cdp_session(page).send("Browser.setDownloadBehavior", dict(base))   # 兜底：page 级
+    if last is not None:
+        print(f"[门户] ⚠️ context/浏览器级设下载目录都失败（{last}）⇒ 退回 page 级（实测常常不生效）",
+              file=sys.stderr)
+    return {"scope": "page", "browserContextId": ""}
+
+
+def install_hooks(page) -> None:
+    """钩住 window.open / XHR，用于抓导出产生的预签名下载地址。"""
+    page.evaluate("""() => {
+      if (window.__wy) return;
+      window.__wy = {opens: [], reqs: []};
+      const ow = window.open;
+      window.open = function (u) { try { window.__wy.opens.push(String(u)); } catch (e) {} return ow.apply(this, arguments); };
+      const oo = XMLHttpRequest.prototype.open, os = XMLHttpRequest.prototype.send;
+      XMLHttpRequest.prototype.open = function (m, u) { this.__m = m; this.__u = u; return oo.apply(this, arguments); };
+      XMLHttpRequest.prototype.send = function (b) {
+        try { window.__wy.reqs.push({m: this.__m, u: String(this.__u), b: b ? String(b).slice(0, 300) : ''}); } catch (e) {}
+        return os.apply(this, arguments);
+      };
+    }""")
+
+
+def hooks(page) -> dict:
+    return page.evaluate("() => (window.__wy || {opens: [], reqs: []})")
+
+
+# ───────────────────────────── 只读 ─────────────────────────────
+
+def login_state(page) -> dict:
+    return page.evaluate("""() => ({
+      url: location.href,
+      needLogin: !!document.querySelector('input[type=password]'),
+      onList: /跨境电商订单/.test(document.body.innerText || ''),
+      summary: (document.querySelector('.ff-base-table2-summary')?.innerText || '').trim()
+    })""")
+
+
+def close_task_panel(page) -> bool:
+    """关掉右上角「导出任务」面板。返回是否已确认收起。
+
+    ⚠️ 2026-09-18 踩坑（皮 10i 的真因）：该面板 **Esc 关不掉**，而它的容器
+    （`.task-his`，实测 498×6888px）会盖在「查询」按钮上 ⇒ `btn.click()` 超时后
+    走的 `click(force=True)` **点在了遮罩上、查询根本没发出去**，DOM 里残留的是
+    **上一次查询的结果**。据此做查重 ⇒ 假阳性白停一票、假阴性则重复导入对方生产系统。
+    """
+    try:
+        if not page.evaluate("() => !!document.querySelector('.task-his')?.offsetWidth"):
+            return True
+        page.evaluate("() => document.querySelector('.taskcenterHandle')?.click()")
+        page.wait_for_timeout(1200)
+        return not page.evaluate("() => !!document.querySelector('.task-his')?.offsetWidth")
+    except Exception:
+        return False
+
+
+def close_overlays(page) -> None:
+    """关掉可能挡住点击的浮层（导出任务面板/下拉/弹窗）。
+    实测：导出任务面板留着不关，其遮罩会拦截「查询」按钮的点击（TimeoutError）。"""
+    for _ in range(3):
+        try:
+            page.keyboard.press("Escape")
+            page.wait_for_timeout(500)
+        except Exception:
+            break
+    if page.locator(".next-dialog.ff-modal").count():
+        el = page.query_selector(".next-dialog-close-icon")
+        if el and el.is_visible():
+            el.click()
+            page.wait_for_timeout(800)
+    close_task_panel(page)
+
+
+def reset_query(page) -> None:
+    """点「重置」，别把筛选条件留给下一个人。"""
+    try:
+        page.locator("button", has_text="重置").first.click()
+        page.wait_for_timeout(2500)
+    except Exception:
+        pass
+
+
+def query_shipment(page, shipment_no: str) -> dict:
+    """按货件号查询（只读）。返回 {count, rows:[文本], summary, api_total, dom_count}。
+
+    ⚠️ 2026-09-18 fail-closed 加固：**只认接口响应，不认 DOM 残留**。
+    踩坑实录：导出任务面板遮罩挡住「查询」按钮 ⇒ 点击超时后走的 `click(force=True)`
+    点在遮罩上、**请求根本没发出**，DOM 里留着上一次查询的旧行；此时读 DOM 会得到
+    假阳性（白停一票）或假阴性（重复导入对方生产系统）。故改为：
+      ① 用 `expect_response` 抓 `/api/v1/lcl/order/page`，以 `data.page.totalCount` 为准；
+      ② 抓不到响应/N 解析不出 ⇒ **直接报错**，绝不回落到可能过期的 DOM 数字。
+    """
+    close_overlays(page)
+    reset_query(page)
+    inp = page.locator("input[placeholder='支持多号查询']").nth(2)   # 1=业务编号 2=导入批次号 3=货件号
+    inp.fill(shipment_no)
+    page.wait_for_timeout(300)
+    btn = page.get_by_role("button", name="查询", exact=True)
+    api_total = None
+
+    def _is_our_query(r) -> bool:
+        """只认**本次货件号**的查询响应（避免抓到重置/上一次查询的迟到响应）。
+        post_data 取不到时放宽为仅按 URL 匹配，避免误判成"没发出去"。"""
+        try:
+            if "/api/v1/lcl/order/page" not in r.url:
+                return False
+            pd = r.request.post_data
+            return pd is None or shipment_no in pd
+        except Exception:
+            return False
+
+    try:
+        with page.expect_response(_is_our_query, timeout=20000) as ri:
+            try:
+                btn.click(timeout=8000)
+            except Exception:
+                close_overlays(page)
+                btn.click(force=True, timeout=8000)     # 兜底：无视遮罩
+        body = ri.value.json() or {}
+        api_total = ((body.get("data") or {}).get("page") or {}).get("totalCount")
+    except Exception as e:
+        raise RuntimeError(
+            f"「查询」未真正发出或未收到接口响应（多半是遮罩挡住了按钮）："
+            f"{type(e).__name__}: {str(e)[:200]}"
+        ) from e
+    if api_total is None:
+        raise RuntimeError("查询接口响应里没有 totalCount，拒绝用 DOM 残留做判断（fail-closed）")
+    page.wait_for_timeout(3500)
+    summary = page.evaluate("() => (document.querySelector('.ff-base-table2-summary')?.innerText || '').trim()")
+    rows = page.evaluate("""() => Array.from(document.querySelectorAll('.BaseTable__row.ddp-row'))
+        .map(r => (r.innerText || '').replace(/\\s+/g, ' ').trim()).filter(t => /货件号/.test(t))""")
+    n = 0
+    for tok in summary.replace("已选择", " ").split():
+        if tok.isdigit():
+            n = int(tok)
+    return {"count": int(api_total), "rows": rows, "summary": summary,
+            "api_total": int(api_total), "dom_count": n}
+
+
+def select_shipment(page, shipment_no: str) -> dict:
+    """勾选该货件号所在行。返回 {selected, summary}。"""
+    row = page.locator(".BaseTable__row.ddp-row").filter(has_text=shipment_no).first
+    cb = row.locator("input[type=checkbox], .next-checkbox").first
+    cb.click()
+    page.wait_for_timeout(1500)
+    summary = page.evaluate("() => (document.querySelector('.ff-base-table2-summary')?.innerText || '').trim()")
+    return {"selected": "已选择 1" in summary, "summary": summary}
+
+
+def warehouse_menu_items(page) -> list:
+    """只读：点开「导出进仓单」看菜单项（不点选）。"""
+    if not page.locator("li:has-text('集货仓')").count():
+        page.get_by_role("button", name="导出进仓单").click()
+        page.wait_for_timeout(1800)
+    return page.evaluate("""() => Array.from(document.querySelectorAll('.next-menu-item'))
+        .map(e => (e.innerText || '').trim()).filter(t => /仓/.test(t))""")
+
+
+# ───────────────────────────── 写操作 ─────────────────────────────
+
+def import_order(page, xlsx: str) -> dict:
+    """⑤ 导入订单（**真写对方生产系统**）。"""
+    page.get_by_role("button", name="导入订单", exact=True).click()
+    page.wait_for_timeout(2500)
+    page.locator(".next-dialog.ff-modal input[type=file]").first.set_input_files(str(xlsx))
+    page.wait_for_timeout(3500)
+    page.get_by_role("button", name="导入", exact=True).last.click()
+    toasts: list = []
+    for _ in range(15):
+        page.wait_for_timeout(2000)
+        toasts = page.evaluate("""() => Array.from(document.querySelectorAll('.next-message,.next-toast,.next-notification'))
+            .map(e => (e.innerText || '').replace(/\\s+/g, ' ').trim()).filter(Boolean)""")
+        if toasts:
+            break
+    text = " | ".join(dict.fromkeys(toasts))
+    return {"toasts": toasts, "text": text, "ok": ("成功" in text and "失败 0" in text)}
+
+
+def export_receipt(page, label: str = RECEIPT_MENU_LABEL) -> dict:
+    """⑦ 导出进仓单：菜单选仓 → 预签名 xlsx 走 window.open。"""
+    page.get_by_role("button", name="导出进仓单").click()
+    page.wait_for_timeout(1800)
+    page.locator(".next-menu-item", has_text=label).first.click()
+    page.wait_for_timeout(5000)
+    opens = hooks(page).get("opens", [])
+    return {"url": opens[-1] if opens else None}
+
+
+def export_marks(page) -> dict:
+    """⑧ 导出唛头（异步任务；文件去「导出任务」面板取）。"""
+    page.get_by_role("button", name="导出唛头", exact=True).click()
+    page.wait_for_timeout(6000)
+    toasts = page.evaluate("""() => Array.from(document.querySelectorAll('.next-message,.next-toast,.next-notification'))
+        .map(e => (e.innerText || '').replace(/\\s+/g, ' ').trim()).filter(Boolean)""")
+    text = " | ".join(dict.fromkeys(toasts))
+    return {"toasts": toasts, "text": text, "ok": "成功" in text}
+
+
+def open_task_panel(page) -> None:
+    if not page.locator("button:has-text('下载')").count():
+        page.click("text=导出任务")
+        page.wait_for_timeout(2500)
+
+
+def top_task(page) -> dict:
+    """「导出任务」面板最上面一条（= 本次）。返回 {text, downloads}。"""
+    open_task_panel(page)
+    return page.evaluate("""() => {
+      const dl = Array.from(document.querySelectorAll('button,a,[class*=btn]'))
+        .filter(e => (e.innerText || '').trim() === '下载' && e.getBoundingClientRect().width);
+      return {downloads: dl.length};
+    }""")
+
+
+def fetch_bytes(page, url: str) -> bytes:
+    """用**页面自身会话**取字节（同源带 cookie），不依赖浏览器下载落盘。"""
+    import base64
+    r = page.evaluate("""async (u) => {
+      const res = await fetch(u, {credentials: 'include'});
+      const buf = await res.arrayBuffer();
+      const bytes = new Uint8Array(buf);
+      let s = '';
+      const CH = 8192;
+      for (let i = 0; i < bytes.length; i += CH) s += String.fromCharCode.apply(null, bytes.subarray(i, i + CH));
+      return {status: res.status, b64: btoa(s), len: bytes.length};
+    }""", url)
+    if r.get("status") != 200:
+        raise RuntimeError(f"取字节失败 HTTP {r.get('status')}")
+    return base64.b64decode(r["b64"])
+
+
+def _is_date_like(tok: str) -> bool:
+    """`20260911` 这种 8 位**日期**不是货件号（货件号都是 `79…`/`76…` 开头）。
+    没有这条过滤，文件名里带日期的正常下载会被误判成"别的票"而白停一票。"""
+    if len(tok) != 8 or not tok.startswith("20"):
+        return False
+    return 1 <= int(tok[4:6]) <= 12 and 1 <= int(tok[6:8]) <= 31
+
+
+def assert_download_owned(name: str, expect_shipment: str) -> dict:
+    """**下载归属**（2026-10-12 次生竞争固化）：文件名里带 8 位票号且不是本票 ⇒ **报错**。
+
+    实测 DDP 包名是 `唛头<YYYYMMDDHHMMSS>.zip`（**不含票号**）⇒ 那种情况这里放行，交给
+    `assert_zip_owned()` 用**包内文件名**（`<运单号>-<货件号>_mark.pdf`）判归属。
+    8 位日期（`20260911`）不算票号（见 `_is_date_like`），避免误判白停。
+    返回 `{"checked": bool, "tokens": [...]}`；⛔ 不匹配时**抛错而不是静默用错文件**。
+    """
+    toks = [t for t in TICKET_RE.findall(name or "") if not _is_date_like(t)]
+    if expect_shipment and toks and expect_shipment not in toks:
+        raise RuntimeError(
+            f"❌ 下载文件名「{name}」属于别的票（期望 {expect_shipment}，实见 {toks}）—— "
+            "并发跑批拿错了文件；本次**不使用**它（请检查门户锁/下载目录绑定）"
+        )
+    return {"checked": bool(expect_shipment and toks), "tokens": toks}
+
+
+def assert_zip_owned(zip_path: str, expect_shipment: str) -> list:
+    """**包内容归属**：DDP 包内是 `<运单号>-<货件号>_mark.pdf` ⇒ 必须含本票货件号。
+
+    返回成员名列表。⛔ 不符即报错（外层文件名是时间戳时，这是唯一能拦住"用错文件"的判据）。
+    """
+    with zipfile.ZipFile(zip_path) as z:
+        names = list(z.namelist())
+    if expect_shipment and not any(expect_shipment in n for n in names):
+        raise RuntimeError(
+            f"❌ 下载的压缩包与本票不符（期望含 {expect_shipment}，实见 {names[:5]}）—— "
+            "并发跑批拿错了文件；本次**不使用**它"
+        )
+    return names
+
+
+def download_latest_ddp(page, download_dir: Path, *, expect_shipment: str = "") -> dict:
+    """⑨ 取「导出任务」面板最上面一条并下载（⚠️ 面板混着历史任务，靠"最上面"=最新）。
+
+    两条路，优先走**页面取字节**：
+      ① `expect_download()` 只为拿到**稳定 URL**，然后用页面会话 fetch 字节——
+         实测 `download.path()` 的临时文件会被 Playwright 清掉（`FileNotFoundError` 竞态），
+         而 `save_as()` 又会存成 0 字节，所以都不可靠；
+      ② 兜底：临时文件还在就 `shutil.copy`。
+
+    `expect_shipment` 给了就做**归属校验**（文件名 8 位票号 + 包内容成员名），不符即报错。
+    """
+    open_task_panel(page)
+    with page.expect_download(timeout=40000) as info:
+        page.locator("button:has-text('下载'), a:has-text('下载')").first.click()
+    d = info.value
+    name = d.suggested_filename or ""
+    owned = assert_download_owned(name, expect_shipment)      # ⛔ 先判归属，再落盘（不落错文件）
+    download_dir.mkdir(parents=True, exist_ok=True)
+    dest = download_dir / (name or "ddp.zip")
+    url = d.url
+    try:
+        data = fetch_bytes(page, url)
+        dest.write_bytes(data)
+        how = "page-fetch"
+    except Exception:
+        shutil.copy(d.path(), dest)       # 兜底
+        how = "temp-copy"
+    inner: list = []
+    if zipfile.is_zipfile(dest):
+        inner = assert_zip_owned(str(dest), expect_shipment)
+    close_overlays(page)                  # ⚠️ 用完就关，别让遮罩挡住下一步
+    return {"path": str(dest), "name": dest.name, "size": dest.stat().st_size, "url": url,
+            "how": how, "owned": owned, "inner": inner}
+
+
+def unzip_marks(zip_path: str, out_dir: Path) -> list:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(zip_path) as z:
+        z.extractall(out_dir)
+        return [str(p) for p in sorted(out_dir.rglob("*")) if p.is_file()]
+
+
+def rename_mark(pdf_path: str, shipment_no: str, boxes, name_cn: str) -> str:
+    """⑪ 按 `运单-<货件号>-<箱数>箱-<中文品名>.pdf` 改名。"""
+    src = Path(pdf_path)
+    dest = src.with_name(f"运单-{shipment_no}-{boxes}箱-{name_cn}.pdf")
+    src.rename(dest)
+    return str(dest)
+
+
+# ───────────────────────────── CLI ─────────────────────────────
+
+def lock_probe() -> int:
+    """排障入口：**按生产同一顺序**（先有界拿门户锁 → 再开一个自己的隔离页）。
+
+    退出码：0 = 拿到锁且开得出自己的页；3 = **门户被占用/等待超时**（文案见 `PortalLockTimeout`，
+    此时**根本不开浏览器**、连 playwright 都不 import ⇒ "超时 = 不进入门户阶段"）；2 = 锁本身不可用（fail-closed）。
+    """
+    try:
+        with portal_lock(site="portal.lock-probe", reporter=lambda m: print(m, flush=True)) as waited:
+            from playwright.sync_api import sync_playwright          # ⚠️ 进门户阶段才 import（超时路径零依赖）
+            with sync_playwright() as p:
+                sess = connect(p)
+                try:
+                    print(json.dumps({"ok": True, "waited": round(waited, 2), "locked": True,
+                                      "targetId": sess.target_id}, ensure_ascii=False))
+                finally:
+                    sess.close()
+    except LockError as exc:
+        print(f"❌ 门户锁不可用（fail-closed，绝不无锁继续）：{exc}", file=sys.stderr)
+        return 2
+    except PortalLockTimeout as exc:
+        print(f"❌ {exc}", file=sys.stderr)
+        return 3
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--state", action="store_true")
+    ap.add_argument("--query")
+    ap.add_argument("--warehouse-menu", action="store_true")
+    ap.add_argument("--lock-probe", action="store_true",
+                    help="门户锁体检：先有界拿锁（拿不到 ⇒ 退出码 3 + 标准文案），再开一个自己的隔离页")
+    a = ap.parse_args()
+    if a.lock_probe:
+        return lock_probe()
+    from playwright.sync_api import sync_playwright
+    with sync_playwright() as p:
+        sess = connect(p)
+        try:
+            page = sess.page
+            if a.state:
+                print(json.dumps(login_state(page), ensure_ascii=False, indent=1))
+            if a.query:
+                print(json.dumps(query_shipment(page, a.query), ensure_ascii=False, indent=1))
+            if a.warehouse_menu:
+                print(json.dumps(warehouse_menu_items(page), ensure_ascii=False, indent=1))
+                page.keyboard.press("Escape")
+        finally:
+            sess.close()          # ⛔ 只关自己这个页（开→办事→关闭）
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())