@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/ml_schema_check.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""ML 流程的**数据源字段缺口检查**（事实采集，不做判断）。
+
+分诊层需要的"事实"：**给定数据源的实际字段** vs **某流程声明的必需字段**。
+判断（归谁/能不能跑/要不要人等）交给 SKILL 与角色 —— 本脚本只输出差异，机器可读。
+
+用法：
+    python3 scripts/ml_schema_check.py --flow wenyao-invoice --table <表 id> --profile <身份>
+    python3 scripts/ml_schema_check.py --flow wenyao-invoice --fields-from-json /tmp/fields.json   # 离线（测试/夹具）
+退出码：0 = 字段齐备 ; 1 = 有缺口 ; 2 = 读不到源/参数错误（**区别于"有缺口"**）
+"""
+import argparse, json, subprocess, sys
+from pathlib import Path
+
+REQ = Path(__file__).resolve().with_name("flow-requirements.json")
+
+try:
+    from flow_registry import consumer_doc as _registry_doc
+except Exception:  # noqa: BLE001 —— 半坏机器上退回单文件
+    def _registry_doc(path=None):
+        _p = pathlib.Path(path) if path else REQ
+        return json.loads(_p.read_text(encoding="utf-8"))
+
+LARK = "lark-cli"
+
+
+def live_field_names(table: str, profile: str | None) -> list[str]:
+    """用 lark-cli 读表的实际字段名（live schema）。"""
+    cmd = [LARK]
+    if profile:
+        cmd += ["--profile", profile]
+    cmd += ["base", "+field-list", "--table-id", table, "--format", "json"]
+    out = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+    if out.returncode != 0:
+        raise RuntimeError(f"lark-cli 失败({out.returncode}): {(out.stderr or out.stdout)[:300]}")
+    data = json.loads(out.stdout)
+    items = data.get("items") or data.get("data", {}).get("items") or []
+    return [str(i.get("field_name") or i.get("name") or "") for i in items if i]
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="ML 流程数据源字段缺口检查")
+    ap.add_argument("--flow", required=True)
+    ap.add_argument("--table", default="")
+    ap.add_argument("--profile", default=None)
+    ap.add_argument("--fields-from-json", default=None, help="离线：直接给字段名数组（测试用）")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+
+    try:
+        flows = _registry_doc()["flows"]
+    except Exception as exc:
+        print(f"读取 flow-requirements.json 失败: {exc}", file=sys.stderr)
+        return 2
+    # P2a：旧 id 经**加载器的别名解析**（别再往引擎里写业务线名 —— vertical-lint 会拦）
+    try:
+        import flow_registry
+        _canon = flow_registry.resolve_flow_id(a.flow)
+    except Exception:                                             # noqa: BLE001
+        _canon = a.flow
+    flow = flows.get(_canon)
+    if flow is None:
+        print(f"未知流程: {a.flow}（可选: {', '.join(flows)}）", file=sys.stderr)
+        return 2
+
+    try:
+        if a.fields_from_json:
+            have = [str(x) for x in json.loads(Path(a.fields_from_json).read_text(encoding="utf-8"))]
+        else:
+            table = a.table or flow.get("source", {}).get("table", "")
+            if not table:
+                print("缺 --table（或流程未声明 source.table）", file=sys.stderr)
+                return 2
+            have = live_field_names(table, a.profile or flow.get("source", {}).get("identity"))
+    except Exception as exc:
+        print(f"读不到数据源: {exc}", file=sys.stderr)
+        return 2
+
+    # 字段要求按**当前变体**解析（FULL 的 legacy/lip 列名不同；见 flow_config.load_config）
+    try:
+        import flow_config as _fc
+        _cfg = _fc.load_config(a.flow, strict=False)   # P2a：不要传 base 路径（会退化成单文件）
+        want = _cfg.get("required") or flow["required"]
+    except Exception:
+        want = flow["required"]
+    missing = [f for f in want if f["name"] not in have]
+    # 2026-09-15：同一源列在需求里出现多次（如「重量」对应模板 K/L 两行）时，缺口按名去重
+    _seen, _uniq = set(), []
+    for _m in missing:
+        if _m["name"] in _seen:
+            continue
+        _seen.add(_m["name"])
+        _uniq.append(_m)
+    missing = _uniq
+    extra_hint = [f for f in want if f["name"] in have]
+    result = {
+        "flow": a.flow, "role": flow.get("role"), "ok": not missing,
+        "have": len(have), "required": len(want),
+        "missing": missing, "satisfied": [f["name"] for f in extra_hint],
+    }
+    if a.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(f"流程 {a.flow}（责任角色 {flow.get('role')}）｜数据源字段 {len(have)} 个｜要求 {len(want)} 个")
+        if missing:
+            print(f"\n❌ 缺 {len(missing)} 个字段（分诊层据此落卡并提示补录）：")
+            for f in missing:
+                print(f"  · {f['name']:<16} 用途: {f.get('why') or f.get('usedBy') or '-'}｜应由: {f.get('owner','?')} 补")
+        else:
+            print("\n✅ 字段齐备，可分派给该流程角色")
+    return 0 if not missing else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/engine/scripts/ml_store_ids.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""ML（美客多）店铺 → 卖家 user_id 的**唯一解析入口**（真源：`scripts/ml-store-ids.json`）。
+
+## 为什么要有这个文件（2026-09-19 真实事故）
+同一个概念曾在三处各写一份、键格式还不同，其中鑫中航发票那条线因查不到映射**静默回退**成
+**紫鸟 store_id**（浏览器店铺 ID，如 27494792824433），而不是 ML 卖家 ID（如 2475636269）——
+6 张发票的 PO Number 全写错、无人发现。根因不是"少配一个文件"，而是：
+  · 同一概念多处副本（改一处不改另一处）；
+  · **查不到就用一个"看起来合理"的近似值顶上**（错误被静默吞掉）。
+本模块一次性解决两条：单点真源 + 查不到**响亮失败**（返回空串，调用方必须据此停手，
+绝不回退成另一个 ID 体系的值）。
+
+用法：
+  from ml_store_ids import resolve, load, store_key
+  resolve("墨西哥-2店-子账号")   # → '2475636269'
+  resolve("巴西-1店")            # → ''（未配置 ⇒ 调用方必须停手并报出来）
+"""
+from __future__ import annotations
+
+import json
+import pathlib
+import re
+
+MAP_PATH = pathlib.Path(__file__).resolve().parent / "ml-store-ids.json"
+
+_CACHE: dict | None = None
+
+# 已知「有行但未配置」的店铺（写进文档，让"没配"是显式的而不是撞运气撞出来的）
+UNKNOWN_HINT = ["巴西-1店"]
+
+# 这些店铺**为什么**没有 ID —— 直接写进给运营看的错误信息里（2026-09-19 用户口径：
+# 「巴西-1店当前是没有给到账号的，所以可以写明原因即可」）。
+# 区分"运营还没给账号"（等对方）与"店铺名没认出来"（多半是写法变了/选错行），
+# 因为两者的下一步动作完全不同 —— 混成一句话会让人去查错方向。
+NO_ACCOUNT_YET = {
+    "巴西-1店": "该店铺尚未取得 ML 账号 ID（运营待提供）",
+}
+
+
+def missing_reason(store_name) -> str:
+    """解析不到 ID 时，给**人看**的原因（写进「发票错误信息」/日志）。
+
+    语气刻意是"陈述 + 下一步"，不是"报错"：这是一种已知的、可接受的等待态
+    （巴西店还没账号），不是系统故障。
+    """
+    key = store_key(store_name)
+    if key in NO_ACCOUNT_YET:
+        return NO_ACCOUNT_YET[key]
+    if not key:
+        return f"店铺名「{store_name}」无法识别为『国家-店号』（多半是写法变了或选错了行）"
+    return f"真源 scripts/ml-store-ids.json 里没有「{key}」（新店？请运营提供 ML 账号 ID）"
+
+
+def load(path: pathlib.Path | None = None) -> dict:
+    """读真源（`{_doc..., stores: {'<N>店': '<mlUserId>'}}`）。"""
+    global _CACHE
+    if path is not None:
+        return json.loads(pathlib.Path(path).read_text(encoding="utf-8")).get("stores") or {}
+    if _CACHE is None:
+        _CACHE = json.loads(MAP_PATH.read_text(encoding="utf-8")).get("stores") or {}
+    return _CACHE
+
+
+def parse_store_name(store_name):
+    r"""店铺名 → (国家, '<N>店')；取不到国家返回 ''（历史短名如 '2店-子账号'）。
+
+    拆开国家与本号是**刻意的**：2026-09-19 自测发现，若只用 `(\d+)店` 取键，
+    「**巴西**-1店」会命中「1店」并返回**墨西哥**-1店的 ML ID —— 跨国家静默串号，
+    与本次事故同一类错误（错得"看起来合理"）。lip 表确有 5 行巴西店。
+    """
+    s = store_name
+    if isinstance(s, list):
+        s = s[0] if s else ""
+    if isinstance(s, dict):
+        s = s.get("text") or s.get("name") or ""
+    if s is None:
+        return "", ""
+    text = str(s)
+    m = re.search(r"(\d+)\s*店", text)
+    key = f"{m.group(1)}店" if m else ""
+    c = re.search(r"(墨西哥|巴西|智利|哥伦比亚|阿根廷|秘鲁|乌拉圭)", text)
+    return (c.group(1) if c else ""), key
+
+
+def store_key(store_name) -> str:
+    """店铺名 → 真源键 `<国家>-<N>店`；历史短名（无国家前缀，如 '2店-子账号'）按墨西哥处理。
+
+    "无国家前缀按墨西哥"是**有据**的：短名只出现在 legacy 旧表与旧管线（那时只有墨西哥店），
+    lip 表自身的『店铺』值一律带国家前缀。带国家前缀但该国未配置（如巴西）⇒ 返回原样键，
+    查不到即失败（**不跨国家兜底**）。
+    """
+    country, key = parse_store_name(store_name)
+    if not key:
+        return ""
+    if not country:
+        return f"墨西哥-{key}"          # legacy 短名
+    return f"{country}-{key}"
+
+
+def resolve(store_name, ids: dict | None = None) -> str:
+    """店铺名 → ML user_id；**未配置返回空串**（绝不回退成紫鸟 ID 之类的近似值）。
+
+    调用方契约：返回空串 = **停手并报出来**（写「发票错误信息」/跳过该行），
+    绝不许拿别的 ID 顶上 —— 2026-09-19 的 6 张错发票就是"顶上"顶出来的。
+    """
+    table = ids if ids is not None else load()
+    k = store_key(store_name)
+    if k and k in table:
+        return str(table[k]).strip()
+    # 兜底：整名命中（历史映射里出现过完整名作键的写法）
+    s = str(store_name or "").strip()
+    return str(table.get(s, "")).strip() if s else ""
+
+
+def main(argv=None) -> int:
+    import argparse
+    ap = argparse.ArgumentParser(description="店铺 → ML 卖家 ID 解析（真源 scripts/ml-store-ids.json）")
+    ap.add_argument("store", nargs="?", help="店铺名（如 墨西哥-2店-子账号）；省略则打印全表")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+    table = load()
+    if not a.store:
+        if a.json:
+            print(json.dumps(table, ensure_ascii=False, indent=2))
+        else:
+            print(f"  真源 {MAP_PATH}")
+            for k, v in table.items():
+                print(f"    {k:6} → {v}")
+        return 0
+    v = resolve(a.store)
+    if a.json:
+        print(json.dumps({"store": a.store, "key": store_key(a.store), "mlUserId": v}, ensure_ascii=False))
+    else:
+        print(f"  {a.store}（键 {store_key(a.store) or '—'}）→ {v or '❌ 未配置（不得回退成其它 ID 体系的值）'}")
+    return 0 if v else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())