@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/invoice_ready_audit.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""发票「放行勾」残留巡检（幂等收口）—— 只读优先，`--yes` 才写。
+
+## 为什么需要它（2026-09-18 真实事故）
+「发票就绪」是**运营的放行勾**：发票流程的开启闸门是
+`FULL状态=已完成 ∧ 发票就绪=true`。流程跑完后这个勾**必须被释放**（否则该行在表上
+一直显示"还等着跑"；更危险的是：一旦台账那条 `done` 失效——身份漂移/台账轮转——
+闸门会重新放行 ⇒ **重复开票、重复上传**。当晚 23:17 已真实预演过一次）。
+
+文鳐的收口（`wenyao_run.py` P14）此前**漏了释放**这一步（鑫中航的 runner 一直有）。
+修完之后仍需要一条**独立巡检**：因为历史遗留、异常中断、人工改表都可能再留下同样的状态，
+不能只靠"下一次跑流程时顺手清掉"——已完成的行不会再跑。
+
+判据（刻意很窄，避免误伤）：
+  发票状态 = 已完成  ∧  发票就绪 = true   ⇒  残留（应释放）
+**只**碰 `发票就绪` 一个字段，且走与流程同一个写手（`wenyao-invoice-writeback.mjs --clear-ready`：
+记录白名单 + 写前整行备份 + 写后读回验收 + 审计 + **单向只允许 false**）。
+
+用法：
+  python3 scripts/invoice_ready_audit.py                 # 只读巡检（默认）
+  python3 scripts/invoice_ready_audit.py --json
+  python3 scripts/invoice_ready_audit.py --flow wenyao-invoice --fix --yes   # 真写（逐条走守卫）
+退出码：0 = 无残留（或全部处置成功）；1 = 有残留未处置；2 = 环境/读取失败。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import tempfile
+import pathlib
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+SCRIPTS = ROOT / "scripts"
+WB = SCRIPTS / "wenyao-invoice-writeback.mjs"
+
+# 巡检用的窄投影（按表头名；飞书宽投影会错位，实测教训见 AGENTS.md）
+PROJECTION = ["货件号", "货代公司", "发票状态", "发票就绪"]
+
+
+def is_truthy(v) -> bool:
+    """飞书 checkbox 真值：可能是 True/False 布尔，也可能是 'True'/'False' 字符串。"""
+    if isinstance(v, list):
+        v = v[0] if v else None
+    if isinstance(v, dict):
+        v = v.get("text") or v.get("name")
+    if v is True:
+        return True
+    if v is None or v is False:
+        return False
+    return str(v).strip().lower() in ("true", "1", "yes", "是")
+
+
+def one(v):
+    if isinstance(v, list):
+        v = v[0] if v else None
+    if isinstance(v, dict):
+        v = v.get("text") or v.get("name")
+    return v
+
+
+def resolve_target(flow: str) -> dict:
+    """取该流程的 base/table/identity（复用唯一读取点 flow_config.py）。"""
+    r = subprocess.run([sys.executable, str(SCRIPTS / "flow_config.py"), "--flow", flow, "--json"],
+                       capture_output=True, text=True)
+    if r.returncode != 0 or not r.stdout.strip().startswith("{"):
+        raise RuntimeError((r.stderr or r.stdout).strip()[:300])
+    src = (json.loads(r.stdout).get("source") or {})
+    base, table, profile = str(src.get("base") or ""), str(src.get("table") or ""), str(src.get("identity") or "")
+    if not (base and table and profile):
+        raise RuntimeError(f"流程 {flow} 未解析出 base/table/identity")
+    return {"flow": flow, "base": base, "table": table, "profile": profile}
+
+
+def list_rows(t: dict) -> list[dict]:
+    """窄投影拉全表（ndjson）。
+
+    ⚠️ 实测（2026-09-18）：`--format ndjson` 输出到 **stdout** 时，lark-cli 会先打印一个
+    **跨多行的 manifest 信封**（manifest_version/format/rev/query_context…），逐行 json.loads
+    会在信封行上炸（`'str' object has no attribute 'get'`）。而 `--output ./f.ndjson` 写出的
+    **文件是纯 ndjson**（每行一条记录，无信封）。⇒ 落到临时目录再读文件；`--output` 只接受
+    当前目录下的相对路径，所以用 cwd=临时目录。
+    """
+    cmd = ["lark-cli", "base", "+record-list", "--base-token", t["base"], "--table-id", t["table"],
+           "--as", "bot", "--profile", t["profile"], "--format", "ndjson", "--limit", "2000",
+           "--output", "./rows.ndjson"]
+    for f in PROJECTION:
+        cmd += ["--field-id", f]
+    with tempfile.TemporaryDirectory(prefix="invoice-ready-audit-") as d:
+        r = subprocess.run(cmd, capture_output=True, text=True, cwd=d)
+        p = pathlib.Path(d) / "rows.ndjson"
+        if r.returncode != 0 or not p.exists():
+            raise RuntimeError(((r.stderr or r.stdout).strip() or "无输出")[:300])
+        # ndjson 字段是**扁平**的：字段名与 `record_id` 同级（无 fields 包裹）
+        out = []
+        for line in p.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except Exception:
+                continue
+            if not isinstance(rec, dict):
+                continue
+            rid = rec.get("record_id") or rec.get("_record_id") or ""
+            if not rid:
+                continue
+            out.append({"recordId": rid, "fields": rec})
+        return out
+
+
+def find_leftovers(rows: list[dict]) -> list[dict]:
+    hits = []
+    for r in rows:
+        f = r["fields"]
+        if str(one(f.get("发票状态")) or "").strip() != "已完成":
+            continue
+        if not is_truthy(f.get("发票就绪")):
+            continue
+        hits.append({"recordId": r["recordId"], "货件号": one(f.get("货件号")) or "",
+                     "货代公司": one(f.get("货代公司")) or ""})
+    return hits
+
+
+def release_cmd(flow: str, record_id: str, *, yes: bool) -> list[str]:
+    """释放动作的命令行（**纯函数**，便于回归锁住两条安全性质）。
+
+    安全性质：
+      ① 缺省必须是 `--dry-run`（只有显式 yes=True 才真写）—— 巡检这类批量动作，
+         "忘了加 --yes" 必须表现为**什么都没干**，而不是"悄悄写了一批"；
+      ② 必须带 `--allow-record`（写回器的记录白名单是必填项）—— 不允许出现"能写任意记录"的调用。
+    """
+    return ["node", str(WB), "--flow", flow, "--record-id", record_id, "--allow-record", record_id,
+            "--text-only", "--clear-ready", "--yes" if yes else "--dry-run"]
+
+
+def release(t: dict, record_id: str, *, yes: bool) -> dict:
+    """走**同一个写手**释放放行勾（单向只允许 false + 备份 + 读回 + 审计）。"""
+    r = subprocess.run(release_cmd(t["flow"], record_id, yes=yes), capture_output=True, text=True)
+    return {"rc": r.returncode, "out": (r.stdout or r.stderr).strip()}
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="发票放行勾残留巡检（默认只读；--fix --yes 才写）")
+    ap.add_argument("--flow", default="wenyao-invoice", help="流程 id（决定表与身份）；默认文鳐")
+    ap.add_argument("--fix", action="store_true", help="释放残留的放行勾（需同时 --yes 才真写）")
+    ap.add_argument("--yes", action="store_true", help="真写（缺省 dry-run 预览）")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+
+    try:
+        t = resolve_target(a.flow)
+        rows = list_rows(t)
+    except Exception as e:
+        print(f"❌ 读取失败：{e}", file=sys.stderr)
+        return 2
+
+    hits = find_leftovers(rows)
+    results = []
+    if a.fix:
+        for h in hits:
+            res = release(t, h["recordId"], yes=a.yes)
+            results.append({**h, **res, "done": res["rc"] == 0})
+    if a.json:
+        print(json.dumps({"flow": a.flow, "scanned": len(rows), "leftovers": hits,
+                          "fix": bool(a.fix), "dryRun": not a.yes, "results": results},
+                         ensure_ascii=False, indent=2))
+    else:
+        print(f"  流程 {a.flow}｜扫 {len(rows)} 行｜**放行勾残留 {len(hits)} 条**")
+        for h in hits:
+            print(f"    {h['recordId']}  货件号={h['货件号']}  {h['货代公司']}")
+        for r in results:
+            print(f"    {'✅' if r['done'] else '❌'} {r['recordId']} rc={r['rc']}")
+            for line in (r["out"] or "").splitlines()[-6:]:
+                print(f"        {line}")
+        if hits and not a.fix:
+            print("  （只读巡检：加 `--fix --yes` 才会释放；先 `--fix` 不带 --yes 可预览）")
+        if not hits:
+            print("  ✅ 无残留（已完成的行都已释放放行勾）")
+
+    if not hits:
+        return 0
+    if a.fix and a.yes and all(r["done"] for r in results):
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())