@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/ml_artifact_attribution.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""产物归属解析 —— 单店多标签并发时的**第二道防线**（纯函数，无 I/O、无宿主依赖）。
+
+## 为什么需要它（2026-10-09 评估）
+单店多标签页并行跑多票时，同一店铺浏览器只有一个下载目录，两票的**箱唛**会先后落进
+同一个目录。历史上靠"目录里新出现/最新的文件"来认领（`_snapshot_download_dir` 差值），
+同店并行时必然串号（P5 结论，见 `docs/本机接班运行清单.md` §8.12）。
+
+本模块把"文件名 → 哪一票"这件事**变成一个可测的纯函数**，并钉死一条铁律：
+**判不出来就报错，绝不猜**（`ambiguous` / `unmatched` 两个显式出口，没有"取最新"这种兜底）。
+
+## 关键判据：强键 / 弱键（这是"不能靠感觉"的部分）
+从今天台账的真实文件名取证（见 `docs/Argent-ML-FULL-*` 评估文档）：
+
+| 产物 | 原始下载名 | 重命名后（上传飞书的名字） | 含什么键 |
+|---|---|---|---|
+| 箱唛 | `Envio-<货件号>-Etiquetas-de-bultos.pdf` | `79084293-20箱-100张纹身转印纸.pdf` | **货件号** |
+| 产品标 | `Etiquetas-de-producto-<ML码>.pdf` | `产品标+HW-MX-119+MEHQ15678+…+recvvgPQgoUOwx.pdf` | **ML码**（重命名后另有 record_id） |
+
+⇒ **货件号是全局唯一的票级标识；ML码是"产品/listing"级标识，同一 SKU 的两票可能同码。**
+所以：
+
+- **强键（单独命中即可归属，票级唯一）**：`shipment_id`（货件号）、`record_id`（表行号）
+- **弱键（只有"全批次唯一持有者"时才算数）**：`ml_code`
+
+⛔ 这条区分不是洁癖：用户提出的"产品标带 ML 码 ⇒ 可映射"在**同一产品并发两票**时不成立
+（两票 ML 码相同 ⇒ 原始下载名分辨不出来）。因此产品标**不能只靠文件名归属**，
+必须靠第一道防线（逐标签页下载目录，`<下载目录>/<record_id>/`，见 `per_tab_dir()`）。
+本模块是"漏进来之后"的兜底与验收判据，不是唯一防线。
+
+## 冲突处置（⛔ 不许猜）
+- 命中 **≥2 个强键** ⇒ `ambiguous`：文件必须移入 `ambiguous/` 子目录**并且报错**（`plan.ambiguous`）。
+- 命中 **0 个强键、≥2 个弱键** ⇒ `ambiguous`（同上：同 ML 码两票就是这种形态）。
+- 命中 **0 个键** ⇒ `unmatched`：既不入账也不猜，等下一轮或交人工。
+- **强键胜出**：恰有 1 个强键 + 另有弱键重叠 ⇒ 归强键那一票（票级唯一 > 产品级），
+  但 `reason` 里记明重叠，便于事后审计。
+
+跑法（回归）：`scripts/tests/artifact-attribution.test.py`
+"""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Optional, Sequence
+
+# ── CDP 下载落点的作用域事实（设计依据，写死在这里防止文档漂移）──────────────────
+# 权威判据 = CDP 协议定义（`Browser.setDownloadBehavior` 的参数只有 `browserContextId`，
+# 没有 targetId/pageId；`Page.setDownloadBehavior` 已被标 deprecated）：
+#   · Browser.setDownloadBehavior{behavior, browserContextId?, downloadPath, eventsEnabled}
+#     ⇒ 作用域 = **BrowserContext**（省略 browserContextId = 默认 context）⇒ **不能按标签页分**
+#   · Page.setDownloadBehavior ⇒ deprecated，且无 target 参数（靠所在 session 绑定）
+# ⇒ 本项目所有标签页都取 `contexts[0]`（同一登录态）⇒ **CDP 层做不到"每标签页一个 downloadPath"**。
+# 真正可用的逐页隔离 = Playwright 的 `page.on("download")` + `download.save_as(<票目录>)`
+# （生产日志已实证该事件在 connect_over_cdp 下会触发），即 `per_tab_dir()` 的形态。
+CDP_DOWNLOAD_PATH_SCOPE = "browser-context"  # browser | browser-context | page
+CDP_DOWNLOAD_PATH_PER_TAB_OK = False         # ⛔ 不要改成 True 除非协议变了
+
+# ── 解析规则（正则）────────────────────────────────────────────────────────────
+# 货件号：ML 的 shipment id 是 7~10 位纯数字（实测 79084293 / 79103608 / 77840234）
+RE_SHIPMENT_ID = re.compile(r"(?<!\d)(\d{7,10})(?!\d)")
+# ML码：2~6 个大写字母 + 4~10 位数字（实测 MEHQ15678）。刻意**不**匹配 MXCD05（地址码）
+RE_ML_CODE = re.compile(r"(?<![A-Z0-9])([A-Z]{2,6}\d{4,10})(?![A-Z0-9])")
+# record_id：rec + 10~20 位（实测 recvvgPQgoUOwx / recvs4bZSwb3ej）
+RE_RECORD_ID = re.compile(r"(?<![A-Za-z0-9])(rec[A-Za-z0-9]{10,20})(?![A-Za-z0-9])")
+
+# 无关文件（不是本流程的交付物）：按历史实现 `_is_claimed_pdf` 的口径
+RE_IRRELEVANT = re.compile(r"(listado|descargar|preparation)", re.IGNORECASE)
+
+# 产物分类关键词（中英文都认：原始名是西语，重命名后是中文）
+KW_BOX = ("Etiquetas-de-bultos", "箱唛")
+KW_PRODUCT = ("Etiquetas-de-producto", "产品标")
+
+STRONG_KEYS = ("shipment_id", "record_id")
+WEAK_KEYS = ("ml_code",)
+
+# 开关：FULL_STORE_TABS（默认 1 = 零行为变化）。上限 3 是**协议级**上限的做法：
+# 见评估文档「并发上限与收益」——单票实测峰值已达 404~414 次/分，×3 会越过平台退化阈值。
+STORE_TABS_DEFAULT = 1
+STORE_TABS_MAX = 3
+
+
+def store_tabs_from_env(env: Optional[Mapping[str, str]] = None) -> int:
+    """读 `FULL_STORE_TABS`，**默认 1**（= 今天的串行行为，一个开关就能回滚）。
+
+    非法/越界值一律**收敛到合法区间**而不是报错（这是并发开关，不是数据校验点；
+    取 0/负数会让票静默不跑，故下限钉在 1）。读不到 ⇒ 1。
+    """
+    raw = (env if env is not None else os.environ).get("FULL_STORE_TABS")
+    try:
+        n = int(str(raw).strip())
+    except (TypeError, ValueError):
+        return STORE_TABS_DEFAULT
+    return max(1, min(STORE_TABS_MAX, n))
+
+
+def per_tab_dir(base_dir: Any, record_id: str) -> Path:
+    """第一道防线：该票的**专属下载目录**（`<下载目录>/<record_id>/`）。
+
+    record_id 用**完整值**（不是前 8 位）：同批创建的飞书记录前缀相同
+    （`recvs4bZSwb3ej` 与 `recvs4bZSwp6YJ` 同为 `recvs4bZ` 开头），截断会互相覆盖。
+    """
+    rid = str(record_id or "").strip()
+    if not rid:
+        raise ValueError("per_tab_dir 需要非空 record_id（空值会把两票的产物混进同一目录）")
+    if "/" in rid or "\\" in rid or rid in (".", ".."):
+        raise ValueError(f"record_id 含路径分隔符，拒绝拼路径：{rid!r}")
+    return Path(base_dir) / rid
+
+
+# ── 数据结构 ──────────────────────────────────────────────────────────────────
+@dataclass(frozen=True)
+class TicketKeys:
+    """一票的**可匹配键**。字段名与表/引擎口径一致（别名由 `normalize_ticket` 收敛）。"""
+
+    record_id: str = ""
+    shipment_id: str = ""
+    ml_code: str = ""
+    sku: str = ""
+    store: str = ""
+
+    @property
+    def discriminating(self) -> bool:
+        """是否至少有一个可用于归属的键（否则这票无法参与归属判定）。"""
+        return bool(self.shipment_id or self.record_id or self.ml_code)
+
+
+@dataclass(frozen=True)
+class Claim:
+    """一个"这文件像我"的声明。strength: strong=票级唯一键命中；weak=产品级键命中。"""
+
+    record_id: str
+    key: str
+    strength: str          # strong | weak
+    detail: str = ""
+
+
+@dataclass
+class IngestPlan:
+    """归属计划（纯数据）。调用方按 `by_ticket` 上传、按 `ambiguous` 报错并隔离。"""
+
+    by_ticket: dict = field(default_factory=dict)      # record_id -> [(filename, reason)]
+    ambiguous: list = field(default_factory=list)      # [{"file","claimants","reason"}]
+    unmatched: list = field(default_factory=list)      # [filename]（无任何键命中）
+    irrelevant: list = field(default_factory=list)     # [filename]（非本流程产物）
+
+    @property
+    def ok(self) -> bool:
+        """只有"没有歧义"才算干净 —— 未匹配不算错（可能是别的东西），歧义一定是错。"""
+        return not self.ambiguous
+
+    def to_dict(self) -> dict:
+        return {
+            "by_ticket": {k: [n for n, _ in v] for k, v in self.by_ticket.items()},
+            "ambiguous": list(self.ambiguous),
+            "unmatched": list(self.unmatched),
+            "irrelevant": list(self.irrelevant),
+            "ok": self.ok,
+        }
+
+
+# ── 键提取与归一 ──────────────────────────────────────────────────────────────
+def extract_keys(filename: str) -> dict:
+    """从文件名抽出三族键（各为 frozenset，可能多值）。纯函数、不抛异常。"""
+    name = str(filename or "")
+    return {
+        "shipment_id": frozenset(RE_SHIPMENT_ID.findall(name)),
+        "ml_code": frozenset(RE_ML_CODE.findall(name)),
+        "record_id": frozenset(RE_RECORD_ID.findall(name)),
+    }
+
+
+def classify_filename(filename: str) -> str:
+    """`box_label` / `product_label` / `irrelevant` / `other`。"""
+    name = str(filename or "")
+    if RE_IRRELEVANT.search(name):
+        return "irrelevant"
+    if any(k in name for k in KW_BOX):
+        return "box_label"
+    if any(k in name for k in KW_PRODUCT):
+        return "product_label"
+    return "other"
+
+
+# 表字段 → TicketKeys 的别名收敛表（lip / legacy / 引擎内部名都可能出现）
+_FIELD_ALIASES = {
+    "record_id": ("record_id", "recordId", "_record_id", "id"),
+    "shipment_id": ("shipment_id", "shipmentId", "货件号", "货件编号"),
+    "ml_code": ("ml_code", "mlCode", "ML码", "ML编码"),
+    "sku": ("sku", "SKU"),
+    "store": ("store", "store_name", "storeName", "店铺"),
+}
+
+
+def normalize_ticket(src: Any) -> TicketKeys:
+    """把 dict / TicketKeys / 具名对象 收敛成 TicketKeys（缺字段留空，不抛）。"""
+    if isinstance(src, TicketKeys):
+        return src
+    get = src.get if isinstance(src, Mapping) else (lambda k, d=None: getattr(src, k, d))
+    out = {}
+    for canon, aliases in _FIELD_ALIASES.items():
+        val = ""
+        for a in aliases:
+            try:
+                v = get(a)
+            except Exception:                     # noqa: BLE001
+                v = None
+            if v not in (None, ""):
+                val = str(v).strip()
+                break
+        out[canon] = val
+    return TicketKeys(**out)
+
+
+# ── 归属判定 ──────────────────────────────────────────────────────────────────
+def _ml_holders(tickets: Sequence[TicketKeys]) -> dict:
+    """ml_code → 持有它的票数（=1 才够"票级唯一"，才能当强键用）。"""
+    holders: dict = {}
+    for t in tickets:
+        if t.ml_code:
+            holders[t.ml_code] = holders.get(t.ml_code, 0) + 1
+    return holders
+
+
+def claimants(filename: str, tickets: Sequence[TicketKeys]) -> list:
+    """列出所有"自称是本票产物"的票（去重，保留最强的那个键）。空列表 = 无票认领。"""
+    keys = extract_keys(filename)
+    holders = _ml_holders(tickets)
+    out: dict = {}
+    for t in tickets:
+        if not t.record_id:
+            continue                          # 没有 record_id 无法归属（也无法落账）
+        claim: Optional[Claim] = None
+        if t.shipment_id and t.shipment_id in keys["shipment_id"]:
+            claim = Claim(t.record_id, "shipment_id", "strong", f"货件号 {t.shipment_id}")
+        elif t.record_id in keys["record_id"]:
+            claim = Claim(t.record_id, "record_id", "strong", f"record_id {t.record_id}")
+        elif t.ml_code and t.ml_code in keys["ml_code"]:
+            n = holders.get(t.ml_code, 0)
+            if n == 1:
+                claim = Claim(t.record_id, "ml_code", "strong",
+                              f"ML码 {t.ml_code}（全批次唯一持有者）")
+            else:
+                claim = Claim(t.record_id, "ml_code", "weak",
+                              f"ML码 {t.ml_code}（**{n} 票共有**，不足以定票）")
+        if claim is not None:
+            out[t.record_id] = claim
+    return list(out.values())
+
+
+def plan_ingest(filenames: Iterable[str], tickets: Iterable[Any]) -> IngestPlan:
+    """把一批文件名分配给一批票。**判不出就报歧义，绝不猜**（核心判据，纯函数）。"""
+    tks = [normalize_ticket(t) for t in tickets]
+    plan = IngestPlan()
+    for name in filenames:
+        fname = str(name)
+        if classify_filename(fname) == "irrelevant":
+            plan.irrelevant.append(fname)
+            continue
+        claims = claimants(fname, tks)
+        strong = [c for c in claims if c.strength == "strong"]
+        weak = [c for c in claims if c.strength == "weak"]
+        if len(strong) == 1:
+            # 强键票级唯一 ⇒ 归属确定；弱键重叠只记账（不改变结论）
+            extra = ("；另有弱键重叠：" + ", ".join(sorted(c.record_id for c in weak))
+                     if weak else "")
+            plan.by_ticket.setdefault(strong[0].record_id, []).append(
+                (fname, f"强键 {strong[0].detail}{extra}"))
+        elif len(strong) >= 2:
+            plan.ambiguous.append({
+                "file": fname,
+                "claimants": sorted(c.record_id for c in strong),
+                "reason": "命中 ≥2 个票级唯一键（强键冲突）⇒ 移入 ambiguous/ 并报错，不得猜",
+                "keys": sorted({c.key for c in strong}),
+            })
+        elif len(weak) == 1:
+            plan.by_ticket.setdefault(weak[0].record_id, []).append(
+                (fname, f"弱键 {weak[0].detail}"))
+        elif len(weak) >= 2:
+            plan.ambiguous.append({
+                "file": fname,
+                "claimants": sorted(c.record_id for c in weak),
+                "reason": (f"仅弱键（ML码）命中且 {len(weak)} 票共有 ⇒ 不足以定票 ⇒ "
+                           "移入 ambiguous/ 并报错，不得猜"),
+                "keys": sorted({c.key for c in weak}),
+            })
+        else:
+            plan.unmatched.append(fname)
+    return plan
+
+
+def ambiguous_moves(plan: IngestPlan, download_dir: Any,
+                    ambiguous_dirname: str = "ambiguous") -> list:
+    """歧义文件的**隔离动作**（`下载目录/<file>` → `下载目录/ambiguous/<file>`）。
+
+    只算路径、不落盘（保持纯函数）⇒ 便于在夹具里断言，也便于 dry-run 打印。
+    """
+    base = Path(download_dir)
+    dst_dir = base / ambiguous_dirname
+    return [(base / str(a["file"]), dst_dir / str(a["file"]))
+            for a in plan.ambiguous]
+
+
+def apply_moves(moves: Iterable[Any]) -> list:
+    """执行 `ambiguous_moves()` 的搬运（唯一有 I/O 的函数，显式与纯函数分开）。
+
+    目标已存在 ⇒ 加 `.1`/`.2` 后缀，**绝不覆盖**（歧义文件也是证据，不能被吞掉）。
+    """
+    done = []
+    for src, dst in moves:
+        s, d = Path(src), Path(dst)
+        if not s.exists():
+            continue
+        d.parent.mkdir(parents=True, exist_ok=True)
+        target = d
+        i = 0
+        while target.exists():
+            i += 1
+            target = d.with_name(f"{d.stem}.{i}{d.suffix}")
+        s.replace(target)
+        done.append((str(s), str(target)))
+    return done
+
+
+__all__ = [
+    "CDP_DOWNLOAD_PATH_SCOPE", "CDP_DOWNLOAD_PATH_PER_TAB_OK",
+    "STRONG_KEYS", "WEAK_KEYS", "STORE_TABS_DEFAULT", "STORE_TABS_MAX",
+    "TicketKeys", "Claim", "IngestPlan",
+    "store_tabs_from_env", "per_tab_dir",
+    "extract_keys", "classify_filename", "normalize_ticket",
+    "claimants", "plan_ingest", "ambiguous_moves", "apply_moves",
+]