@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/flow_status_reconcile.py

@@ -0,0 +1,344 @@
+#!/usr/bin/env python3
+"""flow_status_reconcile —— **只读**「表 ⇄ 台账」双向对账（两个方向都要能报出来）。
+
+## 为什么需要它（2026-10-09 一天里两个方向各出现一次）
+
+- **台账 done，表=失败**（本现场，货件 79191341）：引擎把"其实已生效的取消"报成了失败 ⇒
+  表 `FULL状态=失败` / `当前步骤=步骤8 取消预约失败`，而角色自己只读核验后写台账 `done`
+  ⇒ **两处相反**，只有人工改表才对齐（本次就是人工纠正的）。
+  根因已修（步骤3/4/8 加"失败前核验"，见 `scripts/flow_write_verify.py`），但**历史行**与
+  "核验/写表之间再出岔子"的行仍会留下这种错位 ⇒ 需要一条**只读对账**把它们**报出来**。
+- **表=已完成，台账=blocked**（更早出现过）：表说做完了、账本说卡住了 ⇒ 下游（发票流程的
+  开启闸门是 `FULL状态=已完成`）与失败回路读到的"事实"互相矛盾。
+
+⇒ 本命令把两条边**同时**报出来，并给**建议动作**（含同源文案）。
+⛔ **只读**：不写表、不写台账、不派发、不落卡。`FULL状态` / `当前步骤` 的**改写权在人/用户**
+（引擎侧唯一受控写入口是 `_hub_manual_complete` 的"识别为运营手动完成"路径，本命令不碰）。
+
+## 判据（确定性；全部来自注册表 / 台账，⛔ 不猜）
+
+| 报告桶 | 判据 |
+|---|---|
+| `ledger_done_table_failed` | 台账该 case 最后事件 = `done` ∧ 表「状态」∈ 失败值集（注册表 `pick.retryFrom`） |
+| `table_done_ledger_not_done` | 表「状态」∈ 完成值集 ∧ 台账该 case 最后事件 ∈ {failed, blocked, retry, planned, dispatched, requeued} |
+| `consistent_failed` | 表=失败 ∧ 台账=失败/阻塞（一致，无需动作） |
+| `consistent_done` | 表=已完成 ∧ 台账=done（一致） |
+| `table_done_no_ledger_case` | 表=已完成 ∧ 台账**没有该 case**（历史/人工完成，引擎没跑过；信息，**不算错位**） |
+| `table_failed_no_ledger_case` | 表=失败 ∧ 台账**没有该 case**（同上；信息，**不算错位**） |
+| `unknown` | 表「状态」为空/其它（**只报数**，不下结论） |
+
+⚠️ **"台账没有该 case" 不是错位**（2026-10-09 生产实测：读客户 lip 表 530 行，表=已完成 187 行里
+**128 行**属于这种"历史/人工完成"）—— 把它当错位会把真正的矛盾（实测 3 条）淹掉。
+故本命令的 `findings`（= 退出码 1 的来源）**只含两类真矛盾**，其余进桶计数。
+
+## 用法
+
+    python3 scripts/flow_status_reconcile.py --flow full [--examples 3] [--json]
+    python3 scripts/flow_status_reconcile.py --flow full --rows-file rows.json   # 离线夹具（纯回归用）
+    python3 scripts/flow_status_reconcile.py --flow full --ledger /path/flow-ledger.jsonl
+
+退出码：0 = 无错位；1 = 有错位（**只报不改**）；2 = 读取失败。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import subprocess
+import sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+sys.path.insert(0, str(HERE / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+
+import flow_failure as F          # noqa: E402  文案唯一来源（ops_message / case_prefixes）
+import flow_ledger as L           # noqa: E402  台账读取（唯一实现）
+
+CASES = pathlib.Path(resolve_data_dir()['dir']) / 'flow-cases'
+
+CAT_DONE_TABLE_FAILED = 'ledger_done_table_failed'
+CAT_TABLE_DONE_LEDGER_NOT_DONE = 'table_done_ledger_not_done'
+CAT_CONSISTENT_FAILED = 'consistent_failed'
+CAT_CONSISTENT_DONE = 'consistent_done'
+CAT_TABLE_DONE_NO_LEDGER_CASE = 'table_done_no_ledger_case'
+CAT_TABLE_FAILED_NO_LEDGER_CASE = 'table_failed_no_ledger_case'
+CAT_UNKNOWN = 'unknown'
+CATS = (CAT_DONE_TABLE_FAILED, CAT_TABLE_DONE_LEDGER_NOT_DONE,
+        CAT_CONSISTENT_FAILED, CAT_CONSISTENT_DONE,
+        CAT_TABLE_DONE_NO_LEDGER_CASE, CAT_TABLE_FAILED_NO_LEDGER_CASE, CAT_UNKNOWN)
+# **只有这两类是真矛盾**（= findings = 退出码 1 的来源）；其余桶只计数（见模块 docstring）
+CAT_CONTRADICTIONS = (CAT_DONE_TABLE_FAILED, CAT_TABLE_DONE_LEDGER_NOT_DONE)
+
+LABELS = {
+    CAT_DONE_TABLE_FAILED: '❌ 台账 done ✗ 表=失败（本现场：79191341）',
+    CAT_TABLE_DONE_LEDGER_NOT_DONE: '❌ 表=已完成 ✗ 台账未 done（更早出现过）',
+    CAT_CONSISTENT_FAILED: '· 表=失败 ∧ 台账=失败/阻塞（一致）',
+    CAT_CONSISTENT_DONE: '· 表=已完成 ∧ 台账=done（一致）',
+    CAT_TABLE_DONE_NO_LEDGER_CASE: '· 表=已完成 ∧ 台账无该 case（历史/人工完成；不算错位）',
+    CAT_TABLE_FAILED_NO_LEDGER_CASE: '· 表=失败 ∧ 台账无该 case（历史遗留；不算错位）',
+    CAT_UNKNOWN: '? 判不了（表「状态」为空/其它）',
+}
+# 台账事件 → 是否等价于"表做完了"；其余（failed/blocked/retry/planned/dispatched/无）都算"没做完"
+LEDGER_DONE_EVENTS = ('done',)
+LEDGER_OPEN_EVENTS = ('failed', 'blocked', 'retry', 'wake', 'planned', 'dispatched', 'requeued')
+
+
+def _one(v):
+    """飞书单元格取值（list/dict 包装 ⇒ 取标量；与 `invoice_ready_audit.one()` 同口径）。"""
+    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 _text(v) -> str:
+    return str(_one(v) or '').strip()
+
+
+def flow_target(flow: str) -> dict:
+    """该流程的表侧栏位名（复用唯一读取点 `flow_config.py`，它自己会解析 source 变体）。"""
+    r = subprocess.run([sys.executable, str(HERE / '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])
+    doc = json.loads(r.stdout)
+    src = doc.get('source') or {}
+    names = src.get('fields') or {}
+    picks = []
+    for name in ([str(src.get('default') or '')] + list((src.get('variants') or {}).keys()))[::-1]:
+        v = (src.get('variants') or {}).get(name) or {}
+        if v.get('pick'):
+            picks.append(v['pick'])
+    picks.append(src.get('pick') or {})
+    retry_from = []
+    for p in picks:
+        for x in (p.get('retryFrom') or []):
+            if str(x).strip():
+                retry_from.append(str(x).strip())
+    return {'flow': flow, 'names': names, 'retryFrom': retry_from, 'base': src.get('base') or '',
+            'table': src.get('table') or ''}
+
+
+def read_live_rows(flow: str) -> list:
+    """**只读**拉该流程的全部行（不应用 pick 门）。
+
+    与既有的只读清点脚本（`read_flow_rows`）**同一条读取路径**（`flow_source.py --no-pick-filter`
+    + 逐 case 的 `flow-cases/<flow>__<ticket>.json`），本文件自带一份是为了让本命令**可独立分发**
+    （不依赖未进能力包的兄弟脚本）；口径若变，两处必须同改。
+    """
+    p = subprocess.run([sys.executable, str(HERE / 'flow_source.py'), '--flow', flow,
+                        '--source', 'feishu-base', '--no-pick-filter', '--json'],
+                       capture_output=True, text=True, timeout=600)
+    if not p.stdout.strip().startswith('{'):
+        raise RuntimeError((p.stderr or p.stdout).strip()[:300])
+    doc = json.loads(p.stdout)
+    rows = []
+    for item in doc.get('cases') or []:
+        ticket = str(item.get('ticket') or '')
+        f = CASES / f'{flow}__{ticket}.json'
+        fields = {}
+        if f.exists():
+            try:
+                fields = json.loads(f.read_text(encoding='utf-8')).get('fields') or {}
+            except Exception:                                    # noqa: BLE001
+                fields = {}
+        rows.append({'ticket': ticket, 'recordId': str(item.get('recordId') or ''),
+                     'fields': fields, 'missing': item.get('missing') or []})
+    return rows
+
+
+def ledger_index(path: pathlib.Path, flow: str) -> dict:
+    """台账 → `{caseId: {'event','reason','ts','phase','by'}}`（该 case 的**最后一条**事件）。
+
+    前缀口径复用 `flow_failure.case_prefixes()`（规范 id 与旧短名都认）⇒ `--flow full` 与
+    `--flow <业务线>.<流程>` 都能找到同一批 case（台账里写的是当时的名字）。
+    """
+    prefixes = F.case_prefixes(flow) or ()
+    out = {}
+    for e in L.read(path):
+        cid = str(e.get('caseId') or '')
+        if not cid or (prefixes and not cid.startswith(prefixes)):
+            continue
+        out[cid] = e                                   # 文件按时间追加 ⇒ 后者覆盖前者 = 最后一条
+    return out
+
+
+def table_state(fields: dict, names: dict, *, done_values, failed_values) -> tuple:
+    """表侧状态 → `(state, why)`；`state` ∈ {done, failed, other}。"""
+    status_col = str(names.get('status') or '')
+    step_col = str(names.get('step') or '')
+    status = _text((fields or {}).get(status_col)) if status_col else ''
+    step = _text((fields or {}).get(step_col)) if step_col else ''
+    if status and status in done_values:
+        return 'done', f'{status_col}={status}'
+    if status and status in failed_values:
+        return 'failed', f'{status_col}={status}'
+    if step.endswith('失败'):
+        # 状态列既非完成也非失败、但「当前步骤」停在 `<步骤>失败` ⇒ 也是失败态（口径见 _progress_failed_step）
+        return 'failed', f'{step_col}={step}'
+    return 'other', f'{status_col}={status or "（空）"}' + (f'｜{step_col}={step}' if step else '')
+
+
+def classify_pairs(rows: list, ledger: dict, *, flow: str, names: dict,
+                   done_values=None, failed_values=None) -> dict:
+    """把「表行 + 台账最后事件」逐行判桶（**纯函数**：离线夹具可回归，⛔ 不碰表/台账）。
+
+    返回 `{'flow','total','buckets','findings','examples'}`；`findings` 只含两类**错位**，
+    每条带 `suggest`（建议动作）与 `opsMessage`（**同源文案**：`flow_failure.ops_message()`）。
+    """
+    done_values = set(done_values or ['已完成'])
+    failed_values = set(failed_values or ['失败'])
+    prefixes = F.case_prefixes(flow) or (f'{flow}__',)
+    buckets, findings, examples = {}, [], {}
+    for r in rows:
+        ticket = str(r.get('ticket') or '')
+        fields = r.get('fields') or {}
+        cid, ev = '', None
+        for p in prefixes:
+            if f'{p}{ticket}' in ledger:
+                cid, ev = f'{p}{ticket}', ledger[f'{p}{ticket}']
+                break
+        tstate, twhy = table_state(fields, names, done_values=done_values,
+                                   failed_values=failed_values)
+        lev = str((ev or {}).get('event') or '')
+        if tstate == 'done':
+            if lev in LEDGER_DONE_EVENTS:
+                cat = CAT_CONSISTENT_DONE
+            elif not lev:
+                # ⚠️ **不是错位**：表说完成、台账压根没这个 case（历史/人工完成的行，引擎没跑过）
+                cat = CAT_TABLE_DONE_NO_LEDGER_CASE
+            else:
+                cat = CAT_TABLE_DONE_LEDGER_NOT_DONE
+        elif tstate == 'failed':
+            if lev in LEDGER_DONE_EVENTS:
+                cat = CAT_DONE_TABLE_FAILED
+            elif not lev:
+                cat = CAT_TABLE_FAILED_NO_LEDGER_CASE
+            else:
+                cat = CAT_CONSISTENT_FAILED if lev in LEDGER_OPEN_EVENTS else CAT_UNKNOWN
+        else:
+            cat = CAT_UNKNOWN
+        buckets[cat] = buckets.get(cat, 0) + 1
+        examples.setdefault(cat, []).append(ticket)
+        if cat in CAT_CONTRADICTIONS:
+            note_col = str(names.get('note') or '')
+            ledger_reason = F.canonical_reason((ev or {}).get('reason') or (ev or {}).get('error') or '')
+            table_note = _text(fields.get(note_col)) if note_col else ''
+            findings.append({
+                'category': cat,
+                'ticket': ticket, 'caseId': cid or f'{prefixes[0]}{ticket}',
+                'recordId': str(r.get('recordId') or ''),
+                'table': twhy,
+                'ledger': f"{lev or '（无该 case）'}"
+                          + (f"｜reason={ledger_reason[:160]}" if ledger_reason else ''),
+                'tableNote': table_note[:200],
+                'ledgerReason': ledger_reason[:200],
+                # 建议动作（**只读**：本命令不改表、不改台账）
+                'suggest': _suggest(cat, status_col=str(names.get('status') or ''),
+                                    note_col=note_col),
+                # 同源文案（单一来源 flow_failure.ops_message()）—— 供运维照抄
+                'opsMessage': _ops_message(flow, cat, ledger_reason, table_note),
+            })
+    return {'flow': flow, 'total': len(rows), 'buckets': buckets, 'findings': findings,
+            'examples': examples}
+
+
+def _suggest(cat: str, *, status_col: str, note_col: str) -> str:
+    """建议动作（**审计口径**：告诉人去做什么，⛔ 本命令自己不写）。"""
+    if cat == CAT_DONE_TABLE_FAILED:
+        return (f"① 只读复核真相（hub-v2 + 列表页，或查台账该 case 的 done 依据）；"
+                f"② 复核确认已完成后，**由人工/用户**把「{status_col}」置为「已完成」、"
+                f"「{note_col}」更新为核验结论（⛔ 引擎不自动改表状态）；"
+                f"③ 若复核发现其实没完成 ⇒ 按失败处置（表状态改回「失败」并把备注改成真实原因）。")
+    return (f"① 若表确为完成（或 hub-v2 实测完成）⇒ 由角色补一条台账 done："
+            f"`python3 scripts/flow_ledger.py --case-id <caseId> --event done --by <角色> "
+            f"--detail \"依据：hub-v2/列表页实测\"`；"
+            f"② 若实际未完成 ⇒ 按失败重跑（并**由人工**把「{status_col}」改回「失败」）。")
+
+
+def _ops_message(flow: str, cat: str, ledger_reason: str, table_note: str) -> str:
+    """错位行的**同源文案**（`flow_failure.ops_message()` 是唯一措辞来源，⛔ 不另写一套）。
+
+    为什么用 ops_message：运维在表里看到的"结论+动作"与台账/卡片必须是**同一串**
+    （生产实测过的教训：两处口径不一致会把人带偏）。这里把它作为**建议文案**附在对账结果里。
+    """
+    reason = table_note or ledger_reason or ''
+    if reason.startswith('失败：'):
+        reason = reason[len('失败：'):]
+    if not reason:
+        return ''
+    try:
+        return F.ops_message(flow, reason, kind='needs_agent' if cat == CAT_DONE_TABLE_FAILED else None)
+    except Exception:                                            # noqa: BLE001
+        return ''
+
+
+def _load_rows_file(path: str) -> list:
+    """离线夹具：`[{ticket, fields, recordId?}]` 或 `{'rows': [...]}`。"""
+    doc = json.loads(pathlib.Path(path).read_text(encoding='utf-8'))
+    rows = doc.get('rows') if isinstance(doc, dict) else doc
+    return [{'ticket': str(r.get('ticket') or ''), 'recordId': str(r.get('recordId') or ''),
+             'fields': r.get('fields') or {}} for r in (rows or [])]
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description='表 ⇄ 台账 双向只读对账（不自动改表）')
+    ap.add_argument('--flow', default='full', help='流程 id（规范 id 或旧短名，别名都认）')
+    ap.add_argument('--ledger', default=str(L.DEFAULT_LEDGER))
+    ap.add_argument('--rows-file', help='离线夹具行 JSON（给了就不读表）')
+    ap.add_argument('--fields-file', help='离线夹具栏位名 JSON（{"status":…,"step":…,"note":…}）')
+    ap.add_argument('--done-values', help='逗号分隔的"完成"状态值（缺省：已完成）')
+    ap.add_argument('--failed-values', help='逗号分隔的"失败"状态值（缺省：注册表 retryFrom ∪ 失败）')
+    ap.add_argument('--examples', type=int, default=3)
+    ap.add_argument('--json', action='store_true')
+    a = ap.parse_args(argv)
+
+    try:
+        tgt = flow_target(a.flow)
+        names = dict(tgt['names'])
+        if a.fields_file:
+            names.update(json.loads(pathlib.Path(a.fields_file).read_text(encoding='utf-8')) or {})
+        rows = _load_rows_file(a.rows_file) if a.rows_file else read_live_rows(a.flow)
+        ledger = ledger_index(pathlib.Path(a.ledger), a.flow)
+    except Exception as e:                                       # noqa: BLE001
+        print(f'❌ 读取失败：{e}', file=sys.stderr)
+        return 2
+
+    done_values = [x.strip() for x in (a.done_values or '已完成').split(',') if x.strip()]
+    failed_values = [x.strip() for x in (a.failed_values or '').split(',') if x.strip()] \
+        or (tgt['retryFrom'] or []) + ['失败']
+    res = classify_pairs(rows, ledger, flow=a.flow, names=names,
+                         done_values=done_values, failed_values=failed_values)
+    res['ledger'] = str(a.ledger)
+    res['table'] = tgt.get('table') or ''
+    res['readOnly'] = True
+    if a.json:
+        print(json.dumps(res, ensure_ascii=False, indent=2))
+    else:
+        n_bad = len(res['findings'])
+        print(f"\n── {a.flow}｜表 {res['total']} 行 ⇄ 台账 {len(ledger)} case"
+              f"｜**错位 {n_bad} 条**（只读，不改表）")
+        for cat in CATS:
+            n = res['buckets'].get(cat, 0)
+            if not n:
+                continue
+            print(f"   {LABELS[cat]:44} {n:>4}"
+                  + (f"｜例：{', '.join(str(x) for x in res['examples'][cat][:a.examples])}"
+                     if a.examples else ''))
+        for f in res['findings'][:max(0, a.examples)]:
+            print(f"\n   【{f['category']}】{f['ticket']}（caseId={f['caseId']}）")
+            print(f"     表：{f['table']}｜台账：{f['ledger']}")
+            if f['tableNote']:
+                print(f"     表备注：{f['tableNote'][:120]}")
+            print(f"     建议：{f['suggest']}")
+            if f['opsMessage']:
+                print(f"     同源文案（ops_message）：{f['opsMessage'][:200]}")
+        if not n_bad:
+            print("   ✅ 无错位（表与台账两个方向都一致）")
+    return 1 if res['findings'] else 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())