@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/flow_sources/cases_json.py

@@ -0,0 +1,106 @@
+"""cases-json 数据面（P4，2026-09-29）：从 `flow_source.py` **逻辑搬家**（行为不变）。
+
+契约（见 `flow_sources.validate_module`）：`KIND` + `pull_cases(spec, args) -> (exit_code | None, rows)`。
+  · `exit_code is None` ⇒ 拿到了 `rows`（`(票据键, 字段)` 列表，可能为空），**引擎**继续建案 / 缺口检查 / 输出；
+  · `exit_code` 为整数 ⇒ 该数据面自己已给结论并**打印过原因**（再生成失败 / 清单过期 / 读失败 / 空清单）。
+
+⚠️ 这里的"再生成 + 过期守卫"是 **2026-09-18 / 09-20 两次日报静默停摆事故**的修复，
+注释一字未改 —— 它们解释了"为什么读流程声明的清单就必须查过期、不能因为传了 --from-json 就绕过"。
+
+⚠️ 形态说明：它和 feishu-base 一样产出 **rows**（所以 `pull_cases` 与 `pull` 只差"来源"），
+但语义上属于"上游已产出待处理单元"，故用 cases 命名以区别于"外部数据源现读"。
+"""
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import subprocess
+import sys
+import time
+
+from flow_sources.common import read_cases_batch, read_cases_notes
+
+# 引擎脚本目录（本模块在 scripts/flow_sources/ 下）——搬家前这里用的是 flow_source.HERE
+SCRIPTS = pathlib.Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(SCRIPTS / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+
+KIND = 'cases-json'
+
+
+def pull_cases(spec: dict, args):
+    """见模块 docstring 的契约。"""
+    src = spec.get('source') or {}
+    batch = args.from_json or str(src.get('file') or '')
+    if batch and batch != '-':
+        batch = os.path.expanduser(batch)
+        if not os.path.isabs(batch):
+            batch = str(pathlib.Path(resolve_data_dir()['dir']) / batch)
+    # ⚠️ 2026-09-20 二次故障（同一事故复发）：上面的"再生成 + 过期守卫"曾被
+    # `--from-json` **整体绕过** —— 而 flow_triage 生产路径恰恰总是传 `--from-json`，
+    # 于是修复只在"直接调 flow_source"时生效，真实链路里清单**冻结 43 小时**没人发现：
+    # 日报 09-19 14:05（站点本地 00:05）该推的那天静默没推，且因为清单里还写着
+    # "09-17 已推送"，每轮都显示"无票可认领（已推送）"——看起来一切正常。
+    # 定则改为：**读的是流程声明的那个文件 ⇒ 该再生成就再生成、该查过期就查过期**；
+    # 只有读"别处的临时清单"（测试夹具/排障）才跳过 —— 那才是 --from-json 的本意。
+    def _resolved(p: str) -> str:
+        pp = os.path.expanduser(str(p))
+        if not os.path.isabs(pp):
+            pp = str(pathlib.Path(resolve_data_dir()['dir']) / pp)
+        return os.path.abspath(pp)
+
+    declared = str(src.get('file') or '')
+    reading_declared = bool(declared) and batch != '-' and _resolved(batch) == _resolved(declared)
+
+    # ── 源的"再生成"（2026-09-18 真实故障：日报静默停摆一整天）────────────────
+    # 日报的待办单元不是静态文件，而是「店铺 × 站点本地日期 × 幂等标记」的差集，
+    # 由 daily-report-inbox.py 算出。此前**没有任何调用方**（不在触发器、不在插件、
+    # cron 已清空）⇒ 清单冻结在 09-17 10:57 的旧内容，其唯一单元早已被影子轮消费
+    # （台账 done）⇒ 之后每轮都是"无票可认领"（看起来一切正常，实际当天永不推送）。
+    # 约定：流程在 `source.regenerate` 里声明生成器，源适配器读之前先跑它；
+    # 生成失败**响亮停住**（exit 2），绝不退化成"0 票"。
+    regen = src.get('regenerate') or {}
+    if regen and reading_declared and not getattr(args, 'no_regenerate', False):
+        script = str(regen.get('script') or '')
+        if script:
+            cmd = [sys.executable, str(SCRIPTS / script)] + [str(x) for x in (regen.get('args') or [])]
+            env = dict(os.environ)
+            env.setdefault('ARGENT_DATA_DIR', resolve_data_dir()['dir'])   # 传给再生成器（唯一判据解析出来的）
+            try:
+                r = subprocess.run(cmd, capture_output=True, text=True, env=env,
+                                   timeout=int(regen.get('timeoutSec') or 120))
+            except Exception as e:
+                print(f'❌ 源再生成异常（{script}）: {e}', file=sys.stderr)
+                return 2, []
+            if r.returncode != 0:
+                print(f'❌ 源再生成失败（{script}，exit={r.returncode}）：'
+                      f'{(r.stderr or r.stdout).strip()[:300]}', file=sys.stderr)
+                return 2, []
+    # 过期守卫：生成器没在跑 ⇒ 清单会一直"合法地空" ⇒ 必须响亮暴露（不许静默 0 票）
+    max_age = int(src.get('maxAgeSec') or 0)
+    if (max_age and batch and batch != '-' and reading_declared
+            and not getattr(args, 'no_regenerate', False) and pathlib.Path(batch).exists()):
+        age_sec = time.time() - pathlib.Path(batch).stat().st_mtime
+        if age_sec > max_age:
+            print(f'❌ 批量清单过期（{int(age_sec / 60)} 分钟未更新，上限 {max_age // 60} 分钟）：{batch}'
+                  f' —— 上游生成器未在运行，本轮不派发', file=sys.stderr)
+            return 2, []
+    try:
+        rows = read_cases_batch(batch)
+    except Exception as e:
+        print(f'❌ 读取批量清单失败（{batch or "stdin"}）: {e}', file=sys.stderr)
+        return 2, []
+    notes = read_cases_notes(batch)
+    if not rows:
+        # 空清单是**合法结论**（当前没有待处理单元）⇒ exit 0，
+        # 让分诊给出"无票可派"而不是报错（否则定时轮每小时刷一条假错误）；
+        # 但**必须带上原因**（未到点/已推送/窗口已过），否则运维看到的是"无票可认领"
+        # 这种没有信息量的结论 —— 2026-09-18 用户实测正是被它误导。
+        if args.json:
+            print(json.dumps({'flow': args.flow, 'source': args.source, 'cases': [], 'exit': 0,
+                              'notes': notes}, ensure_ascii=False, indent=2))
+        else:
+            print('  · 批量清单为空（当前没有待处理单元）' + (f'：{"；".join(notes)}' if notes else ''))
+        return 0, []
+    return None, rows

package/engine/scripts/flow_sources/common.py

@@ -0,0 +1,428 @@
+"""数据面共享原语（P4）：读表/收窄/票据键/字段缺口 —— 引擎与各实现共用。
+
+从 `flow_source.py` **原样搬出**（纯搬家，不改行为）；`flow_source.py` 继续再导出这些名字，
+历史调用点（`flow_triage` 的 `_truthy`、`flow_retry` 的 `load_allowed_stores`、测试的
+`ticket_key`/`wanted_pick_columns`/`apply_pick`）不感知这次搬迁。
+"""
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import subprocess
+import sys
+import time
+
+TRANSIENT_PAT = (
+    'context deadline exceeded', '"subtype":"transport"', '"subtype":"timeout"',
+    'subtype": "transport', 'subtype": "timeout', 'socket hang up', 'ETIMEDOUT',
+    'ECONNRESET', 'EPIPE', 'accounts.feishu.cn/oauth', 'network',
+)
+
+CMD_TIMEOUT_SEC = int(os.environ.get('ARGENT_CMD_TIMEOUT') or 120)   # 单次外部命令硬超时
+
+CMD_RETRIES = int(os.environ.get('ARGENT_CMD_RETRIES') or 3)
+
+# ── 相位（**唯一真源**）────────────────────────────────────────────────────────
+# `apply_pick()` 给每行打的 `_phase` **只从这一份取**；门禁 `check-sop-consistency.mjs` 的 C2
+# （提示词里提到的相位 ⊆ 引擎实际产出的相位）经 `flow_source.py --list-phases` **问这里**。
+# ⛔ 不要在别处再抄一份相位名单：2026-10-08 修的正是这个形态 —— 门禁在 Node 侧另抄了一份，
+#    又用正则去解析**源码文本**；P4（2026-09-29）把赋值从 `flow_source.py` 搬进本文件后，
+#    那次解析恒得**空集**，C2 变成"空集 ⊆ 任何集合"的**静默空转**（输出里 `引擎产出（）`）。
+PHASES = ('identify', 'execute', 'await_release', 'retry', 'needs_human')
+# 赋值点用这组名字（与 PHASES 同源），避免字面量在代码里再散一份
+PHASE_IDENTIFY, PHASE_EXECUTE, PHASE_AWAIT_RELEASE, PHASE_RETRY, PHASE_NEEDS_HUMAN = PHASES
+
+def _is_transient(text: str) -> bool:
+    t = (text or '').lower()
+    return any(pat.lower() in t for pat in TRANSIENT_PAT)
+
+def run(cmd: list[str], timeout: int = None, retries: int = None) -> tuple[int, str, str]:
+    """跑外部命令（lark-cli 读表等）——**必须带超时**。
+
+    为什么（2026-09-22 事故）：飞书 API 出现半开连接时 `lark-cli` **永不返回**，而这里原本
+    没有超时 ⇒ `flow_triage.py` 卡死，文鳐/鑫中航两个定时器各自冻结 **4 小时 51 分**：
+    日志停在那一刻、没有任何报错、认领锁一直被占，整条发票流程静默停摆。
+    超时按 124（GNU timeout 约定）返回，调用方据此走"响亮失败"分支。
+    瞬时网络错误（网关超时/连接重置）按指数退避重试，避免一次抖动就记一条人工处理。
+    """
+    timeout = timeout or CMD_TIMEOUT_SEC
+    retries = retries if retries is not None else CMD_RETRIES
+    last = (124, '', f'命令超时 {timeout}s（{cmd[0]} …）')
+    for attempt in range(max(1, retries)):
+        try:
+            p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        except subprocess.TimeoutExpired:
+            last = (124, '', f'命令超时 {timeout}s（{cmd[0]} …）')
+            if attempt + 1 < retries:
+                time.sleep(min(2 ** attempt, 8))
+            continue
+        if p.returncode != 0 and _is_transient(p.stderr) and attempt + 1 < retries:
+            last = (p.returncode, p.stdout, p.stderr)
+            time.sleep(min(2 ** attempt, 8))
+            continue
+        return p.returncode, p.stdout, p.stderr
+    return last
+
+def read_cases_batch(path: str) -> list:
+    """读取**批量**待处理清单（cases-json）。
+
+    接受三种形状（宽松，便于各系统导出直接用）：
+      [{"ticketKey": "站点-日期-id", "fields": {...}}, ...]
+      {"cases": [ ...同上... ]}
+      {"<ticketKey>": { ...直接是字段... }, ...}
+    返回 [(ticketKey, fields)]；形状不对的条目跳过（不静默造假数据）。
+    """
+    raw = sys.stdin.read() if (not path or path == '-') else pathlib.Path(path).read_text(encoding='utf-8')
+    doc = json.loads(raw)
+    items = None
+    if isinstance(doc, dict) and isinstance(doc.get('cases'), list):
+        items = doc['cases']
+    elif isinstance(doc, list):
+        items = doc
+    elif isinstance(doc, dict):
+        items = [{'ticketKey': k, 'fields': v} for k, v in doc.items()]
+    out = []
+    for it in items or []:
+        if not isinstance(it, dict):
+            continue
+        tk = it.get('ticketKey') or it.get('ticket') or it.get('key')
+        fields = it.get('fields')
+        if fields is None:
+            fields = {k: v for k, v in it.items() if k not in ('ticketKey', 'ticket', 'key')}
+        if tk and isinstance(fields, dict):
+            out.append((str(tk), fields))
+    return out
+
+def read_cases_notes(path: str) -> list:
+    """批量清单里的"为什么没有待处理单元"说明（`notes` / `skipped`）。
+
+    日报这类流程的清单由生成器算出：空清单可能是"今天已推送"、"还没到推送点"、
+    "错过补推窗口"——三种结论对运维的意义完全不同 ⇒ 必须一路带到触发器日志里。
+    """
+    if not path or path == '-':
+        return []
+    try:
+        doc = json.loads(pathlib.Path(path).read_text(encoding='utf-8'))
+    except Exception:
+        return []
+    if not isinstance(doc, dict):
+        return []
+    out = []
+    for n in (doc.get('notes') or []):
+        if isinstance(n, str) and n.strip():
+            out.append(n.strip())
+    if out:
+        return out[:6]          # 生成器已给出原因 ⇒ 不再从 skipped 重复推导
+    for it in (doc.get('skipped') or []):
+        if isinstance(it, dict):
+            store = it.get('store') or it.get('storeKey') or ''
+            why = it.get('reason') or it.get('why') or ''
+            if store or why:
+                out.append(f'{store} {why}'.strip())
+        elif isinstance(it, str) and it.strip():
+            out.append(it.strip())
+    return out[:6]
+
+def read_fields(path: str) -> dict:
+    raw = sys.stdin.read() if path == '-' else pathlib.Path(path).read_text(encoding='utf-8')
+    v = json.loads(raw)
+    if isinstance(v, dict) and 'fields' in v and isinstance(v['fields'], dict):
+        v = v['fields']          # 兼容直接传 case 文件
+    if not isinstance(v, dict):
+        raise ValueError('字段必须是 JSON 对象')
+    return v
+
+def _flat(v):
+    """把飞书单元格值归一化：单元素数组展开、多元素拼接、None → 空串。"""
+    if v is None:
+        return ''
+    if isinstance(v, list):
+        parts = [_flat(x) for x in v]
+        parts = [x for x in parts if x != '']
+        return parts[0] if len(parts) == 1 else ' | '.join(parts)
+    if isinstance(v, dict):
+        for k in ('text', 'name', 'value', 'file_name'):
+            if k in v:
+                return _flat(v[k])
+        return json.dumps(v, ensure_ascii=False)[:200]
+    return str(v)
+
+def _has_value(v) -> bool:
+    """字段**真有值**吗（缺口判据用，2026-09-17 P4 实测修正）。
+
+    为什么需要它：`ml_schema_check` 离线模式的判据是"这个字段名在不在提供的名单里"，
+    而 `fields` 里**投影到的每一列都存在**（空单元格 = `''`）⇒ 若不过滤空值，
+    「发票就绪」（运营放行 checkbox，未勾选时接口返回空）会被算作**已提供** ⇒
+    全表只要有 `货代公司=上海文鳐` 就判"字段齐备"，分诊直接 `to_dispatch`
+    （2026-09-17 实测：lip 表 535 行 → 文鳐 90 行 → 分诊报可派发 83，而人工核对只有个位数真候选）。
+
+    判据：`None`／空白串／空容器 ⇒ 未提供；**`False` 与字符串 `False`/`false` 也视为未提供**
+    （飞书 checkbox 未勾选在部分接口形态下就返回这两种值，放行开关必须因此挡住）；
+    数字 0、字符串 `'0'`、`'否'` 等**算有值**（是真取值，不是缺省）。
+    """
+    if v is None or v is False:
+        return False
+    if isinstance(v, str):
+        return v.strip() not in ('', 'False', 'false')
+    if isinstance(v, (list, tuple, dict, set)):
+        return len(v) > 0
+    return True
+
+LAST_NARROW: dict = {}    # 记录「候选收窄把行清空」这一合法情形（见 pull_feishu）
+
+LAST_PICK_NOTES: list = []  # 候选收窄的说明（跨函数传：pull_feishu → main 的 JSON 输出）
+
+def _truthy(v) -> bool:
+    """checkbox 类字段的**真值**判断（2026-09-17 实测补）。
+
+    坑：`_flat()` 把飞书布尔值转成字符串 ⇒ 未勾选是 `'False'`，而它是**非空字符串**，
+    直接 `if v` 会判成"真" ⇒ 放行门（就绪）/就绪类开关会被绕过，未放行的行照样被派发。
+    判据：`None`/`False`/空白/`false`/`0`/`no`/`否`/`未`/`空` ⇒ 假；其余非空 ⇒ 真。
+    """
+    if v is None or v is False:
+        return False
+    if isinstance(v, str):
+        return v.strip().lower() not in ('', 'false', '0', 'no', '否', '未', '空')
+    if isinstance(v, (list, tuple, dict, set)):
+        return len(v) > 0
+    return bool(v)
+
+def load_allowed_stores(path: str) -> set:
+    """读 `stores.json`（本机紫鸟已授权的店：名 → {store_id, cdp_port}）取**可驱动的店名集合**。
+
+    用途（`pick.onlyStoresFrom`）：本机只授权了客户 6 家里的 3 家 ⇒ 其余行的店铺我们**驱动不了**。
+    旧行为下识别层会把它们判成"未授权"并**把「跳过」写进生产表**（写脏数据）；加了这层收窄后，
+    不属于本机授权店的行**根本不进候选**——不派发、也不写任何字段，等本机授权补齐再说。
+    """
+    import json as _json
+    if not path:
+        return set()
+    p = pathlib.Path(os.path.expanduser(str(path)))
+    try:
+        doc = _json.loads(p.read_text(encoding='utf-8'))
+    except Exception:
+        return set()
+    if isinstance(doc, dict) and isinstance(doc.get('stores'), dict):
+        doc = doc['stores']                     # 兼容 {stores:{…}} 包装
+    return set(doc.keys()) if isinstance(doc, dict) else set()
+
+def wanted_upstream_columns(src: dict) -> list[str]:
+    """**上游变化观察列**（`pick.releaseReDispatch.upstreamHash.watch`，真列名）—— 必须进投影。
+
+    2026-10-13（放行额度随上游数据变化重置）：判据是"该票上游行走流程读取的字段变了没有"，
+    而 case 文件只装**投影到**的列 ⇒ 不在投影里的列（如发票流程的 `产品图`：运营补了它、
+    流程也需要它，却从不出现在 case 里）**永远不会被算作"变"**。
+    与 `wanted_pick_columns` 同一形状（都返回真列名，由 feishu_base 拼进投影），
+    但**语义不同**：pick 列缺失是硬故障（过滤读空 ⇒ 静默收窄到 0 行），
+    观察列缺失只是判据更窄 ⇒ 调用方**静默跳过该列**（⛔ 不硬失败）。
+    """
+    rd = ((src.get('pick') or {}).get('releaseReDispatch') or {})
+    up = rd.get('upstreamHash') or {}
+    out, seen = [], set()
+    for nm in (up.get('watch') or []):
+        nm = str(nm).strip()
+        if nm and nm not in seen:
+            seen.add(nm)
+            out.append(nm)
+    return out
+
+
+def wanted_pick_columns(src: dict) -> list[str]:
+    """`pick` 规则要用到哪些**真列名**（投影必须覆盖它们，否则过滤读到空值 → 静默收窄到 0 行）。
+
+    2026-09-17 实测事故：FULL lip 变体的 `pick.status=FULL状态`、`pick.ready=就绪` 两列既不在
+    `required` 里、也不是路由/票号列 ⇒ 没进投影 ⇒ 每行这两列都是空 ⇒ 530 行全部被"收窄"掉，
+    日志只显示「候选收窄 100 → 0 行」，看起来像"今天没活干"。判据来源：
+      · `pick.status` → `source.fields.status`（领域名→真列名，缺省按领域名）
+      · `pick.ready`（只要声明了，无论真假）→ `source.fields.ready`
+      · `pick.equals` 的键、`pick.requireEmpty` 的元素 —— 这两处写的**已经是真列名**
+    """
+    sf = src.get('fields') or {}
+    pk = src.get('pick') or {}
+    doms: list[str] = []
+    if pk.get('status'):
+        doms.append('status')
+    if pk.get('ready') is not None:
+        doms.append('ready')
+    doms += list((pk.get('equals') or {}).keys())
+    doms += list(pk.get('requireEmpty') or [])
+    rel = pk.get('release') or {}
+    if rel.get('field'):
+        doms.append(str(rel['field']))       # release.field 写的是真列名（如「就绪」）
+    if pk.get('onlyStoresFrom'):
+        doms.append('store')                 # 店铺收窄要用到店铺列（fields.store → 真列名）
+    if pk.get('retryFrom'):
+        doms.append('note')                  # 失败分类要读备注（fields.note → 真列名）
+    out, seen = [], set()
+    for d in doms:
+        nm = str(sf.get(d) or d)
+        if nm not in seen:
+            seen.add(nm); out.append(nm)
+    return out
+
+def apply_pick(rows: list[dict], src: dict, *, no_pick_filter: bool = False):
+    """按流程声明的 `pick` 收窄候选行，并标出每行的**阶段**（纯函数，便于离线回归）。
+
+    阶段（2026-09-17 用户口径 F5「triage 即识别层」）：
+      · `identify`      —— 状态为空 = 未识别的新行（角色只做识别：写「待执行」/「跳过」+备注）
+      · `execute`       —— 已识别 且 放行门通过（`pick.release`/`pick.ready`）
+      · `await_release` —— 已识别 但运营还没勾放行（分诊只报数、不派发、不落卡）
+
+    放行门只对**已识别**的行生效；真值判断走 `_truthy()`（`'False'` 不算放行）。
+    返回 `(rows, meta)`，meta 含 before/rule/detail 供上层打日志与判「收窄到 0」。
+    """
+    pick = src.get('pick') or {}
+    if not pick or no_pick_filter:
+        return rows, {'before': len(rows)}
+    names = src.get('fields') or {}
+    want_status = [str(x).strip().lower() for x in (pick.get('status') or [])]
+    equals = {str(k): str(v).strip().lower() for k, v in (pick.get('equals') or {}).items()}
+    status_col = names.get('status')
+    ready_col = names.get('ready')
+    require_empty = list(pick.get('requireEmpty') or [])
+    # 已（人工/自动）完成的排除规则（2026-09-22 用户口径：lip 表里大量行是客户运营**人工完成**的
+    # 历史数据，必须分辨清楚）：命中即不进候选，也不写任何字段，只计数上报。
+    #   · excludeEquals    {列: [值,…]}        任一命中 ⇒ 排除
+    #   · excludeAllPresent [[列,…],…]         某一组**全部非空** ⇒ 排除（"两个产物都在"才算做完）
+    excl_equals = {str(k): [str(x).strip().lower() for x in (v if isinstance(v, list) else [v])]
+                   for k, v in (pick.get('excludeEquals') or {}).items()}
+    excl_all = [[str(c) for c in grp] for grp in (pick.get('excludeAllPresent') or []) if grp]
+    dropped_done = 0
+    release = pick.get('release') or {}
+    rel_col = release.get('field') or ready_col
+    rel_want = release.get('equals', True)
+    # 店铺收窄（2026-09-17）：只处理**本机紫鸟已授权**的店；其余行不进候选、也不写任何字段。
+    store_col = names.get('store') or pick.get('storeField') or ''
+    allowed = load_allowed_stores(pick.get('onlyStoresFrom') or '') if pick.get('onlyStoresFrom') else set()
+    dropped_store = 0
+    keep = []
+    # 计数字典的相位键**从 PHASES 派生**（唯一真源）；`excludedDone` 不是相位，是"已完成排除"的计数
+    phases = {p: 0 for p in PHASES}
+    phases['excludedDone'] = 0
+    for r in rows:
+        if equals and any(str(r.get(col) or '').strip().lower() != want for col, want in equals.items()):
+            continue
+        if excl_equals and any(str(r.get(col) or '').strip().lower() in vals
+                               for col, vals in excl_equals.items()):
+            dropped_done += 1
+            continue
+        if excl_all and any(all(str(r.get(c) or '').strip() for c in grp) for grp in excl_all):
+            dropped_done += 1
+            continue
+        if allowed and store_col:
+            st = str(r.get(store_col) or '').strip()
+            # 只有**写了店名但本机没授权**的行才剔除（我们驱动不了，且不该写「跳过」）；
+            # **店铺为空**的行要留下 —— 那是"缺字段"，由 triage 归入 need_fields 让人补，
+            # 直接吞掉会让这批行彻底从视野里消失（2026-09-17 实测：91 行差一点被吞）。
+            if st and st not in allowed:
+                dropped_store += 1
+                continue
+        got = str(r.get(status_col) or '').strip().lower() if status_col else ''
+        identified = bool(got)          # ⚠️ 必须在 retry 分支**之前**定义（否则会用到上一行的值）
+        # 2026-09-18 实测修：**失败行的重跑分支必须先于状态门**。
+        # 上一版把 retry 分支放在 requireEmpty 之前（对），但仍放在 `want_status` 之后（错）——
+        # 而 `pick.status` 只含 ["", "待执行"]，`失败` 根本不在其中 ⇒ 行在状态门就被
+        # `continue` 掉，**retryFrom 分支实际不可达**（实测：77445732 / recvvgPQgoB4qL
+        # `FULL状态=失败` 在分诊结果里彻底不出现，plan.retry 恒为 0）。
+        # 这正是注释里说的"第一版踩的坑"——只是差了**一步**位置。失败行天然带非空状态，
+        # 所以必须独立于"候选状态集合"判定。
+        retry_from = [str(x).strip().lower() for x in (pick.get('retryFrom') or [])]
+        if identified and status_col and got in retry_from:
+            note_col = names.get('note') or ''
+            text = str(r.get(note_col) or '') if note_col else ''
+            try:
+                from flow_failure import classify as _classify
+                res = _classify(text, attempt=int((pick.get('retry') or {}).get('attempt', 1)),
+                                max_attempts=int((pick.get('retry') or {}).get('maxAttempts', 3)))
+                # classify() 返回 dict（{kind, reason, error}）—— 第一版按字符串比，结果全落到 needs_human
+                kind = str((res or {}).get('kind') or 'needs_agent') if isinstance(res, dict) else str(res)
+            except Exception:
+                kind = 'needs_agent'
+            r['_phase'] = PHASE_RETRY if kind == 'retryable' else PHASE_NEEDS_HUMAN
+            r['_failureKind'] = kind
+            phases[r['_phase']] = phases.get(r['_phase'], 0) + 1
+            keep.append(r)
+            continue
+        if want_status and status_col and got not in want_status:
+            continue
+        if require_empty and any(str(r.get(c) or '').strip() for c in require_empty):
+            continue
+        released = True
+        if identified and rel_col:
+            curr = r.get(rel_col)
+            released = (_truthy(curr) if rel_want is True
+                        else str(curr or '').strip().lower() == str(rel_want).strip().lower())
+        r['_phase'] = (PHASE_IDENTIFY if not identified
+                       else (PHASE_EXECUTE if released else PHASE_AWAIT_RELEASE))
+        phases[r['_phase']] += 1
+        keep.append(r)
+    rule = ('、'.join(f'{k}={v}' for k, v in (pick.get('equals') or {}).items())
+            or f'状态∈{pick.get("status") or "-"}')
+    if rel_col:
+        rule += f' ∧（已识别的行）{rel_col}=放行'
+    if require_empty:
+        rule += f' ∧ {"、".join(require_empty)}为空'
+    # 2026-09-18：失败行的重跑旁路必须写进规则文案 —— 否则日志只显示「货件号为空」，
+    # 运维/角色会以为"失败的行（货件号非空）根本不会被拾取"，与实测相反（实测 77445732 会进）。
+    if (pick.get('retryFrom') or []):
+        rule += (f'；**例外**：状态∈{"、".join(str(x) for x in pick["retryFrom"])} 的行'
+                 f'**不受上面任何一条限制**（按失败分类器分流 retry/needs_human）')
+    if allowed:
+        rule += f' ∧ {store_col or "店铺"}∈本机已授权 {len(allowed)} 店'
+    if excl_equals or excl_all:
+        bits = [f'{k}∈{"、".join(v)}' for k, v in excl_equals.items()]
+        bits += ['且'.join(grp) + '都已填' for grp in excl_all]
+        rule += f'；**排除**：{"；".join(bits)} ⇒ 视为已完成，不进候选'
+    detail = '、'.join(f'{k} {v}' for k, v in phases.items() if v)
+    if dropped_store:
+        detail += (('，' if detail else '') + f'店未授权跳过 {dropped_store}')
+    if dropped_done:
+        detail += (('，' if detail else '') + f'已完成排除 {dropped_done}')
+    phases['excludedDone'] = dropped_done
+    return keep, {'before': len(rows), 'rule': rule, 'phases': phases, 'detail': detail,
+                  'allowedStores': len(allowed), 'droppedStore': dropped_store,
+                  'droppedDone': dropped_done}
+
+def ticket_key(rec: str, fields: dict, ticket_field: str, mode: str = '') -> str:
+    """行的**身份**（caseId 的后半段）。
+
+    2026-09-18 二次修正（第一次改错了，见下）：身份**必须逐流程选**，不能一刀切。
+    各流程的既有约定（实测 flow-ledger.jsonl 去重计数）：
+      · `full`            → **record_id**（19/19）。因为 FULL 是**流程中途才建出货件号**：
+        派发时「货件号」为空、身份只能是 record_id；若改成"票号列优先"，同一条票在
+        建单失败后会**换成第二个身份**（full__<货件号>），于是与失败台账 caseId 对不上
+        （查不到事件 ⇒ blocked 的票被当成"全新票"自动重派，绕过"needs_human 不许自动派发"）。
+      · `wenyao-invoice` / `xzh-invoice` → **货件号**（10+5 条）。这两个流程的行**天然已有**
+        货件号（开启前提是 FULL状态=已完成），历史身份一直是数字；改成 record_id 会让
+        "已完成"的行换个身份重新被认领（实测 23:17 立刻重复认领了 77447894，多亏角色
+        判 blocked 才没重复写生产表）。
+    ⇒ 由注册表 `source.ticketKey` 显式声明（'record_id' 或 'ticketField'），缺省保持历史行为。
+    """
+    m = str(mode or '').strip()
+    if m == 'record_id':
+        return str(rec or fields.get(ticket_field) or '')
+    return str(fields.get(ticket_field) or rec or '')      # 历史默认：票号列优先
+
+def required_projection(spec: dict) -> list[str]:
+    """`required` 里**该从数据源拉取**的字段名（= 投影的 required 部分）。
+
+    判据＝显式 `role`（2026-09-20 迭代1-步骤2 起），不再是 owner 的中文子串：
+      · `input`  运营提供的数据      → 拉
+      · `state`  运行中读写的状态位  → **拉**（规则与 runner 都可能读它，如发票状态/发票就绪）
+      · `output` 流程产物            → 不拉（不是数据源的输入）
+      · `derived`上游生成器提供      → 不拉（不是表列）
+    旧判据 `'系统' in owner` 把 `发票状态`（owner=系统/运营）误排除 ⇒ 依赖该列的规则会静默拿到空值。
+    """
+    out = []
+    for r in (spec.get('required') or []):
+        name = r.get('name')
+        if not name:
+            continue
+        role = str(r.get('role') or '')
+        if not role:      # 兜底：裸调（未经 flow_config 校验）时按旧判据推理
+            role = 'output' if '系统' in str(r.get('owner') or '') else 'input'
+        if role in ('output', 'derived'):
+            continue
+        out.append(str(name))
+    return out