@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/flow_billing.py

@@ -0,0 +1,354 @@
+#!/usr/bin/env python3
+"""flow_billing —— 结果计费：从台账**派生**可计费的成功件 + 月度账单 + value receipt。
+
+为什么是"派生"而不是"跑完时写一笔"（2026-09-21 批 C2/C3 的设计取舍）：
+  · 台账（flow-ledger.jsonl）本来就是**不可变的事实流**（done/failed/blocked/phase…）；
+    计费口径后来才定，派生脚本可以**追溯**已跑过的历史，且随时可复核；
+  · 写时计费会把"口径"烙进业务脚本 —— 改价、改单位、修正误判都要动主链路；
+  · 幂等由 `outcomes.jsonl` 里的 `outcomeId` 保证（同一票只落一次），重复跑不会重复计费。
+
+三条铁规（来自用户口径 + 市场惯例）：
+  ① **只算成功**：只认终态 `done`（failed / blocked / 在飞 一律不计）；
+  ② **一票一结**：同一 caseId 只算一次（重跑、重建、复核留言都不再加倍）；
+  ③ **证据可核**：done 的 detail 必须命中注册表 `billing.units.<cap>.evidence` 里的标记，
+     否则进 `unverified`（列出来给人看，不计费）—— 例：角色发的"交接复核：无需动作"也是 done，
+     但它不是交付物。
+
+用法：
+  python3 scripts/flow_billing.py --report --month 2026-09            # 打账单 + value receipt
+  python3 scripts/flow_billing.py --write                             # 落 outcomes.jsonl（幂等）
+  python3 scripts/flow_billing.py --json --month 2026-09              # 机器可读
+  python3 scripts/flow_billing.py --unverified                        # 只看证据不足的票（人工复核）
+退出码：0 正常；2 参数/读取错误
+"""
+from __future__ import annotations
+import argparse, datetime as dt, hashlib, json, os, pathlib, re, sys, time
+
+HERE = pathlib.Path(__file__).resolve().parent
+REGISTRY = HERE / "flow-requirements.json"
+
+try:
+    from flow_registry import consumer_doc as _registry_doc
+except Exception:  # noqa: BLE001 —— 半坏机器上退回单文件（升级链路要能跑）
+    def _registry_doc(path=None):
+        return json.loads((pathlib.Path(path) if path else REGISTRY).read_text(encoding="utf-8"))
+
+# 数据目录：**唯一判据**在 `scripts/lib/argent_datadir.py`（三级链 `ARGENT_DATA_DIR` →
+# `$DSH_HOME/argent` → `~/.dsh/argent`，与 JS 内核 `core/lib/argent-datadir.mjs` 同语义）。
+# 历史：先**硬编码** ~/.dsh/argent（隔离实例照样读**生产**台账，2026-10-02 修），
+# 后改两级链（不看 DSH_HOME）—— 都不算数：判据只能有一份。
+sys.path.insert(0, str(HERE / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402
+_DATA_DIR = pathlib.Path(resolve_data_dir()['dir'])
+DEFAULT_LEDGER = _DATA_DIR / "flow-ledger.jsonl"
+DEFAULT_OUT = _DATA_DIR / "billing"
+
+# `by` → 流程：历史台账里有一批 caseId **没带流程前缀**（早期只写 record_id），
+# 只能靠记账者反推（`ml-fulfillment`/`full-executor` = FULL；两条发票角色各归各的）。
+BY_FLOW = {
+    "ml-fulfillment": "full", "full-executor": "full", "orchestrator": "full",
+    "gw-ml-invoice-wy": "wenyao-invoice", "wenyao-invoice": "wenyao-invoice",
+    "gw-ml-invoice-xzh": "xzh-invoice", "xzh-invoice": "xzh-invoice",
+}
+FLOW_CAPABILITY: dict = {}          # 运行时从注册表填：flow → capability
+
+
+def load_registry(path: pathlib.Path | None = None) -> dict:
+    return _registry_doc(str(path) if path else None)
+
+
+def _alias_of(flow: str) -> tuple:
+    """指向该流程的所有旧名（P2a：台账里的前缀是**写台账时**的流程名）。"""
+    try:
+        import flow_registry
+        doc = flow_registry.load_doc()
+        return tuple(k for k, v in (doc.get('aliases') or {}).items() if v == flow)
+    except Exception:                                             # noqa: BLE001
+        return ()
+
+
+def flow_of(case_id: str, by: str, flows: set) -> str:
+    """caseId 前缀 → 流程（**规范 id**）；没前缀的用记账者反推；都不行 ⇒ 空串（进 unattributed）。
+
+    P2a：`flows` 里是规范 id（`<vertical>.<flow>`），而台账前缀可能是旧短名 ⇒ 两种都认，
+    返回的始终是规范 id（计费单位/能力归属都按规范 id 查）。
+    """
+    for f in sorted(flows, key=len, reverse=True):
+        if case_id.startswith(f + "__") or any(case_id.startswith(a + "__") for a in _alias_of(f)):
+            return f
+    # 反推值历史上写的是短名 ⇒ 过一遍别名，统一返回规范 id（P2a）
+    guess = BY_FLOW.get(str(by or "").strip(), "")
+    if not guess:
+        return ""
+    try:
+        import flow_registry
+        return flow_registry.resolve_flow_id(guess)
+    except Exception:                                             # noqa: BLE001
+        return guess
+
+
+def capability_of(flow: str, doc: dict) -> str:
+    return str((doc.get("flows", {}).get(flow) or {}).get("capability") or "")
+
+
+def month_of(ts: float) -> str:
+    return dt.datetime.fromtimestamp(float(ts or 0)).strftime("%Y-%m")
+
+
+def evidence_ok(detail: str, patterns: list) -> bool:
+    """证据判据：**全部**标记都要命中（宁可少算，不可多算）。"""
+    text = str(detail or "")
+    if not patterns:
+        return True
+    return all(re.search(str(p), text) for p in patterns)
+
+
+def derive_outcomes(ledger: pathlib.Path, doc: dict) -> dict:
+    """台账 → {outcomes: [...], unverified: [...], unattributed: [...], stores: {...}}（纯函数）。"""
+    flow_caps = {fid: str((f or {}).get("capability") or "") for fid, f in (doc.get("flows") or {}).items()}
+    units = (doc.get("billing") or {}).get("units") or {}
+    billed: dict = {}              # caseId → 已计费的成功件（**一票一结**：同一票只算一次）
+    pending: dict = {}             # caseId → 证据不足的 done（等后续带明细的 done 把它升级）
+    unattributed: list = []
+    unattributed_seen: set = set()
+    stores: dict = {}              # (capability, store) → 出现过的月份集合（日报按店包月要看店数）
+    if not ledger.exists():
+        return {"outcomes": [], "unverified": [], "unattributed": [], "stores": {}}
+    for line in ledger.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            e = json.loads(line)
+        except Exception:
+            continue
+        if str(e.get("event") or "") != "done":
+            continue
+        cid = str(e.get("caseId") or "")
+        if not cid or cid in billed:
+            continue                      # 已计费的票：后续 done（复核留言）不再看
+        flow = flow_of(cid, e.get("by"), set(flow_caps))
+        cap = flow_caps.get(flow) or flow_caps.get(cid.split("__")[0], "")
+        if not flow or not cap:
+            if cid not in unattributed_seen:
+                unattributed_seen.add(cid)
+                unattributed.append({"caseId": cid, "by": e.get("by"), "ts": e.get("ts")})
+            continue
+        spec = units.get(cap) or {}
+        detail = str(e.get("detail") or "")
+        rec = {"capability": cap, "flow": flow, "caseId": cid, "at": float(e.get("ts") or 0),
+               "month": month_of(e.get("ts")), "unit": spec.get("unit", ""),
+               "by": str(e.get("by") or ""), "evidence": detail[:300]}
+        rec["outcomeId"] = hashlib.sha256(f"{cap}|{cid}".encode("utf-8")).hexdigest()[:16]
+        if not evidence_ok(detail, spec.get("evidence") or []):
+            # 证据不足：**不立刻进复核清单** —— 实测有票先记一条不带明细的 done、之后才补记带产物的
+            # done（后补明细）。先记"待定"，等后面的 done 有机会把它升级成计费件。
+            if cid not in billed and cid not in pending:
+                pending[cid] = {**rec, "reason": "done 的 detail 未命中证据标记（可能是复核/无需动作类留言）"}
+            continue
+        if cid in billed:
+            continue                      # 一票一结：已计费过就不再计
+        billed[cid] = rec
+        pending.pop(cid, None)             # 升级：从"证据不足"里移除
+        unattributed_seen.discard(cid)
+        # 日报：从明细里取店铺（幂等标记带 store id；detail 里有「店铺 X」字样）
+        if str(spec.get("mode") or "") == "per_store_month":
+            m = re.search(r"store-([0-9A-Za-z]+)", detail) or re.search(r"店铺\s*([^\s；;，,]+)", detail)
+            store = m.group(1) if m else "(未知店)"
+            stores.setdefault((cap, store), set()).add(str(rec["month"]))
+    return {"outcomes": list(billed.values()), "unverified": list(pending.values()),
+            "unattributed": unattributed, "stores": {f"{k[0]}|{k[1]}": sorted(v) for k, v in stores.items()}}
+
+
+def month_report(derived: dict, doc: dict, month: str) -> dict:
+    """某月的账单 + value receipt（人类可读的数字都在这里算）。"""
+    b = doc.get("billing") or {}
+    units = b.get("units") or {}
+    wage = float(b.get("laborHourlyYuan") or 0)
+    rows, total_fee, total_minutes = [], 0.0, 0.0
+    caps = sorted({o["capability"] for o in derived["outcomes"]} | set(units))
+    for cap in caps:
+        spec = units.get(cap) or {}
+        mine = [o for o in derived["outcomes"] if o["capability"] == cap and o["month"] == month]
+        mode = str(spec.get("mode") or "")
+        if mode == "per_store_month":
+            # 日报：按"这个月出现过推送的店数"× 单价（不按天计件）
+            n = len([k for k, v in derived["stores"].items() if k.startswith(cap + "|") and month in v])
+            label = f"{n} 店×月"
+        elif mode == "per_seat_month":
+            n, label = 0, "按合同（无流程事件）"
+        else:
+            n, label = len(mine), f"{len(mine)} 件"
+        fee = round(n * float(spec.get("rateYuan") or 0), 2)
+        minutes = n * float(spec.get("humanMinutes") or 0)
+        total_fee += fee
+        total_minutes += minutes
+        rows.append({"capability": cap, "unit": spec.get("unit", ""), "count": n, "label": label,
+                     "rateYuan": float(spec.get("rateYuan") or 0), "feeYuan": fee,
+                     "humanMinutes": minutes,
+                     "cases": [o["caseId"] for o in mine][:50]})
+    human_yuan = round(total_minutes / 60.0 * wage, 2)
+    return {
+        "month": month, "currency": str(b.get("currency") or "CNY"),
+        "rows": rows, "totalFeeYuan": round(total_fee, 2),
+        "humanHours": round(total_minutes / 60.0, 1), "humanValueYuan": human_yuan,
+        "laborHourlyYuan": wage,
+        "valueMultiple": (round(human_yuan / total_fee, 1) if total_fee else None),
+        # 两个计数**故意分开**：outcomesRaw = 台账里的成功件事实（日报两天就是两条），
+        # billable = 账单口径的计费单位（日报按店×月合并成 1）—— 混在一起会让人对不上账。
+        "counts": {"billable": sum(r["count"] for r in rows),
+                   "outcomesRaw": len([o for o in derived["outcomes"] if o["month"] == month]),
+                   "unverified": len([o for o in derived["unverified"] if o["month"] == month]),
+                   "unattributed": len(derived["unattributed"])},
+    }
+
+
+def statement_markdown(report: dict, derived: dict, doc: dict, month: str, *, customer: str = "") -> str:
+    """客户版账单（Markdown）：完成件数 → 单价 → 金额；附证据清单与"未计费"说明。
+
+    为什么要有它：工作台那张卡是给我们看的；**能收钱**需要一份客户能复核、能归档、
+    能拿去做对公转账凭据的东西 —— 每一件都能追到台账里的那行证据（只算成功、一票一结）。
+    """
+    b = doc.get("billing") or {}
+    lines = [
+        f"# Argent 服务账单（{month}）",
+        "",
+        f"- 客户：{customer or '（未填写）'}",
+        f"- 计费周期：{month}（自然月）",
+        f"- 计费口径：只计**成功交付**的业务对象；同一票只计一次；失败/交还运营不计费",
+        f"- 单价来源：注册表 `billing.units`（当前为**占位价**，以合同为准）",
+        "",
+        "| 能力 | 计费单位 | 数量 | 单价（元） | 金额（元） |",
+        "|---|---|---:|---:|---:|",
+    ]
+    for r in report["rows"]:
+        if not r["count"] and "合同" not in str(r.get("label", "")):
+            continue
+        lines.append(f"| {r['capability']} | {r['label']} | {r['count']} | {r['rateYuan']:.2f} | {r['feeYuan']:.2f} |")
+    lines += [
+        f"| **合计** |  |  |  | **{report['totalFeeYuan']:.2f}** |",
+        "",
+        f"**本期费用：{report['totalFeeYuan']:.2f} {report['currency']}**",
+        "",
+        "## 价值对账（value receipt）",
+        f"- 本期完成计费单位 **{report['counts']['billable']}**（台账成功件 {report['counts']['outcomesRaw']} 条事实）",
+        f"- 等价人工：**{report['humanHours']} 小时** × {report['laborHourlyYuan']:.0f} 元/小时 = **{report['humanValueYuan']:.2f} 元**",
+        (f"- 价值 / 费用 = **{report['valueMultiple']}×**" if report.get("valueMultiple") else ""),
+        "",
+        "## 证据清单（每件都能在台账里复查）",
+    ]
+    month_cases = [o for o in derived["outcomes"] if o["month"] == month]
+    for o in sorted(month_cases, key=lambda x: x["at"]):
+        when = time.strftime("%m-%d %H:%M", time.localtime(float(o["at"] or 0)))
+        ev = str(o.get("evidence") or "").replace("\n", " ")[:110]
+        lines.append(f"- `{o['caseId']}`｜{o['capability']}｜{when}｜{ev}")
+    if not month_cases:
+        lines.append("-（本期无成功件）")
+    un = [o for o in derived["unverified"] if o["month"] == month]
+    lines += ["", f"## 未计费项（{len(un)} 条，**不计入本期费用**）"]
+    for o in un[:10]:
+        lines.append(f"- `{o['caseId']}`：{o.get('reason', '证据不足')}｜{str(o.get('evidence') or '')[:90]}")
+    if not un:
+        lines.append("-（无）")
+    lines += ["", "---", f"_由 `scripts/flow_billing.py --statement` 生成（{time.strftime('%Y-%m-%d %H:%M')}）；"
+                      f"单价与人工时薪来自注册表，改注册表即改账单口径。_"]
+    return "\n".join(lines)
+
+def render(report: dict, derived: dict, month: str) -> str:
+    L = [f"  账单 {report['month']}（{report['currency']}，单价与人时来自注册表 billing.units —— 目前是占位）",
+         "  " + "-" * 96]
+    for r in report["rows"]:
+        L.append(f"  {r['capability']:16} {r['label']:16} × {r['rateYuan']:>6.2f} = {r['feeYuan']:>8.2f}"
+                 f"   人工等价 {r['humanMinutes']/60.0:>5.1f} 小时")
+    L.append("  " + "-" * 96)
+    L.append(f"  合计费用 {report['totalFeeYuan']:.2f} {report['currency']}"
+             f"｜等价人工 {report['humanHours']} 小时 = {report['humanValueYuan']:.2f} {report['currency']}"
+             f"（时薪 {report['laborHourlyYuan']:.0f}）"
+             + (f"｜价值/费用 = {report['valueMultiple']}×" if report["valueMultiple"] else ""))
+    L.append(f"  本月计费单位 {report['counts']['billable']}（台账成功件 {report['counts']['outcomesRaw']} 条事实）"
+             f"｜证据不足（未计费，待复核）{report['counts']['unverified']}"
+             f"｜无法归属 {report['counts']['unattributed']}")
+    for o in [x for x in derived["unverified"] if x["month"] == month][:5]:
+        L.append(f"    ⚠️ 未计费 {o['caseId']}：{o['reason']}｜{o['evidence'][:80]}")
+    return "\n".join(L)
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="结果计费：台账 → 成功件 → 月结账单 + value receipt")
+    ap.add_argument("--ledger", default=str(DEFAULT_LEDGER))
+    ap.add_argument("--out-dir", default=str(DEFAULT_OUT))
+    ap.add_argument("--month", help="YYYY-MM（缺省=当前月）")
+    ap.add_argument("--report", action="store_true", help="打账单（人类可读）")
+    ap.add_argument("--write", action="store_true", help="把新出现的成功件落 outcomes.jsonl（幂等）")
+    ap.add_argument("--unverified", action="store_true", help="只列证据不足的票")
+    ap.add_argument("--statement", action="store_true",
+                    help="输出**客户版账单**（Markdown：件数/单价/金额 + 价值对账 + 逐件证据）")
+    ap.add_argument("--customer", help="账单抬头（客户名）")
+    ap.add_argument("--out", help="--statement 的落盘路径（省略则打印到 stdout）")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--no-snapshot", action="store_true",
+                    help="只读：不写 <月>.json 快照（工作台控制台轮询用；快照由 --report 或已排期的月结任务写）")
+    a = ap.parse_args(argv)
+
+    try:
+        doc = load_registry()
+    except Exception as exc:                                   # noqa: BLE001
+        print(f"❌ 读取注册表失败：{exc}", file=sys.stderr)
+        return 2
+    ledger = pathlib.Path(a.ledger).expanduser()
+    derived = derive_outcomes(ledger, doc)
+    month = a.month or dt.datetime.now().strftime("%Y-%m")
+
+    if a.unverified:
+        rows = [o for o in derived["unverified"] if o["month"] == month]
+        if a.json:
+            print(json.dumps(rows, ensure_ascii=False, indent=2))
+        else:
+            print(f"  证据不足（不计费）{len(rows)} 条：")
+            for o in rows:
+                print(f"    {o['caseId']:34} {o['capability']:14}｜{o['evidence'][:100]}")
+        return 0
+
+    out_dir = pathlib.Path(a.out_dir).expanduser()
+    if a.write:
+        out_dir.mkdir(parents=True, exist_ok=True)
+        f = out_dir / "outcomes.jsonl"
+        known = set()
+        if f.exists():
+            for ln in f.read_text(encoding="utf-8").splitlines():
+                try:
+                    known.add(json.loads(ln).get("outcomeId"))
+                except Exception:
+                    continue
+        new = [o for o in derived["outcomes"] if o["outcomeId"] not in known]
+        with f.open("a", encoding="utf-8") as fh:
+            for o in sorted(new, key=lambda x: x["at"]):
+                fh.write(json.dumps({**o, "recordedAt": int(time.time())}, ensure_ascii=False) + "\n")
+        print(f"  ✅ outcomes.jsonl：新增 {len(new)} 条（已存在 {len(known)} 条，重复跑不会重复计费）→ {f}")
+
+    report = month_report(derived, doc, month)
+    if a.statement:
+        md = statement_markdown(report, derived, doc, month, customer=a.customer or "")
+        if a.out:
+            pathlib.Path(a.out).expanduser().write_text(md + "\n", encoding="utf-8")
+            print(f"  ✅ 客户版账单已写出：{a.out}")
+        else:
+            print(md)
+        return 0
+    snap = out_dir / f"{month}.json"
+    if not a.no_snapshot:
+        out_dir.mkdir(parents=True, exist_ok=True)
+        snap.write_text(json.dumps({**report, "generatedAt": int(time.time()),
+                                    "unverified": [o for o in derived["unverified"] if o["month"] == month],
+                                    "stores": derived["stores"]}, ensure_ascii=False, indent=2) + "\n",
+                        encoding="utf-8")
+    if a.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        print(render(report, derived, month))
+        print(f"  （快照已写：{snap}）" if not a.no_snapshot else "  （--no-snapshot：未写快照）")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())