合入期 1 数字推演沙盘:证据面板里改口径卡的输入、排除查询结果的行,即时看指标和报告引用处的新值;推演只读、不写运行记录,醒目标注推演非出具;口径卡的容器型输入此后另存完整值

# Conflicts:
#	scripts/check-all.mjs
This commit is contained in:
ThearchyHelios
2026-10-05 07:53:42 +08:00
16 changed files with 5424 additions and 22 deletions
+354 -2
View File
@@ -1,9 +1,361 @@
"""数字推演:在一次运行的基础上改动输入,推演指标会怎样变化,不改原运行。
目前只登记了路由前缀,接口由数字推演的工作包补上。路径挂在 /api/runs/{run_id}/… 下面。
POST /api/runs/{run_id}/evidence/whatif:证据面板里点开口径卡上的一个数,改某个输入的值、或者排除它背后查询结果里的
几行,看这个指标和报告里引用它的地方会变成多少。推演永远不是出具:不追加任何事件(last_seq 不变)、不落工件、
不改报告,结果只交回给发请求的人。
GET /api/runs/{run_id}/evidence/whatif/rows:推演时勾行用,按页取封存范围内一份查询快照的行(遮罩列写「已遮罩」)。
证据面板的查询步骤只给被引用的行前后各 2 行,整份结果作输入(len(vars.res.rows) 这种)时每一行都可能要勾。
只认这次运行封存范围内的工件,和证据接口同一套白名单(api/evidence.py 的 _sealed / _sealed_loader):口径卡的指标集
从封存的 node.finished 台账找,排除行只认封存范围内交回过的查询快照,nodes.* 的完整值从封存的节点产出工件取,
vars.* 的完整值(value_artifact)只认封存的指标集里写着的。还在跑、停在审批的运行也能推演,结果里 sealed 为假:
数据可能还会变。遮罩列(查询当时记下的加数据源现在设的)不给值、也不能拿来推演,见 engine/recompute.py。
重算本身是纯函数(engine/recompute.py)。这里负责:认请求、找卡、准备工件和遮罩、找报告里引用的地方、标出可能受影响
的下游口径卡。
"""
from __future__ import annotations
from fastapi import APIRouter
import asyncio
from collections.abc import Iterator, Mapping
from dataclasses import replace
from typing import Any
from fastapi import APIRouter, Body
from app.api.coded import CodedHTTPException
from app.api.evidence import (
MASKED,
MISSING_QUERY,
REPORT_NOT_FOUND,
TAMPERED_QUERY,
_Masks,
_merge_masks,
_recorded_masks,
_reports,
_Sealed,
_sealed,
_sealed_cards,
_sealed_loader,
)
from app.core.artifact_store import load
from app.engine import recompute
from app.engine.merge_query import MERGE_SOURCE
router = APIRouter(prefix="/api/runs", tags=["whatif"])
BAD_REQUEST = "whatif_bad_request"
BAD_INPUT = "whatif_bad_input"
CARD_NOT_FOUND = "whatif_card_not_found"
CARD_TAMPERED = "whatif_card_tampered"
METRIC_NOT_FOUND = "whatif_metric_not_found"
BAD_REQUEST_TEXT = ("请求格式有误:card 应为口径卡节点的 ID;report、metric 可省略,填写时为节点 ID 和指标 ID;"
"overrides.inputs 应为「输入路径 → 新值」,overrides.exclude_rows 应为「查询快照的工件 ID → 行号列表」")
#: 一次最多改几个输入、排除几份快照里的行、每份最多几行:再多就是请求写错了
MAX_INPUTS = 200
MAX_SNAPSHOTS = 50
MAX_ROWS = 10000
#: 勾行时一页给几行、最多几行
ROWS_PAGE = 50
MAX_ROWS_PAGE = 200
OUT_OF_SCOPE = "这份查询快照不属于这次运行,或不在封存范围内,不能用于推演"
@router.post("/{run_id}/evidence/whatif")
async def evidence_whatif(run_id: str, payload: Any = Body(None)) -> dict[str, Any]:
"""在一次运行的口径卡上推演:请求体 {report?, card, metric?, overrides: {inputs, exclude_rows}}。
返回 {sealed, seal, card, metrics, segments, unsupported, affected_cards}:每个指标的旧值、新值、变化量和输入,
报告里引用这些指标的地方会写成什么,不能用于推演的输入和原因,以及引用了这张卡、可能受影响(未重算)的下游口径卡。
"""
report, card_node, metric, changes = _request(payload)
sealed = await _sealed(run_id)
reports = _reports(sealed)
if report is not None and not any(r.node_id == report for r in reports):
raise CodedHTTPException(404, "本次运行中没有所选报告撰写节点的文档", REPORT_NOT_FOUND)
cards = _sealed_cards(sealed)
artifact, card, started = _card_of(sealed, cards, card_node, reports, report)
if metric is not None and not any(isinstance(m, dict) and str(m.get("id")) == metric
for m in card.get("metrics") or []):
raise CodedHTTPException(404, f"口径卡中没有指标「{metric}」", METRIC_NOT_FOUND)
sources = _sources(sealed, cards, started, asyncio.get_running_loop())
docs = [(r.node_id, r.doc) for r in reports
if r.doc is not None and r.hash_ok is True and (report is None or r.node_id == report)]
try:
# 重算连同读工件(快照、完整值、节点产出)都在线程里:快照大的时候不挡住同一进程里别的请求。
# 遮罩用到哪份快照才算哪份(_Hidden),查库那一步交回事件循环
result, segments = await asyncio.to_thread(_compute, card, changes, sources, metric, docs, card_node, artifact)
except recompute.WhatIfError as e:
raise CodedHTTPException(422, str(e), BAD_INPUT) from None
# 改动可能改变了某个指标——算出来变了,或者碰到了它却推演不了(还原不了、遮罩),新值不知道——下游才可能受影响。
# 不能只看 changed:整个推演不了的指标 changed 一律为空,什么都没改时也一样(recompute.whatif 的 maybe_changed)
maybe = result["maybe_changed"]
edges = [(e.get("source"), e.get("target")) for e in sealed.graph.get("edges") or [] if isinstance(e, dict)]
return {
"run_id": run_id,
"card": {"node_id": card_node, "artifact": artifact, "caliber": card.get("caliber") or "",
"version": card.get("caliber_version") or ""},
"report": report,
# 封存了、而且封存核对通过:推演依据的数据不会再变。没封存(还在跑、停在审批)或封存核对没过的照样能推演
"sealed": sealed.trusted,
"seal": {"sealed": sealed.sealed, "ok": sealed.seal["ok"]},
"metrics": result["metrics"],
"segments": segments,
"unsupported": result["unsupported"],
# 什么都没变,下游也不会变;顺着画布的边找,经中间节点用到卡上值的下游卡也标
"affected_cards": recompute.downstream_cards(cards, card_node, edges=edges) if maybe else [],
}
@router.get("/{run_id}/evidence/whatif/rows")
async def evidence_whatif_rows(run_id: str, artifact: str | None = None, offset: str | None = None,
limit: str | None = None) -> dict[str, Any]:
"""一页查询快照的行:{artifact, columns, rows, row_offset, row_index, total_rows, masked, hash_ok, sealed, note?}。
形状和证据面板的查询步骤一致(界面用同一个函数读)。只认这次运行封存范围内交回过的快照;遮罩列(查询当时记下的
加数据源现在设的)写「已遮罩」;读不出来、与哈希不一致的不给行,note 照实说。只读:不追加事件、不落工件。
"""
if not artifact or not artifact.strip():
raise CodedHTTPException(422, "请求格式有误:artifact 应为查询快照的工件 ID", BAD_REQUEST)
artifact = artifact.strip()
start, size = _count(offset, "offset", 0), min(_count(limit, "limit", ROWS_PAGE), MAX_ROWS_PAGE)
sealed = await _sealed(run_id)
info = sealed.queries.get(artifact)
if info is None:
raise CodedHTTPException(422, OUT_OF_SCOPE, BAD_INPUT)
try:
snap = await asyncio.to_thread(load, artifact)
hash_ok: bool | None = True if snap is not None else None
except ValueError:
snap, hash_ok = None, False
page: dict[str, Any] = {
"run_id": run_id, "artifact": artifact, "node_id": info.get("node_id"), "tool": info.get("tool"),
"source": info.get("source") or (snap.get("source") if isinstance(snap, dict) else None),
"columns": [], "rows": [], "row_offset": start, "row_index": [], "total_rows": None, "truncated": None,
"masked": [], "hash_ok": hash_ok, "sealed": sealed.trusted,
}
if not isinstance(snap, dict) or not isinstance(snap.get("rows"), list):
return {**page, "note": TAMPERED_QUERY if hash_ok is False else MISSING_QUERY}
hidden = await _mask_of(snap, info, _Masks())
columns = [str(c) for c in snap.get("columns") or []]
masked = {i for i, c in enumerate(columns) if c.lower() in hidden}
rows = snap["rows"]
picked = range(start, min(start + size, len(rows)))
return {**page, "columns": columns, "total_rows": len(rows), "truncated": bool(snap.get("truncated")),
"masked": [columns[i] for i in sorted(masked)],
"column_types": snap.get("column_types") if isinstance(snap.get("column_types"), dict) else {},
"row_index": list(picked),
"rows": [[MASKED if i in masked else v for i, v in enumerate(rows[r])] if isinstance(rows[r], list)
else rows[r] for r in picked]}
def _count(raw: str | None, name: str, default: int) -> int:
"""查询参数里的非负整数;没给用默认值。写错了 422,说清是哪一个。"""
if raw is None or not raw.strip():
return default
try:
value = int(raw)
except ValueError:
value = -1
if value < 0:
raise CodedHTTPException(422, f"请求格式有误:{name} 应为不小于 0 的整数", BAD_REQUEST)
return value
def _compute(card: dict[str, Any], changes: recompute.Changes, sources: recompute.Sources, metric: str | None,
docs: list[tuple[str, dict[str, Any]]], card_node: str, artifact: str
) -> tuple[dict[str, Any], list[dict[str, Any]]]:
result = recompute.whatif(card, changes, sources, metric=metric)
segments = recompute.report_segments(docs, card_node=card_node, card_artifact=artifact, results=result["metrics"])
return result, segments
def _request(payload: Any) -> tuple[str | None, str, str | None, recompute.Changes]:
"""(report, card, metric, 改动)。形状不对一律 422 whatif_bad_request;值对不对(路径在不在、行号越没越界)由重算时核对。"""
def bad() -> CodedHTTPException:
return CodedHTTPException(422, BAD_REQUEST_TEXT, BAD_REQUEST)
if not isinstance(payload, dict):
raise bad()
card, report, metric = payload.get("card"), payload.get("report"), payload.get("metric")
if not isinstance(card, str) or not card.strip():
raise bad()
if any(v is not None and (not isinstance(v, str) or not v.strip()) for v in (report, metric)):
raise bad()
overrides = payload.get("overrides")
overrides = {} if overrides is None else overrides
if not isinstance(overrides, dict):
raise bad()
inputs = {} if overrides.get("inputs") is None else overrides["inputs"]
exclude = {} if overrides.get("exclude_rows") is None else overrides["exclude_rows"]
if not isinstance(inputs, dict) or not isinstance(exclude, dict) \
or len(inputs) > MAX_INPUTS or len(exclude) > MAX_SNAPSHOTS:
raise bad()
rows: dict[str, frozenset[int]] = {}
for artifact, picked in exclude.items():
if not isinstance(picked, list) or len(picked) > MAX_ROWS \
or not all(isinstance(r, int) and not isinstance(r, bool) for r in picked):
raise bad()
if picked:
rows[str(artifact)] = frozenset(picked)
return (report.strip() if report else None, card.strip(), metric.strip() if metric else None,
recompute.Changes(inputs={str(k): v for k, v in inputs.items()}, exclude=rows))
def _card_of(sealed: _Sealed, cards: list[tuple[str, str, dict[str, Any]]], node_id: str, reports: list[Any],
report: str | None) -> tuple[str, dict[str, Any], int]:
"""要推演的那份指标集:(工件 id, 内容, 那次执行的 node.started 序号)。
哪些 node.finished 算这张卡的执行,和 _sealed_cards 一样认:台账里的 metric_set 条目;一期以前没有台账的,画布上确实
是口径卡的节点,产出本身就是指标集。同一张卡在循环里算过几次时,选报告引用的那一份(指定了 report 看那份报告,
没指定看任意一份),都没引用就取最后一次。内容只认 _sealed_cards 取回、复验过哈希的:执行记录里有、内容却对不上
哈希的说清是被改过,不说「没有这张卡」。
"""
calibers = set(sealed.nodes_of("metrics"))
runs: list[tuple[int, str]] = []
for seq, etype, nid, data in sealed.events:
if etype != "node.finished" or nid != node_id or not isinstance(data, dict):
continue
arts = [str(e["artifact"]) for e in data.get("evidence") or []
if isinstance(e, dict) and e.get("kind") == "metric_set" and e.get("artifact")]
if not arts and nid in calibers and data.get("artifact"):
arts = [str(data["artifact"])]
runs.extend((seq, art) for art in arts)
if not runs:
raise CodedHTTPException(404, "这次运行中没有这张口径卡的结果:节点不存在、不是口径卡、尚未执行或执行失败",
CARD_NOT_FOUND)
cited = {e.get("artifact") for r in reports if r.doc is not None and (report is None or r.node_id == report)
for e in (r.doc.get("catalog") or {}).values()
if isinstance(e, dict) and e.get("kind") == "metric" and e.get("node_id") == node_id}
seq, artifact = next(((s, a) for s, a in reversed(runs) if a in cited), runs[-1])
good = {art: card for nid, art, card in cards if nid == node_id}
if artifact not in good:
raise CodedHTTPException(409, "口径卡的指标集与哈希不一致或无法读取,疑似被修改,不能推演", CARD_TAMPERED)
started = max((s for s, etype, nid, _ in sealed.events if etype == "node.started" and nid == node_id and s < seq),
default=seq)
return artifact, good[artifact], started
def _sources(sealed: _Sealed, cards: list[tuple[str, str, dict[str, Any]]], started: int,
loop: asyncio.AbstractEventLoop) -> recompute.Sources:
"""重算要用的东西(recompute.Sources):封存范围内的工件、口径卡那次执行之前的节点产出和跑完的时刻、快照交回的
时刻、用到哪份才算哪份的遮罩。拿到的 Sources 要在工作线程里用(_Hidden 在线程里等事件循环查库)。"""
loader = _loader(sealed, cards)
return recompute.Sources(load=loader, queries=tuple(sealed.queries), outputs=_outputs_before(sealed, started),
masked=_Hidden(sealed, loader, loop), returned=_returned(sealed),
finished=_finished_before(sealed, started))
def _outputs_before(sealed: _Sealed, started: int) -> dict[str, str]:
"""口径卡那次执行开始之前,每个节点最后一次的产出工件:口径卡当时读到的 nodes.* 就是它们。"""
out: dict[str, str] = {}
for seq, etype, node_id, data in sealed.events:
if seq >= started:
break
if etype == "node.finished" and node_id and isinstance(data, dict) and data.get("artifact"):
out[node_id] = str(data["artifact"])
return out
def _finished_before(sealed: _Sealed, started: int) -> dict[str, int]:
"""口径卡那次执行开始之前,每个节点最后一次跑完的事件序号:口径卡读到的 vars.*、nodes.* 是那一刻写下的。"""
out: dict[str, int] = {}
for seq, etype, node_id, _ in sealed.events:
if seq >= started:
break
if etype == "node.finished" and node_id:
out[node_id] = seq
return out
def _returned(sealed: _Sealed) -> dict[str, int]:
"""封存范围内每份查询快照第一次交回的事件序号:tool.end 的 query_artifact,或者 node.finished 台账里的 query
条目(合并查询只有后者)。排除这份快照里的行,只可能影响在这之后才算出来的值。"""
out: dict[str, int] = {}
for seq, etype, _, data in sealed.events:
if not isinstance(data, dict):
continue
if etype == "tool.end" and data.get("query_artifact"):
out.setdefault(str(data["query_artifact"]), seq)
elif etype == "node.finished":
for entry in data.get("evidence") or []:
if isinstance(entry, dict) and entry.get("kind") == "query" and entry.get("artifact"):
out.setdefault(str(entry["artifact"]), seq)
return out
def _loader(sealed: _Sealed, cards: list[tuple[str, str, dict[str, Any]]]) -> Any:
"""只认这次运行封存范围内的工件:证据接口的白名单(查询、表结构、检索快照和台账记过的),加上封存的节点产出工件,
以及封存的指标集里写着的完整值(value_artifact——写在内容寻址、又在封存范围内的指标集里,属于封存链的延伸)。
未封存、封存核对没过的运行也能推演(结果里 sealed 为假):白名单按同一套规则算,只是不要求封存完好。
取回时照旧复验哈希,对不上抛 ValueError(artifact_store.load 的约定),由重算照实说。
"""
base = _sealed_loader(replace(sealed, seal={**sealed.seal, "sealed": True, "ok": True}))
extra = {str(data["artifact"]) for _, etype, _, data in sealed.events
if etype == "node.finished" and isinstance(data, dict) and data.get("artifact")}
extra |= {str(item["value_artifact"]) for _, _, card in cards
for metric in card.get("metrics") or [] if isinstance(metric, dict)
for item in metric.get("inputs") or [] if isinstance(item, dict) and item.get("value_artifact")}
memo: dict[str, Any] = {}
def loader(artifact: str) -> Any:
key = str(artifact)
if key not in memo:
memo[key] = load(key) if key in extra else base(key)
return memo[key]
return loader
class _Hidden(Mapping[str, frozenset[str]]):
"""封存范围内的查询快照 → 要遮的列(小写),推演用到哪份才算哪份。
遮的列和证据面板查询步骤同一套(api/evidence.py 的 _query_step):查询当时记下的加数据源现在设的,合并查询按它
合并的那几个数据源算。快照读不出来、被改过时照样按台账记的数据源算:遮罩不能因为快照坏了就失效(那一格的值另由
重算不给)。
在重算的工作线程里取用:快照经推演用的同一个 loader 读(重算本来也要读这一份,读过的不再读盘);查数据源现在
设的遮罩要访问库,交回事件循环去查(_Masks 是异步的),线程在这里等它。以前每次请求在事件循环里把这次运行的
全部快照读一遍、复验一遍哈希,不管卡上用没用到。
"""
def __init__(self, sealed: _Sealed, loader: Any, loop: asyncio.AbstractEventLoop) -> None:
self._sealed, self._loader, self._loop = sealed, loader, loop
self._masks = _Masks()
self._memo: dict[str, frozenset[str]] = {}
def __getitem__(self, artifact: str) -> frozenset[str]:
key = str(artifact)
if key not in self._sealed.queries:
raise KeyError(key)
if key not in self._memo:
try:
running = asyncio.get_running_loop()
except RuntimeError:
running = None
if running is self._loop:
raise RuntimeError("遮罩只能在工作线程里取:在事件循环里同步等它查库会卡死")
try:
snap = self._loader(key)
except ValueError:
snap = None
found = _mask_of(snap if isinstance(snap, dict) else None, self._sealed.queries[key], self._masks)
self._memo[key] = frozenset(asyncio.run_coroutine_threadsafe(found, self._loop).result())
return self._memo[key]
def __iter__(self) -> Iterator[str]:
return iter(self._sealed.queries)
def __len__(self) -> int:
return len(self._sealed.queries)
async def _mask_of(snap: dict[str, Any] | None, info: dict[str, Any], masks: _Masks) -> set[str]:
"""一份查询快照要遮的列(小写)。snap 为 None(读不出来)时只能按台账记的数据源现在设的遮罩算。"""
if snap is not None and snap.get("source") == MERGE_SOURCE:
hidden, _ = await _merge_masks(snap, masks)
return hidden
hidden, _ = await masks.of(info.get("source") or (snap or {}).get("source"))
return hidden | (_recorded_masks(snap) if snap is not None else set())
+33
View File
@@ -137,6 +137,13 @@ async def run_metrics(state: GraphState, ctx: NodeContext) -> dict[str, Any]:
incomplete = {"incomplete": True, "incomplete_reason": _incomplete_reason(sources),
"truncated_sources": sources}
inputs = [_input_of(path, values[path], state, ctx, tctx) for path in paths]
for path, item in zip(paths, inputs):
# 容器型的 vars.* 输入(列表、字典)另存一份完整值:卡里只记了「[12 项]」这样的大概,事后推演
# (engine/recompute.py)要拿完整的值重算。nodes.*、input.* 的完整值在那个节点封存的产出工件里,
# agent 字段能按出处从查询快照还原,都不用另存;vars 是谁写的、写进去的是不是节点产出本身说不准,
# 只能在这一刻存下。只给这种输入多一个键:没有容器型 vars 输入的卡和以前逐字节相同
if _container_var(path, values[path]) and (stored := await _store_value(path, values[path], ctx)):
item["value_artifact"] = stored
sql_check: dict[str, Any] = {}
if failed := _failed_queries(inputs, list(use.sources.values()), paths, tctx, checked):
sql_check = {"sql_check_failed": True, "sql_check_reason": _sql_check_reason(failed),
@@ -726,6 +733,32 @@ def _recompute(substituted: str, tctx: dict[str, Any], value: Any, decimals: int
return again == value
#: 另存的完整值最大多少字节(规范 JSON)。查询结果整份赋给变量时可能很大,每张卡都再存一份不值当:大过这个数就
#: 不存,推演照实说当时没有保存完整值
VALUE_ARTIFACT_MAX = 4 * 1024 * 1024
def _container_var(path: str, value: Any) -> bool:
head = _REF_HEAD.match(path)
return isinstance(value, (list, dict)) and head is not None and head.group(1) == "vars"
async def _store_value(path: str, value: Any, ctx: NodeContext) -> str | None:
"""容器型 vars 输入的完整值落成 metric_input 工件:{path, value}。它的 id 记在指标集里,指标集内容寻址、
在封存范围内,完整值也就随运行封存,不另起台账条目。存不下(太大、写失败)就不存:口径卡照常算出来,
只是这个输入以后推演不了。"""
from app.core.artifact_store import canonical_json, put_json
content = {"path": path, "value": value}
try:
if len(canonical_json(content).encode()) > VALUE_ARTIFACT_MAX:
return None
return await put_json(content, kind="metric_input", run_id=ctx.run.run_id, node_id=ctx.node.id,
meta={"path": path})
except Exception: # noqa: BLE001 - 完整值存不下不该毁掉口径卡
return None
async def _store(card: dict[str, Any], caliber: str, version: str, ctx: NodeContext) -> str | None:
"""整张卡落成 metric_set 工件。写失败不毁掉运行,只是这张卡没法被引用。"""
from app.core.artifact_store import put_json
+944
View File
@@ -0,0 +1,944 @@
"""数字推演的重算:在一张口径卡上改几个输入的值、排除查询快照里的几行,算出指标会变成多少。
推演永远不是出具。这里只算数:不读库、不写工件、不追加事件。接口(api/whatif.py)把这次运行封存范围内取得到的
工件交进来(Sources),结果原样交回给点开证据面板的人,运行记录和报告一个字都不动。
口径卡怎么算的,这里就怎么算:同一条原式、同一个求值器(expressions.eval_expression),浮点结果按卡上记的小数位
round(和 metrics.run_metrics 一样只 round 浮点),渲染走 evidence.render_metric。重算前先把每个输入当时的值还原
出来,卡上记着的就用卡上的:
- 标量输入(数、文本、布尔、空值):卡上记的 value 就是当时代进去的值。cell() 取的格、agent 的单格字段和数组里的
一个元素也是标量,它们落在查询快照的哪一行记在 locator 里:排除了那一行,这个输入就当缺失,指标标「排除后无法计算」
- 容器输入卡上只记了「[12 项]」这样的大概(metrics._brief),完整值另找:
- agent 的数组字段:agent 节点封存的产出里的 data;第 k 个元素是快照的第 a + k 行(locator.rows),排除行就去掉对应的元素
- nodes.* / input.*:那个节点在口径卡执行之前最后一次的产出工件
- vars.*:有 value_artifact(口径卡当时另存的完整值)才还原得出来;老运行照实说当时没有保存
- 容器本身是一份查询结果(带 artifact 的 {columns, rows},或者和某份快照的 rows 一模一样的列表):排除行就去掉那几行
- 遮罩列取来的输入不给值、也不拿来推演:改一个输入、排除一行,新值和原值一比就能算出遮住的那一格
- 落在读不出来(文件不在、与哈希不一致)的查询快照上的输入同样不给值、不推演:那一格遮没遮核对不了,宁可多遮
有的指标不论改什么都推演不了(_Plan.blocked):卡上没记全输入、用到了遮罩列、最外层的输入还原不了(容器的完整值
找不回来、所在的快照读不出来)。这种不改动也照实交回 unsupported / masked 和原因,输入一个都不让改、不给行段:
界面一打开就只写原因,不写「无变化」,也不摆改了、勾了也推演不出来的输入框和勾选框。
同一张口径卡的指标不能互相引用(算这张卡时卡上的值还不存在),所以只有用到了被改的输入、被排除的行的指标需要重算,
别的原样交回。排除行时有两种例外,都只能说不知道(unsupported),不能报「无变化」:
- 指标的某个输入对不上任何快照(完整值找不回来的容器、加工过的结果、按位置从结果里取的一格、由查询结果算出来的数),
它可能就是从被排除了行的那份结果来的,重算不了。写它的节点在那份快照交回之前就跑完了的,影响不到它,照常不算
- 决定取哪一格的容器(cell(nodes.q, len(vars.res.rows) - 1, …) 里的 vars.res.rows)少了几行:取到的是哪一格说不准。
这种容器也就不给可勾的行段(勾了只能说不知道);决定取哪一格的单格照给,勾掉它确定是排除后无法计算
给了新值的以新值为准:只嵌在给了新值的引用里的输入(cell(…) 那一格给了新值,它行号里的 vars.res.rows)取到哪一格
已无关紧要,它那一行排除了、它说不准受不受影响都不碍事(_Plan.moot)。
"""
from __future__ import annotations
import ast
import copy
import json
import math
import re
from collections.abc import Callable, Iterable, Mapping
from dataclasses import dataclass, field
from typing import Any
from app.core.errors import describe_exception
from app.engine.evidence import DEFAULT_FORMAT, MISSING, RenderError, is_number, iter_units, render_metric, render_number
from app.engine.expressions import (
ExpressionError,
_cell_call,
_chain_root,
eval_expression,
leaf_refs,
parse_expression,
substitute,
)
from app.engine.nodes.metrics import _REF_HEAD, _brief
NO_LINEAGE = "这个指标生成于系统升级前,口径卡没有记录输入,不能推演"
NO_FULL_VALUE = "当时没有保存这个输入的完整值"
NOT_RESTORABLE = "这类输入当时没有保存完整值"
MASKED_INPUT = "这一列在数据源中设置了遮罩,不能用于推演"
MASKED_TABLE = "这份查询结果里有设置了遮罩的列,不能用于推演"
MASKED_METRIC = "这个指标用到了设置了遮罩的列,不能推演"
SELECTOR = "这个输入决定取哪一行、哪一项,修改它需要重新取数,不能推演"
EXCLUDED = "排除后无法计算"
UNREADABLE = "查询快照无法读取"
TAMPERED = "查询快照与哈希不一致,疑似被修改"
#: 不能改、也没有行可勾的输入(_fixed)
FIXED_CONTAINER = "列表或对象不能直接修改,也没有对应的查询结果可以排除行"
NOT_NUMBER = "不是数值,不能修改"
#: 排除了行,却说不准这个输入受不受影响(_doubt)
DOUBT = "排除行对 {path} 的影响无法确定:{why}"
DOUBT_UNMATCHED = "它对不上任何查询快照,可能是由查询结果加工而来"
DOUBT_DERIVED = "它不是直接取自查询结果的格,可能由查询结果算出"
DOUBT_SELECTOR = "它决定取哪一行、哪一项,排除行后需要重新取数"
NOT_FINITE = "计算结果不是有限的数值(溢出或非数),无法推演"
#: 卡上给容器记的大概(metrics._brief):「[12 项]」「{3 个字段}」
_BRIEF = re.compile(r"^(?:\[\d+ 项\]|\{\d+ 个字段\})$")
#: 重算时最外层引用换成的占位名。不在 EXPRESSION_ROOTS 里,原式自己写不出这种名字
_PLACEHOLDER = "__whatif_{}"
class WhatIfError(ValueError):
"""推演请求本身不合法:路径不存在、值不是数、行号越界、工件不属于这次运行……接口回 422,消息原样给人看。"""
@dataclass(frozen=True)
class Changes:
"""一次推演的改动:inputs 是输入路径 → 新值;exclude 是查询快照的工件 id → 要排除的行号(从 0 数)。"""
inputs: Mapping[str, Any] = field(default_factory=dict)
exclude: Mapping[str, frozenset[int]] = field(default_factory=dict)
@dataclass
class Sources:
"""还原输入要用到的东西,由调用方从这次运行的封存范围里准备好。
- load:工件 id → 内容。只认封存范围内的工件,范围外的、文件不在的返回 None,内容和哈希对不上抛 ValueError
(artifact_store.load 的约定)
- queries:封存范围内的查询快照,按在事件里第一次出现的顺序。排除行只认这些快照;容器按内容对快照时也按这个顺序
- outputs:节点 id → 口径卡执行之前它最后一次的产出工件(nodes.*、input.* 的容器、agent 的数组字段从这里还原)
- masked:查询快照 → 要遮的列(小写):查询当时记下的加数据源现在设的。只用到 get,调用方可以给一个用到哪份
才算哪份的映射(快照读不出来时照样按台账记的数据源算)
- returned:查询快照 → 它第一次交回时的事件序号;finished:节点 → 口径卡执行之前它最后一次跑完的事件序号。
排除行只可能影响在那份快照交回之后才算出来的值(_doubt)。不知道的一律当可能受影响
"""
load: Callable[[str], Any]
queries: tuple[str, ...] = ()
outputs: Mapping[str, str] = field(default_factory=dict)
masked: Mapping[str, frozenset[str]] = field(default_factory=dict)
returned: Mapping[str, int] = field(default_factory=dict)
finished: Mapping[str, int] = field(default_factory=dict)
class _Store:
"""一次推演里取过的工件:同一份快照、产出只读一次。get 给 (内容, 问题),问题是 None、missing 或 tampered。"""
def __init__(self, sources: Sources) -> None:
self.sources = sources
self._memo: dict[str, tuple[Any, str | None]] = {}
def get(self, artifact: Any) -> tuple[Any, str | None]:
key = str(artifact or "")
if key not in self._memo:
try:
content = self.sources.load(key) if key else None
self._memo[key] = (content, None if content is not None else "missing")
except ValueError:
self._memo[key] = (None, "tampered")
return self._memo[key]
def snapshot(self, artifact: Any) -> dict[str, Any] | None:
content, _ = self.get(artifact)
return content if isinstance(content, dict) and isinstance(content.get("rows"), list) else None
def output(self, node_id: Any) -> tuple[Any, str | None]:
artifact = self.sources.outputs.get(str(node_id)) if node_id else None
return self.get(artifact) if artifact else (None, "missing")
@dataclass
class _Input:
item: dict[str, Any]
path: str
#: scalar:卡上记的就是当时的值;container:卡上只记了大概,value 是另找来的完整值
shape: str = "scalar"
value: Any = None
#: 完整值找不回来的原因(只有容器会有)
problem: str | None = None
#: 落在哪份查询快照上:单格是 row,数组字段是一段行 rows,table 是整份结果(或它的 rows)
snapshot: str | None = None
row: int | None = None
rows: tuple[int, int] | None = None
table: bool = False
masked: bool = False
#: 落在的查询快照读不出来(文件不在、与哈希不一致):遮没遮核对不了,值不给,也不拿来推演
unreadable: bool = False
#: 出现在别的输入的下标、cell() 的行列里:它决定取哪一格,改它要重新取数
selector: bool = False
@dataclass
class _Plan:
metric: dict[str, Any]
tree: ast.Expression | None = None
#: 最外层的引用,按出现顺序:重算时换成占位名的就是这些
tops: list[str] = field(default_factory=list)
inputs: dict[str, _Input] = field(default_factory=dict)
problem: str | None = None
#: 嵌在别的引用里的输入 → 包着它的最外层引用(_refs)
within: dict[str, set[str]] = field(default_factory=dict)
def settled(self, path: str, changes: Changes) -> bool:
"""包着这个输入的最外层引用都给了新值:它决定取哪一格已无关紧要,那几个引用以新值为准。"""
outer = self.within.get(path)
return bool(outer) and all(top in changes.inputs for top in outer)
def moot(self, path: str, changes: Changes) -> bool:
"""这个输入这次用不上:只嵌在别的引用里,包着它的又都给了新值。它那一行排除了、它说不准受不受影响,都碍不着
重算。它自己也是最外层引用的不算:那一处照常拿它的值。"""
return path not in self.tops and self.settled(path, changes)
@property
def blocked(self) -> tuple[str, str] | None:
"""整个指标推演不了(不论改什么):(status, 原因),推演得了的是 None。
卡上没记全输入、表达式有误;用到了遮罩列(哪怕只是嵌在下标里的一格);最外层的输入还原不了——容器的完整值
找不回来,或者所在的查询快照读不出来。嵌在下标里的输入还原不了不碍事:它取到的那一格的值卡上记着。
遮罩排在还原不了前面:同一格既遮着、快照又读不出来时,说遮罩(快照修好了它照样遮着)。
"""
if self.problem:
return "unsupported", self.problem
if any(inp.masked for inp in self.inputs.values()):
return "masked", MASKED_METRIC
for path in self.tops:
if problem := self.inputs[path].problem:
return "unsupported", f"无法推演:{path}({problem})"
return None
# --------------------------------------------------------------------------
# 入口
# --------------------------------------------------------------------------
def whatif(card: dict[str, Any], changes: Changes, sources: Sources, *, metric: str | None = None) -> dict[str, Any]:
"""在一张口径卡上推演:{metrics: [每个指标的旧值、新值、输入…], unsupported: [不能用于推演的输入和原因],
maybe_changed: 有没有指标可能因这次改动而变}。
metric 给了就只推演这一个指标。改动不合法时抛 WhatIfError,一个指标都不算。没碰到改动的指标不重算,
原值原样交回(status: unchanged);整个推演不了的指标(_Plan.blocked)不论有没有改动都交回 unsupported / masked
和原因。unsupported 不论有没有改动都列全(遮罩的、还原不了的、不能改也没有行可勾的;整个指标推演不了的另有一条
input 为空的),界面一打开就能说清哪些输入不能动。
maybe_changed 只给调用方决定要不要标下游口径卡:改动碰到了某个指标,它又算出来变了或者说不准(推演不了的指标
新值不知道)。推演不了的指标 changed 一律为 None,只看它分不出「什么都没改」。
"""
store = _Store(sources)
metrics = [m for m in card.get("metrics") or [] if isinstance(m, dict) and m.get("id") is not None]
if metric is not None:
metrics = [m for m in metrics if str(m["id"]) == str(metric)]
if not metrics:
raise WhatIfError(f"口径卡中没有指标「{metric}」")
plans = [_plan(m, store) for m in metrics]
_check(changes, plans, store, metric=metric)
outcomes = [_outcome(p, changes, sources) for p in plans]
return {"metrics": [result for result, _ in outcomes], "unsupported": _unsupported(plans),
"maybe_changed": any(moved for _, moved in outcomes)}
def recompute(metric: dict[str, Any], changes: Changes, sources: Sources) -> dict[str, Any]:
"""重算一个指标,不管改动碰没碰到它,也不校验改动。核对还原是否忠实时用:什么都不改,重算出来应当和卡上记的一样。"""
return _outcome(_plan(metric, _Store(sources)), changes, sources, force=True)[0]
# --------------------------------------------------------------------------
# 还原输入
# --------------------------------------------------------------------------
def _plan(metric: dict[str, Any], store: _Store) -> _Plan:
expr = str(metric.get("expression") or "").strip()
items = metric.get("inputs")
if not expr or not isinstance(items, list):
return _Plan(metric, problem=NO_LINEAGE)
try:
tree, _, _ = parse_expression(expr)
except ExpressionError as e:
return _Plan(metric, problem=f"表达式有误({e})")
tops, within = _refs(tree)
remaining = _remaining(metric.get("substituted"), [*tops, *within])
inputs: dict[str, _Input] = {}
for item in items:
if isinstance(item, dict) and isinstance(item.get("path"), str) and item["path"] not in inputs:
inputs[item["path"]] = _restore(item, remaining, set(within), store)
plan = _Plan(metric, tree, tops, inputs, within=within)
if lost := [p for p in tops if p not in inputs]:
plan.problem = f"口径卡缺少输入 {'、'.join(lost[:3])} 的记录,不能推演"
return plan
def _refs(tree: ast.AST) -> tuple[list[str], dict[str, set[str]]]:
"""表达式引用的值:(最外层的引用, 嵌在别的引用里面的 → 包着它的最外层引用)。和 leaf_refs 按同一套规则认引用,
只多分一下里外:vars.rows[vars.i] 里的 vars.i、cell(nodes.q, vars.r, 'gmv') 里的 vars.r 是嵌在里面的,它们决定
取哪一格。嵌了几层的也记最外层那个:重算时只有最外层的引用拿值(_evaluate),给了新值的就是它们。"""
top: list[str] = []
within: dict[str, set[str]] = {}
def add(node: ast.AST, outer: str | None) -> str:
"""记下这个引用,交回它里面的引用归谁:已经嵌在里面的归原来那个最外层引用,最外层的归它自己。"""
path = ast.unparse(node)
if outer is not None:
within.setdefault(path, set()).add(outer)
return outer
if path not in top:
top.append(path)
return path
def visit(node: ast.AST, outer: str | None) -> None:
if _cell_call(node):
owner = add(node, outer)
for arg in node.args[1:]:
visit(arg, owner)
return
if isinstance(node, (ast.Attribute, ast.Subscript, ast.Name)) and _chain_root(node):
owner = add(node, outer)
cur: ast.AST = node
while isinstance(cur, (ast.Attribute, ast.Subscript)):
if isinstance(cur, ast.Subscript):
visit(cur.slice, owner)
cur = cur.value
return
for child in ast.iter_child_nodes(node):
visit(child, outer)
visit(tree, None)
return top, within
def _remaining(substituted: Any, paths: list[str]) -> set[str]:
"""代入式里还留着原路径的引用:没被代成字面量的,也就是容器(或卡上记的不是原值)。代入式读不出来就当全都留着。"""
try:
return set(leaf_refs(parse_expression(str(substituted))[0])) if substituted else set(paths)
except ExpressionError:
return set(paths)
def _restore(item: dict[str, Any], remaining: set[str], nested: set[str], store: _Store) -> _Input:
path = item["path"]
inp = _Input(item=item, path=path, value=item.get("value"), selector=path in nested)
locator = item.get("locator") if isinstance(item.get("locator"), dict) else {}
artifact = item.get("artifact") if isinstance(item.get("artifact"), str) and item.get("artifact") else None
if item.get("via") in ("tool_cell", "agent_field") and artifact:
if _row(locator.get("row")) is not None:
inp.snapshot, inp.row = artifact, locator["row"]
elif (span := _span(locator.get("rows"))) is not None:
inp.snapshot, inp.rows = artifact, span
# 卡上记的是「[3 项]」、代入式里又还留着原路径:当时的值是容器,卡上只记了大概。真是这几个字的短文本会被代成字面量
if item.get("value_artifact") or (isinstance(inp.value, str) and _BRIEF.match(inp.value) and path in remaining):
inp.shape = "container"
inp.value, inp.problem = _full_value(item, store)
if inp.problem is None and inp.rows is not None \
and not (isinstance(inp.value, list) and len(inp.value) == inp.rows[1] - inp.rows[0] + 1):
inp.snapshot, inp.rows = None, None # 元素和行对不上号:不按行排除
elif inp.problem is None and inp.snapshot is None:
inp.snapshot = _table_of(inp.value, store)
inp.table = inp.snapshot is not None
if inp.snapshot is not None:
_, trouble = store.get(inp.snapshot)
if trouble or store.snapshot(inp.snapshot) is None:
# 卡上记着这一格的值,可快照读不出来:这一列遮没遮核对不了(查询当时记下的遮罩在快照里),值不给,
# 也不拿来推演。数据源现在设的遮罩照样认(_masked),认出来了就按遮罩说
inp.unreadable = True
inp.problem = inp.problem or (TAMPERED if trouble == "tampered" else UNREADABLE)
inp.masked = _masked(inp, locator, store)
return inp
def _full_value(item: dict[str, Any], store: _Store) -> tuple[Any, str | None]:
"""容器输入的完整值:(值, 找不回来的原因)。"""
path = item["path"]
if ref := item.get("value_artifact"):
content, problem = store.get(ref)
if problem == "tampered":
return None, "保存的完整值与哈希不一致,疑似被修改"
if not isinstance(content, dict) or "value" not in content:
return None, "无法读取保存的完整值"
return content["value"], None
locator = item.get("locator") if isinstance(item.get("locator"), dict) else {}
if item.get("via") == "agent_field" and _span(locator.get("rows")) is not None and item.get("field"):
# agent 的数组字段:assign_to 写进 vars 的、nodes.<agent>.data 下的,都是核对后的 data(值以快照为准)
output, problem = store.output(item.get("node_id"))
value = _dig(output.get("data") if isinstance(output, dict) else None, str(item["field"]))
if isinstance(value, list):
return value, None
return None, _output_problem(item.get("node_id"), problem)
head = _REF_HEAD.match(path)
root = head.group(1) if head else None
if root in ("nodes", "input"):
node_id = head.group(2) if root == "nodes" else item.get("node_id")
output, problem = store.output(node_id)
if problem or output is None:
return None, _output_problem(node_id, problem)
if not _static(path):
return None, "取值路径里有变量下标,无法从节点的产出中还原"
try:
value = eval_expression(path, {"nodes": {str(node_id): output}} if root == "nodes" else {"input": output})
except Exception: # noqa: BLE001 - 取不出来就是还原不了
value = None
if isinstance(value, (list, dict)):
return value, None
return None, f"无法从节点「{node_id}」当时的产出中还原这个输入"
if root == "vars":
return None, NO_FULL_VALUE
return None, NOT_RESTORABLE
def _output_problem(node_id: Any, problem: str | None) -> str:
if problem == "tampered":
return f"节点「{node_id}」的产出与哈希不一致,疑似被修改"
return f"无法读取节点「{node_id}」当时的产出"
def _table_of(value: Any, store: _Store) -> str | None:
"""容器是不是一份查询结果(或它的 rows):带着封存范围内快照的 artifact,或者 rows 和某份快照一模一样。
空的不算:空列表和哪份空结果都对得上,排除行也无从谈起。"""
if isinstance(value, dict) and isinstance(value.get("rows"), list):
artifact = value.get("artifact")
if isinstance(artifact, str) and artifact in store.sources.queries:
return artifact # 快照读不读得出来由 _restore 核对
rows = value["rows"]
elif isinstance(value, list):
rows = value
else:
return None
if not rows:
return None
for artifact in store.sources.queries:
snap = store.snapshot(artifact)
if snap is not None and len(snap["rows"]) == len(rows) and snap["rows"] == rows:
return artifact
return None
def _masked(inp: _Input, locator: dict[str, Any], store: _Store) -> bool:
"""这个输入取自遮罩列:单格、数组字段看用到的那几列;整份查询结果只要有一列遮着就算。"""
hidden = store.sources.masked.get(inp.snapshot) if inp.snapshot else None
if not hidden:
return False
if inp.table:
snap = store.snapshot(inp.snapshot) or {}
return any(str(c).lower() in hidden for c in snap.get("columns") or [])
columns = [locator.get("column")] if locator.get("column") else list((locator.get("columns") or {}).values())
return any(isinstance(c, str) and c.lower() in hidden for c in columns)
def _static(path: str) -> bool:
"""取值路径的下标全是字面量(nodes.q.rows[0]),没有 nodes.q.rows[vars.i] 这种要另取一个值才知道是哪一项的。"""
try:
tree = ast.parse(path, mode="eval")
except SyntaxError:
return False
for node in ast.walk(tree):
if isinstance(node, ast.Subscript) and not isinstance(node.slice, ast.Constant) and not (
isinstance(node.slice, ast.UnaryOp) and isinstance(node.slice.operand, ast.Constant)):
return False
return True
def _dig(data: Any, key: str) -> Any:
for part in key.split("."):
data = data.get(part) if isinstance(data, dict) else None
return data
def _row(value: Any) -> int | None:
return value if isinstance(value, int) and not isinstance(value, bool) and value >= 0 else None
def _span(rows: Any) -> tuple[int, int] | None:
if isinstance(rows, list) and len(rows) == 2 and all(_row(r) is not None for r in rows) and rows[0] <= rows[1]:
return rows[0], rows[1]
return None
# --------------------------------------------------------------------------
# 校验改动
# --------------------------------------------------------------------------
def _number(value: Any) -> bool:
"""算得动的数:bool 不算;无穷大、非数不算;浮点放不下的大整数(10 ** 400)也不算——math.isfinite 对它抛
OverflowError,JSON 写得出来,界面却只能读成 Infinity。"""
if not is_number(value):
return False
try:
return math.isfinite(value)
except OverflowError:
return False
def _check(changes: Changes, plans: list[_Plan], store: _Store, *, metric: str | None) -> None:
known: dict[str, list[_Input]] = {}
for plan in plans:
for path, inp in plan.inputs.items():
known.setdefault(path, []).append(inp)
for path, value in changes.inputs.items():
found = known.get(path)
if not found:
raise WhatIfError(f"指标「{metric}」没有输入「{path}」" if metric is not None else f"口径卡里没有输入「{path}」")
if not is_number(value):
raise WhatIfError(f"输入「{path}」的新值需要是数值,当前为{_shown(value)}")
if not _number(value):
raise WhatIfError(f"输入「{path}」的新值超出可计算的范围,需要是有限的数值")
if any(i.masked for i in found):
raise WhatIfError(f"输入「{path}」取自设置了遮罩的列,不能用于推演")
if unreadable := next((i for i in found if i.unreadable), None):
raise WhatIfError(f"输入「{path}」所在的{unreadable.problem},不能用于推演")
if any(i.selector for i in found):
raise WhatIfError(f"输入「{path}」决定取哪一行、哪一项,修改它需要重新取数,不能推演")
if found[0].shape != "scalar":
raise WhatIfError(f"输入「{path}」是列表或对象,不能直接修改,可以在查询结果里勾选要排除的行")
if not (found[0].value is None or _number(found[0].value)):
raise WhatIfError(f"输入「{path}」不是数值,不能修改")
for artifact, rows in changes.exclude.items():
if artifact not in store.sources.queries:
raise WhatIfError(f"工件 {str(artifact)[:12]}… 不属于这次运行,或不在封存范围内,不能排除其中的行")
_, problem = store.get(artifact)
if problem == "tampered":
raise WhatIfError("查询快照与哈希不一致,疑似被修改,不能用于推演")
snap = store.snapshot(artifact)
if snap is None:
raise WhatIfError("无法读取查询快照,不能排除其中的行")
total = len(snap["rows"])
for row in sorted(rows):
if not 0 <= row < total:
raise WhatIfError(f"行号 {row} 超出范围:这份查询结果只有 {total} 行(行号从 0 开始)")
def _shown(value: Any) -> str:
"""不合法的新值写给人看:空值写「空值」,文本照原样,别的按 JSON 的写法——不露出 None、单引号这些 Python 写法。"""
if value is None:
return "空值"
text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False, default=str)
return f"「{text if len(text) <= 40 else text[:40] + '…'}」"
# --------------------------------------------------------------------------
# 重算
# --------------------------------------------------------------------------
def _apply(inp: _Input, changes: Changes) -> tuple[Any, list[int] | None, bool]:
"""改动之后这个输入的值:(值, 起了作用的被排除行, 是不是改了值)。给了新值的以新值为准,不看排除。"""
if inp.path in changes.inputs:
return changes.inputs[inp.path], None, True
excluded = changes.exclude.get(inp.snapshot) if inp.snapshot else None
if not excluded:
return inp.value, None, False
if inp.row is not None:
return (None, [inp.row], False) if inp.row in excluded else (inp.value, None, False)
if inp.rows is not None:
# 数组字段只用到快照里的一段行:段外的行排除了也影响不到它
first, last = inp.rows
hit = sorted(r for r in excluded if first <= r <= last)
if not hit:
return inp.value, None, False
if not isinstance(inp.value, list):
# 完整值找不回来(inp.problem):用到的行少了,它一定变了,变成什么不知道。照样算碰到了它,指标因这个
# 输入还原不了而推演不了(_Plan.blocked),不会拿原值算出一个「无变化」
return None, hit, False
return [v for k, v in enumerate(inp.value) if first + k not in excluded], hit, False
if inp.table:
rows = inp.value["rows"] if isinstance(inp.value, dict) else inp.value
hit = sorted(r for r in excluded if r < len(rows))
if not hit:
return inp.value, None, False
kept = [r for i, r in enumerate(rows) if i not in excluded]
return ({**inp.value, "rows": kept} if isinstance(inp.value, dict) else kept), hit, False
return inp.value, None, False
def _outcome(plan: _Plan, changes: Changes, sources: Sources, *,
force: bool = False) -> tuple[dict[str, Any], bool]:
"""(这个指标的推演结果, 它会不会因这次改动而变:碰到了它,又算出来变了或者说不准)。"""
values: dict[str, Any] = {}
notes: dict[str, list[int]] = {}
touched = False
for path, inp in plan.inputs.items():
values[path], excluded, overridden = _apply(inp, changes)
if excluded:
notes[path] = excluded
touched = touched or overridden or bool(excluded)
doubt = _doubt(plan, changes, sources)
# 说不准受不受影响的也算碰到了;卡上没记全输入的指标不知道它用了什么,有任何改动都说不准它变不变
touched = touched or doubt is not None or (plan.problem is not None and bool(changes.inputs or changes.exclude))
if blocked := plan.blocked:
# 整个推演不了:不改动也照实说,不拿原值报「无变化」。碰没碰到它只决定下游要不要标
status, reason = blocked
result = _result(plan, status, None, reason, values, notes)
elif not touched and not force:
result = _result(plan, "unchanged", plan.metric.get("value"), None, values, notes)
else:
status, new, reason = _compute(plan, values, notes, changes, doubt)
result = _result(plan, status, new, reason, values, notes)
return result, touched and result["changed"] is not False
def _doubt(plan: _Plan, changes: Changes, sources: Sources) -> str | None:
"""排除了行,这个指标却有输入说不准受不受影响:返回原因;没排除行、或者输入都对得上号的返回 None。
对得上号的输入(cell() 那一格、agent 的单格字段和数组字段、整份查询结果)排除行怎么影响它是确定的,_apply 照办;
数组字段的完整值找不回来时也知道它用到哪几行,排除了那几行就算碰到了它(指标因它还原不了而推演不了)。
别的输入——完整值找不回来的容器、对不上任何快照的容器(加工过的结果)、不是直接取自快照的数(按位置从整份结果里
取的一格、transform 由查询结果算出来的数)——都可能来自被排除了行的那份结果,又重算不了,只能说不知道,不能拿
原值算出一个「无变化」或者一个不对应任何一份数据的数。给了新值的以新值为准,只嵌在给了新值的引用里的也就无关紧要
(_Plan.moot);写它的节点在那份快照交回之前就跑完了的,影响不到它(_after)。
"""
if not changes.exclude:
return None
for path, inp in plan.inputs.items():
if path in changes.inputs or inp.snapshot is not None or plan.moot(path, changes):
continue
if any(_after(snapshot, inp, sources) for snapshot in changes.exclude):
why = inp.problem or (DOUBT_UNMATCHED if inp.shape == "container" else DOUBT_DERIVED)
return DOUBT.format(path=path, why=why)
return None
def _after(snapshot: str, inp: _Input, sources: Sources) -> bool:
"""这个输入可能是在这份快照交回之后才算出来的:写它的节点不早于快照交回跑完(合并查询的快照就记在它自己跑完的
那条事件里),或者两样有一样不知道。"""
writer = inp.item.get("node_id")
returned = sources.returned.get(snapshot)
finished = sources.finished.get(str(writer)) if writer else None
return returned is None or finished is None or finished >= returned
def _compute(plan: _Plan, values: dict[str, Any], notes: dict[str, list[int]], changes: Changes,
doubt: str | None) -> tuple[str, Any, str | None]:
"""(status, 新值, 原因)。整个推演不了的(_Plan.blocked)到不了这里。排除后缺了的、说不准受不受影响的先说,
都没有才求值。只嵌在给了新值的引用里的输入(_Plan.moot)不论排除了什么都不碍事:那几个引用以新值为准。"""
hit = [(path, inp) for path, inp in plan.inputs.items()
if path in notes and path not in changes.inputs and not plan.moot(path, changes)]
for path, inp in hit:
if inp.row is not None:
return "excluded", None, f"{EXCLUDED}:{path} 所在的第 {inp.row + 1} 行已排除"
for path, inp in hit:
if inp.selector and not plan.settled(path, changes):
# 嵌在下标、cell() 行列里的容器少了几行:外面那个引用取到的是哪一格跟着变,卡上记的值不再作数。
# 包着它的引用都给了新值时,它只剩自己作为最外层引用的那一处(排除了哪几行是确定的),照常算
return "unsupported", None, DOUBT.format(path=path, why=DOUBT_SELECTOR)
if doubt:
return "unsupported", None, doubt
value, reason = _evaluate(plan, values)
if reason is None and is_number(value) and not _number(value):
# 溢出成无穷大、算出非数、乘出浮点放不下的整数:口径卡渲染成「—」,这里也说清算不出来(JSON 里也放不下)
reason = NOT_FINITE
return ("ok", value, None) if reason is None else ("error", None, reason)
class _Bind(ast.NodeTransformer):
"""把最外层的引用换成占位名,值从上下文里按名字取:和口径卡当时在完整的上下文里取到的是同一个值。
认引用的规则和 expressions._Substitute 一样(取值链、整个 cell() 调用)。"""
def __init__(self, names: dict[str, str]) -> None:
self.names = names
def _swap(self, node: ast.AST) -> ast.AST | None:
name = self.names.get(ast.unparse(node))
return None if name is None else ast.copy_location(ast.Name(id=name, ctx=ast.Load()), node)
def visit_Call(self, node: ast.Call) -> ast.AST:
if _cell_call(node) and (swapped := self._swap(node)) is not None:
return swapped
return self.generic_visit(node)
def _chain(self, node: ast.AST) -> ast.AST:
if _chain_root(node) is None:
return self.generic_visit(node)
swapped = self._swap(node)
return swapped if swapped is not None else node
visit_Attribute = visit_Subscript = visit_Name = _chain
def _evaluate(plan: _Plan, values: dict[str, Any]) -> tuple[Any, str | None]:
"""按原式求值,报错的说法和口径卡一致。浮点结果按卡上的小数位 round(metrics.run_metrics 同样只 round 浮点)。"""
names = {path: _PLACEHOLDER.format(i) for i, path in enumerate(plan.tops)}
bound = ast.fix_missing_locations(_Bind(names).visit(copy.deepcopy(plan.tree)))
ctx = {names[p]: values.get(p) for p in plan.tops}
try:
value = eval_expression(ast.unparse(bound), ctx)
except ExpressionError as e:
return None, f"表达式有误({e})"
except ZeroDivisionError:
return None, "除以零"
except Exception as e: # noqa: BLE001 - None 参与算术、类型不对:和口径卡一样说人话
if any(v is None for v in ctx.values()) or "NoneType" in str(e):
return None, "有输入为空值,无法计算"
if isinstance(e, TypeError):
return None, "输入的类型不正确,无法计算"
return None, f"无法计算({describe_exception(e)})"
decimals = plan.metric.get("decimals")
if isinstance(value, float) and isinstance(decimals, int) and not isinstance(decimals, bool):
value = round(value, decimals)
return value, None
# --------------------------------------------------------------------------
# 结果
# --------------------------------------------------------------------------
#: 这几种状态下新值是确定的(算出来了,或者确定算不出来);unsupported、masked 是不知道
_KNOWN = frozenset({"unchanged", "ok", "excluded", "error"})
def _result(plan: _Plan, status: str, new: Any, reason: str | None, values: dict[str, Any],
notes: dict[str, list[int]]) -> dict[str, Any]:
metric = plan.metric
old = metric.get("value")
known = status in _KNOWN
blocked = plan.blocked is not None
delta, rendered_delta = _delta(metric, old, new) if known else (None, None)
substituted = metric.get("substituted") if status == "unchanged" \
else substitute(plan.tree, values) if status == "ok" and plan.tree is not None else None
if any(inp.masked or inp.unreadable for inp in plan.inputs.values()):
substituted = None # 代入式里代进去的就是遮罩列(或者遮没遮核对不了)的那一格
return {
"id": metric.get("id"), "name": metric.get("name") or metric.get("id"), "unit": metric.get("unit") or "",
"decimals": metric.get("decimals"), "format": metric.get("format") or DEFAULT_FORMAT,
"old": _finite(old), "new": _finite(new), "delta": delta,
"rendered_old": _render(metric, old), "rendered_new": _render(metric, new) if known else None,
"rendered_delta": rendered_delta,
"changed": (not _same(old, new)) if known else None,
"status": status, "reason": reason, "substituted": substituted,
"inputs": [_input_view(inp, values, notes, blocked=blocked) for inp in plan.inputs.values()],
}
def _render(metric: dict[str, Any], value: Any, conv: str | None = None) -> str:
"""按卡上的格式渲染:和口径卡的 rendered、报告里的字同一套规则。渲染不出来的显示「—」(metrics._rendered 同样)。"""
try:
return render_metric({**metric, "value": value}, conv)
except RenderError:
return MISSING
def _finite(value: Any) -> Any:
"""无穷大、非数、浮点放不下的整数换成 None:老卡上可能记着(口径卡渲染成「—」),JSON 里放不下或界面读不准。"""
return None if is_number(value) and not _number(value) else value
def _same(a: Any, b: Any) -> bool:
if is_number(a) and is_number(b):
return a == b or (isinstance(a, float) and isinstance(b, float) and math.isnan(a) and math.isnan(b))
return a == b
def _delta(metric: dict[str, Any], old: Any, new: Any) -> tuple[Any, str | None]:
"""变化量和它的写法。比率、百分数的变化写「个百分点」:8.7% 到 19.0% 是多了 10.3 个百分点,不是 10.3%。"""
if not (_number(old) and _number(new)):
return None, None
delta = new - old
decimals = metric.get("decimals")
places = decimals if isinstance(decimals, int) and not isinstance(decimals, bool) else None
if isinstance(delta, float) and places is not None:
delta = round(delta, places)
if delta == 0:
return delta, None
fmt = metric.get("format") or DEFAULT_FORMAT
unit = str(metric.get("unit") or "")
try:
if fmt == "percent_of_ratio":
text = render_number(abs(delta), decimals=places, fmt=fmt).rstrip("%") + " 个百分点"
elif unit in ("%", "%"):
text = render_number(abs(delta), decimals=places, fmt=fmt) + " 个百分点"
else:
text = render_number(abs(delta), unit=unit, decimals=places, fmt=fmt)
except RenderError:
return delta, None
return delta, ("+" if delta > 0 else "-") + text
def _kind(inp: _Input) -> str:
if inp.shape == "container":
return "container"
value = inp.item.get("value")
return "missing" if value is None else "bool" if isinstance(value, bool) \
else "number" if is_number(value) else "text"
def _editable(inp: _Input, *, blocked: bool) -> bool:
"""推演里能改的输入:数值(或原本缺失)的标量,不是遮罩列、不决定取哪一格、还原得出。整个指标推演不了时一个都不算:
改了也推演不出来。"""
return not blocked and inp.shape == "scalar" and not inp.masked and not inp.selector and inp.problem is None \
and (inp.value is None or _number(inp.value))
def _row_span(inp: _Input) -> tuple[int, int] | None:
"""这个输入实际用到的快照行(含两端):单格一行、数组字段一段、整份结果全部。排除别的行影响不到它,界面据此只让
这几行可勾。遮罩的、还原不了的(完整值找不回来、快照读不出来,都记在 problem 里)不给:排除它们的行什么也推演
不出来。决定取哪一格的数组字段、整份结果也不给:少了几行,外面那个引用取到哪一格说不准(_compute),勾了只能
说不知道,「不支持推演的输入」里又说它不能用。决定取哪一格的单格照给:勾掉它,确定是排除后无法计算。"""
if inp.snapshot is None or inp.masked or inp.problem is not None:
return None
if inp.row is not None:
return inp.row, inp.row
if inp.selector:
return None
if inp.rows is not None:
return inp.rows
rows = inp.value.get("rows") if isinstance(inp.value, dict) else inp.value
return (0, len(rows) - 1) if inp.table and isinstance(rows, list) and rows else None
def _input_view(inp: _Input, values: dict[str, Any], notes: dict[str, list[int]], *, blocked: bool) -> dict[str, Any]:
"""一个输入在推演里的样子:原值、新值、排除了哪几行、用到快照的哪几行(row_span)。遮罩列取来的、落在读不出来的
快照上的不给值。容器写大概(「[12 项]」)。整个指标推演不了时(blocked)一个都不让改、不给行段。"""
item = inp.item
span = None if blocked else _row_span(inp)
view: dict[str, Any] = {"path": inp.path, "via": item.get("via"), "node_id": item.get("node_id"),
**({"artifact": inp.snapshot} if inp.snapshot else {}),
**({"locator": item["locator"]} if isinstance(item.get("locator"), dict) else {}),
**({"row_span": list(span)} if span else {}),
"kind": _kind(inp), "editable": _editable(inp, blocked=blocked)}
if inp.masked:
return {**view, "old": None, "new": None, "changed": False, "masked": True}
if inp.unreadable and inp.shape == "scalar":
return {**view, "old": None, "new": None, "changed": False, "withheld": True}
if inp.shape == "container":
old = _outline(inp.value, inp.table) if inp.problem is None else item.get("value")
new = _outline(values.get(inp.path), inp.table) if inp.problem is None else None
# 完整值找不回来的数组排除了它用到的行:少了几项是确定的,只是新的样子不知道(new 为空)
changed = not _same(old, new) if inp.problem is None else inp.path in notes
else:
old, new = _finite(item.get("value")), _finite(values.get(inp.path))
changed = not _same(old, new)
view.update(old=old, new=new, changed=changed)
if inp.path in notes:
view["excluded_rows"] = notes[inp.path]
return view
def _outline(value: Any, table: bool) -> Any:
"""容器的大概。整份查询结果写行数(「[12 项]」),排除了几行看得出来;别的照卡上的写法。"""
if table and isinstance(value, dict) and isinstance(value.get("rows"), list):
return _brief(value["rows"])
return _brief(value) if isinstance(value, (list, dict)) else value
def _unsupported(plans: list[_Plan]) -> list[dict[str, Any]]:
"""不能用于推演的输入和原因:遮罩的、完整值找不回来的(含快照读不出来的)、决定取哪一格的、既不能改也没有行可勾的。
整个指标推演不了的(_Plan.blocked)先有一条 input 为空的,原因和指标上的一样:界面据此只写原因,不画输入框、
勾选框。之后只列卡住它的输入(遮罩的、还原不了的),别的输入能不能改已无从谈起;卡本身没记输入的只有这一条。
"""
out: list[dict[str, Any]] = []
for plan in plans:
metric_id = plan.metric.get("id")
if blocked := plan.blocked:
out.append({"metric": metric_id, "input": None, "reason": blocked[1]})
if plan.problem:
continue
for inp in plan.inputs.values():
if blocked and not (inp.masked or inp.problem):
continue
reason = (MASKED_TABLE if inp.table else MASKED_INPUT) if inp.masked \
else f"无法推演:{inp.problem}" if inp.problem \
else SELECTOR if inp.selector else _fixed(inp)
if reason:
out.append({"metric": metric_id, "input": inp.path, "reason": reason})
return out
def _fixed(inp: _Input) -> str | None:
"""还原得出、没遮罩,却既不能改值、也没有行可勾的输入:说清为什么,不让人对着一个改不了的值干看。"""
if inp.shape == "container":
return None if _row_span(inp) is not None else FIXED_CONTAINER
value = inp.item.get("value")
return None if value is None or is_number(value) else NOT_NUMBER
# --------------------------------------------------------------------------
# 报告里引用的地方、下游口径卡
# --------------------------------------------------------------------------
def report_segments(reports: Iterable[tuple[str, dict[str, Any]]], *, card_node: str, card_artifact: str,
results: list[dict[str, Any]]) -> list[dict[str, Any]]:
"""报告里引用了这些指标的片段,推演之后会写成什么:[{report, unit, sid, metric, rendered_old, rendered_new, changed}]。
只认指向这张卡这一份指标集的引用(目录条目的 node_id、artifact):循环里同一张卡算过几次,报告引用的是哪一次
就是哪一次。新值按片段自己的换算(|万、|pct……)渲染,和报告里的字同一套规则。指标推演不了(unsupported、masked)
时 rendered_new、changed 为 None:不知道会变成什么。缺输入、当时就显示「—」的引用也列上:推演里补上了值,它会变。
"""
by_id = {str(r.get("id")): r for r in results}
out: list[dict[str, Any]] = []
for report_node, doc in reports:
catalog = doc.get("catalog") or {}
for _, unit in iter_units(doc):
for seg in unit.get("segments") or []:
cite = seg.get("cite") or {}
entry = catalog.get(cite.get("alias")) or {}
if entry.get("kind") != "metric" or entry.get("node_id") != card_node \
or entry.get("artifact") != card_artifact or not _cites(seg, cite, entry):
continue
result = by_id.get(str((entry.get("locator") or {}).get("metric")))
if result is None:
continue
new = None if result.get("rendered_new") is None else _render(result, result.get("new"), cite.get("conv"))
out.append({"report": report_node, "unit": unit.get("id"), "sid": seg.get("id"), "metric": result["id"],
"rendered_old": seg.get("text"), "rendered_new": new,
"changed": None if new is None else new != seg.get("text")})
return out
def _cites(seg: dict[str, Any], cite: dict[str, Any], entry: dict[str, Any]) -> bool:
"""片段引用了这个指标:解析成功的引用,或者指标在、只是这次缺输入没有值(显示「—」)的那种。"""
if cite.get("kind") != "metric":
return False
if seg.get("state") == "deterministic" and cite.get("status") == "resolved":
return True
return cite.get("status") == "unresolved" and entry.get("value") is None and entry.get("status") == "missing_input"
def downstream_cards(cards: Iterable[tuple[str, str, dict[str, Any]]], node_id: str, *,
edges: Iterable[tuple[Any, Any]] = ()) -> list[dict[str, Any]]:
"""引用了这张口径卡的下游口径卡:[{node_id, artifact, caliber, version, metrics, direct}]。
只标「可能受影响」,不重算:下游卡怎么用这张卡的值(取第几个指标、和别的什么一起算)要整条链重放才说得准。
认引用看下游指标的输入从哪个节点来(node_id,或者 nodes.<卡> 这样的路径):直接来自这张卡的标 direct。
经别的卡间接用到的也标;给了画布上的边(edges)时,从这张卡顺着边走得到的节点也算上游——下游卡经 transform 之类
的中间节点用到卡上的值(输入写的是 vars.t.g,来自中间节点),同样可能受影响。循环的回边会让循环里的节点都走得到,
宁可多标。同一张卡执行过几次的按最后一次。
"""
latest: dict[str, tuple[str, dict[str, Any]]] = {}
for nid, artifact, card in cards:
latest[str(nid)] = (artifact, card)
latest.pop(str(node_id), None)
def uses(card: dict[str, Any], upstream: set[str]) -> list[str]:
found = []
for metric in card.get("metrics") or []:
for item in (metric.get("inputs") or []) if isinstance(metric, dict) else []:
head = _REF_HEAD.match(str(item.get("path") or "")) if isinstance(item, dict) else None
origins = {str(item.get("node_id") or "")} | ({head.group(2)} if head and head.group(1) == "nodes" else set())
if origins & upstream:
found.append(metric.get("id"))
break
return found
upstream = {str(node_id)} | _reach(edges, str(node_id))
flagged: dict[str, dict[str, Any]] = {}
grew = True
while grew:
# 标出来的卡本身也成了上游:经它间接用到的再标一轮,直到没有新的
grew = False
for nid, (artifact, card) in latest.items():
if nid in flagged or not (metrics := uses(card, upstream)):
continue
flagged[nid] = {"node_id": nid, "artifact": artifact, "caliber": card.get("caliber") or "",
"version": card.get("caliber_version") or "", "metrics": metrics,
"direct": bool(uses(card, {str(node_id)}))}
upstream.add(nid)
grew = True
return [flagged[nid] for nid in latest if nid in flagged]
def _reach(edges: Iterable[tuple[Any, Any]], start: str) -> set[str]:
"""从 start 顺着边走得到的节点(不含 start 自己,除非绕回来)。"""
after: dict[str, list[str]] = {}
for a, b in edges:
after.setdefault(str(a), []).append(str(b))
seen: set[str] = set()
todo = [start]
while todo:
for nxt in after.get(todo.pop(), []):
if nxt not in seen:
seen.add(nxt)
todo.append(nxt)
return seen
+208
View File
@@ -0,0 +1,208 @@
{
"_comment": "口径卡的金样:加 value_artifact 之前的代码(feat/verify-suite 35bb23d)真跑出来的 metric_set 工件。scalar 是只有标量输入的卡,改动之后工件必须逐字节相同(工件 id 不变);box 带容器型 vars 输入,改动之后只多 value_artifact 这一个键。虚构数据。",
"scalar": {
"artifact": "4af4e64d2fac8bae1f0acc8f65573afb3b527547878c053cc9b6d6687e321408",
"card": {
"caliber": "推演口径",
"caliber_version": "v3",
"kind": "metric_set",
"metrics": [
{
"decimals": 1,
"expression": "vars.kpi.gmv",
"format": "thousands",
"id": "gmv",
"inputs": [
{
"field": "gmv",
"node_id": "fetch",
"path": "vars.kpi.gmv",
"status": "ok",
"value": 45678.5,
"via": "transform"
}
],
"name": "销售额",
"recompute_ok": true,
"rendered": "45,678.5元",
"status": "ok",
"substituted": "45678.5",
"unit": "元",
"value": 45678.5
},
{
"decimals": 1,
"expression": "round((vars.kpi.gmv - vars.kpi.gmv_prev) / vars.kpi.gmv_prev * 100, 1)",
"format": "plain",
"id": "wow",
"inputs": [
{
"field": "gmv",
"node_id": "fetch",
"path": "vars.kpi.gmv",
"status": "ok",
"value": 45678.5,
"via": "transform"
},
{
"field": "gmv_prev",
"node_id": "fetch",
"path": "vars.kpi.gmv_prev",
"status": "ok",
"value": 42010.0,
"via": "transform"
}
],
"name": "环比增幅",
"recompute_ok": true,
"rendered": "8.7%",
"status": "ok",
"substituted": "round((45678.5 - 42010.0) / 42010.0 * 100, 1)",
"unit": "%",
"value": 8.7
},
{
"decimals": null,
"expression": "vars.kpi.orders",
"format": "thousands",
"id": "orders",
"inputs": [
{
"field": "orders",
"node_id": "fetch",
"path": "vars.kpi.orders",
"status": "ok",
"value": 1234,
"via": "transform"
}
],
"name": "订单数",
"recompute_ok": true,
"rendered": "1,234单",
"status": "ok",
"substituted": "1234",
"unit": "单",
"value": 1234
},
{
"decimals": 4,
"expression": "vars.kpi.refunds / vars.kpi.orders",
"format": "percent_of_ratio",
"id": "refund_rate",
"inputs": [
{
"field": "refunds",
"node_id": "fetch",
"path": "vars.kpi.refunds",
"status": "ok",
"value": 29,
"via": "transform"
},
{
"field": "orders",
"node_id": "fetch",
"path": "vars.kpi.orders",
"status": "ok",
"value": 1234,
"via": "transform"
}
],
"name": "退款率",
"recompute_ok": true,
"rendered": "2.35%",
"status": "ok",
"substituted": "29 / 1234",
"unit": "",
"value": 0.0235
}
]
}
},
"box": {
"artifact": "e2ec0b24639f78e4c14a22408516e5e6d7e4890025a6d0cbcad6fa7828bfbee9",
"card": {
"caliber": "推演口径",
"caliber_version": "v3",
"kind": "metric_set",
"metrics": [
{
"decimals": null,
"expression": "len(vars.kpi.items)",
"format": "thousands",
"id": "n",
"inputs": [
{
"field": "items",
"node_id": "fetch",
"path": "vars.kpi.items",
"status": "ok",
"value": "[3 项]",
"via": "transform"
}
],
"name": "条数",
"recompute_ok": true,
"rendered": "3",
"status": "ok",
"substituted": "len(vars.kpi.items)",
"unit": "",
"value": 3
},
{
"decimals": null,
"expression": "len(vars.kpi.meta)",
"format": "thousands",
"id": "m",
"inputs": [
{
"field": "meta",
"node_id": "fetch",
"path": "vars.kpi.meta",
"status": "ok",
"value": "{2 个字段}",
"via": "transform"
}
],
"name": "字段数",
"recompute_ok": true,
"rendered": "2",
"status": "ok",
"substituted": "len(vars.kpi.meta)",
"unit": "",
"value": 2
},
{
"decimals": null,
"expression": "sum(vars.kpi.items) + vars.kpi.gmv",
"format": "thousands",
"id": "s",
"inputs": [
{
"field": "items",
"node_id": "fetch",
"path": "vars.kpi.items",
"status": "ok",
"value": "[3 项]",
"via": "transform"
},
{
"field": "gmv",
"node_id": "fetch",
"path": "vars.kpi.gmv",
"status": "ok",
"value": 10,
"via": "transform"
}
],
"name": "合计",
"recompute_ok": true,
"rendered": "25",
"status": "ok",
"substituted": "sum(vars.kpi.items) + 10",
"unit": "",
"value": 25
}
]
}
}
}
+138
View File
@@ -0,0 +1,138 @@
"""口径卡给容器型的 vars.* 输入另存一份完整值(value_artifact),数字推演据此重算。
卡里的输入对列表、字典只记一个大概(「[12 项]」),事后要改一行、重算一遍,手里没有完整的值。nodes.*、input.*
的完整值在那个节点封存的产出工件里,agent 字段能按出处从查询快照还原;vars 是谁写的、写进去的是不是节点产出
本身说不准,只能在口径卡算的那一刻存下来。
守的是「只多一个键」:只有标量输入的卡逐字节和改动之前一样(工件 id 不变,引用它的报告也就不变);带容器型
vars 输入的卡,去掉 value_artifact 之后和改动之前一样。金样是改动之前的代码真跑出来的(fixtures/whatif)。
"""
from __future__ import annotations
import asyncio
import copy
import json
from pathlib import Path
import pytest
from sqlalchemy import select
from app.core import artifact_store
from app.db.base import SessionLocal
from app.db.models import Artifact, Run, RunEvent
from app.engine.runner import run_manager
GOLDEN = json.loads((Path(__file__).parent / "fixtures" / "whatif" / "golden_cards.json").read_text("utf-8"))
SCALAR_KPI = "{'gmv': 45678.5, 'gmv_prev': 42010.0, 'orders': 1234, 'refunds': 29}"
SCALAR = [
{"id": "gmv", "name": "销售额", "unit": "元", "decimals": 1, "expression": "vars.kpi.gmv"},
{"id": "wow", "name": "环比增幅", "unit": "%", "decimals": 1, "format": "plain",
"expression": "round((vars.kpi.gmv - vars.kpi.gmv_prev) / vars.kpi.gmv_prev * 100, 1)"},
{"id": "orders", "name": "订单数", "unit": "单", "expression": "vars.kpi.orders"},
{"id": "refund_rate", "name": "退款率", "decimals": 4, "format": "percent_of_ratio",
"expression": "vars.kpi.refunds / vars.kpi.orders"},
]
BOX_KPI = "{'items': [3, 5, 7], 'meta': {'a': 1, 'b': 2}, 'gmv': 10}"
BOX = [
{"id": "n", "name": "条数", "expression": "len(vars.kpi.items)"},
{"id": "m", "name": "字段数", "expression": "len(vars.kpi.meta)"},
{"id": "s", "name": "合计", "expression": "sum(vars.kpi.items) + vars.kpi.gmv"},
]
@pytest.fixture(autouse=True)
async def engine_up():
await run_manager.setup()
yield
await run_manager.shutdown()
def node(nid, ntype, **config):
return {"id": nid, "type": ntype, "position": {"x": 0, "y": 0}, "data": {"label": nid, "config": config}}
def graph(expr, metrics):
nodes = [node("start", "input"), node("fetch", "transform", mode="expression", expression=expr, assign_to="kpi"),
node("card", "metrics", caliber="推演口径", caliber_version="v3", metrics=metrics),
node("out", "output", fields=[{"name": "清单", "value": "{{ nodes.card.text }}"}])]
return {"nodes": nodes, "edges": [{"source": a["id"], "target": b["id"]} for a, b in zip(nodes, nodes[1:])]}
async def finished(g) -> tuple[Run, dict]:
run = await run_manager.start(graph=g, input_payload={})
for _ in range(300):
await asyncio.sleep(0.05)
async with SessionLocal() as session:
row = await session.get(Run, run.id)
if row.status in ("succeeded", "failed") and row.manifest_seq is not None:
break
assert row.status == "succeeded", row.error
async with SessionLocal() as session:
[event] = (await session.execute(select(RunEvent).where(
RunEvent.run_id == run.id, RunEvent.type == "node.finished", RunEvent.node_id == "card"))).scalars()
return row, event.data
def without_value_artifacts(card: dict) -> dict:
out = copy.deepcopy(card)
for metric in out["metrics"]:
for item in metric.get("inputs") or []:
item.pop("value_artifact", None)
return out
async def test_a_card_with_only_scalar_inputs_is_byte_identical_to_before():
row, data = await finished(graph(SCALAR_KPI, SCALAR))
[entry] = data["evidence"]
assert entry["artifact"] == GOLDEN["scalar"]["artifact"], "只有标量输入的卡,工件 id 不能变"
assert artifact_store.load(entry["artifact"]) == GOLDEN["scalar"]["card"]
assert "value_artifact" not in json.dumps(artifact_store.load(entry["artifact"]))
async def test_container_vars_inputs_carry_their_full_value():
row, data = await finished(graph(BOX_KPI, BOX))
[entry] = data["evidence"]
card = artifact_store.load(entry["artifact"])
# 去掉新加的键,和改动之前一字不差:值、渲染、代入式、复算、其余字段都不变
assert without_value_artifacts(card) == GOLDEN["box"]["card"]
by_path = {(m["id"], i["path"]): i for m in card["metrics"] for i in m["inputs"]}
items, meta = by_path[("n", "vars.kpi.items")], by_path[("m", "vars.kpi.meta")]
assert items["value"] == "[3 项]" and meta["value"] == "{2 个字段}"
assert artifact_store.load(items["value_artifact"]) == {"path": "vars.kpi.items", "value": [3, 5, 7]}
assert artifact_store.load(meta["value_artifact"]) == {"path": "vars.kpi.meta", "value": {"a": 1, "b": 2}}
# 同一个输入在两个指标里:同一份内容只存一份
assert by_path[("s", "vars.kpi.items")]["value_artifact"] == items["value_artifact"]
# 标量输入不另存
assert "value_artifact" not in by_path[("s", "vars.kpi.gmv")]
async with SessionLocal() as session:
stored = await session.get(Artifact, (items["value_artifact"], row.id))
assert stored is not None and stored.kind == "metric_input" and stored.node_id == "card"
# 台账只有指标集这一条:完整值经指标集(内容寻址、封存范围内)引用,不另起台账条目
assert [e["kind"] for e in data["evidence"]] == ["metric_set"]
assert row.output["清单"] == "指标清单(口径 推演口径 @ v3):\n- n(条数)= 3\n- m(字段数)= 2\n- s(合计)= 25"
async def test_only_vars_containers_are_stored():
"""nodes.* 的完整值在那个节点封存的产出工件里,不另存。"""
row, data = await finished(graph(BOX_KPI, [
{"id": "n", "name": "条数", "expression": "len(nodes.fetch.items)"},
{"id": "v", "name": "条数", "expression": "len(vars.kpi.items)"},
]))
card = artifact_store.load(data["evidence"][0]["artifact"])
[n_input] = card["metrics"][0]["inputs"]
[v_input] = card["metrics"][1]["inputs"]
assert n_input["path"] == "nodes.fetch.items" and "value_artifact" not in n_input
assert v_input["path"] == "vars.kpi.items" and "value_artifact" in v_input
async def test_a_value_too_large_to_keep_is_skipped(monkeypatch):
"""完整值大过上限就不另存:推演据此说明当时没有保存,卡照常算出来。"""
from app.engine.nodes import metrics
monkeypatch.setattr(metrics, "VALUE_ARTIFACT_MAX", 10)
row, data = await finished(graph(BOX_KPI, BOX))
card = artifact_store.load(data["evidence"][0]["artifact"])
assert card == GOLDEN["box"]["card"]
+903
View File
@@ -0,0 +1,903 @@
"""数字推演的重算(engine/recompute.py):纯函数,口径卡怎么算的这里就怎么算。
卡、查询快照、节点产出都是照 metrics.py 的形状手写的虚构数据;工件库换成一个字典。守的是:
- 不改任何输入时,每个能还原的指标重算出来和卡上记的一模一样
- 改输入、排除快照里的行,结果和手算一致;排除了 cell() 那一格所在的行,指标标「排除后无法计算」
- 容器输入的还原:agent 数组字段(按 locator.rows 去掉被排除的行)、nodes.* 从节点产出、vars.* 只认 value_artifact
- 遮罩列取来的输入既不给值、也不能拿来推演
- 整个指标推演不了的(遮罩列、还原不了的输入、读不出来的快照、没记输入),不改动也照实说,输入一个都不让动
- 排除了行却说不准受不受影响的指标,不报「无变化」,也不给勾了只能说不准的行段;给了新值的以新值为准
- 不合法的请求抛 WhatIfError(接口回 422),说清哪里不对
"""
from __future__ import annotations
import json
import math
import pytest
from app.engine.recompute import Changes, Sources, WhatIfError, downstream_cards, recompute, report_segments, whatif
S1, S2, BAD = "a1" * 32, "b2" * 32, "c3" * 32
SNAPSHOTS = {
S1: {"columns": ["region", "amount", "phone"], "source": "shop", "sql": "SELECT region, amount, phone FROM sales",
"rows": [["华东", 120.5, "p1"], ["华南", 80.0, "p2"], ["华北", 99.5, "p3"], ["西南", 40.0, "p4"]]},
S2: {"columns": ["store", "phone"], "source": "crm", "sql": "SELECT store, phone FROM stores",
"rows": [["一号店", "13800000000"], ["二号店", "13900000000"]]},
}
BOT_OUT = "d4" * 32
FETCH_OUT = "e5" * 32
ITEMS_VALUE = "f6" * 32
RES_ROWS = "a7" * 32
STORE = {
**SNAPSHOTS,
BOT_OUT: {"text": "四个区域合计 340", "data": {"amounts": [120.5, 80.0, 99.5, 40.0]},
"data_evidence": {"amounts": {"ref": "Q1.r0-3.amount", "call": "Q1", "artifact": S1,
"locator": {"rows": [0, 3], "column": "amount"}, "status": "verified"}}},
FETCH_OUT: {"items": ["甲", "乙", "丙"], "k": 2},
ITEMS_VALUE: {"path": "vars.kpi.items", "value": ["甲", "乙", "丙"]},
RES_ROWS: {"path": "vars.res.rows", "value": SNAPSHOTS[S1]["rows"]},
}
def load(artifact):
if artifact == BAD:
raise ValueError("工件内容与哈希不符,疑似被篡改")
return STORE.get(artifact)
def sources(**kw):
base = {"load": load, "queries": (S1, S2, BAD), "outputs": {"bot": BOT_OUT, "fetch": FETCH_OUT},
"masked": {S2: frozenset({"phone"})}}
return Sources(**{**base, **kw})
def scalar(path, value, node="fetch", via="transform"):
return {"path": path, "value": value, "node_id": node, "via": via, "field": path.split(".", 2)[-1], "status": "ok"}
def cell(node, row, column, value, artifact=S1):
return {"path": f"cell(nodes.{node}, {row}, '{column}')", "value": value, "node_id": node, "via": "tool_cell",
"locator": {"row": row, "column": column}, "artifact": artifact, "eid": "ev:cell:x", "status": "verified"}
AMOUNTS = {"path": "vars.kpi.amounts", "value": "[4 项]", "node_id": "bot", "via": "agent_field", "field": "amounts",
"ref": "Q1.r0-3.amount", "artifact": S1, "locator": {"rows": [0, 3], "column": "amount"},
"eid": "ev:rows:x", "status": "verified"}
def metric(mid, expression, substituted, value, inputs, *, decimals=None, fmt="thousands", unit="", rendered=None):
from app.engine.evidence import render_number
return {"id": mid, "name": mid, "unit": unit, "value": value, "expression": expression, "decimals": decimals,
"format": fmt, "rendered": rendered if rendered is not None else render_number(
value, unit=unit, decimals=decimals, fmt=fmt),
"inputs": inputs, "substituted": substituted, "recompute_ok": True, "status": "ok"}
WOW = "round((vars.kpi.gmv - vars.kpi.prev) / vars.kpi.prev * 100, 1)"
CARD = {"kind": "metric_set", "caliber": "推演口径", "caliber_version": "v3", "metrics": [
metric("wow", WOW, "round((45678.5 - 42010.0) / 42010.0 * 100, 1)", 8.7,
[scalar("vars.kpi.gmv", 45678.5), scalar("vars.kpi.prev", 42010.0)], decimals=1, fmt="plain", unit="%"),
metric("total", "sum(vars.kpi.amounts)", "sum(vars.kpi.amounts)", 340.0, [AMOUNTS], decimals=1, unit="元"),
metric("east", "cell(nodes.pull, 0, 'amount')", "120.5", 120.5, [cell("pull", 0, "amount", 120.5)],
decimals=1, unit="元"),
metric("share", "round(cell(nodes.pull, 0, 'amount') / sum(vars.kpi.amounts) * 100, 1)",
"round(120.5 / sum(vars.kpi.amounts) * 100, 1)", 35.4, [cell("pull", 0, "amount", 120.5), AMOUNTS],
decimals=1, fmt="plain", unit="%"),
metric("ratio", "vars.kpi.refunds / vars.kpi.orders", "29 / 1234", 0.0235,
[scalar("vars.kpi.refunds", 29), scalar("vars.kpi.orders", 1234)], decimals=4, fmt="percent_of_ratio"),
# 老运行:容器型 vars 输入没有 value_artifact
metric("n", "len(vars.kpi.items) * vars.kpi.k", "len(vars.kpi.items) * 2", 6,
[scalar("vars.kpi.items", "[3 项]"), scalar("vars.kpi.k", 2)]),
# 新运行:有 value_artifact
metric("n2", "len(vars.kpi.items) * vars.kpi.k", "len(vars.kpi.items) * 2", 6,
[{**scalar("vars.kpi.items", "[3 项]"), "value_artifact": ITEMS_VALUE}, scalar("vars.kpi.k", 2)]),
# nodes.* 容器从节点产出还原
metric("n3", "len(nodes.fetch.items) + vars.kpi.k", "len(nodes.fetch.items) + 2", 5,
[{**scalar("nodes.fetch.items", "[3 项]"), "field": "items"}, scalar("vars.kpi.k", 2)]),
# 整份查询结果赋给了变量:排除行就去掉那几行
metric("rows", "len(vars.res.rows) * vars.kpi.k", "len(vars.res.rows) * 2", 8,
[{**scalar("vars.res.rows", "[4 项]", node="parse"), "value_artifact": RES_ROWS}, scalar("vars.kpi.k", 2)]),
# 取自遮罩列
metric("phone_len", "len(cell(nodes.crm, 0, 'phone'))", "len('13800000000')", 11,
[cell("crm", 0, "phone", "13800000000", artifact=S2)]),
# 下标里的引用决定取哪一格
metric("pick", "vars.kpi.list[vars.kpi.i] + 1", "20 + 1", 21,
[scalar("vars.kpi.list[vars.kpi.i]", 20), scalar("vars.kpi.i", 1)]),
]}
def by_id(result):
return {m["id"]: m for m in result["metrics"]}
def one(mid, changes=Changes(), **kw):
found = next(m for m in CARD["metrics"] if m["id"] == mid)
return recompute(found, changes, sources(**kw))
# --------------------------------------------------------------------------
# 不改输入:还原是忠实的
# --------------------------------------------------------------------------
@pytest.mark.parametrize("mid", ["wow", "total", "east", "share", "ratio", "n2", "n3", "rows", "pick"])
def test_unchanged_inputs_reproduce_the_card(mid):
out = one(mid)
old = next(m for m in CARD["metrics"] if m["id"] == mid)
assert out["status"] == "ok", out
assert out["new"] == old["value"] and out["rendered_new"] == old["rendered"]
assert out["changed"] is False and out["delta"] == 0
def test_an_old_run_container_cannot_be_restored():
out = one("n")
assert out["status"] == "unsupported" and out["new"] is None and out["rendered_new"] is None
assert "当时没有保存这个输入的完整值" in out["reason"] and "vars.kpi.items" in out["reason"]
def test_a_baseline_lists_what_cannot_be_used_without_recomputing_anything():
result = whatif(CARD, Changes(), sources())
metrics = by_id(result)
# 推演得了的指标原样交回;整个推演不了的(老运行没存完整值的容器、遮罩列)不改动也照实说,不报「无变化」
assert all(m["status"] == "unchanged" and m["new"] == m["old"] and m["changed"] is False
for k, m in metrics.items() if k not in ("n", "phone_len"))
assert [(metrics[k]["status"], metrics[k]["changed"], metrics[k]["rendered_new"]) for k in ("n", "phone_len")] == [
("unsupported", None, None), ("masked", None, None)]
assert result["maybe_changed"] is False
unsupported = {(u["metric"], u["input"]): u["reason"] for u in result["unsupported"]}
assert "完整值" in unsupported[("n", "vars.kpi.items")]
assert "遮罩" in unsupported[("phone_len", "cell(nodes.crm, 0, 'phone')")]
assert "取哪" in unsupported[("pick", "vars.kpi.i")]
# 整个指标推演不了的另有一条 input 为空的:界面据此只写原因
assert unsupported[("n", None)] == metrics["n"]["reason"]
assert unsupported[("phone_len", None)] == metrics["phone_len"]["reason"]
assert {m for m, i in unsupported if i is None} == {"n", "phone_len"}
# 还原得出的容器不算「完整值找不回来」,只是不能直接改、也没有行可勾
assert "完整值" not in unsupported[("n2", "vars.kpi.items")] and "完整值" not in unsupported[("n3", "nodes.fetch.items")]
# 遮罩列的值不给
[phone] = metrics["phone_len"]["inputs"]
assert phone["masked"] is True and phone["old"] is None and phone["new"] is None and phone["editable"] is False
# 代入式里代进去的就是那一格:同样不给
assert metrics["phone_len"]["substituted"] is None and "13800000000" not in str(metrics["phone_len"])
# 能改的只有数值标量;整个推演不了的指标里,本来能改的数也不让改
editable = {i["path"]: i["editable"] for i in metrics["wow"]["inputs"] + metrics["total"]["inputs"]}
assert editable == {"vars.kpi.gmv": True, "vars.kpi.prev": True, "vars.kpi.amounts": False}
assert [i["editable"] for i in metrics["n"]["inputs"]] == [False, False]
# --------------------------------------------------------------------------
# 改输入、排除行:和手算一致
# --------------------------------------------------------------------------
def test_changing_an_input_recomputes_only_the_metrics_that_use_it():
result = whatif(CARD, Changes(inputs={"vars.kpi.gmv": 50000}), sources())
metrics = by_id(result)
wow = metrics["wow"]
assert wow["status"] == "ok" and wow["new"] == round((50000 - 42010.0) / 42010.0 * 100, 1) == 19.0
assert wow["old"] == 8.7 and wow["changed"] is True and wow["delta"] == 10.3
assert (wow["rendered_old"], wow["rendered_new"], wow["rendered_delta"]) == ("8.7%", "19.0%", "+10.3 个百分点")
assert wow["substituted"] == "round((50000 - 42010.0) / 42010.0 * 100, 1)"
gmv = next(i for i in wow["inputs"] if i["path"] == "vars.kpi.gmv")
assert (gmv["old"], gmv["new"], gmv["changed"]) == (45678.5, 50000, True)
# 别的指标没碰到:原样交回(整个推演不了的照旧说推演不了)
assert {k: m["status"] for k, m in metrics.items() if k != "wow" and m["status"] != "unchanged"} == {
"n": "unsupported", "phone_len": "masked"}
def test_excluding_rows_drops_them_from_an_agent_array_field():
# vars.kpi.k 是 fetch 节点在快照交回之前写的:排除行影响不到它(不知道先后时说不准,见下面几条)
result = whatif(CARD, Changes(exclude={S1: frozenset({1})}), sources(returned={S1: 10}, finished={"fetch": 5}))
metrics = by_id(result)
total = metrics["total"]
assert total["new"] == 340.0 - 80.0 and total["rendered_new"] == "260.0元" and total["delta"] == -80.0
assert total["rendered_delta"] == "-80.0元"
[amounts] = total["inputs"]
assert amounts["excluded_rows"] == [1] and (amounts["old"], amounts["new"]) == ("[4 项]", "[3 项]")
assert metrics["share"]["new"] == round(120.5 / 260.0 * 100, 1) == 46.3
# 第 0 行没排除:cell 取的那一格不受影响
assert metrics["east"]["status"] == "unchanged"
# 整份结果赋给变量的,同一行也去掉
assert metrics["rows"]["new"] == 3 * 2
assert next(i for i in metrics["rows"]["inputs"] if i["path"] == "vars.res.rows")["excluded_rows"] == [1]
def test_excluding_the_row_of_a_cell_makes_the_metric_uncomputable():
result = whatif(CARD, Changes(exclude={S1: frozenset({0, 3})}), sources())
metrics = by_id(result)
east = metrics["east"]
assert east["status"] == "excluded" and east["new"] is None and east["rendered_new"] == "—"
assert "排除后无法计算" in east["reason"] and "第 1 行" in east["reason"]
[inp] = east["inputs"]
assert inp["new"] is None and inp["excluded_rows"] == [0]
assert metrics["share"]["status"] == "excluded"
assert metrics["total"]["new"] == 80.0 + 99.5
def test_an_explicit_value_wins_over_an_excluded_row():
path = "cell(nodes.pull, 0, 'amount')"
result = whatif(CARD, Changes(inputs={path: 100}, exclude={S1: frozenset({0})}), sources())
east = by_id(result)["east"]
assert east["status"] == "ok" and east["new"] == 100 and east["rendered_new"] == "100.0元"
def test_a_ratio_moves_in_percentage_points():
ratio = by_id(whatif(CARD, Changes(inputs={"vars.kpi.refunds": 37}), sources()))["ratio"]
assert ratio["new"] == round(37 / 1234, 4) == 0.03
assert (ratio["rendered_old"], ratio["rendered_new"], ratio["rendered_delta"]) == ("2.35%", "3.00%", "+0.65 个百分点")
def test_division_by_zero_is_explained():
wow = by_id(whatif(CARD, Changes(inputs={"vars.kpi.prev": 0}), sources()))["wow"]
assert wow["status"] == "error" and wow["new"] is None and wow["reason"] == "除以零"
def test_an_overflow_is_an_error_not_a_crash():
"""算出无穷大:说清算不出来;老卡上记着无穷大的也不往外送(JSON 放不下,接口会 500)。"""
result = whatif(CARD, Changes(inputs={"vars.kpi.refunds": 1e308, "vars.kpi.orders": 1e-10}), sources(),
metric="ratio")
[ratio] = result["metrics"]
assert ratio["status"] == "error" and ratio["new"] is None and "有限" in ratio["reason"]
card = {**CARD, "metrics": [metric("big", "vars.kpi.x * 2", "inf * 2", math.inf,
[scalar("vars.kpi.x", math.inf)], rendered="—")]}
big = whatif(card, Changes(), sources())["metrics"][0]
assert big["old"] is None and big["inputs"][0]["old"] is None and big["rendered_old"] == "—"
json.dumps([result, big], allow_nan=False)
def test_a_missing_input_can_be_supplied():
card = {**CARD, "metrics": [metric("cost", "vars.kpi.cost / vars.kpi.orders", "vars.kpi.cost / 1234", None,
[scalar("vars.kpi.cost", None), scalar("vars.kpi.orders", 1234)], decimals=2,
rendered="—")]}
cost = whatif(card, Changes(inputs={"vars.kpi.cost": 2468}), sources())["metrics"][0]
assert cost["old"] is None and cost["new"] == 2.0 and cost["rendered_old"] == "—" and cost["rendered_new"] == "2.00"
# --------------------------------------------------------------------------
# 容器输入的还原
# --------------------------------------------------------------------------
def test_new_runs_restore_vars_containers_from_the_value_artifact():
metrics = by_id(whatif(CARD, Changes(inputs={"vars.kpi.k": 5}), sources()))
assert metrics["n2"]["status"] == "ok" and metrics["n2"]["new"] == 15
assert metrics["n3"]["status"] == "ok" and metrics["n3"]["new"] == 3 + 5
assert metrics["rows"]["new"] == 4 * 5
# 老运行的那个照实说做不到
assert metrics["n"]["status"] == "unsupported" and "完整值" in metrics["n"]["reason"]
def test_a_tampered_or_missing_full_value_is_not_used():
metrics = by_id(whatif(CARD, Changes(inputs={"vars.kpi.k": 5}), sources(
load=lambda a: (_ for _ in ()).throw(ValueError("篡改")) if a == ITEMS_VALUE else load(a))))
assert metrics["n2"]["status"] == "unsupported" and "哈希" in metrics["n2"]["reason"]
metrics = by_id(whatif(CARD, Changes(inputs={"vars.kpi.k": 5}), sources(outputs={})))
assert metrics["n3"]["status"] == "unsupported" and "nodes.fetch.items" in metrics["n3"]["reason"]
def test_an_agent_array_is_restored_from_the_node_output_and_the_snapshot_rows():
"""老运行没有 value_artifact:agent 的数组字段按封存的节点产出还原,行号按 locator.rows 对到快照。"""
out = one("total", Changes(exclude={S1: frozenset({2, 3})}))
assert out["new"] == 120.5 + 80.0 and out["inputs"][0]["excluded_rows"] == [2, 3]
# --------------------------------------------------------------------------
# 遮罩
# --------------------------------------------------------------------------
def test_masked_inputs_cannot_drive_a_whatif():
with pytest.raises(WhatIfError, match="遮罩"):
whatif(CARD, Changes(inputs={"cell(nodes.crm, 0, 'phone')": 1}), sources())
phone = by_id(whatif(CARD, Changes(exclude={S2: frozenset({0})}), sources()))["phone_len"]
assert phone["status"] == "masked" and phone["new"] is None and phone["rendered_new"] is None
assert "遮罩" in phone["reason"]
assert all(i["old"] is None and i["new"] is None for i in phone["inputs"])
def test_a_query_result_with_a_masked_column_is_masked_as_a_whole():
card = {**CARD, "metrics": [metric("cnt", "len(vars.res.rows) * vars.kpi.k", "len(vars.res.rows) * 2", 8,
[{**scalar("vars.res.rows", "[4 项]"), "value_artifact": RES_ROWS},
scalar("vars.kpi.k", 2)])]}
masked = sources(masked={S1: frozenset({"phone"})})
baseline = whatif(card, Changes(), masked)
# 整个指标一条,再列出卡住它的那个输入;本来能改的 vars.kpi.k 不再单列
assert [(u["input"], "遮罩" in u["reason"]) for u in baseline["unsupported"]] == [
(None, True), ("vars.res.rows", True)]
assert baseline["metrics"][0]["status"] == "masked"
cnt = whatif(card, Changes(inputs={"vars.kpi.k": 3}), masked)["metrics"][0]
assert cnt["status"] == "masked" and cnt["new"] is None
# --------------------------------------------------------------------------
# 不合法的请求
# --------------------------------------------------------------------------
@pytest.mark.parametrize("changes, words", [
(Changes(inputs={"vars.kpi.nope": 1}), ["vars.kpi.nope"]),
(Changes(inputs={"vars.kpi.gmv": "很多"}), ["vars.kpi.gmv", "数值"]),
(Changes(inputs={"vars.kpi.gmv": True}), ["数值"]),
(Changes(inputs={"vars.kpi.gmv": math.nan}), ["数值"]),
(Changes(inputs={"vars.kpi.gmv": math.inf}), ["数值"]),
(Changes(inputs={"vars.kpi.amounts": 3}), ["列表", "排除"]),
(Changes(inputs={"vars.kpi.i": 0}), ["取哪"]),
(Changes(exclude={"f" * 64: frozenset({0})}), ["不属于这次运行", "封存范围"]),
(Changes(exclude={S1: frozenset({4})}), ["行号 4", "4 行"]),
(Changes(exclude={S1: frozenset({-1})}), ["行号"]),
(Changes(exclude={BAD: frozenset({0})}), ["哈希"]),
])
def test_invalid_requests_say_what_is_wrong(changes, words):
with pytest.raises(WhatIfError) as caught:
whatif(CARD, changes, sources())
assert all(w in str(caught.value) for w in words), str(caught.value)
def test_text_inputs_cannot_be_changed():
card = {**CARD, "metrics": [metric("len", "len(vars.kpi.name) + vars.kpi.k", "len('华东区') + 2", 5,
[scalar("vars.kpi.name", "华东区"), scalar("vars.kpi.k", 2)])]}
with pytest.raises(WhatIfError, match="不是数值"):
whatif(card, Changes(inputs={"vars.kpi.name": 3}), sources())
[name, k] = whatif(card, Changes(), sources())["metrics"][0]["inputs"]
assert name["editable"] is False and name["kind"] == "text" and k["editable"] is True
def test_a_single_metric_is_checked_against_its_own_inputs():
with pytest.raises(WhatIfError, match="vars.kpi.amounts"):
whatif(CARD, Changes(inputs={"vars.kpi.amounts": 1}), sources(), metric="wow")
result = whatif(CARD, Changes(inputs={"vars.kpi.gmv": 50000}), sources(), metric="wow")
assert [m["id"] for m in result["metrics"]] == ["wow"]
def test_a_card_from_before_lineage_cannot_be_recomputed():
legacy = {"id": "old", "name": "旧指标", "unit": "", "value": 3, "expression": "vars.x + 1"}
out = recompute(legacy, Changes(), sources())
assert out["status"] == "unsupported" and "没有记录输入" in out["reason"]
# --------------------------------------------------------------------------
# 报告里引用的地方、下游口径卡
# --------------------------------------------------------------------------
def doc_with(*segments):
catalog = {
"m:wow": {"alias": "m:wow", "kind": "metric", "node_id": "card", "artifact": "CARD", "locator": {"metric": "wow"}},
"m:total": {"alias": "m:total", "kind": "metric", "node_id": "card", "artifact": "CARD",
"locator": {"metric": "total"}},
"m:other": {"alias": "m:other", "kind": "metric", "node_id": "card", "artifact": "OLDER",
"locator": {"metric": "wow"}},
}
return {"catalog": catalog, "blocks": [{"id": "b1", "type": "paragraph", "units": [
{"id": "u1", "kind": "claim", "segments": list(segments)}]}]}
def seg(sid, text, alias, conv=None):
cite = {"alias": alias, "kind": "metric", "status": "resolved", **({"conv": conv} if conv else {})}
return {"id": sid, "text": text, "kind": "value", "state": "deterministic", "cite": cite}
def test_report_segments_render_the_new_value_the_way_the_report_does():
result = whatif(CARD, Changes(inputs={"vars.kpi.gmv": 50000}), sources())
doc = doc_with(seg("s1", "8.7%", "m:wow"), seg("s2", "340.0元", "m:total"),
seg("s3", "8.7%", "m:other"), {"id": "s4", "text": "本周", "kind": "text", "state": "neutral"})
found = report_segments([("write", doc)], card_node="card", card_artifact="CARD", results=result["metrics"])
assert found == [
{"report": "write", "unit": "u1", "sid": "s1", "metric": "wow", "rendered_old": "8.7%", "rendered_new": "19.0%",
"changed": True},
{"report": "write", "unit": "u1", "sid": "s2", "metric": "total", "rendered_old": "340.0元",
"rendered_new": "340.0元", "changed": False},
]
# 报告里写了换算的,按同样的换算渲染
total = whatif(CARD, Changes(exclude={S1: frozenset({0})}), sources())
[one_seg] = report_segments([("write", doc_with(seg("s9", "0.03万元", "m:total", conv="万")))], card_node="card",
card_artifact="CARD", results=total["metrics"])
assert (one_seg["rendered_old"], one_seg["rendered_new"]) == ("0.03万元", "0.02万元")
def test_downstream_cards_that_use_this_card_are_flagged_not_recomputed():
upstream = ("card", "A1", CARD)
yearly = ("yearly", "B1", {"caliber": "年报口径", "caliber_version": "v1", "metrics": [
metric("y", "vars.m.metrics[0].value * 52", "8.7 * 52", 452.4,
[{"path": "vars.m.metrics[0].value", "value": 8.7, "node_id": "card", "via": "metric", "status": "ok"}]),
metric("z", "vars.kpi.k", "2", 2, [scalar("vars.kpi.k", 2)])]})
board = ("board", "C1", {"caliber": "看板口径", "caliber_version": "v2", "metrics": [
metric("b", "nodes.yearly.metrics[0].value + 1", "452.4 + 1", 453.4,
[{"path": "nodes.yearly.metrics[0].value", "value": 452.4, "node_id": "yearly", "via": "metric",
"status": "ok"}])]})
unrelated = ("misc", "D1", {"caliber": "其他", "caliber_version": "v1", "metrics": [
metric("q", "vars.kpi.k", "2", 2, [scalar("vars.kpi.k", 2)])]})
assert downstream_cards([upstream, yearly, board, unrelated], "card") == [
{"node_id": "yearly", "artifact": "B1", "caliber": "年报口径", "version": "v1", "metrics": ["y"], "direct": True},
{"node_id": "board", "artifact": "C1", "caliber": "看板口径", "version": "v2", "metrics": ["b"], "direct": False},
]
# --------------------------------------------------------------------------
# 排除行:说不准受不受影响的指标不能报「无变化」
# --------------------------------------------------------------------------
def lone(mid, expression, substituted, value, inputs, **kw):
"""只有一个指标的卡(同一套快照、产出)。"""
return {**CARD, "metrics": [metric(mid, expression, substituted, value, inputs, **kw)]}
#: 老运行:cell() 一格加一个没存完整值的 vars 容器(写它的是 parse 节点)
OLD_MIX = lone("mix", "round(cell(nodes.pull, 0, 'amount') / len(vars.res.rows), 2)",
"round(120.5 / len(vars.res.rows), 2)", 30.13,
[cell("pull", 0, "amount", 120.5), scalar("vars.res.rows", "[4 项]", node="parse")], decimals=2)
def test_excluding_rows_never_reports_an_unrestorable_metric_as_unchanged():
"""排除的是 cell 那一格以外的行:容器的完整值找不回来,它会不会少几行说不准,指标不能报「无变化」。"""
[mix] = whatif(OLD_MIX, Changes(exclude={S1: frozenset({2})}), sources())["metrics"]
assert mix["status"] == "unsupported" and mix["changed"] is None and mix["rendered_new"] is None
assert mix["new"] is None and "vars.res.rows" in mix["reason"] and "完整值" in mix["reason"]
# 不改动也一样:完整值找不回来,这个指标本来就推演不了,不报「无变化」
[mix] = whatif(OLD_MIX, Changes(), sources())["metrics"]
assert mix["status"] == "unsupported" and mix["changed"] is None and "完整值" in mix["reason"]
#: cell() 一格加一个还原得出、却对不上任何快照的容器(加工过的结果,写它的是 fetch 节点)
MIXED = lone("mixed", "cell(nodes.pull, 0, 'amount') + len(vars.kpi.items)", "120.5 + len(vars.kpi.items)", 123.5,
[cell("pull", 0, "amount", 120.5), {**scalar("vars.kpi.items", "[3 项]"), "value_artifact": ITEMS_VALUE}],
decimals=1)
#: 按位置取自整份结果的一格,除以整份结果的行数(都是 parse 节点写的)
FIRST_SHARE = lone("first_share", "round(vars.res.rows[0][1] / len(vars.res.rows), 2)",
"round(120.5 / len(vars.res.rows), 2)", 30.12,
[scalar("vars.res.rows[0][1]", 120.5, node="parse"),
{**scalar("vars.res.rows", "[4 项]", node="parse"), "value_artifact": RES_ROWS}], decimals=2)
def test_a_container_matching_no_snapshot_is_doubted_when_rows_are_excluded():
"""能还原、却对不上任何快照的容器(加工过的结果):排除行后它会不会变说不准。"""
[mixed] = whatif(MIXED, Changes(exclude={S1: frozenset({3})}), sources())["metrics"]
assert mixed["status"] == "unsupported" and mixed["changed"] is None
assert "排除行对 vars.kpi.items 的影响无法确定" in mixed["reason"] and "对不上任何查询快照" in mixed["reason"]
def test_a_scalar_taken_by_position_from_the_excluded_table_is_doubted():
"""vars.res.rows[0][1] 按位置取自整份结果:排除第 0 行后,len 变了,分子却还是原来第 0 行的值——不能算出一个
不对应任何一份数据的数。"""
assert recompute(FIRST_SHARE["metrics"][0], Changes(), sources())["new"] == round(120.5 / 4, 2) == 30.12
[share] = whatif(FIRST_SHARE, Changes(exclude={S1: frozenset({0})}), sources())["metrics"]
assert share["status"] == "unsupported" and share["new"] is None and share["changed"] is None
assert "vars.res.rows[0][1]" in share["reason"]
def test_an_explicit_value_settles_an_input_that_would_be_doubted():
"""按位置取的那一格给了新值:它的值以新值为准,排除行影响不到它,指标照常按剩下的行重算。"""
changes = Changes(inputs={"vars.res.rows[0][1]": 100}, exclude={S1: frozenset({0})})
[share] = whatif(FIRST_SHARE, changes, sources())["metrics"]
assert share["status"] == "ok" and share["new"] == round(100 / 3, 2) == 33.33
@pytest.mark.parametrize("finished, doubted", [(5, False), (10, True), (12, True)])
def test_only_inputs_written_after_the_snapshot_came_back_are_doubted(finished, doubted):
"""写这个输入的节点在快照交回之前就跑完了:排除这份快照里的行影响不到它。跑完的那条事件就是交回快照的那一条
(合并查询的快照记在它自己跑完的事件里),或者更晚:说不准。"""
timed = sources(returned={S1: 10}, finished={"fetch": finished})
[mixed] = whatif(MIXED, Changes(exclude={S1: frozenset({2})}), timed)["metrics"]
assert (mixed["status"], mixed["changed"]) == (("unsupported", None) if doubted else ("unchanged", False))
#: cell() 的行号由整份结果算出:取最后一行
LAST_CELL = "cell(nodes.pull, len(vars.res.rows) - 1, 'amount')"
LAST = lone("last", LAST_CELL, "40.0", 40.0, [
{**cell("pull", 3, "amount", 40.0), "path": LAST_CELL},
{**scalar("vars.res.rows", "[4 项]", node="parse"), "value_artifact": RES_ROWS}], decimals=1)
def test_a_container_that_picks_the_cell_is_doubted_when_its_rows_are_excluded():
"""排除了别的行,行号跟着变,取到的是哪一格说不准,不能报「无变化」。整份结果因此不给行段:勾了也推演不出来,
「不支持推演的输入」里又说它不能用。那一格自己那一行照给:勾掉它,确定是排除后无法计算。"""
assert recompute(LAST["metrics"][0], Changes(), sources())["new"] == 40.0
baseline = whatif(LAST, Changes(), sources())
assert [(i["path"], i.get("row_span")) for i in baseline["metrics"][0]["inputs"]] == [
(LAST_CELL, [3, 3]), ("vars.res.rows", None)]
assert [u["input"] for u in baseline["unsupported"]] == ["vars.res.rows"]
assert "取哪" in baseline["unsupported"][0]["reason"]
for row in (0, 1, 2):
[last] = whatif(LAST, Changes(exclude={S1: frozenset({row})}), sources())["metrics"]
assert last["status"] == "unsupported" and last["changed"] is None and "vars.res.rows" in last["reason"]
[last] = whatif(LAST, Changes(exclude={S1: frozenset({3})}), sources())["metrics"]
assert last["status"] == "excluded" and "第 4 行" in last["reason"]
@pytest.mark.parametrize("rows", [{1}, {3}, {0, 1, 2, 3}])
def test_an_explicit_value_on_the_picked_cell_settles_the_container_that_picks_it(rows):
"""那一格给了新值:取到的是哪一格已无关紧要,以新值为准。排除整份结果里的行(哪怕连它自己那一行)照常算。"""
[last] = whatif(LAST, Changes(inputs={LAST_CELL: 100}, exclude={S1: frozenset(rows)}), sources())["metrics"]
assert (last["status"], last["new"], last["changed"]) == ("ok", 100, True), last
def test_a_container_that_is_also_counted_keeps_only_the_count_once_the_cell_has_a_new_value():
"""整份结果既拿来数行数、又决定取哪一格:那一格给了新值,它只剩数行数的那一处,排除了哪几行是确定的,照常算。"""
card = lone("both", f"len(vars.res.rows) + {LAST_CELL}", "len(vars.res.rows) + 40.0", 44.0, [
{**scalar("vars.res.rows", "[4 项]", node="parse"), "value_artifact": RES_ROWS},
{**cell("pull", 3, "amount", 40.0), "path": LAST_CELL}], decimals=1)
assert recompute(card["metrics"][0], Changes(), sources())["new"] == 44.0
[both] = whatif(card, Changes(exclude={S1: frozenset({1})}), sources())["metrics"]
assert both["status"] == "unsupported" and "vars.res.rows" in both["reason"]
[both] = whatif(card, Changes(inputs={LAST_CELL: 100}, exclude={S1: frozenset({1})}), sources())["metrics"]
assert (both["status"], both["new"]) == ("ok", 3 + 100), both
#: 按第 2 行的区域取费率:费率写在查询之前(fetch),区域那一格决定取哪一项
FEE = "vars.kpi.rates[cell(nodes.pull, 1, 'region')]"
REGION = "cell(nodes.pull, 1, 'region')"
@pytest.mark.parametrize("expression, substituted, value, after", [
# 区域那一格只用来取费率:费率给了新值,它就无关紧要
(f"{FEE} * 100", "0.05 * 100", 5.0, ("ok", 8.0)),
# 区域那一格另外还拿来数字数:那一处照常拿它的值,它那一行排除了照样算不出来
(f"len({REGION}) + {FEE} * 100", "len('华南') + 0.05 * 100", 7.0, ("excluded", None)),
])
def test_a_cell_that_picks_the_item_is_moot_once_the_item_has_a_new_value(expression, substituted, value, after):
"""区域那一格所在的行排除了:取哪一项不知道,排除后无法计算。费率给了新值:取哪一项已无关紧要,照常算——
那一格另外还直接参与计算的除外。"""
card = lone("fee", expression, substituted, value, [scalar(FEE, 0.05), cell("pull", 1, "region", "华南")],
decimals=1)
timed = sources(returned={S1: 10}, finished={"fetch": 5})
assert recompute(card["metrics"][0], Changes(), timed)["new"] == value
[fee] = whatif(card, Changes(exclude={S1: frozenset({1})}), timed)["metrics"]
assert fee["status"] == "excluded" and "第 2 行" in fee["reason"]
[fee] = whatif(card, Changes(inputs={FEE: 0.08}, exclude={S1: frozenset({1})}), timed)["metrics"]
assert (fee["status"], fee["new"]) == after, fee
@pytest.mark.parametrize("path, middle", [
("vars.kpi.rates[vars.kpi.region]", []),
# 嵌了两层:区域名先换成区域代码再取费率,包着它的最外层引用照样是费率
("vars.kpi.rates[vars.kpi.codes[vars.kpi.region]]", [scalar("vars.kpi.codes[vars.kpi.region]", "S")]),
])
def test_an_index_that_would_be_doubted_is_moot_once_the_item_has_a_new_value(path, middle):
"""取哪一项由区域名决定,区域名是查询交回之后才算出来的(对不上快照):排除行后取到的是哪一项说不准。费率给了
新值:区域名受不受影响已无关紧要,按剩下的行照常算。"""
card = lone("fee2", f"round({path} * sum(vars.kpi.amounts), 1)", "round(0.05 * sum(vars.kpi.amounts), 1)", 17.0,
[scalar(path, 0.05), *middle, scalar("vars.kpi.region", "华南", node="label"), AMOUNTS], decimals=1)
timed = sources(returned={S1: 10}, finished={"fetch": 5, "label": 12})
assert recompute(card["metrics"][0], Changes(), timed)["new"] == 17.0
[fee] = whatif(card, Changes(exclude={S1: frozenset({1})}), timed)["metrics"]
assert fee["status"] == "unsupported" and "排除行对 vars.kpi.region 的影响无法确定" in fee["reason"]
[fee] = whatif(card, Changes(inputs={path: 0.1}, exclude={S1: frozenset({1})}), timed)["metrics"]
assert (fee["status"], fee["new"]) == ("ok", round(0.1 * (340.0 - 80.0), 1)) == ("ok", 26.0), fee
def test_an_index_shared_by_two_items_is_moot_only_when_both_have_new_values():
"""费率和固定费都按区域名取:只给费率新值,固定费取到哪一项照样说不准;两样都给了才无关紧要。"""
rate, fixed = "vars.kpi.rates[vars.kpi.region]", "vars.kpi.fixed[vars.kpi.region]"
card = lone("fee4", f"round({rate} * sum(vars.kpi.amounts) + {fixed}, 1)",
"round(0.05 * sum(vars.kpi.amounts) + 3, 1)", 20.0,
[scalar(rate, 0.05), scalar("vars.kpi.region", "华南", node="label"), AMOUNTS, scalar(fixed, 3)],
decimals=1)
timed = sources(returned={S1: 10}, finished={"fetch": 5, "label": 12})
assert recompute(card["metrics"][0], Changes(), timed)["new"] == 20.0
[fee] = whatif(card, Changes(inputs={rate: 0.1}, exclude={S1: frozenset({1})}), timed)["metrics"]
assert fee["status"] == "unsupported" and "vars.kpi.region" in fee["reason"]
[fee] = whatif(card, Changes(inputs={rate: 0.1, fixed: 5}, exclude={S1: frozenset({1})}), timed)["metrics"]
assert (fee["status"], fee["new"]) == ("ok", 31.0), fee
def test_a_change_that_leaves_the_value_as_it_was_moves_nothing_downstream():
"""改动碰到了指标,算出来却没变:4 行里排除 1 行,min(行数, 3) 还是 3;填回原值也一样。照实说无变化,下游也不会
受影响(maybe_changed 为假)。排除到只剩 2 行才变。"""
card = lone("cap", "min(len(vars.res.rows), 3)", "min(len(vars.res.rows), 3)", 3,
[{**scalar("vars.res.rows", "[4 项]", node="parse"), "value_artifact": RES_ROWS}])
result = whatif(card, Changes(exclude={S1: frozenset({3})}), sources())
[cap] = result["metrics"]
assert (cap["status"], cap["new"], cap["changed"], cap["inputs"][0]["excluded_rows"]) == ("ok", 3, False, [3])
assert result["maybe_changed"] is False
same = whatif(CARD, Changes(inputs={"vars.kpi.gmv": 45678.5}), sources(), metric="wow")
assert (same["metrics"][0]["status"], same["metrics"][0]["changed"], same["maybe_changed"]) == ("ok", False, False)
moved = whatif(card, Changes(exclude={S1: frozenset({0, 3})}), sources())
assert moved["metrics"][0]["new"] == 2 and moved["maybe_changed"] is True
def test_a_metric_without_lineage_is_unsupported_whatever_changes():
legacy = {"id": "old", "name": "旧指标", "unit": "", "value": 3, "expression": "vars.x + 1"}
card = {**CARD, "metrics": [legacy, CARD["metrics"][0]]}
for changes in (Changes(), Changes(inputs={"vars.kpi.gmv": 50000}), Changes(exclude={S1: frozenset({1})})):
old = by_id(whatif(card, changes, sources()))["old"]
assert old["status"] == "unsupported" and old["changed"] is None and "没有记录输入" in old["reason"]
#: 按遮罩列那一格的长度取第几项
PHONE_PICK = "vars.kpi.list[len(cell(nodes.crm, 0, 'phone')) - 10]"
#: 整个指标推演不了的几种:(卡, Sources 的改动, 改点什么, 状态, 原因里该有的字)。每种都另有一个本来能改的输入
BLOCKED = {
# 老运行:容器型 vars 输入没存完整值
"old_container": (lone("n", "len(vars.kpi.items) * vars.kpi.k", "len(vars.kpi.items) * 2", 6,
[scalar("vars.kpi.items", "[3 项]"), scalar("vars.kpi.k", 2)]),
{}, Changes(inputs={"vars.kpi.k": 5}), "unsupported", ["vars.kpi.items", "完整值"]),
# 用到了遮罩列:那一格不给、代入式不给
"masked": (lone("mix", "len(cell(nodes.crm, 0, 'phone')) + vars.kpi.k", "len('13800000000') + 2", 13,
[cell("crm", 0, "phone", "13800000000", artifact=S2), scalar("vars.kpi.k", 2)]),
{}, Changes(inputs={"vars.kpi.k": 5}), "masked", ["遮罩"]),
# 遮罩列的那一格只嵌在下标里(决定取哪一项):改了别的输入,取到哪一项照样露出它的长度
"masked_index": (lone("pick_m", f"{PHONE_PICK} + vars.kpi.k", "20 + 2", 22,
[scalar(PHONE_PICK, 20), cell("crm", 0, "phone", "13800000000", artifact=S2),
scalar("vars.kpi.k", 2)]),
{}, Changes(inputs={"vars.kpi.k": 5}), "masked", ["遮罩"]),
# 那一格所在的查询快照读不出来:遮没遮核对不了
"unreadable": (lone("mix2", "cell(nodes.pull, 0, 'amount') + vars.kpi.k", "120.5 + 2", 122.5,
[cell("pull", 0, "amount", 120.5), scalar("vars.kpi.k", 2)], decimals=1),
{"load": lambda a: None if a == S1 else load(a)}, Changes(inputs={"vars.kpi.k": 5}), "unsupported",
["cell(nodes.pull, 0, 'amount')", "无法读取"]),
# agent 的数组字段:节点产出不在了,完整值找不回来
"lost_array": (lone("share", "round(cell(nodes.pull, 0, 'amount') / sum(vars.kpi.amounts) * 100, 1)",
"round(120.5 / sum(vars.kpi.amounts) * 100, 1)", 35.4,
[cell("pull", 0, "amount", 120.5), AMOUNTS], decimals=1, fmt="plain", unit="%"),
{"load": lambda a: None if a == BOT_OUT else load(a)}, Changes(exclude={S1: frozenset({1})}),
"unsupported", ["vars.kpi.amounts", "无法读取节点「bot」当时的产出"]),
# 升级前的卡:没记输入
"no_lineage": ({**CARD, "metrics": [{"id": "old", "name": "旧指标", "unit": "", "value": 3,
"expression": "vars.x + 1"}]},
{}, Changes(exclude={S1: frozenset({1})}), "unsupported", ["没有记录输入"]),
}
@pytest.mark.parametrize("name", list(BLOCKED))
def test_a_metric_that_cannot_be_recomputed_says_so_before_anything_changes(name):
"""遮罩列、还原不了的最外层输入、读不出来的快照、没记输入:不论改什么都推演不了。一打开就照实说,不报「无变化」;
输入一个都不让改、不让勾(改了、勾了也推演不出来);unsupported 里另有一条 input 为空的,界面据此只写原因。"""
card, kw, change, status, words = BLOCKED[name]
result = whatif(card, Changes(), sources(**kw))
[m] = result["metrics"]
assert m["status"] == status and all(w in m["reason"] for w in words), m
assert [m[k] for k in ("new", "rendered_new", "changed", "delta", "rendered_delta")] == [None] * 5
assert all(i["editable"] is False and "row_span" not in i for i in m["inputs"]), m["inputs"]
assert {"metric": m["id"], "input": None, "reason": m["reason"]} in result["unsupported"]
# 什么都没改:它不会变,下游也不会受影响
assert result["maybe_changed"] is False
# 改了它的输入、排除了它用到的行:照样推演不了,原因不变;它可能变了,下游可能受影响
after = whatif(card, change, sources(**kw))
assert [(x["status"], x["reason"], x["changed"]) for x in after["metrics"]] == [(status, m["reason"], None)]
assert after["maybe_changed"] is True
assert "13800000000" not in json.dumps([result, after], ensure_ascii=False)
@pytest.mark.parametrize("lost", ["missing", "tampered", "value_artifact"])
def test_excluding_rows_of_an_array_whose_full_value_is_lost_is_never_unchanged(lost):
"""agent 的数组字段完整值找不回来(节点产出不在、被改过,或者另存的完整值读不出来):排除它用到的行,它一定少了
一项,少的是多少不知道。指标不能报「无变化」,报告里引用它的地方也不能报「不受影响」;它也不给行段,不让人勾。"""
item = {**AMOUNTS, "value_artifact": "99" * 32} if lost == "value_artifact" else AMOUNTS
card = lone("total", "sum(vars.kpi.amounts)", "sum(vars.kpi.amounts)", 340.0, [item], decimals=1, unit="元")
broken = {"missing": lambda a: None if a == BOT_OUT else load(a),
"tampered": lambda a: (_ for _ in ()).throw(ValueError("篡改")) if a == BOT_OUT else load(a),
"value_artifact": load}[lost]
result = whatif(card, Changes(exclude={S1: frozenset({1})}), sources(load=broken))
[total] = result["metrics"]
assert total["status"] == "unsupported" and total["changed"] is None and total["new"] is None
assert total["rendered_new"] is None and "vars.kpi.amounts" in total["reason"]
[amounts] = total["inputs"]
assert "row_span" not in amounts and amounts["excluded_rows"] == [1] and amounts["editable"] is False
# 少了一项是确定的,少了之后什么样不知道
assert (amounts["old"], amounts["new"], amounts["changed"]) == ("[4 项]", None, True)
assert result["maybe_changed"] is True
[found] = report_segments([("write", doc_with(seg("s2", "340.0元", "m:total")))], card_node="card",
card_artifact="CARD", results=result["metrics"])
assert found["rendered_new"] is None and found["changed"] is None
def test_only_excluded_rows_inside_an_array_span_reach_it():
"""数组字段只用到快照的第 1–2 行(从 0 数):排除第 0 行影响不到它;同时排除第 0、2 行,起作用的只有第 2 行。"""
out = "c9" * 32
mid = {"path": "vars.kpi.mid", "value": "[2 项]", "node_id": "bot2", "via": "agent_field", "field": "mid",
"artifact": S1, "locator": {"rows": [1, 2], "column": "amount"}, "eid": "ev:rows:y", "status": "verified"}
card = lone("mid", "sum(vars.kpi.mid)", "sum(vars.kpi.mid)", 179.5, [mid], decimals=1, unit="元")
span = sources(load=lambda a: {"data": {"mid": [80.0, 99.5]}} if a == out else load(a),
outputs={"bot": BOT_OUT, "fetch": FETCH_OUT, "bot2": out})
assert whatif(card, Changes(), span)["metrics"][0]["inputs"][0]["row_span"] == [1, 2]
[m] = whatif(card, Changes(exclude={S1: frozenset({0})}), span)["metrics"]
assert m["status"] == "unchanged" and "excluded_rows" not in m["inputs"][0]
[m] = whatif(card, Changes(exclude={S1: frozenset({0, 2})}), span)["metrics"]
assert m["status"] == "ok" and m["new"] == 80.0 and m["inputs"][0]["excluded_rows"] == [2]
# --------------------------------------------------------------------------
# 查询快照读不出来:值不给、不推演
# --------------------------------------------------------------------------
@pytest.mark.parametrize("broken, words", [
(lambda a: None if a == S1 else load(a), "无法读取"),
(lambda a: (_ for _ in ()).throw(ValueError("篡改")) if a == S1 else load(a), "哈希"),
# 读得出来,却不是一份查询结果(没有 rows):同样核对不了
(lambda a: {"columns": ["region", "amount", "phone"], "source": "shop"} if a == S1 else load(a), "无法读取"),
])
def test_an_unreadable_snapshot_withholds_its_cells(broken, words):
"""快照读不出来,遮没遮核对不了:卡上记着的那一格也不给、不能改、没有行可勾,用到它的指标推演不了。"""
path = "cell(nodes.pull, 0, 'amount')"
result = whatif(CARD, Changes(), sources(load=broken), metric="east")
[east] = result["metrics"]
[inp] = east["inputs"]
assert inp["old"] is None and inp["new"] is None and inp["editable"] is False and inp["withheld"] is True
assert "row_span" not in inp and east["status"] == "unsupported" and words in east["reason"]
assert east["substituted"] is None and "120.5" not in str(east["inputs"]) + str(east["substituted"])
assert [(u["input"], words in u["reason"]) for u in result["unsupported"]] == [(None, True), (path, True)]
with pytest.raises(WhatIfError, match="快照"):
whatif(CARD, Changes(inputs={path: 100}), sources(load=broken), metric="east")
# 别的指标照样推演,只是用到这份快照的推演不了(数组字段的出处也在这份快照上)
metrics = by_id(whatif(CARD, Changes(inputs={"vars.kpi.gmv": 50000}), sources(load=broken)))
assert metrics["wow"]["status"] == "ok" and metrics["wow"]["new"] == 19.0
assert metrics["total"]["status"] == "unsupported" and "120.5" not in str(metrics["total"]["inputs"])
def test_a_masked_column_stays_masked_when_its_snapshot_is_unreadable():
phone = by_id(whatif(CARD, Changes(), sources(load=lambda a: None if a == S2 else load(a))))["phone_len"]
[inp] = phone["inputs"]
assert inp["masked"] is True and inp["old"] is None and phone["substituted"] is None
# 既遮着、快照又读不出来:说遮罩,快照修好了它照样遮着
assert phone["status"] == "masked" and "遮罩" in phone["reason"]
def test_a_withheld_cell_inside_another_reference_stays_out_of_the_substituted_expression():
"""取第几行由一格决定,这一格落在读不出来的快照上;取到的又是长文本(代入式不代长文本,就把行号代了进去)。
嵌在里面不碍事,指标照样推演得了,但代入式里有那一格的值,同样不给。"""
s3, note = "d3" * 32, "备注" * 50
store = {**STORE, s3: {"columns": ["note"], "source": "crm", "rows": [["短"], ["短"], [note]]}}
path = "cell(nodes.memo, vars.kpi.r, 'note')"
r = {**scalar("vars.kpi.r", 2), "via": "agent_field", "artifact": S1, "locator": {"row": 0, "column": "amount"}}
card = lone("memo_len", f"len({path})", "len(cell(nodes.memo, 2, 'note'))", 100,
[{**cell("memo", 2, "note", note, artifact=s3), "path": path}, r])
[m] = whatif(card, Changes(), sources(load=lambda a: None if a == S1 else store.get(a)))["metrics"]
assert m["status"] == "unchanged" and m["substituted"] is None
assert [i.get("withheld") for i in m["inputs"]] == [None, True]
# 那一格所在的快照读不出来:它那一行也不给勾(排除读不出来的快照里的行,接口回 422)
assert "row_span" not in m["inputs"][1]
# --------------------------------------------------------------------------
# 超大的数、给人看的值
# --------------------------------------------------------------------------
def test_numbers_too_large_to_compute_are_rejected_not_crashed():
with pytest.raises(WhatIfError, match="范围"):
whatif(CARD, Changes(inputs={"vars.kpi.gmv": 10 ** 400}), sources())
# 1e308 本身放得下,乘出来的整数放不下:说清算不出来
[n2] = whatif(CARD, Changes(inputs={"vars.kpi.k": 10 ** 308}), sources(), metric="n2")["metrics"]
assert n2["status"] == "error" and n2["new"] is None and "有限" in n2["reason"]
json.dumps(n2, allow_nan=False)
@pytest.mark.parametrize("value, shown", [(None, "空值"), ({"a": 1}, '{"a": 1}'), ([1, "两"], '[1, "两"]')])
def test_invalid_values_are_shown_the_way_a_person_writes_them(value, shown):
with pytest.raises(WhatIfError) as caught:
whatif(CARD, Changes(inputs={"vars.kpi.gmv": value}), sources())
assert shown in str(caught.value) and "None" not in str(caught.value) and "'a'" not in str(caught.value)
# --------------------------------------------------------------------------
# 推演里能动什么:可勾的行、不能动的原因
# --------------------------------------------------------------------------
def test_inputs_say_which_snapshot_rows_they_use():
"""输入实际落在快照的哪几行(row_span,含两端):单格一行、数组字段一段、整份结果全部。遮罩的不给。"""
result = whatif(CARD, Changes(), sources())
spans = {(m["id"], i["path"]): i.get("row_span") for m in result["metrics"] for i in m["inputs"]}
assert spans[("east", "cell(nodes.pull, 0, 'amount')")] == [0, 0]
assert spans[("total", "vars.kpi.amounts")] == [0, 3]
assert spans[("rows", "vars.res.rows")] == [0, 3]
assert spans[("phone_len", "cell(nodes.crm, 0, 'phone')")] is None
assert spans[("wow", "vars.kpi.gmv")] is None and spans[("n2", "vars.kpi.items")] is None
def test_inputs_that_cannot_be_adjusted_say_why():
"""不能改、也没有行可勾的输入都列进「不支持推演的输入」,不让人对着一个改不了的值干看。"""
card = {**CARD, "metrics": [
*CARD["metrics"],
metric("label", "len(vars.kpi.name) + vars.kpi.k", "len('华东区') + 2", 5,
[scalar("vars.kpi.name", "华东区"), scalar("vars.kpi.k", 2)]),
metric("flag", "vars.kpi.on * 3", "True * 3", 3, [scalar("vars.kpi.on", True)]),
# 老运行:容器没存完整值,整个推演不了
metric("label_n", "len(vars.kpi.name) + len(vars.kpi.items)", "len('华东区') + len(vars.kpi.items)", 6,
[scalar("vars.kpi.name", "华东区"), scalar("vars.kpi.items", "[3 项]")])]}
reasons = {(u["metric"], u["input"]): u["reason"] for u in whatif(card, Changes(), sources())["unsupported"]}
assert "列表或对象不能直接修改" in reasons[("n2", "vars.kpi.items")]
assert "列表或对象不能直接修改" in reasons[("n3", "nodes.fetch.items")]
assert "不是数值" in reasons[("label", "vars.kpi.name")] and "不是数值" in reasons[("flag", "vars.kpi.on")]
# 能排除行的容器、能改的数不在其中
assert ("total", "vars.kpi.amounts") not in reasons and ("rows", "vars.res.rows") not in reasons
assert ("label", "vars.kpi.k") not in reasons and ("wow", "vars.kpi.gmv") not in reasons
# 整个推演不了的指标:一条整个指标的,再加卡住它的那个输入;别的输入能不能改已无从谈起,不再单列
assert [i for m, i in reasons if m == "label_n"] == [None, "vars.kpi.items"]
def test_a_lost_array_inside_a_subscript_offers_no_rows():
"""cell() 的行号由 agent 的数组字段算出,这个数组另存的完整值又读不出来:嵌在里面不碍事(取到的那一格卡上记着),
指标照样推演得了,那一格能改、能勾它那一行;数组本身不给行段。排除了数组用到的行,取到哪一格说不准。"""
path = "cell(nodes.pull, len(vars.kpi.amounts) - 1, 'amount')"
lost = {**AMOUNTS, "value_artifact": "99" * 32}
card = lone("last2", path, "40.0", 40.0, [{**cell("pull", 3, "amount", 40.0), "path": path}, lost], decimals=1)
[m] = whatif(card, Changes(), sources())["metrics"]
assert m["status"] == "unchanged" and [i.get("row_span") for i in m["inputs"]] == [[3, 3], None]
assert [i["editable"] for i in m["inputs"]] == [True, False]
[m] = whatif(card, Changes(exclude={S1: frozenset({1})}), sources())["metrics"]
assert m["status"] == "unsupported" and m["changed"] is None and "vars.kpi.amounts" in m["reason"]
# --------------------------------------------------------------------------
# 还原时的几处保护
# --------------------------------------------------------------------------
def test_an_array_whose_length_does_not_match_its_rows_is_not_excluded_by_row():
"""数组字段 4 行的出处、产出里却只有 3 个元素:元素和行对不上号,不能按行去掉元素(会去错)。"""
short = sources(load=lambda a: {**STORE[BOT_OUT], "data": {"amounts": [120.5, 80.0, 99.5]}} if a == BOT_OUT
else load(a))
card = lone("total3", "sum(vars.kpi.amounts)", "sum(vars.kpi.amounts)", 300.0, [AMOUNTS], decimals=1, unit="元")
assert recompute(card["metrics"][0], Changes(), short)["new"] == 300.0
[total] = whatif(card, Changes(exclude={S1: frozenset({1})}), short)["metrics"]
assert total["status"] == "unsupported" and total["new"] is None
assert "excluded_rows" not in total["inputs"][0] and total["inputs"][0].get("row_span") is None
def test_a_node_path_with_a_variable_index_is_not_restored():
card = lone("pick2", "len(nodes.fetch.lists[vars.kpi.i])", "len(nodes.fetch.lists[vars.kpi.i])", 2,
[{**scalar("nodes.fetch.lists[vars.kpi.i]", "[2 项]"), "field": "lists[vars.kpi.i]"},
scalar("vars.kpi.i", 0)])
out = recompute(card["metrics"][0], Changes(), sources())
assert out["status"] == "unsupported" and "变量下标" in out["reason"]
def test_text_that_merely_looks_like_a_container_summary_is_a_plain_value():
"""值恰好是「[3 项]」这几个字的文本,代入式里被代成了字面量:它就是当时的值,不是容器。"""
card = lone("tag", "len(vars.kpi.tag)", "len('[3 项]')", 5, [scalar("vars.kpi.tag", "[3 项]")])
out = recompute(card["metrics"][0], Changes(), sources())
assert out["status"] == "ok" and out["new"] == 5 and out["inputs"][0]["kind"] == "text"
def test_a_query_result_carrying_its_snapshot_id_is_mapped_by_it():
"""容器带着封存范围内快照的 artifact(数据源工具交回的结果原样解析):按它认快照,哪怕行的写法和快照不同。"""
parsed = "b8" * 32
rows = [["华东", "120.5", "p1"], ["华南", "80.0", "p2"], ["华北", "99.5", "p3"], ["西南", "40.0", "p4"]]
store = {**STORE, parsed: {"path": "vars.res", "value": {"columns": ["region", "amount", "phone"], "rows": rows,
"artifact": S1}}}
card = lone("cnt", "len(get(vars.res, 'rows'))", "len(get(vars.res, 'rows'))", 4,
[{**scalar("vars.res", "{3 个字段}", node="parse"), "value_artifact": parsed}])
mapped = sources(load=lambda a: store.get(a) if a != BAD else load(a))
assert recompute(card["metrics"][0], Changes(), mapped)["new"] == 4
[cnt] = whatif(card, Changes(exclude={S1: frozenset({0, 2})}), mapped)["metrics"]
assert cnt["status"] == "ok" and cnt["new"] == 2
assert cnt["inputs"][0]["artifact"] == S1 and cnt["inputs"][0]["excluded_rows"] == [0, 2]
def test_a_segment_whose_metric_had_no_value_is_listed_when_the_whatif_supplies_one():
"""缺输入、当时显示「—」的引用也列上:推演里补上了值,它会变。"""
card = {**CARD, "metrics": [metric("cost", "vars.kpi.cost / vars.kpi.orders", "vars.kpi.cost / 1234", None,
[scalar("vars.kpi.cost", None), scalar("vars.kpi.orders", 1234)], decimals=2,
rendered="—")]}
result = whatif(card, Changes(inputs={"vars.kpi.cost": 2468}), sources())
doc = doc_with({"id": "s7", "text": "—", "kind": "value", "state": "flagged",
"cite": {"alias": "m:cost", "kind": "metric", "status": "unresolved"}})
doc["catalog"]["m:cost"] = {"alias": "m:cost", "kind": "metric", "node_id": "card", "artifact": "CARD",
"locator": {"metric": "cost"}, "value": None, "status": "missing_input"}
[found] = report_segments([("write", doc)], card_node="card", card_artifact="CARD", results=result["metrics"])
assert (found["sid"], found["rendered_old"], found["rendered_new"], found["changed"]) == ("s7", "—", "2.00", True)
# --------------------------------------------------------------------------
# 下游口径卡:经中间节点引用的也标
# --------------------------------------------------------------------------
def test_downstream_cards_reached_through_other_nodes_are_flagged():
"""card → mid(transform 用了卡上的值)→ yearly:yearly 的输入写的是 vars.t.g,来自 mid,不是卡本身。
按画布上的边从这张卡往下找:经别的节点间接用到的也标「可能受影响」。"""
upstream = ("card", "A1", CARD)
yearly = ("yearly", "B1", {"caliber": "年报口径", "caliber_version": "v1", "metrics": [
metric("y", "vars.t.g * 26", "17.4 * 26", 452.4,
[{"path": "vars.t.g", "value": 17.4, "node_id": "mid", "via": "transform", "status": "ok"}])]})
before = ("before", "C1", {"caliber": "早口径", "caliber_version": "v1", "metrics": [
metric("b", "vars.kpi.k", "2", 2, [scalar("vars.kpi.k", 2, node="fetch")])]})
edges = [("fetch", "before"), ("before", "card"), ("card", "mid"), ("mid", "yearly")]
assert downstream_cards([upstream, yearly, before], "card") == []
assert downstream_cards([upstream, yearly, before], "card", edges=edges) == [
{"node_id": "yearly", "artifact": "B1", "caliber": "年报口径", "version": "v1", "metrics": ["y"], "direct": False}]
+951
View File
@@ -0,0 +1,951 @@
"""数字推演接口:POST /api/runs/{run_id}/evidence/whatif。
真跑一遍图(虚构的 SQLite 库、MockChatModel 写报告),再在这次运行上推演:
- 什么都不改:每个指标原样交回,报告里引用它们的地方一处不变
- 改输入、排除查询快照里的行:新值和手算一致,报告里会变的那几处按报告的写法渲染
- 只读:不追加事件(last_seq 不变)、不落工件、封存核对照旧一致
- 只认这次运行封存范围内的工件;遮罩列不给值、不能拿来推演;输入不合法回 422 并说清哪里不对
- 输入的还原:nodes.* 从节点产出、agent 数组字段按 locator.rows、新运行的 vars.* 从 value_artifact;
老运行(没有 value_artifact)的 vars 容器照实说推演不了
"""
from __future__ import annotations
import asyncio
import json
import sqlite3
import pytest
from httpx import ASGITransport, AsyncClient
from langchain_core.messages import AIMessage, ToolMessage
from sqlalchemy import func, select
from app.core.config import settings
from app.data.engine import engines
from app.db.base import SessionLocal
from app.db.models import Artifact, DataSource, Run, RunEvent
from app.engine.runner import run_manager, verify_manifest
from app.main import app
SQL = "SELECT id, region, amount FROM orders ORDER BY id"
REGIONS = ["华东", "华南", "华北", "西南", "东北"]
ROWS = [(i, REGIONS[i % 5], float(i * 100) + 0.5) for i in range(1, 11)]
AMOUNT5 = "cell(nodes.fetch, 5, 'amount')"
METRICS = [
{"id": "amount5", "name": "第六单金额", "unit": "元", "decimals": 1, "format": "thousands", "expression": AMOUNT5},
{"id": "cnt", "name": "订单数", "unit": "单", "format": "thousands", "expression": "len(vars.res.rows)"},
{"id": "per", "name": "平均每单", "unit": "元", "decimals": 2, "format": "thousands",
"expression": f"round({AMOUNT5} / len(vars.res.rows), 2)"},
]
TEXT = "第六单金额 [[m:amount5]],共 [[m:cnt]],平均每单 [[m:per]]。"
@pytest.fixture(autouse=True)
async def engine_up():
await run_manager.setup()
yield
await run_manager.shutdown()
@pytest.fixture
async def client():
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c:
yield c
async def set_source(path, options=None):
async with SessionLocal() as session:
row = (await session.execute(select(DataSource).where(DataSource.name == "shop"))).scalar_one_or_none()
if row is None:
row = DataSource(name="shop", kind="sqlite", database=str(path), readonly=True, enabled=True)
session.add(row)
row.database, row.kind, row.enabled, row.readonly = str(path), "sqlite", True, True
row.options = dict(options or {})
await session.commit()
return row.id
@pytest.fixture(autouse=True)
async def shop(tmp_path):
path = tmp_path / "shop.db"
db = sqlite3.connect(path)
db.executescript("CREATE TABLE orders (id INTEGER PRIMARY KEY, region TEXT, amount REAL, week TEXT);")
db.executemany("INSERT INTO orders VALUES (?, ?, ?, ?)",
[(i, r, a, "2026-W37" if i > 3 else "2026-W36") for i, r, a in ROWS])
db.commit()
db.close()
source_id = await set_source(path)
await engines.invalidate(source_id)
yield path
await engines.invalidate(source_id)
def node(nid, ntype, **config):
return {"id": nid, "type": ntype, "position": {"x": 0, "y": 0}, "data": {"label": nid, "config": config}}
def chain(*nodes):
return {"nodes": list(nodes), "edges": [{"source": a["id"], "target": b["id"]} for a, b in zip(nodes, nodes[1:])]}
def query_graph(*, between=(), metrics=METRICS, sql=SQL):
return chain(
node("start", "input"),
node("fetch", "tool", tool="db_query__shop", args={"sql": sql}),
node("parse", "transform", mode="json", template="{{ nodes.fetch }}", assign_to="res"),
node("card", "metrics", caliber="推演口径", caliber_version="v3", metrics=metrics),
*between,
node("write", "report", instructions="写周报", on_violation="flag"),
node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}]),
)
def script(monkeypatch, text=TEXT):
from app.providers import mock_model
monkeypatch.setattr(mock_model.MockChatModel, "_decide", lambda self, messages: AIMessage(content=text))
async def wait(run_id: str, statuses=("succeeded", "failed")) -> Run:
for _ in range(400):
await asyncio.sleep(0.05)
async with SessionLocal() as session:
row = await session.get(Run, run_id)
if row.status in statuses and (row.status == "interrupted" or row.manifest_seq is not None):
return row
raise AssertionError(f"run {run_id} 没跑完:{row.status}")
async def run_graph(monkeypatch, graph, *, text=TEXT, statuses=("succeeded", "failed")) -> Run:
script(monkeypatch, text)
row = await wait((await run_manager.start(graph=graph, input_payload={})).id, statuses)
assert row.status in statuses and row.status != "failed", row.error
return row
async def snapshot_of(run_id: str, node_id: str = "fetch") -> str:
async with SessionLocal() as session:
[end] = (await session.execute(select(RunEvent).where(
RunEvent.run_id == run_id, RunEvent.type == "tool.end", RunEvent.node_id == node_id))).scalars()
return end.data["query_artifact"]
async def whatif(client, run_id: str, body: dict, status: int = 200) -> dict:
resp = await client.post(f"/api/runs/{run_id}/evidence/whatif", json=body)
assert resp.status_code == status, resp.text
return resp.json()
def by_id(body: dict) -> dict:
return {m["id"]: m for m in body["metrics"]}
async def footprint(run_id: str) -> tuple:
"""这次运行留在库里、盘上的痕迹:last_seq、事件数、工件引用行数、工件文件数。"""
async with SessionLocal() as session:
run = await session.get(Run, run_id)
events = await session.scalar(select(func.count()).select_from(RunEvent).where(RunEvent.run_id == run_id))
artifacts = await session.scalar(select(func.count()).select_from(Artifact))
files = sum(1 for _ in (settings.data_dir / "artifacts").rglob("*.json"))
return run.last_seq, run.manifest_hash, events, artifacts, files
# --------------------------------------------------------------------------
# 不改、改输入、排除行
# --------------------------------------------------------------------------
async def test_a_baseline_changes_nothing(client, monkeypatch):
row = await run_graph(monkeypatch, query_graph())
snapshot = await snapshot_of(row.id)
body = await whatif(client, row.id, {"card": "card"})
assert body["run_id"] == row.id and body["sealed"] is True and body["seal"] == {"sealed": True, "ok": True}
assert body["card"]["node_id"] == "card" and body["card"]["caliber"] == "推演口径" and body["card"]["version"] == "v3"
metrics = by_id(body)
assert {k: (m["old"], m["new"], m["status"], m["changed"]) for k, m in metrics.items()} == {
"amount5": (600.5, 600.5, "unchanged", False), "cnt": (10, 10, "unchanged", False),
"per": (60.05, 60.05, "unchanged", False)}
assert [m["rendered_old"] for m in body["metrics"]] == ["600.5元", "10单", "60.05元"]
[cell] = metrics["amount5"]["inputs"]
assert cell["path"] == AMOUNT5 and cell["editable"] is True and cell["artifact"] == snapshot
assert cell["locator"] == {"row": 5, "column": "amount"} and cell["old"] == 600.5
[rows] = metrics["cnt"]["inputs"]
assert rows["kind"] == "container" and rows["editable"] is False and rows["old"] == "[10 项]"
assert rows["artifact"] == snapshot, "整份查询结果赋给变量:按内容对上了那份快照"
assert body["unsupported"] == [] and body["affected_cards"] == []
# 报告里引用这三个指标的地方,都不变
assert [(s["report"], s["metric"], s["rendered_old"], s["rendered_new"], s["changed"]) for s in body["segments"]] == [
("write", "amount5", "600.5元", "600.5元", False), ("write", "cnt", "10单", "10单", False),
("write", "per", "60.05元", "60.05元", False)]
async def test_excluding_rows_recomputes_like_by_hand(client, monkeypatch):
row = await run_graph(monkeypatch, query_graph())
snapshot = await snapshot_of(row.id)
body = await whatif(client, row.id, {"card": "card", "overrides": {"exclude_rows": {snapshot: [2, 7]}}})
metrics = by_id(body)
assert metrics["amount5"]["status"] == "unchanged"
assert metrics["cnt"]["new"] == 8 and metrics["cnt"]["rendered_new"] == "8单" and metrics["cnt"]["delta"] == -2
assert metrics["per"]["new"] == round(600.5 / 8, 2) == 75.06 and metrics["per"]["rendered_delta"] == "+15.01元"
[rows] = metrics["cnt"]["inputs"]
assert rows["excluded_rows"] == [2, 7] and (rows["old"], rows["new"]) == ("[10 项]", "[8 项]")
changed = [(s["metric"], s["rendered_old"], s["rendered_new"]) for s in body["segments"] if s["changed"]]
assert changed == [("cnt", "10单", "8单"), ("per", "60.05元", "75.06元")]
# 排除了 cell() 那一格所在的行:这个指标排除后无法计算
body = await whatif(client, row.id, {"card": "card", "overrides": {"exclude_rows": {snapshot: [5]}}})
metrics = by_id(body)
assert metrics["amount5"]["status"] == "excluded" and metrics["amount5"]["new"] is None
assert "排除后无法计算" in metrics["amount5"]["reason"] and "第 6 行" in metrics["amount5"]["reason"]
assert metrics["amount5"]["rendered_new"] == "—" and metrics["per"]["status"] == "excluded"
assert metrics["cnt"]["new"] == 9
seg = next(s for s in body["segments"] if s["metric"] == "amount5")
assert seg["rendered_new"] == "—" and seg["changed"] is True
async def test_changing_an_input_of_one_metric(client, monkeypatch):
row = await run_graph(monkeypatch, query_graph())
body = await whatif(client, row.id, {"card": "card", "metric": "per", "report": "write",
"overrides": {"inputs": {AMOUNT5: 1000}}})
[per] = body["metrics"]
assert per["id"] == "per" and per["new"] == 100.0 and per["rendered_new"] == "100.00元"
assert per["substituted"] == "round(1000 / len(vars.res.rows), 2)"
# 只推演一个指标:报告里只列引用它的那一处
assert [(s["metric"], s["rendered_new"]) for s in body["segments"]] == [("per", "100.00元")]
async def faithful(run_id: str) -> list[tuple]:
"""真跑出来的每张卡、每个指标,什么都不改、强制重算一遍:(卡, 指标, 状态, 重算值, 卡上的值)。
输入的还原(标量、cell()、整份查询结果、agent 数组、nodes.*)是否忠实,在真卡上对一遍。和接口一样在工作线程里算。"""
from app.api import whatif as api_whatif
from app.api.evidence import _reports, _sealed, _sealed_cards
from app.engine import recompute
sealed = await _sealed(run_id)
cards = _sealed_cards(sealed)
out = []
for node_id in dict.fromkeys(nid for nid, _, _ in cards):
_, card, started = api_whatif._card_of(sealed, cards, node_id, _reports(sealed), None)
sources = api_whatif._sources(sealed, cards, started, asyncio.get_running_loop())
for metric in card["metrics"]:
again = await asyncio.to_thread(recompute.recompute, metric, recompute.Changes(), sources)
out.append((node_id, metric["id"], again["status"], again["new"], metric["value"]))
return out
async def test_recomputing_real_cards_without_changes_reproduces_them(monkeypatch):
row = await run_graph(monkeypatch, query_graph())
assert [(m, s, new == old) for _, m, s, new, old in await faithful(row.id)] == [
("amount5", "ok", True), ("cnt", "ok", True), ("per", "ok", True)]
async def test_events_appended_after_the_seal_are_ignored(client, monkeypatch):
"""封存之后插进来的 node.finished,哪怕指向一张真的指标集,也不能换掉推演用的那张卡。"""
from app.core.artifact_store import load, put_json
row = await run_graph(monkeypatch, query_graph())
card = (await whatif(client, row.id, {"card": "card"}))["card"]
forged = load(card["artifact"])
forged["metrics"][0]["value"] = 1.5
fake = await put_json(forged, kind="metric_set", run_id=row.id, node_id="card")
async with SessionLocal() as session:
session.add(RunEvent(run_id=row.id, seq=row.manifest_seq + 5, type="node.finished", node_id="card", ts=0.0,
data={"evidence": [{"kind": "metric_set", "node_id": "card", "artifact": fake}]}))
await session.commit()
body = await whatif(client, row.id, {"card": "card"})
assert body["card"]["artifact"] == card["artifact"] and by_id(body)["amount5"]["old"] == 600.5
assert body["sealed"] is True
async def test_whatif_is_read_only(client, monkeypatch):
row = await run_graph(monkeypatch, query_graph())
snapshot = await snapshot_of(row.id)
before = await footprint(row.id)
await whatif(client, row.id, {"card": "card"})
await whatif(client, row.id, {"card": "card", "overrides": {"inputs": {AMOUNT5: 1}, "exclude_rows": {snapshot: [0]}}})
await whatif(client, row.id, {"card": "card", "overrides": {"inputs": {"vars.nope": 1}}}, status=422)
assert await footprint(row.id) == before, "推演不能追加事件、不能落工件"
verdict = await verify_manifest(row.id)
assert verdict["ok"] is True
# --------------------------------------------------------------------------
# 不合法的请求
# --------------------------------------------------------------------------
@pytest.mark.parametrize("body", [
[], {"card": 3}, {"card": " "}, {"card": "card", "report": 1}, {"card": "card", "metric": ["per"]},
{"card": "card", "overrides": []}, {"card": "card", "overrides": {"inputs": []}},
{"card": "card", "overrides": {"exclude_rows": {"abc": 3}}},
{"card": "card", "overrides": {"exclude_rows": {"abc": ["3"]}}},
{"card": "card", "overrides": {"exclude_rows": {"abc": [True]}}},
])
async def test_malformed_requests_are_rejected(client, monkeypatch, body):
row = await run_graph(monkeypatch, query_graph())
resp = await client.post(f"/api/runs/{row.id}/evidence/whatif", json=body)
assert resp.status_code == 422 and resp.json()["code"] == "whatif_bad_request", resp.text
assert "请求格式有误" in resp.json()["detail"]
async def test_invalid_overrides_say_what_is_wrong(client, monkeypatch):
row = await run_graph(monkeypatch, query_graph())
snapshot = await snapshot_of(row.id)
# 别的运行的快照(内容不同,工件 id 也就不同):工件库里确有其物,只是不在这次运行的封存范围内
other = await run_graph(monkeypatch, query_graph(sql="SELECT id, region, amount FROM orders ORDER BY id DESC"))
foreign = await snapshot_of(other.id)
assert foreign != snapshot
card_artifact = (await whatif(client, row.id, {"card": "card"}))["card"]["artifact"]
cases = [
({"inputs": {"vars.nope": 1}}, ["vars.nope"]),
({"inputs": {AMOUNT5: "很多"}}, ["数值", "很多"]),
({"inputs": {AMOUNT5: True}}, ["数值"]),
({"inputs": {"vars.res.rows": 3}}, ["列表", "排除"]),
({"exclude_rows": {snapshot: [10]}}, ["行号 10", "10 行"]),
({"exclude_rows": {snapshot: [-1]}}, ["行号 -1"]),
({"exclude_rows": {foreign: [0]}}, ["不属于这次运行", "封存范围"]),
({"exclude_rows": {card_artifact: [0]}}, ["不属于这次运行"]),
]
for overrides, words in cases:
resp = await client.post(f"/api/runs/{row.id}/evidence/whatif", json={"card": "card", "overrides": overrides})
assert resp.status_code == 422, (overrides, resp.text)
body = resp.json()
assert body["code"] == "whatif_bad_input" and all(w in body["detail"] for w in words), (overrides, body)
async def test_only_artifacts_sealed_in_this_run_are_loaded(monkeypatch):
"""推演取工件只走封存范围内的白名单:别的运行的快照、只在工件表里的东西一律当取不到。"""
from app.api.evidence import _sealed, _sealed_cards
from app.api.whatif import _loader
from app.core.artifact_store import put_json
row = await run_graph(monkeypatch, query_graph())
other = await run_graph(monkeypatch, query_graph(sql="SELECT id, region, amount FROM orders ORDER BY id LIMIT 10"))
stray = await put_json({"path": "vars.res.rows", "value": [1, 2, 3]}, kind="metric_input", run_id=row.id)
sealed = await _sealed(row.id)
loader = _loader(sealed, _sealed_cards(sealed))
assert loader(await snapshot_of(row.id)) is not None
assert loader(await snapshot_of(other.id)) is None and loader(stray) is None
card = loader(sealed.outputs["card"])
value_artifacts = {i["value_artifact"] for m in card["metrics"] for i in m["inputs"] if i.get("value_artifact")}
assert value_artifacts and all(loader(a) is not None for a in value_artifacts)
async def test_missing_things_are_coded_404s(client, monkeypatch):
row = await run_graph(monkeypatch, query_graph())
cases = [
("/api/runs/nope/evidence/whatif", {"card": "card"}, "run_not_found"),
(f"/api/runs/{row.id}/evidence/whatif", {"card": "write"}, "whatif_card_not_found"),
(f"/api/runs/{row.id}/evidence/whatif", {"card": "ghost"}, "whatif_card_not_found"),
(f"/api/runs/{row.id}/evidence/whatif", {"card": "card", "metric": "ghost"}, "whatif_metric_not_found"),
(f"/api/runs/{row.id}/evidence/whatif", {"card": "card", "report": "ghost"}, "evidence_report_not_found"),
]
for url, body, code in cases:
resp = await client.post(url, json=body)
assert resp.status_code == 404 and resp.json()["code"] == code, (body, resp.text)
# --------------------------------------------------------------------------
# 遮罩、封存
# --------------------------------------------------------------------------
async def test_masked_columns_are_neither_shown_nor_used(client, monkeypatch, shop):
await set_source(shop, {"mask_columns": ["amount"]})
row = await run_graph(monkeypatch, query_graph())
snapshot = await snapshot_of(row.id)
body = await whatif(client, row.id, {"card": "card"})
metrics = by_id(body)
[cell] = metrics["amount5"]["inputs"]
assert cell["masked"] is True and cell["old"] is None and cell["new"] is None and cell["editable"] is False
assert metrics["amount5"]["substituted"] is None and metrics["per"]["substituted"] is None
reasons = {(u["metric"], u["input"]): u["reason"] for u in body["unsupported"]}
assert "遮罩" in reasons[("amount5", AMOUNT5)] and "遮罩" in reasons[("cnt", "vars.res.rows")]
# 三个指标都用到了遮罩列:不改动也照实说推演不了,不报「无变化」;什么都没改,下游不受影响
assert {k: (m["status"], m["changed"], m["rendered_new"]) for k, m in metrics.items()} == {
k: ("masked", None, None) for k in ("amount5", "cnt", "per")}
assert all(reasons[(k, None)] == metrics[k]["reason"] for k in metrics) and body["affected_cards"] == []
resp = await client.post(f"/api/runs/{row.id}/evidence/whatif",
json={"card": "card", "overrides": {"inputs": {AMOUNT5: 1}}})
assert resp.status_code == 422 and "遮罩" in resp.json()["detail"]
metrics = by_id(await whatif(client, row.id, {"card": "card", "overrides": {"exclude_rows": {snapshot: [1]}}}))
assert metrics["cnt"]["status"] == "masked" and metrics["cnt"]["new"] is None
assert metrics["per"]["status"] == "masked" and metrics["amount5"]["status"] == "masked"
async def test_a_metric_using_a_masked_column_offers_nothing_to_adjust(client, monkeypatch, shop):
"""指标的一个输入取自遮罩列,另一个是能改的格:整个指标推演不了,那一格也不让改、它那一行也不让勾。
改了也只回「用到了遮罩列」,不给新值。"""
await set_source(shop, {"mask_columns": ["region"]})
region = "cell(nodes.fetch, 5, 'region')"
metrics = [{"id": "mix", "name": "混合", "decimals": 1, "expression": f"len({region}) + {AMOUNT5}"}]
row = await run_graph(monkeypatch, query_graph(metrics=metrics), text="混合 [[m:mix]]。")
body = await whatif(client, row.id, {"card": "card", "metric": "mix", "report": "write"})
[mix] = body["metrics"]
assert (mix["status"], mix["changed"], mix["rendered_new"]) == ("masked", None, None) and "遮罩" in mix["reason"]
inputs = {i["path"]: i for i in mix["inputs"]}
assert inputs[region]["masked"] is True and inputs[AMOUNT5]["old"] == 600.5
assert all(i["editable"] is False and "row_span" not in i for i in inputs.values())
assert {"metric": "mix", "input": None, "reason": mix["reason"]} in body["unsupported"]
[seg] = body["segments"]
assert seg["rendered_new"] is None and seg["changed"] is None and body["affected_cards"] == []
[mix] = (await whatif(client, row.id, {"card": "card", "metric": "mix",
"overrides": {"inputs": {AMOUNT5: 1}}}))["metrics"]
assert (mix["status"], mix["new"], mix["changed"]) == ("masked", None, None)
async def test_masks_recorded_at_query_time_apply_after_the_source_drops_them(client, monkeypatch, shop):
"""查询当时设了遮罩、跑完之后数据源去掉了:快照里记下的遮罩照样算,推演和勾行接口都不给那一列。"""
await set_source(shop, {"mask_columns": ["amount"]})
row = await run_graph(monkeypatch, query_graph())
snapshot = await snapshot_of(row.id)
await set_source(shop, {})
body = await whatif(client, row.id, {"card": "card"})
[cell] = by_id(body)["amount5"]["inputs"]
assert cell["masked"] is True and cell["old"] is None and cell["editable"] is False
assert by_id(body)["amount5"]["status"] == "masked"
assert "600.5" not in json.dumps([m["inputs"] for m in body["metrics"]])
url = f"/api/runs/{row.id}/evidence/whatif/rows"
page = (await client.get(url, params={"artifact": snapshot, "limit": 2})).json()
assert page["masked"] == ["amount"] and page["rows"] == [[1, "华南", "已遮罩"], [2, "华北", "已遮罩"]]
async def test_a_run_waiting_for_approval_can_be_explored_but_is_not_sealed(client, monkeypatch):
row = await run_graph(monkeypatch, query_graph(between=[node("gate", "human", mode="approve", title="确认")]),
statuses=("interrupted",))
before = await footprint(row.id)
body = await whatif(client, row.id, {"card": "card", "overrides": {"inputs": {AMOUNT5: 1000}}})
assert body["sealed"] is False and body["seal"]["sealed"] is False
assert by_id(body)["amount5"]["new"] == 1000 and body["segments"] == []
assert await footprint(row.id) == before
# --------------------------------------------------------------------------
# 容器输入的还原
# --------------------------------------------------------------------------
async def test_an_old_run_without_full_values_says_so(client, monkeypatch):
"""加 value_artifact 之前的运行:vars 的容器没存完整值,用到它的指标推演不了,原因写清楚。"""
from app.engine.nodes import metrics as metrics_node
async def nothing(*args, **kwargs):
return None
monkeypatch.setattr(metrics_node, "_store_value", nothing)
row = await run_graph(monkeypatch, query_graph())
body = await whatif(client, row.id, {"card": "card", "overrides": {"inputs": {AMOUNT5: 1000}}})
reasons = {(u["metric"], u["input"]): u["reason"] for u in body["unsupported"]}
assert reasons[("cnt", "vars.res.rows")] == "无法推演:当时没有保存这个输入的完整值"
per = by_id(body)["per"]
assert per["status"] == "unsupported" and per["new"] is None and per["rendered_new"] is None
assert "当时没有保存这个输入的完整值" in per["reason"]
assert by_id(body)["amount5"]["new"] == 1000
assert next(s for s in body["segments"] if s["metric"] == "per")["rendered_new"] is None
async def test_node_containers_come_from_the_sealed_node_output(client, monkeypatch):
row = await run_graph(monkeypatch, chain(
node("start", "input"),
node("fetch", "transform", mode="expression", expression="{'items': [3, 5, 7], 'k': 2}", assign_to="kpi"),
node("card", "metrics", caliber="推演口径", metrics=[
{"id": "n", "name": "加权条数", "expression": "len(nodes.fetch.items) * vars.kpi.k"}]),
node("out", "output", fields=[{"name": "r", "value": "{{ nodes.card.text }}"}])))
assert [(m, s, new == old) for _, m, s, new, old in await faithful(row.id)] == [("n", "ok", True)]
body = await whatif(client, row.id, {"card": "card", "overrides": {"inputs": {"vars.kpi.k": 5}}})
[n] = body["metrics"]
assert n["status"] == "ok" and (n["old"], n["new"]) == (6, 15)
items = next(i for i in n["inputs"] if i["path"] == "nodes.fetch.items")
assert items["kind"] == "container" and items["old"] == "[3 项]"
assert body["segments"] == []
class AgentScript:
"""agent 查一次按周汇总,抽取把两周的金额交成一个数组字段(出处是 Q1 的第 0–1 行)。"""
WEEKLY = "SELECT week, SUM(amount) AS amount FROM orders GROUP BY week ORDER BY week"
def __init__(self, monkeypatch):
from app.providers import mock_model
extracted = {"amounts": {"value": [601.5, 4903.5], "from": {"call": "Q1", "rows": "0-1", "column": "amount"}}}
def decide(model, messages):
if model.response_format:
return AIMessage(content=json.dumps(extracted, ensure_ascii=False))
if not model.tools:
return AIMessage(content="收尾")
if not any(isinstance(m, ToolMessage) for m in messages):
return AIMessage(content="查。", tool_calls=[
{"name": "db_query__shop", "args": {"sql": self.WEEKLY}, "id": "call_0"}])
return AIMessage(content="两周金额已汇总。")
monkeypatch.setattr(mock_model.MockChatModel, "_decide", decide)
async def test_agent_array_fields_follow_the_excluded_rows(client, monkeypatch):
AgentScript(monkeypatch)
schema = {"type": "object", "properties": {"amounts": {"type": "array", "items": {"type": "number"}}}}
graph = chain(
node("start", "input"),
node("bot", "agent", prompt="按周汇总金额", tools=["db_query__shop"], approval="never",
output_schema=schema, cite_fields=True, assign_to="kpi"),
node("card", "metrics", caliber="推演口径", metrics=[
{"id": "via_node", "name": "合计", "decimals": 1, "expression": "sum(nodes.bot.data.amounts)"},
{"id": "via_vars", "name": "合计", "decimals": 1, "expression": "sum(vars.kpi.amounts)"}]),
node("out", "output", fields=[{"name": "r", "value": "{{ nodes.card.text }}"}]))
row = await wait((await run_manager.start(graph=graph, input_payload={})).id)
assert row.status == "succeeded", row.error
snapshot = await snapshot_of(row.id, "bot")
weeks = {"2026-W36": sum(a for i, _, a in ROWS if i <= 3), "2026-W37": sum(a for i, _, a in ROWS if i > 3)}
total = round(weeks["2026-W36"] + weeks["2026-W37"], 1)
baseline = by_id(await whatif(client, row.id, {"card": "card"}))
assert baseline["via_node"]["old"] == baseline["via_vars"]["old"] == total
assert [(m, s, new == old) for _, m, s, new, old in await faithful(row.id)] == [
("via_node", "ok", True), ("via_vars", "ok", True)]
body = await whatif(client, row.id, {"card": "card", "overrides": {"exclude_rows": {snapshot: [0]}}})
for metric in by_id(body).values():
assert metric["status"] == "ok" and metric["new"] == round(weeks["2026-W37"], 1), metric
[amounts] = metric["inputs"]
assert amounts["excluded_rows"] == [0] and (amounts["old"], amounts["new"]) == ("[2 项]", "[1 项]")
async def test_an_agent_array_whose_node_output_is_gone_is_never_unchanged(client, monkeypatch, damage):
"""agent 节点封存的产出文件不在了:nodes.bot.data.amounts 的完整值找不回来。排除它用到的一行,它一定少了一项,
少的是多少不知道——不能报「无变化」,也不给行段让人勾。vars.kpi.amounts 另存过完整值,照常推演。"""
AgentScript(monkeypatch)
schema = {"type": "object", "properties": {"amounts": {"type": "array", "items": {"type": "number"}}}}
row = await wait((await run_manager.start(graph=chain(
node("start", "input"),
node("bot", "agent", prompt="按周汇总金额", tools=["db_query__shop"], approval="never",
output_schema=schema, cite_fields=True, assign_to="kpi"),
node("card", "metrics", caliber="推演口径", metrics=[
{"id": "via_node", "name": "合计", "decimals": 1, "expression": "sum(nodes.bot.data.amounts)"},
{"id": "via_vars", "name": "合计", "decimals": 1, "expression": "sum(vars.kpi.amounts)"}]),
node("out", "output", fields=[{"name": "r", "value": "{{ nodes.card.text }}"}])), input_payload={})).id)
assert row.status == "succeeded", row.error
snapshot = await snapshot_of(row.id, "bot")
async with SessionLocal() as session:
[finished] = (await session.execute(select(RunEvent).where(
RunEvent.run_id == row.id, RunEvent.type == "node.finished", RunEvent.node_id == "bot"))).scalars()
damage(finished.data["artifact"])
baseline = by_id(await whatif(client, row.id, {"card": "card"}))
assert baseline["via_node"]["status"] == "unsupported" and "bot" in baseline["via_node"]["reason"]
assert all(i["editable"] is False and "row_span" not in i for i in baseline["via_node"]["inputs"])
body = await whatif(client, row.id, {"card": "card", "overrides": {"exclude_rows": {snapshot: [0]}}})
via_node, via_vars = by_id(body)["via_node"], by_id(body)["via_vars"]
assert via_node["status"] == "unsupported" and via_node["changed"] is None and via_node["rendered_new"] is None
assert via_vars["status"] == "ok" and via_vars["new"] == round(sum(a for i, _, a in ROWS if i > 3), 1)
# --------------------------------------------------------------------------
# 下游口径卡
# --------------------------------------------------------------------------
async def test_downstream_cards_are_flagged_only_when_something_changes(client, monkeypatch):
row = await run_graph(monkeypatch, chain(
node("start", "input"),
node("fetch", "transform", mode="expression", expression="{'gmv': 100.0, 'k': 2}", assign_to="kpi"),
node("card", "metrics", caliber="周口径", caliber_version="v1", assign_to="m", metrics=[
{"id": "gmv", "name": "销售额", "decimals": 1, "expression": "vars.kpi.gmv"}]),
node("yearly", "metrics", caliber="年口径", caliber_version="v2", metrics=[
{"id": "year", "name": "年化", "decimals": 1, "expression": "vars.m.metrics[0].value * 52"}]),
node("out", "output", fields=[{"name": "r", "value": "{{ nodes.yearly.text }}"}])))
assert (await whatif(client, row.id, {"card": "card"}))["affected_cards"] == []
assert [(c, m, s, new == old) for c, m, s, new, old in await faithful(row.id)] == [
("card", "gmv", "ok", True), ("yearly", "year", "ok", True)]
body = await whatif(client, row.id, {"card": "card", "overrides": {"inputs": {"vars.kpi.gmv": 120}}})
assert by_id(body)["gmv"]["new"] == 120
[flagged] = body["affected_cards"]
assert (flagged["node_id"], flagged["caliber"], flagged["version"], flagged["metrics"], flagged["direct"]) == (
"yearly", "年口径", "v2", ["year"], True)
# --------------------------------------------------------------------------
# 排除行:说不准受不受影响的指标不报「无变化」
# --------------------------------------------------------------------------
async def test_excluding_rows_of_an_old_run_never_says_unchanged(client, monkeypatch):
"""老运行的 vars.res.rows 没存完整值:排除 cell 那一格以外的行,平均每单会变(分母少了一行),却算不出来。
不能报「60.05元 → 60.05元 无变化」,报告里引用它的地方也不能报「不受影响」。"""
from app.engine.nodes import metrics as metrics_node
async def nothing(*args, **kwargs):
return None
monkeypatch.setattr(metrics_node, "_store_value", nothing)
row = await run_graph(monkeypatch, query_graph())
snapshot = await snapshot_of(row.id)
body = await whatif(client, row.id, {"card": "card", "metric": "per", "report": "write",
"overrides": {"exclude_rows": {snapshot: [3]}}})
[per] = body["metrics"]
assert per["status"] == "unsupported" and per["changed"] is None and per["new"] is None, per
assert "vars.res.rows" in per["reason"]
[seg] = body["segments"]
assert seg["metric"] == "per" and seg["rendered_new"] is None and seg["changed"] is None
cnt = by_id(await whatif(client, row.id, {"card": "card", "overrides": {"exclude_rows": {snapshot: [3]}}}))["cnt"]
assert cnt["status"] == "unsupported" and cnt["changed"] is None
async def test_only_inputs_computed_after_the_snapshot_came_back_are_doubted(client, monkeypatch):
"""写在查询之前的容器(early)排除行影响不到它;查询之后才算出来、又对不上任何快照的(late)说不准。
按位置取自整份结果的一格(vars.res.rows[0][2])同样说不准:排除第 0 行后它取到的是另一行。"""
metrics = [
{"id": "m_early", "name": "加早", "decimals": 1, "expression": f"round({AMOUNT5} + sum(vars.early.items), 1)"},
{"id": "m_late", "name": "加晚", "decimals": 1, "expression": f"round({AMOUNT5} + sum(vars.late.items), 1)"},
{"id": "first", "name": "首单占比", "decimals": 2,
"expression": "round(vars.res.rows[0][2] / len(vars.res.rows), 2)"},
]
row = await run_graph(monkeypatch, chain(
node("start", "input"),
node("early_n", "transform", mode="expression", expression="{'items': [1.5, 2.5]}", assign_to="early"),
node("fetch", "tool", tool="db_query__shop", args={"sql": SQL}),
node("parse", "transform", mode="json", template="{{ nodes.fetch }}", assign_to="res"),
node("late_n", "transform", mode="expression", expression="{'items': [1.5, 2.5]}", assign_to="late"),
node("card", "metrics", caliber="推演口径", metrics=metrics),
node("write", "report", instructions="写周报", on_violation="flag"),
node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}])),
text="加早 [[m:m_early]],加晚 [[m:m_late]],首单占比 [[m:first]]。")
snapshot = await snapshot_of(row.id)
assert [(m, s, new == old) for _, m, s, new, old in await faithful(row.id)] == [
("m_early", "ok", True), ("m_late", "ok", True), ("first", "ok", True)]
metrics = by_id(await whatif(client, row.id, {"card": "card", "overrides": {"exclude_rows": {snapshot: [0]}}}))
assert metrics["m_early"]["status"] == "unchanged" and metrics["m_early"]["changed"] is False
assert metrics["m_late"]["status"] == "unsupported" and "vars.late.items" in metrics["m_late"]["reason"]
assert "对不上任何查询快照" in metrics["m_late"]["reason"]
assert metrics["first"]["status"] == "unsupported" and metrics["first"]["new"] is None
assert "vars.res.rows[0][2]" in metrics["first"]["reason"]
# --------------------------------------------------------------------------
# 查询快照读不出来、封存核对没过、事后加的遮罩、被改过的指标集
# --------------------------------------------------------------------------
def artifact_file(artifact: str):
return settings.data_dir / "artifacts" / artifact[:2] / f"{artifact}.json"
@pytest.fixture
def damage():
"""删掉、改坏工件文件,测完放回原样:工件按内容寻址,同样的查询、同样的卡在后面的测试里还是这一份文件,
put_json 见文件在就不再写——不放回去,后面的测试拿到的就是坏的。"""
saved: list[tuple] = []
def apply(artifact: str, change=None) -> None:
path = artifact_file(artifact)
text = path.read_text("utf-8")
saved.append((path, text))
if change is None:
path.unlink()
return
content = json.loads(text)
change(content)
path.write_text(json.dumps(content, ensure_ascii=False), encoding="utf-8")
yield apply
for path, text in reversed(saved):
path.write_text(text, encoding="utf-8")
def tamper_cell(content):
content["rows"][5][2] = 1.0
@pytest.mark.parametrize("change, words", [(None, "无法读取"), (tamper_cell, "哈希")])
async def test_an_unreadable_snapshot_withholds_the_cells_on_it(client, monkeypatch, damage, change, words):
"""快照文件不在了、被改过:那一格遮没遮核对不了,卡上记着的值也不给、不能改,代入式也不给。"""
row = await run_graph(monkeypatch, query_graph())
damage(await snapshot_of(row.id), change)
body = await whatif(client, row.id, {"card": "card"})
metrics = by_id(body)
[cell] = metrics["amount5"]["inputs"]
assert cell["old"] is None and cell["new"] is None and cell["editable"] is False and cell.get("withheld") is True
assert metrics["amount5"]["substituted"] is None and metrics["per"]["substituted"] is None
assert "600.5" not in json.dumps([m["inputs"] for m in body["metrics"]])
reasons = {(u["metric"], u["input"]): u["reason"] for u in body["unsupported"]}
assert words in reasons[("amount5", AMOUNT5)]
resp = await client.post(f"/api/runs/{row.id}/evidence/whatif",
json={"card": "card", "overrides": {"inputs": {AMOUNT5: 1}}})
assert resp.status_code == 422 and "快照" in resp.json()["detail"], resp.text
async def test_a_mask_set_after_the_run_applies_even_if_the_snapshot_is_gone(client, monkeypatch, shop, damage):
row = await run_graph(monkeypatch, query_graph())
damage(await snapshot_of(row.id))
await set_source(shop, {"mask_columns": ["amount"]})
[cell] = by_id(await whatif(client, row.id, {"card": "card"}))["amount5"]["inputs"]
assert cell["masked"] is True and cell["old"] is None
async def test_masks_added_after_the_run_still_apply(client, monkeypatch, shop):
"""遮罩是查询当时记下的加数据源现在设的:跑完之后才给 amount 加的遮罩照样生效。"""
row = await run_graph(monkeypatch, query_graph())
snapshot = await snapshot_of(row.id)
await set_source(shop, {"mask_columns": ["amount"]})
body = await whatif(client, row.id, {"card": "card"})
metrics = by_id(body)
[cell] = metrics["amount5"]["inputs"]
assert cell["masked"] is True and cell["old"] is None and cell["editable"] is False
assert metrics["amount5"]["substituted"] is None and "row_span" not in cell
resp = await client.post(f"/api/runs/{row.id}/evidence/whatif",
json={"card": "card", "overrides": {"inputs": {AMOUNT5: 1}}})
assert resp.status_code == 422 and "遮罩" in resp.json()["detail"]
cnt = by_id(await whatif(client, row.id, {"card": "card", "overrides": {"exclude_rows": {snapshot: [1]}}}))["cnt"]
assert cnt["status"] == "masked" and cnt["new"] is None
async def test_a_broken_seal_is_not_called_sealed(client, monkeypatch):
"""封存范围里随便一条事件被改过:照样能推演,但 sealed 为假,界面据此说「封存核对未通过」。"""
row = await run_graph(monkeypatch, query_graph())
async with SessionLocal() as session:
started = (await session.execute(select(RunEvent).where(
RunEvent.run_id == row.id, RunEvent.type == "node.started", RunEvent.node_id == "start"))).scalar_one()
started.data = {**(started.data or {}), "note": "事后改过"}
await session.commit()
body = await whatif(client, row.id, {"card": "card", "overrides": {"inputs": {AMOUNT5: 1000}}})
assert body["sealed"] is False and body["seal"] == {"sealed": True, "ok": False}
assert by_id(body)["amount5"]["new"] == 1000
page = (await client.get(f"/api/runs/{row.id}/evidence/whatif/rows",
params={"artifact": await snapshot_of(row.id), "limit": 1})).json()
assert page["sealed"] is False and len(page["rows"]) == 1
async def test_a_tampered_metric_set_is_refused(client, monkeypatch, damage):
row = await run_graph(monkeypatch, query_graph())
card = (await whatif(client, row.id, {"card": "card"}))["card"]["artifact"]
damage(card, lambda content: content["metrics"][0].update(value=1.5))
resp = await client.post(f"/api/runs/{row.id}/evidence/whatif", json={"card": "card"})
assert resp.status_code == 409 and resp.json()["code"] == "whatif_card_tampered", resp.text
# --------------------------------------------------------------------------
# 多份报告、合并查询、循环
# --------------------------------------------------------------------------
async def test_two_reports_are_kept_apart(client, monkeypatch):
"""两个报告节点都引用了这张卡:指定 report 时只列那一份里的地方,不指定时两份都列。"""
row = await run_graph(monkeypatch, chain(
*query_graph()["nodes"][:4],
node("write", "report", instructions="写周报", on_violation="flag"),
node("brief", "report", instructions="写简报", on_violation="flag"),
node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"},
{"name": "简报", "value": "{{ nodes.brief.text }}"}])))
changes = {"overrides": {"inputs": {AMOUNT5: 1000}}}
both = await whatif(client, row.id, {"card": "card", **changes})
assert sorted({s["report"] for s in both["segments"]}) == ["brief", "write"]
one = await whatif(client, row.id, {"card": "card", "report": "brief", **changes})
assert one["report"] == "brief" and one["segments"] and {s["report"] for s in one["segments"]} == {"brief"}
assert len(one["segments"]) == len([s for s in both["segments"] if s["report"] == "brief"])
async def test_a_merged_query_with_a_masked_column(client, monkeypatch, shop):
"""合并查询不是数据源:遮罩按它合并的那几个数据源算,跑完之后才加的遮罩也一样。遮着的列不给值、不能推演。"""
merged = "cell(nodes.merged, 5, 'amount')"
row = await run_graph(monkeypatch, chain(
node("start", "input"),
node("q_amount", "tool", tool="db_query__shop", args={"sql": "SELECT id, amount FROM orders ORDER BY id"}),
node("q_region", "tool", tool="db_query__shop", args={"sql": "SELECT id, region FROM orders ORDER BY id"}),
node("merged", "merge", inputs={"a": "q_amount", "r": "q_region"},
sql="SELECT a.id, r.region, a.amount FROM a JOIN r ON a.id = r.id ORDER BY a.id"),
node("card", "metrics", caliber="推演口径", metrics=[
{"id": "m5", "name": "第六单", "decimals": 1, "expression": merged}]),
node("write", "report", instructions="写周报", on_violation="flag"),
node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}])),
text="第六单 [[m:m5]]。")
[cell] = by_id(await whatif(client, row.id, {"card": "card"}))["m5"]["inputs"]
assert cell["editable"] is True and cell["old"] == 600.5
await set_source(shop, {"mask_columns": ["amount"]})
body = await whatif(client, row.id, {"card": "card"})
[cell] = by_id(body)["m5"]["inputs"]
assert cell["masked"] is True and cell["old"] is None and by_id(body)["m5"]["substituted"] is None
resp = await client.post(f"/api/runs/{row.id}/evidence/whatif",
json={"card": "card", "overrides": {"inputs": {merged: 1}}})
assert resp.status_code == 422 and "遮罩" in resp.json()["detail"]
async def test_a_card_inside_a_loop_uses_the_node_outputs_from_before_that_execution(client, monkeypatch):
"""循环体里口径卡先算、fill 后算:第二轮的卡读到的是第一轮 fill 的产出([1, 10]),不是循环结束时的([2, 20])。
推演按那次执行开始之前的产出还原。"""
row = await run_graph(monkeypatch, {
"nodes": [
node("start", "input"),
node("lp", "loop", mode="foreach", items="[1, 2]", max_iterations=5),
node("card", "metrics", caliber="循环口径", on_missing="null", metrics=[
{"id": "s", "name": "合计", "expression": "sum(nodes.fill.items)"}]),
node("fill", "transform", mode="expression", expression="{'items': [vars.item, vars.item * 10]}"),
node("write", "report", instructions="写周报", on_violation="flag"),
node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}]),
],
"edges": [
{"source": "start", "target": "lp"},
{"source": "lp", "target": "card", "sourceHandle": "body"},
{"source": "card", "target": "fill"},
{"source": "fill", "target": "lp"},
{"source": "lp", "target": "write", "sourceHandle": "done"},
{"source": "write", "target": "out"},
],
}, text="合计 [[m:s]]。")
body = await whatif(client, row.id, {"card": "card", "report": "write"})
[s] = body["metrics"]
assert s["old"] == 11 and s["inputs"][0]["old"] == "[2 项]"
assert [(m, st, new == old) for _, m, st, new, old in await faithful(row.id)] == [("s", "ok", True)]
# --------------------------------------------------------------------------
# 推演里能勾的行
# --------------------------------------------------------------------------
async def test_inputs_carry_the_rows_they_use(client, monkeypatch):
row = await run_graph(monkeypatch, query_graph())
metrics = by_id(await whatif(client, row.id, {"card": "card"}))
[cell] = metrics["amount5"]["inputs"]
[rows] = metrics["cnt"]["inputs"]
assert cell["row_span"] == [5, 5] and rows["row_span"] == [0, 9]
async def test_a_container_that_picks_the_cell_offers_no_rows(client, monkeypatch):
"""cell() 的行号由整份结果算出:整份结果不给行段(勾了别的行,取到哪一格说不准,什么也推演不出来),那一格
自己那一行照常可勾、勾了确定是排除后无法计算。那一格给了新值,取到哪一格已无关紧要,排除别的行照常算。"""
pick = "cell(nodes.fetch, len(vars.res.rows) - 5, 'amount')"
row = await run_graph(monkeypatch, query_graph(metrics=[
{"id": "pick", "name": "倒数第五单金额", "unit": "元", "decimals": 1, "format": "thousands", "expression": pick}]),
text="倒数第五单金额 [[m:pick]]。")
snapshot = await snapshot_of(row.id)
body = await whatif(client, row.id, {"card": "card"})
[m] = body["metrics"]
assert m["status"] == "unchanged" and m["old"] == 600.5
assert [(i["path"], i.get("row_span"), i["editable"]) for i in m["inputs"]] == [
(pick, [5, 5], True), ("vars.res.rows", None, False)]
assert [(u["input"], "取哪" in u["reason"]) for u in body["unsupported"]] == [("vars.res.rows", True)]
[m] = (await whatif(client, row.id, {"card": "card", "overrides": {"exclude_rows": {snapshot: [5]}}}))["metrics"]
assert m["status"] == "excluded" and "第 6 行" in m["reason"]
body = await whatif(client, row.id, {"card": "card", "report": "write",
"overrides": {"inputs": {pick: 1000}, "exclude_rows": {snapshot: [0]}}})
[m] = body["metrics"]
assert (m["status"], m["new"], m["rendered_new"]) == ("ok", 1000, "1,000.0元"), m
assert [(s["rendered_old"], s["rendered_new"]) for s in body["segments"]] == [("600.5元", "1,000.0元")]
async def test_rows_of_a_sealed_snapshot_can_be_paged_with_masks_applied(client, monkeypatch, shop):
"""推演区里给整份结果勾行:按页取封存范围内快照的行,遮罩列写「已遮罩」。只读。"""
row = await run_graph(monkeypatch, query_graph())
snapshot = await snapshot_of(row.id)
url = f"/api/runs/{row.id}/evidence/whatif/rows"
before = await footprint(row.id)
page = (await client.get(url, params={"artifact": snapshot, "offset": 4, "limit": 3})).json()
assert page["artifact"] == snapshot and page["columns"] == ["id", "region", "amount"]
assert page["row_index"] == [4, 5, 6] and page["row_offset"] == 4 and page["total_rows"] == 10
assert page["rows"] == [[5, "华东", 500.5], [6, "华南", 600.5], [7, "华北", 700.5]] and page["masked"] == []
assert page["sealed"] is True and page["hash_ok"] is True
await set_source(shop, {"mask_columns": ["amount"]})
page = (await client.get(url, params={"artifact": snapshot, "limit": 2})).json()
assert page["rows"] == [[1, "华南", "已遮罩"], [2, "华北", "已遮罩"]] and page["masked"] == ["amount"]
assert await footprint(row.id) == before
# 越过末行的页是空的;不属于这次运行的快照、写错的参数说清楚
assert (await client.get(url, params={"artifact": snapshot, "offset": 10})).json()["rows"] == []
other = await run_graph(monkeypatch, query_graph(sql="SELECT id, region, amount FROM orders ORDER BY id DESC"))
for params, words in [({"artifact": await snapshot_of(other.id)}, "封存范围"), ({}, "artifact"),
({"artifact": snapshot, "limit": "很多"}, "limit"), ({"artifact": snapshot, "offset": -1}, "offset")]:
resp = await client.get(url, params=params)
assert resp.status_code == 422 and words in resp.json()["detail"], (params, resp.text)
async def test_rows_of_an_unreadable_snapshot_are_not_served(client, monkeypatch, damage):
row = await run_graph(monkeypatch, query_graph())
snapshot = await snapshot_of(row.id)
damage(snapshot)
page = (await client.get(f"/api/runs/{row.id}/evidence/whatif/rows", params={"artifact": snapshot})).json()
assert page["rows"] == [] and page["hash_ok"] is None and "无法读取" in page["note"]
# --------------------------------------------------------------------------
# 下游口径卡、取整
# --------------------------------------------------------------------------
async def test_downstream_cards_through_an_intermediate_node_are_flagged(client, monkeypatch):
row = await run_graph(monkeypatch, chain(
node("start", "input"),
node("fetch", "transform", mode="expression", expression="{'gmv': 100.0}", assign_to="kpi"),
node("card", "metrics", caliber="周口径", caliber_version="v1", metrics=[
{"id": "gmv", "name": "销售额", "decimals": 1, "expression": "vars.kpi.gmv"}]),
node("mid", "transform", mode="expression", expression="{'g': nodes.card.metrics[0].value * 2}", assign_to="t"),
node("yearly", "metrics", caliber="年口径", caliber_version="v2", metrics=[
{"id": "year", "name": "年化", "decimals": 1, "expression": "vars.t.g * 26"}]),
node("out", "output", fields=[{"name": "r", "value": "{{ nodes.yearly.text }}"}])))
body = await whatif(client, row.id, {"card": "card", "overrides": {"inputs": {"vars.kpi.gmv": 120}}})
[flagged] = body["affected_cards"]
assert (flagged["node_id"], flagged["metrics"], flagged["direct"]) == ("yearly", ["year"], False)
async def test_a_change_that_moves_no_metric_flags_no_downstream_card(client, monkeypatch):
"""改动碰到了指标、算出来却没变(10 单里排除 2 单,min(单数, 3) 还是 3):下游不会受影响,不标。排除到只剩 2 单
才变,这时才标。界面不会提交和原值一样的输入,排除行却常有这种情况(又如 max(…) 勾掉的不是最大值那一行)。"""
row = await run_graph(monkeypatch, query_graph(
metrics=[{"id": "cap", "name": "封顶单数", "unit": "单", "format": "thousands",
"expression": "min(len(vars.res.rows), 3)"}],
between=[node("yearly", "metrics", caliber="年口径", metrics=[
{"id": "year", "name": "年化", "expression": "nodes.card.metrics[0].value * 52"}])]),
text="封顶单数 [[m:cap]]。")
snapshot = await snapshot_of(row.id)
body = await whatif(client, row.id, {"card": "card", "overrides": {"exclude_rows": {snapshot: [2, 7]}}})
[cap] = body["metrics"]
assert (cap["status"], cap["new"], cap["changed"], cap["inputs"][0]["excluded_rows"]) == ("ok", 3, False, [2, 7])
assert body["affected_cards"] == []
body = await whatif(client, row.id, {"card": "card", "overrides": {"exclude_rows": {snapshot: list(range(8))}}})
assert body["metrics"][0]["new"] == 2 and [c["node_id"] for c in body["affected_cards"]] == ["yearly"]
async def test_downstream_cards_are_flagged_when_the_change_cannot_be_followed(client, monkeypatch):
"""改动碰到了指标、它却推演不了(还原不了、遮罩):新值不知道,下游同样可能受影响。"""
from app.engine.nodes import metrics as metrics_node
async def nothing(*args, **kwargs):
return None
monkeypatch.setattr(metrics_node, "_store_value", nothing)
row = await run_graph(monkeypatch, query_graph(between=[node("yearly", "metrics", caliber="年口径", metrics=[
{"id": "year", "name": "年化", "decimals": 1, "expression": "nodes.card.metrics[2].value * 52"}])]))
body = await whatif(client, row.id, {"card": "card", "metric": "per", "overrides": {"inputs": {AMOUNT5: 1000}}})
assert body["metrics"][0]["status"] == "unsupported"
assert [c["node_id"] for c in body["affected_cards"]] == ["yearly"]
# 什么都不改:平均每单本来就推演不了(vars.res.rows 没存完整值),一打开就照实说;那一格也不让改、它那一行
# 也不让勾,报告里引用它的地方不说「不受影响」。什么都没改,下游不会受影响
body = await whatif(client, row.id, {"card": "card", "metric": "per", "report": "write"})
[per] = body["metrics"]
assert (per["status"], per["changed"], per["rendered_new"]) == ("unsupported", None, None)
assert "vars.res.rows" in per["reason"] and "完整值" in per["reason"]
assert all(i["editable"] is False and "row_span" not in i for i in per["inputs"])
assert [(s["metric"], s["rendered_new"], s["changed"]) for s in body["segments"]] == [("per", None, None)]
assert body["affected_cards"] == []
TRICKY = [(2.675, 2), (0.125, 2), (-1.5, 0), (1234.5, -1), (-1250.0, -2), (0.0005, 3), (99.995, 2), (-0.045, 2)]
async def test_rounding_matches_the_card_for_tricky_values(monkeypatch):
"""取整和口径卡逐个对上:二进制里落在半中间的数、负数、负的小数位(取整到十位、百位)。run_metrics 的取整规则哪天
改了(比如换成四舍五入),这里会对不上。"""
import random
rng = random.Random(20261005)
pairs = TRICKY + [(round(rng.uniform(-1e6, 1e6), rng.randint(0, 6)), rng.randint(-3, 6)) for _ in range(24)]
kpi = "{" + ", ".join(f"'v{i}': {v!r}" for i, (v, _) in enumerate(pairs)) + "}"
row = await run_graph(monkeypatch, chain(
node("start", "input"),
node("fetch", "transform", mode="expression", expression=kpi, assign_to="kpi"),
node("card", "metrics", caliber="取整口径", metrics=[
{"id": f"m{i}", "name": f"m{i}", "format": "plain", "decimals": d, "expression": f"vars.kpi.v{i} * 1.0"}
for i, (_, d) in enumerate(pairs)]),
node("out", "output", fields=[{"name": "r", "value": "{{ nodes.card.text }}"}])))
again = await faithful(row.id)
assert len(again) == len(pairs)
assert [(m, s) for _, m, s, new, old in again if s != "ok" or new != old] == []
+90
View File
@@ -0,0 +1,90 @@
"""数字推演取哪一份:同一张口径卡执行过几次时推演哪一次、那次执行之前各节点的产出和跑完的时刻、快照什么时候交回。
照 api/evidence.py 的 _Sealed 手写事件(虚构的工件 id),不起运行、不碰库:真跑的循环图里报告总是引用最后一次执行,
节点也常常不会在口径卡之后再跑,这几条边界只有手写的事件才拿得到。
"""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any
import pytest
from app.api.coded import CodedHTTPException
from app.api.evidence import _Sealed
from app.api.whatif import _card_of, _finished_before, _outputs_before, _returned
FILL1, FILL2, A1, A2, OUT1, OUT2, Q1 = ("f1" * 32, "f2" * 32, "a1" * 32, "a2" * 32, "c1" * 32, "c2" * 32, "d1" * 32)
@dataclass
class Report:
node_id: str
doc: dict[str, Any] | None = field(default_factory=dict)
def sealed(events: list[tuple[int, str, str | None, dict[str, Any]]]) -> _Sealed:
return _Sealed(run_id="r1", graph={"nodes": [{"id": "card", "type": "metrics"}]},
seal={"sealed": True, "ok": True, "manifest_seq": 99, "legacy": False}, events=events)
#: 循环两轮:fill → card,fill → card。第一轮的卡读到 FILL1,第二轮读到 FILL2
LOOP = [
(1, "node.started", "fill", {}),
(2, "tool.end", "fill", {"query_artifact": Q1}),
(3, "node.finished", "fill", {"artifact": FILL1}),
(4, "node.started", "card", {}),
(5, "node.finished", "card", {"artifact": OUT1, "evidence": [{"kind": "metric_set", "artifact": A1}]}),
(6, "node.started", "fill", {}),
(7, "node.finished", "fill", {"artifact": FILL2, "evidence": [{"kind": "query", "artifact": Q1}]}),
(8, "node.started", "card", {}),
(9, "node.finished", "card", {"artifact": OUT2, "evidence": [{"kind": "metric_set", "artifact": A2}]}),
]
CARDS = [("card", A1, {"metrics": [{"id": "s", "value": 1}]}), ("card", A2, {"metrics": [{"id": "s", "value": 2}]})]
def cites(*artifacts: str, node: str = "write") -> Report:
return Report(node, {"catalog": {f"m:{i}": {"kind": "metric", "node_id": "card", "artifact": a}
for i, a in enumerate(artifacts)}})
def test_the_execution_the_report_cites_is_chosen_over_the_last_one():
artifact, card, started = _card_of(sealed(LOOP), CARDS, "card", [cites(A1)], None)
assert (artifact, card["metrics"][0]["value"], started) == (A1, 1, 4)
def test_without_a_citation_the_last_execution_is_used():
assert _card_of(sealed(LOOP), CARDS, "card", [cites()], None)[0] == A2
assert _card_of(sealed(LOOP), CARDS, "card", [], None)[0] == A2
def test_a_chosen_report_decides_which_execution_is_used():
"""两份报告各引用一次执行:指定了 report 就按那一份,不指定按任意一份引用的(取后一次)。"""
reports = [cites(A1, node="weekly"), cites(A2, node="daily")]
assert _card_of(sealed(LOOP), CARDS, "card", reports, "weekly")[0] == A1
assert _card_of(sealed(LOOP), CARDS, "card", reports, "daily")[0] == A2
assert _card_of(sealed(LOOP), CARDS, "card", reports, None)[0] == A2
def test_a_card_whose_content_does_not_verify_is_refused():
with pytest.raises(CodedHTTPException) as caught:
_card_of(sealed(LOOP), CARDS[1:], "card", [cites(A1)], None)
assert caught.value.status_code == 409
def test_node_outputs_and_finish_times_stop_at_the_chosen_execution():
"""第一轮的卡(第 4 条开始)读到的是 FILL1:第二轮 fill 的产出在它之后,不算。"""
events = sealed(LOOP)
assert _outputs_before(events, 4) == {"fill": FILL1}
assert _finished_before(events, 4) == {"fill": 3}
assert _outputs_before(events, 8) == {"fill": FILL2, "card": OUT1}
assert _finished_before(events, 8) == {"fill": 7, "card": 5}
def test_a_snapshot_counts_as_returned_the_first_time_it_shows_up():
assert _returned(sealed(LOOP)) == {Q1: 2}
merged_only = [(3, "node.finished", "merged", {"artifact": OUT1, "evidence": [{"kind": "query", "artifact": Q1}]})]
assert _returned(sealed(merged_only)) == {Q1: 3}
# 同一条查询又跑了一次(结果一样,工件 id 也一样):仍按第一次交回算,第一次之后算出来的值都可能受影响
again = [(2, "tool.end", "fill", {"query_artifact": Q1}), (6, "tool.end", "fill", {"query_artifact": Q1})]
assert _returned(sealed(again)) == {Q1: 2}
+19 -2
View File
@@ -1,7 +1,24 @@
/**
* 数字推演的接口(/api/runs/{run_id}/…)。现在是空的,数字推演的工作包往里加,挂在 api.whatif 上。
* 数字推演的接口(/api/runs/{run_id}/evidence/whatif),挂在 api.whatif 上。推演只读:不写运行记录、不改报告。
*
* 请求函数(get / post / del……)和 ApiError 从 ./http 导入,不要从 ./client 导入:client.ts 要导入
* 这个文件把它挂到 api 上,反过来导入就成了循环(见 http.ts 开头的说明)。
*/
export const whatif = {}
import type { WhatIfRequest, WhatIfResult, WhatIfRowsPage } from '../types'
import { get, request } from './http'
export const whatif = {
/**
* 在一次运行的口径卡上推演。signal 用来丢掉过时的请求:输入还在改、又发了新的一次时,上一次的答复不再要。
* 取消照旧抛 AbortError(request 不把它当成连不上服务端)
*/
run: (runId: string, body: WhatIfRequest, opts?: { signal?: AbortSignal }) =>
request<WhatIfResult>(`/runs/${encodeURIComponent(runId)}/evidence/whatif`, {
method: 'POST', body: JSON.stringify(body), signal: opts?.signal,
}),
/** 一页查询快照的行(从第 offset 行起最多 limit 行,行号从 0 数):推演区里给整份结果、数组字段勾行用 */
rows: (runId: string, artifact: string, page: { offset: number; limit: number }, opts?: { signal?: AbortSignal }) =>
get<WhatIfRowsPage>(`/runs/${encodeURIComponent(runId)}/evidence/whatif/rows?${new URLSearchParams({
artifact, offset: String(page.offset), limit: String(page.limit),
})}`, { signal: opts?.signal }),
}
+33
View File
@@ -0,0 +1,33 @@
import type { JSX } from 'react'
import { EvidenceDoc } from '../../run/EvidenceDoc'
import evidenceQuery from '../../run/__tests__/evidence-query.json'
import type { EvidenceDocData } from '../../types'
/**
* 数字推演的预览用例,scripts/check-whatif.mjs 按它们检查:
* - ?syn=whatif:一份报告(evidence-query.json 里后端 compose_doc 真跑出来的文档,只用通用名),点数字打开证据面板,
* 指标步骤上的「推演」展开推演区。宽屏从右侧弹出,窄屏(390px)从底部抽出
* - ?syn=whatif-rail:同一份报告摆在 360px 的画布右栏里,面板栏内展开
*
* 片段接口、推演接口都由检查脚本用 page.route 伪造(按运行 id 认出这份夹具),直接打开时面板照实说取不到证据链。
* 给了 runClass,文档不再按运行 id 去问运行类别。
*/
const DOC = evidenceQuery.doc as unknown as EvidenceDocData
function Report({ dense = false }: { dense?: boolean }) {
return (
<EvidenceDoc doc={DOC} artifact={evidenceQuery.doc_artifact} runId={evidenceQuery.run_id} label="周报" tally
dense={dense} runClass="formal" />
)
}
export const cases: Record<string, () => JSX.Element> = {
whatif: () => (
<div className="mx-auto max-w-3xl p-4 text-sm" data-fixture="whatif"><Report /></div>
),
'whatif-rail': () => (
<div className="h-full w-[360px] max-w-full overflow-y-auto border-r bg-panel p-2.5" data-fixture="whatif-rail">
<Report dense />
</div>
),
}
+51 -1
View File
@@ -2773,9 +2773,59 @@ export const INQUIRY_TEXT = {
title: '审批质询',
}
/** 数字推演:在一次运行的基础上改动输入,推演指标的变化 */
/**
* 数字推演:在一次运行的基础上改动输入,推演指标的变化(证据面板里口径卡上的数,run/WhatIf.tsx)。
* 推演永远不是出具:横幅要说清不会写进运行记录、不会改动报告。行号对人一律从 1 数(和查询结果表格的 # 列一致)
*/
export const WHATIF_TEXT = {
title: '数字推演',
open: '推演',
openHint: '改动输入或排除查询结果中的行,查看这个数和报告会如何变化',
close: '收起推演',
banner: '推演,非出具:不会写进运行记录,也不会改动报告',
unsealed: '运行未封存,数据可能还会变',
sealBroken: '封存核对未通过,推演所依据的数据可能已被改动',
loading: '推演中…',
failed: '推演失败',
result: '推演结果',
unchanged: '无变化',
delta: (text: string) => `变化 ${text}`,
substituted: '推演代入式',
inputs: '输入',
original: (value: string) => `原值 ${value}`,
inputLabel: (path: string) => `${path} 的推演值`,
notNumber: '请输入数值',
masked: '已遮罩',
withheld: '查询快照无法核对,不显示原值',
excludedRows: (rows: number[]) => `已排除第 ${rows.map((r) => r + 1).join('、')} 行`,
pickRows: (alias: string) => `在查询 ${alias} 中勾选要排除的行`,
pickHere: (n: number) => `勾选要排除的行(共 ${n} 行)`,
pickHereClose: '收起要排除的行',
rowsHint: '勾选的行在推演中视为不存在,这个指标没有用到的行不能勾选',
rowUnused: '这个指标没有用到这一行,排除它不影响结果',
rowsPending: '推演结果返回后才能勾选',
rowsLoading: '正在读取查询结果…',
/** 三个数已按千分位写好(formatNumber) */
rowsRange: (from: string, to: string, total: string) => `第 ${from}–${to} 行,共 ${total} 行`,
rowsMore: (n: number) => `再显示 ${n} 行`,
excludeHead: '排除',
excludeRow: (row: number) => `排除第 ${row + 1} 行`,
excludedCount: (n: number) => `已排除 ${n} 行`,
backToResult: '回到推演结果',
segments: '报告中会变的地方',
segmentsNone: (n: number) => `报告中引用这个指标的 ${n} 处不受影响`,
segmentsUnknown: '这个指标无法推演,报告中引用它的地方会如何变化无法确定',
locate: '定位',
inReport: (node: string) => `另一份报告(${node})`,
unsupported: '不支持推演的输入',
wholeMetric: '整个指标',
nothingToAdjust: '这个指标没有可以修改的输入,也没有可以排除的查询行',
affected: '可能受影响的下游口径卡',
affectedHint: '这些口径卡引用了本卡的指标,推演不会重算它们',
affectedCard: (caliber: string, version: string) => `口径卡「${caliber || '未命名'}」${version ? ` ${version}` : ''}`,
indirect: '间接引用',
reset: '恢复原值',
empty: '这个指标的计算式没有引用任何输入,无可推演',
}
/** 双盲复算节点:节点库说明、检查器和运行结果 */
+81 -10
View File
@@ -30,6 +30,10 @@ import { useEvidenceHost } from './evidenceHost'
import { EvidenceProvenance } from './EvidenceProvenance'
import { CopyChip } from './Markdown'
import { SqlCheckList } from './SqlChecks'
import {
WhatIf, WhatIfRows, WhatIfSummary, WhatIfToggle, focusResult, inSpans, pickMetric, usableRows, useWhatIfDraft,
useWhatIfResult, wholeReason,
} from './WhatIf'
/**
* 证据面板:点开报告里的一个片段,看它从哪来。
@@ -63,6 +67,10 @@ import { SqlCheckList } from './SqlChecks'
* Excel 导入期 4:上传表格的单元格多三节——数据版本、推断的来源、相关核对(EvidenceProvenance)。只在片段是单元格
* 引用、且片段接口的查询步骤带 provenance: true 时请求推断来源接口;推断来源的缓存只在面板开着期间有效。
*
* 数字推演(WhatIf.tsx):指标步骤上的「推演」展开推演区,改输入的值、在查询步骤里勾掉几行,看这个数和报告会变成
* 多少。推演不是出具,不写运行记录、不改报告。勾选框只在推演时出现在查询步骤的结果窗口里,只有这个指标用到的行能勾,
* 表格底下带着推演结果。
*
* 四种摆法:side 从右侧弹出(宽屏),drawer 从底部抽出(窄屏),inline 在 360px 的
* 画布右栏里直接栏内展开,dock 放进页面给的一块常驻位置(记录页的「证据」页签)。
* 都不是模态的:开着面板照样能在正文里走。
@@ -161,7 +169,7 @@ export function EvidencePanel({ id, mode, doc, artifact, runId, runClass, view,
? <ViolationList doc={doc} onLocate={onLocate} />
: found
? <SegmentBody panelId={id} doc={doc} artifact={artifact} runId={runId} runClass={runClass} seg={found.seg}
unit={found.unit} block={found.block} onViolations={onViolations} />
unit={found.unit} block={found.block} onViolations={onViolations} onLocate={onLocate} />
: claimAt
? <ClaimBody doc={doc} artifact={artifact} runId={runId} runClass={runClass} unit={claimAt.unit}
block={claimAt.block} />
@@ -205,11 +213,13 @@ function flashOnce(el: HTMLElement) {
setTimeout(() => { if (el.dataset.flash === 'focus') delete el.dataset.flash }, 1600)
}
function SegmentBody({ panelId, doc, artifact, runId, runClass, seg, unit, block, onViolations }: {
function SegmentBody({ panelId, doc, artifact, runId, runClass, seg, unit, block, onViolations, onLocate }: {
panelId: string
doc: EvidenceDocData; artifact?: string; runId?: string; runClass?: string; seg: EvidenceSegment; unit: EvidenceUnit
block: EvidenceBlock
onViolations: () => void
/** 跳到正文里的某个片段(推演区「报告中会变的地方」的定位) */
onLocate: (segId: string) => void
}) {
const report = doc.node_id || undefined
const key = runId ? segmentKey(runId, seg.id, report) : ''
@@ -295,6 +305,31 @@ function SegmentBody({ panelId, doc, artifact, runId, runClass, seg, unit, block
return i >= 0 ? { index: i, alias: queries[i].alias ?? '', go: () => jumpTo(i) } : undefined
}
const violations = (doc.violations ?? []).filter((v) => v.segment === seg.id)
// 数字推演:按(运行、报告、口径卡、指标)认一份草稿。同一个指标的几处引用之间来回切,推演不收起(定位到另一处
// 引用也是这样);换了指标、换成别的片段才收起清空。卡和指标先按文档目录认:切片段时证据链还没回来,也认得出是同一个
const whatifCard = entry?.kind === 'metric' ? entry.node_id : metricStep?.node_id
const whatifMetric = entry?.kind === 'metric' ? entry.locator?.metric : metricStep?.metric
const whatif = useWhatIfDraft(runId && isMetric && whatifCard && whatifMetric
? [runId, report ?? '', whatifCard, whatifMetric].join('\u0000') : '')
// 证据链回来了、正文就是封存的那一份才给推演:链是别的报告的,推演出来的数也对不上正文
const whatifReady = !!runId && !docIssue && !!metricStep && !!whatifCard && !!whatifMetric
const whatifOpen = whatif.open && whatifReady
const whatifId = `${panelId}-whatif`
// 推演的请求和答复也放在这一层:查询步骤里勾行的表格底下要带着推演结果,和推演区是同一份
const whatifRequest = useMemo(() => (whatifOpen && whatifCard && whatifMetric
? { ...(report ? { report } : {}), card: whatifCard, metric: whatifMetric, overrides: whatif.overrides } : null),
[whatifOpen, report, whatifCard, whatifMetric, whatif.overrides])
const whatifView = useWhatIfResult(runId, whatifRequest)
// 每份快照里这个指标用得到的行:别的行勾了不影响结果,表格里不让勾
const whatifUsable = useMemo(() => usableRows(pickMetric(whatifView.data, whatifMetric)), [whatifView.data, whatifMetric])
// 能勾行的查询步骤:指标的输入(单元格取数、Agent 字段)落在它上面。合并查询的输入步骤不给——指标引用的是合并结果。
// 整个指标推演不了(口径卡没记输入、用到了遮罩列、有输入还原不了)时一行都不给勾
const pickable = new Set(wholeReason(whatifView.data, whatifMetric) ? []
: inputs.map((inp) => inp.artifact).filter((a): a is string => !!a))
const queryLink = (artifactOf?: string) => {
const i = artifactOf ? queries.findIndex((q) => q.artifact === artifactOf && !q.merged_into) : -1
return i >= 0 ? { alias: queries[i].alias ?? '', go: () => jumpTo(i) } : undefined
}
const seal: EvidenceSeal | undefined = docIssue ? undefined : detail?.seal ?? graphData?.seal
const reason = reasonOf(seg) || detail?.note || ''
const verdict = sealVerdict(seal, {
@@ -369,7 +404,13 @@ function SegmentBody({ panelId, doc, artifact, runId, runClass, seg, unit, block
failed={chainFailed}
resolved={state === 'deterministic'}
linkOf={linkOf}
workflowName={workflowName(pinnedWorkflow(metricStep))} />
workflowName={workflowName(pinnedWorkflow(metricStep))}
whatif={whatifReady ? { open: whatifOpen, onToggle: whatif.toggle, controls: whatifId } : undefined}>
{whatifOpen && runId && whatifMetric && (
<WhatIf id={whatifId} runId={runId} report={report} metric={whatifMetric} draft={whatif} view={whatifView}
queryOf={queryLink} onLocate={onLocate} />
)}
</MetricPart>
)}
{isMetric && inputs.some(notableInput) && (
@@ -396,7 +437,17 @@ function SegmentBody({ panelId, doc, artifact, runId, runClass, seg, unit, block
)}
{queries.map((q, i) => (
<QueryPart key={`${q.artifact ?? ''}-${i}`} id={queryId(i)} step={q} seal={seal} masked={masked} />
<QueryPart key={`${q.artifact ?? ''}-${i}`} id={queryId(i)} step={q} seal={seal} masked={masked}
pick={whatifOpen && whatifMetric && q.artifact && !q.merged_into && pickable.has(q.artifact)
? {
excluded: whatif.excluded(q.artifact),
onToggle: (row) => whatif.toggleRow(q.artifact!, row),
usable: whatifUsable ? (row) => inSpans(whatifUsable.get(q.artifact!), row) : undefined,
// 勾了行,新值就在表格底下:推演区在上面,往往已经不在视野里
summary: <WhatIfSummary view={whatifView} metric={whatifMetric} onBack={() => focusResult(whatifId)} />,
busy: whatifView.status === 'loading',
}
: undefined} />
))}
{provenanceOn && runId && <EvidenceProvenance runId={runId} segId={seg.id} report={report} />}
@@ -1073,8 +1124,8 @@ function Sentence({ unit, active }: { unit: EvidenceUnit; active: string }) {
)
}
/** 指标步骤:名称、值、口径与版本(来源、升版处置)、原式、代入式(输入标签)、复算 */
function MetricPart({ step, entry, inputs, runId, seal, pending, failed, resolved, linkOf, workflowName }: {
/** 指标步骤:名称、值、口径与版本(来源、升版处置)、原式、代入式(输入标签)、复算;可以展开数字推演 */
function MetricPart({ step, entry, inputs, runId, seal, pending, failed, resolved, linkOf, workflowName, whatif, children }: {
step?: EvidenceStep
entry?: Record<string, any>
inputs: EvidenceInput[]
@@ -1090,6 +1141,10 @@ function MetricPart({ step, entry, inputs, runId, seal, pending, failed, resolve
linkOf: (input: EvidenceInput) => InputLink
/** 钉住的上游工作流在目录里的名字(接口没给名字时用) */
workflowName?: string
/** 「推演」开关:证据链回来了、正文是封存的那一份才有 */
whatif?: { open: boolean; onToggle: () => void; controls: string }
/** 展开的推演区 */
children?: ReactNode
}) {
const host = useEvidenceHost()
const name = step?.name ?? entry?.name ?? step?.metric ?? entry?.locator?.metric ?? NONE
@@ -1131,6 +1186,7 @@ function MetricPart({ step, entry, inputs, runId, seal, pending, failed, resolve
{EVIDENCE_TEXT.sqlCheckFailed}
</span>
)}
{whatif && <WhatIfToggle open={whatif.open} onToggle={whatif.onToggle} controls={whatif.controls} />}
</div>
{(caliber || version || artifact || from) && (
<div className="mt-0.5 flex flex-wrap items-center gap-x-2 text-2xs text-dim">
@@ -1194,6 +1250,7 @@ function MetricPart({ step, entry, inputs, runId, seal, pending, failed, resolve
{pending ? EVIDENCE_TEXT.chainPending : failed || (runId ? EVIDENCE_TEXT.chainMissing : EVIDENCE_TEXT.noRun)}
</p>
)}
{children}
</Part>
)
}
@@ -1322,7 +1379,16 @@ function SourcesPart({ inputs, linkOf }: { inputs: EvidenceInput[]; linkOf: (inp
* 复验哈希),复用工件查看。被遮罩的列在表里写「已遮罩」。查询快照哈希对不上时用失败色写出来:
* 这时候这些行不能当证据,比「有出处」重要得多
*/
function QueryPart({ id, step, seal, masked }: { id: string; step: EvidenceStep; seal?: EvidenceSeal; masked: string[] }) {
function QueryPart({ id, step, seal, masked, pick }: {
id: string; step: EvidenceStep; seal?: EvidenceSeal; masked: string[]
/**
* 推演时:结果窗口每行前面加勾选框,勾掉的行在推演里视为不存在。usable 说哪几行这个指标用得到(别的行不让勾),
* summary 是画在表格底下的推演结果
*/
pick?: {
excluded: number[]; onToggle: (row: number) => void; usable?: (row: number) => boolean; summary?: ReactNode; busy?: boolean
}
}) {
const host = useEvidenceHost()
const win = useMemo(() => queryWindow(step), [step])
const [open, setOpen] = useState(false)
@@ -1412,9 +1478,14 @@ function QueryPart({ id, step, seal, masked }: { id: string; step: EvidenceStep;
)}
{win.columns.length > 0 && win.rows.length > 0 && (
<div ref={scroller} className={clsx(bad.length > 0 && 'mt-1.5')}>
<ResultTable table={table} full title={EVIDENCE_TEXT.query(alias)}
highlight={win.marks.length || win.cells?.length ? { rows: win.marks, cols: win.cols, cells: win.cells } : undefined}
masked={hidden} />
{pick && win.index
? <WhatIfRows win={win} hidden={hidden} excluded={pick.excluded} onToggle={pick.onToggle} usable={pick.usable}
summary={pick.summary} busy={pick.busy} />
: (
<ResultTable table={table} full title={EVIDENCE_TEXT.query(alias)}
highlight={win.marks.length || win.cells?.length ? { rows: win.marks, cols: win.cols, cells: win.cells } : undefined}
masked={hidden} />
)}
</div>
)}
{!win.rows.length && (
+708
View File
@@ -0,0 +1,708 @@
import { useCallback, useEffect, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboardEvent, type ReactNode } from 'react'
import clsx from 'clsx'
import { CornerDownRight, FlaskConical, ListChecks, LocateFixed, RotateCcw } from 'lucide-react'
import { api } from '../api/client'
import { ErrorNotice, Spinner, isComposing } from '../components/ui'
import { evidenceValue as valueText, queryWindow } from '../lib/evidence'
import { NONE, formatNumber } from '../lib/format'
import { WHATIF_TEXT } from '../lib/terms'
import type { EvidenceStep, WhatIfInput, WhatIfMetric, WhatIfOverrides, WhatIfRequest, WhatIfResult, WhatIfRowsPage } from '../types'
/**
* 数字推演:证据面板里点开口径卡上的一个数,改某个输入的值、或者在查询结果里勾掉几行,立即看到这个指标和报告里
* 引用它的地方会变成多少(POST …/evidence/whatif,后端 engine/recompute.py 按口径卡同一套规则重算)。
*
* 推演永远不是出具:不写进运行记录、不改报告。顶上的横幅一直在,运行没封存时另说「数据可能还会变」。
*
* 几样东西分开放:
* - useWhatIfDraft:改动的草稿(输入框里的原文、提交了的新值、勾掉的行)
* - useWhatIfResult:推演的请求和答复。答复按请求体缓存,「恢复原值」回到原来那份不再请求;新的改动来了旧请求直接丢掉
* 这两样都放在证据面板的片段那一层(SegmentBody):推演区和查询步骤里勾行的表格共用一份草稿、一份答复(勾了行,
* 表格底下就写着新值)。同一个指标的几处引用之间来回切不清空,换了指标才清空
* - WhatIf:推演区。输入框停顿一会儿(或回车、失焦)才提交,勾行立刻提交。请求在路上时,凡是随改动变的地方(结果、
* 报告里会变的地方、下游口径卡、输入上的新值和排除标记)都变淡;请求失败时这些一概不显示,不拿上一次的答复充数
* - WhatIfRows:勾行的表格。推演时查询步骤里的结果窗口换成它;整份结果、数组字段作输入时,推演区里另给一份按页取
* 整份快照的(SnapshotRows)。只有这个指标的输入实际用到的行可勾(row_span),别的行勾了也不影响结果
*
* 不能改的输入(文本、对不上快照的列表、遮罩列、决定取哪一格的下标)照实显示,原因列在「不支持推演的输入」里。
* 整个指标推演不了的(口径卡没记输入、用到了遮罩列、有输入还原不了或所在的快照读不出来,见 wholeReason)只写原因:
* 不写「无变化」,不画输入框、勾选框,也不列报告里引用它的地方——改了、勾了也推演不出来。
*/
/** 输入框停顿多久提交一次:边打字边请求,结果跟着抖 */
const SETTLE_MS = 450
/** 推演区里勾行时一次取几行 */
const ROWS_PAGE = 50
interface DraftState {
scope: string
open: boolean
/** 输入框里的原文。没碰过的输入不在里面,框里显示原值 */
text: Record<string, string>
/** 已提交的新值:请求按它发 */
inputs: Record<string, number>
/** 勾掉的行:查询快照的工件 id → 快照里的行号(从 0 数) */
exclude: Record<string, number[]>
}
const freshDraft = (scope: string, open = false): DraftState => ({ scope, open, text: {}, inputs: {}, exclude: {} })
export interface WhatIfDraft {
open: boolean
toggle: () => void
text: Record<string, string>
/** 输入框改了:停顿一会儿才提交。old 是这个输入的原值,填回原值不算改动 */
type: (path: string, value: string, old: unknown) => void
/** 回车、失焦:立刻提交 */
commit: () => void
/** Esc:输入框退回已提交的值(没提交过就是原值) */
revert: (path: string) => void
toggleRow: (artifact: string, row: number) => void
excluded: (artifact: string | undefined) => number[]
overrides: WhatIfOverrides
/** 有改动(含还没提交的输入框):「恢复原值」可点 */
dirty: boolean
reset: () => void
}
/** 输入框里的文本 → 数。空的是 undefined(回到原值),不是数的是 null。千分位逗号、空格不算错 */
export function parseNumber(raw: string): number | null | undefined {
const text = raw.replace(/[,,\s]/g, '')
if (!text) return undefined
if (!/^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/.test(text)) return null
const n = Number(text)
return Number.isFinite(n) ? n : null
}
/** 原值写进输入框的样子:数照原样(不加千分位,改起来不用先删逗号),缺的是空 */
const plain = (value: unknown): string => (typeof value === 'number' && Number.isFinite(value) ? String(value) : '')
/**
* 提交:输入框里写的是数、而且和原值不同的才算改动。清空了回到原值;写的不是数的保留上一次提交的值——
* 输错一个字,结果不该悄悄跳回原值
*/
function settled(state: DraftState, olds: Record<string, unknown>): Record<string, number> {
const out: Record<string, number> = {}
for (const [path, raw] of Object.entries(state.text)) {
const n = parseNumber(raw)
if (n === null) {
if (path in state.inputs) out[path] = state.inputs[path]
} else if (n !== undefined && olds[path] !== n) {
out[path] = n
}
}
return out
}
export function useWhatIfDraft(scope: string): WhatIfDraft {
const [stored, setState] = useState<DraftState>(() => freshDraft(scope))
// 换了一个指标(另一张卡、另一个数,或者不是指标了):推演收起、改动清空
const state = stored.scope === scope ? stored : freshDraft(scope)
if (stored.scope !== scope) setState(state)
const timer = useRef<ReturnType<typeof setTimeout>>(undefined)
const olds = useRef<Record<string, unknown>>({})
useEffect(() => () => clearTimeout(timer.current), [])
const commit = useCallback(() => {
clearTimeout(timer.current)
setState((s) => ({ ...s, inputs: settled(s, olds.current) }))
}, [])
const type = useCallback((path: string, value: string, old: unknown) => {
olds.current[path] = old
setState((s) => ({ ...s, text: { ...s.text, [path]: value } }))
clearTimeout(timer.current)
timer.current = setTimeout(commit, SETTLE_MS)
}, [commit])
const revert = useCallback((path: string) => {
setState((s) => {
const text = { ...s.text }
if (path in s.inputs) text[path] = String(s.inputs[path])
else delete text[path]
return { ...s, text }
})
}, [])
const toggleRow = useCallback((artifact: string, row: number) => {
setState((s) => {
const rows = s.exclude[artifact] ?? []
const next = rows.includes(row) ? rows.filter((r) => r !== row) : [...rows, row].sort((a, b) => a - b)
const exclude = { ...s.exclude }
if (next.length) exclude[artifact] = next
else delete exclude[artifact]
return { ...s, exclude }
})
}, [])
const reset = useCallback(() => {
clearTimeout(timer.current)
setState((s) => freshDraft(s.scope, s.open))
}, [])
// 收起就清空:再展开从原值开始,勾选框也跟着收起,不留一份看不见的改动
const toggle = useCallback(() => {
clearTimeout(timer.current)
setState((s) => (s.open ? freshDraft(s.scope) : { ...s, open: true }))
}, [])
const overrides = useMemo(() => ({ inputs: state.inputs, exclude_rows: state.exclude }), [state.inputs, state.exclude])
const excluded = useCallback((artifact: string | undefined) => (artifact ? state.exclude[artifact] ?? [] : []),
[state.exclude])
return {
open: state.open, toggle, text: state.text, type, commit, revert, toggleRow, excluded, overrides, reset,
dirty: Object.keys(state.text).length > 0 || Object.keys(state.inputs).length > 0 || Object.keys(state.exclude).length > 0,
}
}
/** 推演的答复:loading 是这次改动的答复还没回来、error 是这次的请求失败了,这两种时候 data 是上一次的 */
export interface WhatIfView {
status: 'loading' | 'ok' | 'error'
data?: WhatIfResult
error?: unknown
retry: () => void
}
type Slot = { key: string; scope: string; status: 'loading' | 'ok' | 'error'; data?: WhatIfResult; error?: unknown; last?: WhatIfResult }
/**
* 发推演请求、收答复。request 为 null(推演收着)时不发。改动之后、请求还没发出去的那一下也算在路上:别拿上一次的
* 答复当这次的。上一次的答复只在同一个指标(运行、报告、卡、指标都一样)之间沿用,换了指标不拿别的指标的数充数
*/
export function useWhatIfResult(runId: string | undefined, request: WhatIfRequest | null): WhatIfView {
const key = runId && request ? JSON.stringify([runId, request]) : ''
const scope = runId && request ? JSON.stringify([runId, request.report ?? '', request.card, request.metric ?? '']) : ''
const [slot, setSlot] = useState<Slot>({ key: '', scope: '', status: 'loading' })
const [nonce, setNonce] = useState(0)
const cache = useRef(new Map<string, WhatIfResult>())
useEffect(() => {
if (!key || !runId) return
const hit = cache.current.get(key)
if (hit) {
setSlot({ key, scope, status: 'ok', data: hit, last: hit })
return
}
const ctrl = new AbortController()
setSlot((s) => ({ key, scope, status: 'loading', last: s.scope === scope ? s.last : undefined }))
const [, body] = JSON.parse(key) as [string, WhatIfRequest]
api.whatif.run(runId, body, { signal: ctrl.signal }).then((data) => {
cache.current.set(key, data)
setSlot({ key, scope, status: 'ok', data, last: data })
}, (error: unknown) => {
if ((error as { name?: string } | null)?.name === 'AbortError') return
setSlot((s) => ({ key, scope, status: 'error', error, last: s.scope === scope ? s.last : undefined }))
})
return () => ctrl.abort()
}, [runId, key, scope, nonce])
const retry = useCallback(() => setNonce((n) => n + 1), [])
const status = slot.key === key ? slot.status : 'loading'
const last = slot.scope === scope ? slot.last : undefined
return { status, data: status === 'ok' ? slot.data : last, error: status === 'error' ? slot.error : undefined, retry }
}
/** 答复里要推演的那个指标 */
export function pickMetric(data: WhatIfResult | undefined, metric: string | undefined): WhatIfMetric | undefined {
return data?.metrics.find((x) => String(x.id) === metric) ?? data?.metrics[0]
}
/**
* 整个指标推演不了(口径卡没记输入、用到了遮罩列、有输入还原不了或所在的快照读不出来):unsupported 里 input 为空的
* 那一条。不论改什么都推演不了,后端不改动也照实给;排除行后才说不准的(只在这次改动下推演不了)没有这一条,照常画
* 输入和勾选框,好让人把行勾回去
*/
export const wholeReason = (data: WhatIfResult | undefined, metric: string | undefined) =>
data?.unsupported.find((u) => String(u.metric) === metric && u.input == null)?.reason
/** 每份快照里这个指标用得到的行段(含两端):各输入的 row_span。答复还没回来时是 undefined */
export function usableRows(m: WhatIfMetric | undefined): Map<string, [number, number][]> | undefined {
if (!m) return undefined
const out = new Map<string, [number, number][]>()
for (const inp of m.inputs) {
if (inp.artifact && inp.row_span) out.set(inp.artifact, [...(out.get(inp.artifact) ?? []), inp.row_span])
}
return out
}
export const inSpans = (spans: [number, number][] | undefined, row: number) =>
!!spans?.some(([a, b]) => row >= a && row <= b)
/** 「回到推演结果」:焦点送回推演结果(推演不了时送回推演区),滚进视野、描一下边 */
export function focusResult(id: string) {
const el = document.getElementById(`${id}-result`) ?? document.getElementById(id)
if (!el) return
el.focus({ preventScroll: true })
el.scrollIntoView({ block: 'nearest' })
el.dataset.flash = 'focus'
setTimeout(() => { if (el.dataset.flash === 'focus') delete el.dataset.flash }, 1600)
}
/** 指标步骤上的「推演」开关 */
export function WhatIfToggle({ open, onToggle, controls }: { open: boolean; onToggle: () => void; controls: string }) {
return (
<button type="button" className={clsx('btn btn-xs ml-auto shrink-0', open && 'border-[var(--st-waiting)]')}
aria-expanded={open} aria-controls={controls} title={open ? WHATIF_TEXT.close : WHATIF_TEXT.openHint}
onClick={onToggle} data-whatif-toggle={open ? 'open' : 'closed'}>
<FlaskConical size={11} aria-hidden /> {WHATIF_TEXT.open}
</button>
)
}
/**
* 推演结果的旧值 → 新值(或原因)、变化量。推演区(big:新值大一号)和勾行的表格底下都用它;tag 是各部分的
* data-* 前缀,两处分开,检查脚本不会把表格底下那份当成推演区的
*/
function Outcome({ m, loading, big = false, tag }: { m: WhatIfMetric; loading: boolean; big?: boolean; tag: string }) {
const at = (part: string) => ({ [`data-${tag}-${part}`]: '' })
return (
<span className="flex flex-wrap items-baseline gap-x-2 gap-y-0.5">
<span className="mono tnum text-dim" {...at('old')}>{m.rendered_old}</span>
<span className="text-faint" aria-hidden>→</span>
<span className={clsx('mono tnum font-semibold', big && 'text-sm')} {...at('new')}
style={m.changed ? { color: 'var(--accent)' } : undefined}>{m.rendered_new ?? NONE}</span>
{m.rendered_delta
? <span className="tnum text-2xs" {...at('delta')}>{WHATIF_TEXT.delta(m.rendered_delta)}</span>
: m.changed === false && <span className="text-2xs text-faint" {...at('delta')}>{WHATIF_TEXT.unchanged}</span>}
{loading && <span className="text-faint"><Spinner size={11} /></span>}
</span>
)
}
/**
* 勾行的表格底下带的推演结果:勾了一行,新值(或推演不了的原因)就在手边,不用回头找。「回到推演结果」把焦点送回
* 推演区。读屏器由推演区的结果播报,这里不再重复
*/
export function WhatIfSummary({ view, metric, onBack }: { view: WhatIfView; metric: string; onBack?: () => void }) {
const m = pickMetric(view.data, metric)
const loading = view.status === 'loading'
const failed = view.status === 'error'
const whole = wholeReason(view.data, metric)
const reason = failed ? undefined : whole ?? m?.reason
return (
<div className="border-t px-1.5 py-1 text-2xs" data-whatif-summary={failed ? 'error' : loading ? 'loading' : m?.status ?? ''}>
<div className="flex flex-wrap items-center gap-x-2 gap-y-0.5">
<span className="font-medium text-faint">{WHATIF_TEXT.result}</span>
{failed
? <span style={{ color: 'var(--err)' }}>{WHATIF_TEXT.failed}</span>
: m && !whole
? <span className={clsx('text-xs transition-opacity', loading && 'opacity-60')}><Outcome m={m} loading={loading} tag="whatif-summary" /></span>
: !m && <Spinner size={11} />}
{onBack && (
<button type="button" className="btn btn-xs btn-ghost ml-auto" onClick={onBack} data-whatif-back="">
{WHATIF_TEXT.backToResult}
</button>
)}
</div>
{reason && (
<p className={clsx('mt-0.5 [overflow-wrap:anywhere] transition-opacity', loading && 'opacity-60')}
style={{ color: 'var(--st-waiting)' }}>{reason}</p>
)}
</div>
)
}
/** 推演区:横幅、结果、输入、不支持的输入、报告里会变的地方、下游口径卡、恢复原值 */
export function WhatIf({ id, runId, report, metric, draft, view, queryOf, onLocate }: {
id: string
runId: string
/** 正文这份报告的撰写节点 id:报告里会变的地方只列它的(都能定位) */
report?: string
metric: string
draft: WhatIfDraft
view: WhatIfView
/** 输入落在哪个查询步骤上:有的话给「在查询 Qn 中勾选要排除的行」,点一下跳过去 */
queryOf: (artifact?: string) => { alias: string; go: () => void } | undefined
/** 定位到正文里的一个片段 */
onLocate?: (segId: string) => void
}) {
const { status, data } = view
const loading = status === 'loading'
const failed = status === 'error'
const m = pickMetric(data, metric)
const unsupported = (data?.unsupported ?? []).filter((u) => String(u.metric) === metric)
// 整个指标推演不了(口径卡没记输入、用到了遮罩列、有输入还原不了):只说原因,不画输入、不写「无变化」
const whole = wholeReason(data, metric)
const unknown = !!m && m.rendered_new == null
const changedSegs = (data?.segments ?? []).filter((s) => s.changed)
const adjustable = !!m?.inputs.some((i) => i.editable || i.row_span)
const summary = <WhatIfSummary view={view} metric={metric} onBack={() => focusResult(id)} />
return (
<section id={id} tabIndex={-1} className="mt-2 space-y-2.5 rounded border p-2 focus:outline-none" data-whatif=""
aria-label={WHATIF_TEXT.title} style={{ borderColor: 'color-mix(in srgb, var(--st-waiting) 45%, var(--border))' }}>
{/* 醒目靠底色、左边的色条和图标;字用正文色:提醒色的字压在同色的浅底上,浅色主题下对比度不到 4.5 */}
<p role="note" className="flex items-start gap-1.5 rounded-r px-2 py-1.5 font-medium leading-snug" data-whatif-banner=""
style={{ color: 'var(--text)', background: 'var(--st-waiting-soft)', borderLeft: '3px solid var(--st-waiting)' }}>
<FlaskConical size={13} className="mt-px shrink-0" style={{ color: 'var(--st-waiting)' }} aria-hidden />
<span>{WHATIF_TEXT.banner}</span>
</p>
{data && !data.sealed && (
<p className="text-2xs" style={{ color: 'var(--st-waiting)' }} data-whatif-unsealed={data.seal.sealed ? 'broken' : 'open'}>
{data.seal.sealed && data.seal.ok === false ? WHATIF_TEXT.sealBroken : WHATIF_TEXT.unsealed}
</p>
)}
{failed && <ErrorNotice error={view.error} onRetry={view.retry} />}
{!data && loading && (
<p className="flex items-center gap-1.5 text-dim" data-whatif-loading=""><Spinner size={12} /> {WHATIF_TEXT.loading}</p>
)}
{m && !failed && (
// 「回到推演结果」把焦点送到这里:描边由 focusResult 设的 data-flash 画(静态描边,减少动效时照样看得见)
<div id={`${id}-result`} tabIndex={-1} aria-live="polite" aria-busy={loading || undefined}
className={clsx('rounded-sm transition-opacity focus:outline-none data-[flash]:outline data-[flash]:outline-2 data-[flash]:outline-offset-2 data-[flash=focus]:outline-[color:var(--accent)]',
loading && 'opacity-60')}
data-whatif-result={loading ? 'loading' : whole ? 'whole' : m.status}>
<div className="mb-0.5 text-2xs font-medium text-faint">{WHATIF_TEXT.result}</div>
{whole ? (
<>
<span className="mono tnum text-dim" data-whatif-old="">{m.rendered_old}</span>
<p className="mt-0.5 [overflow-wrap:anywhere]" style={{ color: 'var(--st-waiting)' }} data-whatif-reason="">{whole}</p>
</>
) : (
<>
<Outcome m={m} loading={loading} big tag="whatif" />
{m.reason && (
<p className="mt-0.5 [overflow-wrap:anywhere]" style={{ color: 'var(--st-waiting)' }} data-whatif-reason="">{m.reason}</p>
)}
{m.status === 'ok' && m.changed && m.substituted && (
<div className="mt-1">
<div className="text-2xs text-faint">{WHATIF_TEXT.substituted}</div>
<code className="mono block whitespace-pre-wrap break-all rounded bg-bg px-1.5 py-1 text-2xs" data-whatif-substituted="">
{m.substituted}
</code>
</div>
)}
</>
)}
</div>
)}
{m && !whole && (
<div data-whatif-inputs="">
<div className="mb-1 text-2xs font-medium text-faint">{WHATIF_TEXT.inputs}</div>
{m.inputs.length ? (
<>
<ul className="space-y-1.5">
{m.inputs.map((inp, i) => (
<InputRow key={inp.path} id={`${id}-in${i}`} runId={runId} input={inp} draft={draft}
link={queryOf(inp.artifact)} status={status} summary={summary} />
))}
</ul>
{!adjustable && <p className="mt-1 text-2xs text-dim" data-whatif-nothing="">{WHATIF_TEXT.nothingToAdjust}</p>}
</>
) : <p className="text-dim" data-whatif-empty="">{WHATIF_TEXT.empty}</p>}
</div>
)}
{!whole && unsupported.length > 0 && (
<div data-whatif-unsupported="">
<div className="mb-0.5 text-2xs font-medium text-faint">{WHATIF_TEXT.unsupported}</div>
<ul className="space-y-0.5">
{unsupported.map((u) => (
<li key={u.input ?? ''} className="[overflow-wrap:anywhere]" data-whatif-unsupported-input={u.input ?? ''}>
<span className="mono">{u.input ?? WHATIF_TEXT.wholeMetric}</span>
<span className="text-dim">:{u.reason}</span>
</li>
))}
</ul>
</div>
)}
{m && !whole && !failed && !!data?.segments.length && (
<div aria-busy={loading || undefined} className={clsx('transition-opacity', loading && 'opacity-60')}
data-whatif-segments={loading ? 'loading' : ''}>
<div className="mb-0.5 text-2xs font-medium text-faint">{WHATIF_TEXT.segments}</div>
{unknown ? <p className="text-dim">{WHATIF_TEXT.segmentsUnknown}</p>
: changedSegs.length ? (
<ul className="space-y-0.5">
{changedSegs.map((s) => (
<li key={`${s.report}-${s.sid}`} className="flex flex-wrap items-center gap-x-1.5" data-whatif-segment={s.sid}>
<span className="mono tnum text-dim">{s.rendered_old}</span>
<span className="text-faint" aria-hidden>→</span>
<span className="mono tnum font-semibold">{s.rendered_new}</span>
{onLocate && (!report || s.report === report)
? (
<button type="button" className="btn btn-xs btn-ghost" onClick={() => onLocate(s.sid)}
data-whatif-locate={s.sid}>
<LocateFixed size={10} aria-hidden /> {WHATIF_TEXT.locate}
</button>
)
: <span className="text-2xs text-faint">{WHATIF_TEXT.inReport(s.report)}</span>}
</li>
))}
</ul>
) : <p className="text-dim" data-whatif-segments-none="">{WHATIF_TEXT.segmentsNone(data.segments.length)}</p>}
</div>
)}
{!whole && !failed && !!data?.affected_cards.length && (
<div aria-busy={loading || undefined} className={clsx('transition-opacity', loading && 'opacity-60')}
data-whatif-affected={loading ? 'loading' : ''}>
<div className="text-2xs font-medium text-faint">{WHATIF_TEXT.affected}</div>
<p className="mb-0.5 text-2xs text-faint">{WHATIF_TEXT.affectedHint}</p>
<ul className="space-y-0.5">
{data.affected_cards.map((c) => (
<li key={c.node_id} data-whatif-affected-card={c.node_id}>
{WHATIF_TEXT.affectedCard(c.caliber, c.version)}
{!c.direct && <span className="text-faint"> · {WHATIF_TEXT.indirect}</span>}
</li>
))}
</ul>
</div>
)}
<div className="flex items-center gap-2 border-t pt-2">
<button type="button" className="btn btn-xs" onClick={draft.reset} disabled={!draft.dirty} data-whatif-reset="">
<RotateCcw size={11} aria-hidden /> {WHATIF_TEXT.reset}
</button>
{loading && data && <span className="flex items-center gap-1 text-2xs text-faint"><Spinner size={11} /> {WHATIF_TEXT.loading}</span>}
</div>
</section>
)
}
/**
* 一个输入:能改的给输入框(原值写在旁边),别的照实显示;排除了几行、去哪勾行,写在下面。
* 随改动变的新值、排除标记来自答复:这次改动的答复还没回来时(loading)是上一次的,变淡;请求失败了(error)不显示
*/
function InputRow({ id, runId, input, draft, link, status, summary }: {
id: string; runId: string; input: WhatIfInput; draft: WhatIfDraft; link?: { alias: string; go: () => void }
status: WhatIfView['status']; summary: ReactNode
}) {
const shown = status !== 'error'
const dim = status === 'loading' ? 'opacity-60' : undefined
const [picking, setPicking] = useState(false)
const raw = draft.text[input.path]
const committed = draft.overrides.inputs[input.path]
const baseline = committed !== undefined ? String(committed) : plain(input.old)
const invalid = raw !== undefined && parseNumber(raw) === null
const onKeyDown = (e: ReactKeyboardEvent<HTMLInputElement>) => {
if (isComposing(e)) return
if (e.key === 'Enter') {
e.preventDefault()
draft.commit()
} else if (e.key === 'Escape' && raw !== undefined && raw !== baseline) {
// 改了一半的值先退回去:这一下 Esc 不关面板
e.preventDefault()
e.stopPropagation()
draft.revert(input.path)
}
}
const span = input.masked ? undefined : input.row_span
// 只用到快照里一行的(单元格取数、Agent 的单格字段)去查询步骤里勾:那儿有前后几行可对照;整份结果、数组字段
// 用到一大段行,查询步骤只给前后几行,在这里按页勾全;单行却没有查询步骤可去的,也在这里勾
const single = !!span && span[0] === span[1]
const pickInQuery = !!link && single && input.kind !== 'container'
const pickHere = !!span && !pickInQuery
return (
<li className="rounded border px-2 py-1.5" data-whatif-input={input.path} data-whatif-kind={input.kind}
style={input.changed && shown ? { borderColor: 'color-mix(in srgb, var(--accent) 55%, var(--border))' } : undefined}>
<div className="mono truncate text-2xs text-dim" title={input.path}>{input.path}</div>
{input.masked ? (
<p className="mt-0.5 italic text-faint" data-whatif-masked="">{WHATIF_TEXT.masked}</p>
) : input.withheld ? (
<p className="mt-0.5 italic text-faint" data-whatif-withheld="">{WHATIF_TEXT.withheld}</p>
) : input.editable ? (
<div className="mt-1 flex flex-wrap items-center gap-x-2 gap-y-1">
<input id={id} type="text" inputMode="decimal" autoComplete="off" spellCheck={false}
className={clsx('field mono tnum w-36 min-w-0 py-1', invalid && 'border-[var(--err)]')}
value={raw ?? plain(input.old)} placeholder={input.old == null ? NONE : undefined}
aria-label={WHATIF_TEXT.inputLabel(input.path)} aria-invalid={invalid || undefined}
aria-describedby={invalid ? `${id}-err` : undefined}
onChange={(e) => draft.type(input.path, e.target.value, input.old)}
onKeyDown={onKeyDown} onBlur={draft.commit} data-whatif-field="" />
<span className="tnum text-2xs text-faint">{WHATIF_TEXT.original(valueText(input.old))}</span>
{invalid && <span id={`${id}-err`} className="text-2xs" style={{ color: 'var(--err)' }}>{WHATIF_TEXT.notNumber}</span>}
</div>
) : (
<p className="mono tnum mt-0.5 [overflow-wrap:anywhere]" data-whatif-value="">
{valueText(input.old)}
{input.changed && shown && (
<span className={dim}> <span className="text-faint" aria-hidden>→</span> {valueText(input.new)}</span>
)}
</p>
)}
{!!input.excluded_rows?.length && shown && (
<p className={clsx('mt-0.5 text-2xs', dim)} style={{ color: 'var(--st-waiting)' }} data-whatif-excluded="">
{WHATIF_TEXT.excludedRows(input.excluded_rows)}
</p>
)}
{pickInQuery && (
<button type="button" className="btn btn-xs btn-ghost -ml-1 mt-0.5" onClick={link!.go} data-whatif-pick="">
<CornerDownRight size={10} aria-hidden /> {WHATIF_TEXT.pickRows(link!.alias)}
</button>
)}
{pickHere && input.artifact && span && (
<>
<button type="button" className="btn btn-xs btn-ghost -ml-1 mt-0.5" aria-expanded={picking}
onClick={() => setPicking((v) => !v)} data-whatif-pick-here={picking ? 'open' : 'closed'}>
<ListChecks size={10} aria-hidden /> {picking ? WHATIF_TEXT.pickHereClose : WHATIF_TEXT.pickHere(span[1] - span[0] + 1)}
</button>
{picking && (
<SnapshotRows key={`${input.artifact}:${span[0]}:${span[1]}`} runId={runId} artifact={input.artifact} span={span}
excluded={draft.excluded(input.artifact)} onToggle={(row) => draft.toggleRow(input.artifact!, row)}
summary={summary} busy={status === 'loading'} />
)}
</>
)}
</li>
)
}
type Loaded = { status: 'loading' | 'ok' | 'error'; page?: WhatIfRowsPage; rows: unknown[][]; index: number[]; error?: unknown }
/**
* 推演区里的勾行表格:按页取这份快照里输入用到的那一段行(整份结果是全部,数组字段是它那一段),遮罩列写「已遮罩」。
* 查询步骤只给被引用的行前后几行,整份结果作输入时大多数行勾不到,所以这里另取
*/
function SnapshotRows({ runId, artifact, span, excluded, onToggle, summary, busy }: {
runId: string; artifact: string; span: [number, number]; excluded: number[]; onToggle: (row: number) => void
summary: ReactNode; busy: boolean
}) {
const [first, last] = span
const [loaded, setLoaded] = useState<Loaded>({ status: 'loading', rows: [], index: [] })
const [offset, setOffset] = useState(first)
const [nonce, setNonce] = useState(0)
useEffect(() => {
const ctrl = new AbortController()
setLoaded((s) => ({ ...s, status: 'loading' }))
api.whatif.rows(runId, artifact, { offset, limit: Math.min(ROWS_PAGE, last - offset + 1) }, { signal: ctrl.signal })
.then((page) => setLoaded((s) => {
// 只留输入用到的那一段(数组字段的行段后面可能还有别的行),已经有的不重复接
const have = new Set(s.index)
const keep = page.row_index.map((r, i) => [r, i] as const).filter(([r]) => r >= first && r <= last && !have.has(r))
return { status: 'ok', page, rows: [...s.rows, ...keep.map(([, i]) => page.rows[i])], index: [...s.index, ...keep.map(([r]) => r)] }
}), (error: unknown) => {
if ((error as { name?: string } | null)?.name === 'AbortError') return
setLoaded((s) => ({ ...s, status: 'error', error }))
})
return () => ctrl.abort()
}, [runId, artifact, offset, first, last, nonce])
const page = loaded.page
const win = useMemo(() => queryWindow({
rows: loaded.rows, columns: page?.columns ?? [], row_index: loaded.index, row_offset: loaded.index[0] ?? first,
total_rows: page?.total_rows ?? null,
} as Pick<EvidenceStep, 'rows' | 'columns' | 'row_offset' | 'row_index' | 'total_rows' | 'highlight'>), [loaded.rows, loaded.index, page, first])
const next = (loaded.index.at(-1) ?? first - 1) + 1
const remaining = Math.max(0, last - next + 1)
return (
<div className="mt-1 space-y-1" data-whatif-snapshot={artifact}>
{loaded.status === 'error' && <ErrorNotice error={loaded.error} onRetry={() => setNonce((n) => n + 1)} />}
{page?.note && <p className="text-2xs text-dim" data-whatif-snapshot-note="">{page.note}</p>}
{!page && loaded.status === 'loading' && (
<p className="flex items-center gap-1.5 text-2xs text-dim"><Spinner size={11} /> {WHATIF_TEXT.rowsLoading}</p>
)}
{win.rows.length > 0 && (
<WhatIfRows win={win} hidden={page?.masked ?? []} excluded={excluded} onToggle={onToggle}
usable={(row) => row >= first && row <= last} summary={summary} busy={busy} />
)}
{win.rows.length > 0 && (
<div className="flex flex-wrap items-center gap-x-2 text-2xs text-faint">
<span data-whatif-snapshot-range="">
{WHATIF_TEXT.rowsRange(formatNumber(first + 1), formatNumber(next), formatNumber(page?.total_rows ?? last + 1))}
</span>
{remaining > 0 && (
<button type="button" className="btn btn-xs btn-ghost" disabled={loaded.status === 'loading'}
onClick={() => setOffset(next)} data-whatif-snapshot-more="">
{loaded.status === 'loading' ? <Spinner size={10} /> : null} {WHATIF_TEXT.rowsMore(Math.min(ROWS_PAGE, remaining))}
</button>
)}
</div>
)}
</div>
)
}
/**
* 勾行的表格:每行前面一个勾选框,勾掉的行在推演里视为不存在(划掉、变淡)。只有知道每一行在快照里是第几行时才画
* (index);被遮罩的列照样写「已遮罩」,高亮的格和平时一样描边。usable 说哪几行这个指标用得到:别的行勾了也不影响
* 结果,勾选框禁用并说明(已经勾上的照样能取消);答复还没回来、不知道时一律先不让勾。
*
* summary(推演结果)连同说明画在表格底下:推演区在上面,勾完行它往往不在视野里。勾了一行就把底下这条带进视野
* (已经看得见就不动),答复回来时(busy 转为假)再带一次:上面的内容(原因、下游口径卡)这时会变高,把表格往下挤。
* 不做成贴底的浮条:表格靠近视野底边时浮条会盖住刚勾的那一行
*/
export function WhatIfRows({ win, hidden, excluded, onToggle, usable, summary, busy = false }: {
win: ReturnType<typeof queryWindow>; hidden: string[]; excluded: number[]; onToggle: (row: number) => void
usable?: (row: number) => boolean
summary?: ReactNode
/** 推演请求还在路上 */
busy?: boolean
}) {
const foot = useRef<HTMLDivElement>(null)
const reveal = useRef(false)
useEffect(() => {
if (!reveal.current || busy) return
reveal.current = false
foot.current?.scrollIntoView({ block: 'nearest' })
})
if (!win.index) return null
const index = win.index
const masked = new Set(hidden)
const cells = win.cells ? new Set(win.cells.map(([r, c]) => `${r}\u0000${c}`)) : null
const marked = new Set([...win.marks, ...(win.cells ?? []).map(([r]) => r)])
const cols = new Set(win.cols)
return (
<div className="overflow-hidden rounded border" data-whatif-rows="">
<div className="overflow-x-auto">
<table className="w-full text-2xs">
<thead>
<tr className="border-b bg-elev">
{/* 勾选框和行号两列只占自己的宽度:表格撑满窄栏时多出来的宽度留给数据列 */}
<th className="w-px whitespace-nowrap px-1.5 py-1 text-left font-medium text-dim">{WHATIF_TEXT.excludeHead}</th>
<th className="mono w-px px-1.5 py-1 text-right font-medium text-dim">#</th>
{win.columns.map((c) => <th key={c} className="mono px-1.5 py-1 text-left font-medium text-dim">{c}</th>)}
</tr>
</thead>
<tbody>
{win.rows.map((row, i) => {
const n = index[i]
const off = excluded.includes(n)
const hit = marked.has(i)
const open = off || (usable ? usable(n) : false)
return (
<tr key={n} className="border-b last:border-0" data-whatif-row={n} data-excluded={off ? '' : undefined}
data-whatif-row-unused={open ? undefined : ''}
style={hit && !off ? { background: 'var(--st-done-soft)' } : undefined}>
<td className="w-px px-1.5 py-1 text-center"
title={open ? undefined : usable ? WHATIF_TEXT.rowUnused : WHATIF_TEXT.rowsPending}>
<input type="checkbox" className="align-middle disabled:cursor-not-allowed disabled:opacity-40"
checked={off} disabled={!open}
onChange={() => {
onToggle(n)
// 勾完把底下的推演结果带进视野(已经看得见就不动):从输入那儿跳过来时表格常在视野边上。
// 答复回来后再带一次(上面的 effect)
reveal.current = true
requestAnimationFrame(() => foot.current?.scrollIntoView({ block: 'nearest' }))
}}
aria-label={WHATIF_TEXT.excludeRow(n)} />
</td>
<td className={clsx('mono w-px px-1.5 py-1 text-right', open ? 'text-faint' : 'text-faint opacity-60')}>{n + 1}</td>
{row.map((cell, j) => {
const col = win.columns[j]
const mark = hit && !off && (cells ? cells.has(`${i}\u0000${col}`) : cols.has(col))
const mask = masked.has(col)
return (
<td key={j} className={clsx('mono max-w-[160px] truncate px-1.5 py-1',
off ? 'text-faint line-through' : mark ? 'font-semibold' : 'text-dim')}
data-highlight={mark ? 'cell' : undefined} data-masked={mask ? '' : undefined}
style={mark ? { outline: '1px solid var(--st-done)', outlineOffset: -1, color: 'var(--text)' } : undefined}
title={mask ? WHATIF_TEXT.masked : cell == null ? '' : String(cell)}>
{mask ? <span className="font-sans italic text-faint">{WHATIF_TEXT.masked}</span>
: cell == null ? <span className="opacity-40">null</span>
: typeof cell === 'object' ? JSON.stringify(cell) : String(cell)}
</td>
)
})}
</tr>
)
})}
</tbody>
</table>
</div>
<div ref={foot} data-whatif-rows-foot="">
<div className="flex flex-wrap items-center gap-x-2 border-t px-1.5 py-1 text-2xs text-faint">
<span>{WHATIF_TEXT.rowsHint}</span>
{excluded.length > 0 && (
<span style={{ color: 'var(--st-waiting)' }} data-whatif-excluded-count="">{WHATIF_TEXT.excludedCount(excluded.length)}</span>
)}
</div>
{summary}
</div>
</div>
)
}
+147
View File
@@ -3020,3 +3020,150 @@ export interface SqlCheckItem {
relation_id?: string
sql_excerpt?: string
}
// ===========================================================================
// 数字推演(后端 app/api/whatif.py、app/engine/recompute.py):在一次运行的口径卡上改输入、排除查询快照里的行,
// 看指标和报告里引用它的地方会变成多少。推演不是出具:不写运行记录、不改报告
// ===========================================================================
/** 推演的改动:输入路径 → 新值;查询快照的工件 id → 要排除的行号(快照里的行号,从 0 数) */
export interface WhatIfOverrides {
inputs: Record<string, number>
exclude_rows: Record<string, number[]>
}
/** POST /runs/{id}/evidence/whatif 的请求体 */
export interface WhatIfRequest {
/** 报告撰写节点 id:只列这份报告里引用的地方 */
report?: string
/** 口径卡节点 id */
card: string
/** 只推演这一个指标 */
metric?: string
overrides: WhatIfOverrides
}
/** 一个输入在推演里的样子 */
export interface WhatIfInput {
path: string
via?: string | null
node_id?: string | null
/** 落在哪份查询快照上(cell() 取的格、agent 字段、整份查询结果):排除这份快照里的行会影响它 */
artifact?: string
locator?: EvidenceLocator
kind: 'number' | 'text' | 'bool' | 'missing' | 'container' | (string & {})
/** 数值(或原本缺失)的标量、不是遮罩列、不决定取哪一格、还原得出:可以改。整个指标推演不了时一律为 false */
editable: boolean
/** 原值、推演用的值。容器写大概(「[12 项]」);遮罩列的一律是 null */
old?: unknown
new?: unknown
changed?: boolean
/** 起了作用的被排除行(快照里的行号,从 0 数) */
excluded_rows?: number[]
/**
* 这个输入实际用到的快照行(含两端,从 0 数):单格一行、数组字段一段、整份查询结果全部。排除别的行影响不到它,
* 界面只让这几行可勾。遮罩的、还原不了的(完整值找不回来、快照读不出来)没有,决定取哪一格的数组字段、整份结果
* 也没有(少了几行,取到哪一格说不准),整个指标推演不了时一律没有
*/
row_span?: [number, number]
masked?: boolean
/** 落在的查询快照读不出来(文件不在、与哈希不一致):遮没遮核对不了,值不给 */
withheld?: boolean
}
/**
* unchanged:没碰到改动,原值原样交回;ok:重算了;excluded:排除行后缺了输入,算不出来;error:新值让计算出错(除以零……);
* unsupported:推演不了(有输入还原不了、口径卡没记输入,或者排除行后说不准受不受影响);masked:用到了遮罩列,
* 不推演。整个指标推演不了的不改动也是 unsupported / masked(unsupported 里另有一条 input 为空的)
*/
export type WhatIfStatus = 'unchanged' | 'ok' | 'excluded' | 'error' | 'unsupported' | 'masked'
export interface WhatIfMetric {
id: string
name: string
unit: string
decimals?: number | null
format?: string
old: unknown
new: unknown
delta: number | null
/** 按口径卡的格式渲染(和报告里的字同一套规则) */
rendered_old: string
/** unsupported、masked 时为 null:不知道会变成什么 */
rendered_new: string | null
/** 带正负号;比率、百分数写「个百分点」。没变化、不是数时为 null */
rendered_delta: string | null
changed: boolean | null
status: WhatIfStatus | (string & {})
reason: string | null
/** 推演用的代入式(重算了才有;没碰到改动的是卡上原来的代入式) */
substituted: string | null
inputs: WhatIfInput[]
}
/** 报告里引用这个指标的一处,推演之后会写成什么 */
export interface WhatIfSegment {
report: string
unit: string
sid: string
metric: string
rendered_old: string
rendered_new: string | null
changed: boolean | null
}
export interface WhatIfUnsupported {
metric: string
/**
* null:整个指标都推演不了(口径卡没记输入、用到了遮罩列、有输入还原不了或所在的快照读不出来),reason 和指标上的
* 一样。不论改什么都推演不了,不改动也有这一条;界面据此只写原因,不画输入框、勾选框
*/
input: string | null
reason: string
}
/** 引用了这张口径卡的下游口径卡:只标可能受影响,不重算 */
export interface WhatIfAffectedCard {
node_id: string
artifact: string
caliber: string
version: string
metrics: string[]
/** 直接引用(false 是经别的卡间接引用) */
direct: boolean
}
/**
* GET /runs/{id}/evidence/whatif/rows:一页查询快照的行(推演时勾行用),形状和证据面板的查询步骤一致,
* 可以直接交给 queryWindow。遮罩列写「已遮罩」;快照读不出来时没有行,note 说明原因
*/
export interface WhatIfRowsPage {
run_id: string
artifact: string
node_id?: string | null
tool?: string | null
source?: string | null
columns: string[]
rows: unknown[][]
row_offset: number
row_index: number[]
total_rows: number | null
truncated: boolean | null
masked: string[]
hash_ok: boolean | null
sealed: boolean
note?: string
}
export interface WhatIfResult {
run_id: string
card: { node_id: string; artifact: string; caliber: string; version: string }
report: string | null
/** 运行已封存且封存核对一致:推演依据的数据不会再变 */
sealed: boolean
seal: { sealed: boolean; ok: boolean | null }
metrics: WhatIfMetric[]
segments: WhatIfSegment[]
unsupported: WhatIfUnsupported[]
affected_cards: WhatIfAffectedCard[]
}
+1 -1
View File
@@ -96,7 +96,7 @@ const ESTIMATE = {
stream: 173, chat: 160, studio: 149, manage: 145, runs: 112, publish: 92, shell: 87,
evidence: 91, versions: 60, catalog: 45, 'ui-kit': 70, ui: 61, guards: 8, 'canvas-layout': 2, copy: 2, tokens: 1, trace: 1, decode: 1,
// 占位,换成真检查时按实测改
schedules: 1, compare: 1, verify: 1, inquiry: 1, bundle: 16, whatif: 1,
schedules: 1, compare: 1, verify: 1, inquiry: 1, bundle: 16, whatif: 33,
}
// 最慢的两项按段拆成几份。用的是它们自己的段过滤:最后一份用 *_SKIP 兜住「其余全部」,以后新加的段
// 不用改这里也跑得到(拆出去的那几份要是一段都没对上,那一份会报「一项都没跑」)。
+763 -6
View File
@@ -1,8 +1,765 @@
// 数字推演的检查。现在只是占位:功能还在开发,这里只打一行通过,让 check-all 的清单先排上它。
// 数字推演的工作包把它换成真检查:沿用别的检查的输出格式——每项缩进两格、以 ✓ / ✗ 开头,最后顶格一行
// 总结,没过的退出码非 0(check-all 按缩进的 ✓ / ✗ 计数)。
// 数字推演(证据面板里口径卡上的数,run/WhatIf.tsx)的回归检查。
//
// 守的是这些「看着没坏、其实用不了」的地方:横幅没了或者不醒目(推演被当成出具)、边打字边发请求、请求体里的
// 输入路径和行号不对(行号对人从 1 数,对接口从 0 数)、勾选框在不推演时也冒出来、恢复原值之后还留着一行没勾回去、
// 不支持的输入一声不吭、窄屏(390px)被推演区撑出横向滚动、浅色主题下横幅看不清。还有复核第 1 轮查出来的:整份
// 结果作输入时无行可勾、窗口里勾了不起作用的行也给勾、勾完行结果不在视野里、加载中和失败后还摆着上一次的答复、
// 封存核对没过不说、整个指标推演不了时又写「无可推演」又写「无变化」。复核第 2 轮:用到了遮罩列、有输入还原不了的
// 指标一打开仍写「无变化」,还给可改的输入框和可勾的行(改了、勾了才说推演不了)。
//
// 跑在预览页上:/preview.html?syn=whatif(宽屏右侧弹出、窄屏底部抽出)和 ?syn=whatif-rail(360px 画布右栏)。
// 文档是 frontend/src/run/__tests__/evidence-query.json 里后端 compose_doc 真跑出来的(只用通用名);片段接口
// 按它的 segments 作答(s18 改成整份结果作输入),推演接口按后端 engine/recompute.py 的规则在这里算(只覆盖用到的
// 几个指标),勾行接口按夹具里 Q3 的快照作答,别的非 GET 一律拦掉。
//
// node scripts/check-whatif.mjs
console.log('=== 数字推演 ===')
console.log(' ✓ 占位:功能开发中')
console.log('\n✓ 数字推演:占位通过')
// 对别的实例跑时带上地址:AGENTLAB_WEB=http://localhost:<前端端口> node scripts/check-whatif.mjs
// WHATIF_SHOTS=<目录> 时亮暗两套各截几张,供人眼复核。
import { mkdirSync, readFileSync } from 'node:fs'
import { chromium } from '../frontend/node_modules/playwright-core/index.mjs'
const WEB = process.env.AGENTLAB_WEB ?? 'http://localhost:5273'
const CHROME = process.env.CHROME_PATH ?? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
const SHOTS = process.env.WHATIF_SHOTS ?? ''
const root = new URL('..', import.meta.url).pathname
const fx = JSON.parse(readFileSync(`${root}frontend/src/run/__tests__/evidence-query.json`, 'utf8'))
const RUN = fx.run_id
const BANNER = '推演,非出具:不会写进运行记录,也不会改动报告'
let failed = 0
const check = (name, cond, detail = '') => {
console.log(` ${cond ? '✓' : '✗'} ${name}${detail ? ` — ${detail}` : ''}`)
if (!cond) failed++
}
async function section(name, fn) {
console.log(`\n=== ${name} ===`)
try {
await fn()
} catch (e) {
check(`${name} 中途出错`, false, String(e?.message ?? e).split('\n')[0])
}
}
// ---------------------------------------------------------------- 夹具
/**
* 片段接口的答复:夹具里的原样,几处改成推演要用到的样子(推演接口的假答复和这里对得上):
* - s22:老运行的容器输入(没存完整值)乘一个本来能改的数,整个指标推演不了
* - s10:Q1 的 gmv 列设了遮罩,整个指标推演不了
* - s8:订单数按文本条件取(文本输入不能改),订单数本身能改
* - s6:销售额是一个加工过的列表求和(对不上任何快照),没有能改的输入、也没有能勾的行
* - s18:整份查询结果作输入(len(vars.orders.rows)):证据链里没有它的查询步骤,和后端真跑出来的一样
*/
function segmentReply(sid) {
const body = structuredClone(fx.segments[sid])
if (sid === 's22') {
body.chain[0] = { ...body.chain[0], expression: 'sum(vars.adjust.items) * vars.adjust.k',
substituted: 'sum(vars.adjust.items) * 1' }
body.chain[1] = { step: 'input', path: 'vars.adjust.items', value: '[4 项]', node_id: 'adjust', via: 'code',
field: 'items', role: 'compute', status: 'ok' }
body.chain.push({ step: 'input', path: 'vars.adjust.k', value: 1, node_id: 'adjust', via: 'code', field: 'k',
role: 'compute', status: 'ok' })
}
if (sid === 's10') body.chain = body.chain.map((s) => (s.step === 'query' ? { ...s, masked: ['gmv'] } : s))
if (sid === 's8') {
body.chain[0] = { ...body.chain[0], expression: "vars.kpi.order_cnt if vars.kpi.region == '华东' else 0",
substituted: "1234 if '华东' == '华东' else 0" }
body.chain.splice(2, 0, { step: 'input', path: 'vars.kpi.region', value: '华东', node_id: 'parse', via: 'transform',
field: 'region', status: 'ok' })
}
if (sid === 's6') {
body.chain = [
{ ...body.chain[0], expression: 'sum(vars.kpi.daily)', substituted: 'sum(vars.kpi.daily)' },
{ step: 'input', path: 'vars.kpi.daily', value: '[7 项]', node_id: 'daily', via: 'transform', field: 'daily', status: 'ok' },
]
}
if (sid === 's18') {
body.chain = [
{ ...body.chain[0], name: '订单笔数', expression: 'len(vars.orders.rows)', substituted: 'len(vars.orders.rows)',
value: 12, rendered: '12单', unit: '单', decimals: null, status: 'ok', recompute_ok: true },
{ step: 'input', path: 'vars.orders.rows', value: '[12 项]', node_id: 'parse', via: 'transform', field: 'rows', status: 'ok' },
]
}
return body
}
const chainOf = (sid) => fx.segments[sid].chain
const inputsOf = (sid) => chainOf(sid).filter((s) => s.step === 'input')
const Q1 = chainOf('s12')[1].artifact
const Q4 = chainOf('s12')[2].artifact
const Q3 = inputsOf('s70')[0].artifact
const SNAP = fx.snapshots.Q3.content
const thousands1 = (v) => v.toLocaleString('en-US', { minimumFractionDigits: 1, maximumFractionDigits: 1 })
const NO_LINEAGE = '这个指标生成于系统升级前,口径卡没有记录输入,不能推演'
const MASKED_METRIC = '这个指标用到了设置了遮罩的列,不能推演'
const LOST = '无法推演:vars.adjust.items(当时没有保存这个输入的完整值)'
/** 整个指标推演不了时后端给的样子:不改动也是 unsupported / masked,新值、变化一概为空 */
const blocked = (status, reason) => ({ new: null, delta: null, rendered_new: null, rendered_delta: null, changed: null,
status, reason, substituted: null })
const AFFECTED = [{ node_id: 'yearly', artifact: 'b1'.repeat(32), caliber: '年报口径', version: 'v1', metrics: ['y'], direct: false }]
/** 推演接口在这里按后端的规则算:给了新值的用新值;cell / agent 字段那一格所在的行被排除了,指标排除后无法计算 */
const METRICS = {
wow: {
sid: 's12', name: '环比增幅', unit: '%', calc: ([g, p]) => Math.round((g - p) / p * 1000) / 10,
render: (v) => `${v.toFixed(1)}%`, delta: (d) => `${d > 0 ? '+' : '-'}${Math.abs(d).toFixed(1)} 个百分点`,
},
spread: {
sid: 's70', name: '首末单差额', unit: '元', calc: ([t, l]) => Math.round((t - l) * 10) / 10,
render: (v) => `${thousands1(v)}元`, delta: (d) => `${d > 0 ? '+' : '-'}${thousands1(Math.abs(d))}元`,
},
}
function whatifReply(body) {
const overrides = body?.overrides ?? {}
const inputs = overrides.inputs ?? {}
const exclude = overrides.exclude_rows ?? {}
const base = { run_id: RUN, card: { node_id: 'caliber', artifact: chainOf('s12')[0].artifact, caliber: '周报口径', version: 'v3' },
report: body?.report ?? null, sealed: true, seal: { sealed: true, ok: true }, affected_cards: [] }
const changed = Object.keys(inputs).length > 0 || Object.keys(exclude).length > 0
if (body?.metric === 'new_users') {
// 整份查询结果作输入:行数就是指标,勾掉几行少几单
const gone = exclude[Q3] ?? []
const value = SNAP.rows.length - gone.length
return { ...base, affected_cards: gone.length ? AFFECTED : [],
metrics: [{ id: 'new_users', name: '订单笔数', unit: '单', old: 12, new: value, delta: value - 12,
rendered_old: '12单', rendered_new: `${value}单`, rendered_delta: gone.length ? `-${gone.length}单` : null,
changed: gone.length > 0, status: gone.length ? 'ok' : 'unchanged', reason: null,
substituted: 'len(vars.orders.rows)',
inputs: [{ path: 'vars.orders.rows', via: 'transform', node_id: 'parse', artifact: Q3, row_span: [0, 11],
kind: 'container', editable: false, old: '[12 项]', new: `[${value} 项]`, changed: gone.length > 0,
...(gone.length ? { excluded_rows: gone } : {}) }] }],
segments: [{ report: 'write', unit: fx.segments.s18.unit.id, sid: 's18', metric: 'new_users', rendered_old: '12单',
rendered_new: `${value}单`, changed: gone.length > 0 }],
unsupported: [] }
}
if (body?.metric === 'refund_rate') {
// 升级前的口径卡:没记输入,整个指标推演不了
return { ...base, metrics: [{ id: 'refund_rate', name: '退款率', unit: '', old: 0.0235, rendered_old: '2.35%',
...blocked('unsupported', NO_LINEAGE), inputs: [] }],
segments: [{ report: 'write', unit: fx.segments.s16.unit.id, sid: 's16', metric: 'refund_rate', rendered_old: '2.35%',
rendered_new: null, changed: null }],
unsupported: [{ metric: 'refund_rate', input: null, reason: NO_LINEAGE }] }
}
if (body?.metric === 'adj') {
// 老运行:容器没存完整值。乘的那个数本来能改,指标整个推演不了,也就不让改
return { ...base, metrics: [{ id: 'adj', name: '调整后销售额', unit: '元', old: 44000, rendered_old: '44,000.0元',
...blocked('unsupported', LOST),
inputs: [{ path: 'vars.adjust.items', via: 'code', node_id: 'adjust', kind: 'container', editable: false,
old: '[4 项]', new: null, changed: false },
{ path: 'vars.adjust.k', via: 'code', node_id: 'adjust', kind: 'number', editable: false, old: 1, new: 1, changed: false }] }],
segments: [{ report: 'write', unit: fx.segments.s22.unit.id, sid: 's22', metric: 'adj', rendered_old: '44,000.0元',
rendered_new: null, changed: null }],
unsupported: [{ metric: 'adj', input: null, reason: LOST },
{ metric: 'adj', input: 'vars.adjust.items', reason: '无法推演:当时没有保存这个输入的完整值' }] }
}
if (body?.metric === 'aov') {
// gmv 列设了遮罩:那一格不给值;订单数本来能改、它那一行本来能勾,指标整个推演不了,一样不让动
const cell = (path, column) => ({ path, via: 'agent_field', node_id: 'fetch', artifact: Q1, locator: { row: 0, column } })
return { ...base, metrics: [{ id: 'aov', name: '客单价', unit: '元', old: 37.0, rendered_old: '37.0元',
...blocked('masked', MASKED_METRIC),
inputs: [{ ...cell('vars.kpi.gmv', 'gmv'), kind: 'number', editable: false, old: null, new: null, changed: false, masked: true },
{ ...cell('vars.kpi.order_cnt', 'order_cnt'), kind: 'number', editable: false, old: 1234, new: 1234, changed: false }] }],
segments: [{ report: 'write', unit: fx.segments.s10.unit.id, sid: 's10', metric: 'aov', rendered_old: '37.0元',
rendered_new: null, changed: null }],
unsupported: [{ metric: 'aov', input: null, reason: MASKED_METRIC },
{ metric: 'aov', input: 'vars.kpi.gmv', reason: '这一列在数据源中设置了遮罩,不能用于推演' }] }
}
if (body?.metric === 'orders') {
// 推演得了的指标里有一个文本输入:照实显示、列出原因,订单数照常能改
return { ...base, metrics: [{ id: 'orders', name: '订单数', unit: '单', old: 1234, new: 1234, delta: 0,
rendered_old: '1,234单', rendered_new: '1,234单', rendered_delta: null, changed: false, status: 'unchanged', reason: null,
substituted: "1234 if '华东' == '华东' else 0",
inputs: [{ path: 'vars.kpi.order_cnt', via: 'agent_field', node_id: 'fetch', artifact: Q1,
locator: { row: 0, column: 'order_cnt' }, row_span: [0, 0], kind: 'number', editable: true, old: 1234, new: 1234, changed: false },
{ path: 'vars.kpi.region', via: 'transform', node_id: 'parse', kind: 'text', editable: false, old: '华东', new: '华东', changed: false }] }],
segments: [{ report: 'write', unit: fx.segments.s8.unit.id, sid: 's8', metric: 'orders', rendered_old: '1,234单',
rendered_new: '1,234单', changed: false }],
unsupported: [{ metric: 'orders', input: 'vars.kpi.region', reason: '不是数值,不能修改' }] }
}
if (body?.metric === 'gmv') {
// 加工过的列表(对不上任何快照):不能改、也没有行可勾,推演得了却没什么可动
return { ...base, metrics: [{ id: 'gmv', name: '销售额', unit: '元', old: 45678.5, new: 45678.5, delta: 0,
rendered_old: '45,678.5元', rendered_new: '45,678.5元', rendered_delta: null, changed: false, status: 'unchanged',
reason: null, substituted: 'sum(vars.kpi.daily)',
inputs: [{ path: 'vars.kpi.daily', via: 'transform', node_id: 'daily', kind: 'container', editable: false,
old: '[7 项]', new: '[7 项]', changed: false }] }],
segments: [{ report: 'write', unit: fx.segments.s6.unit.id, sid: 's6', metric: 'gmv', rendered_old: '45,678.5元',
rendered_new: '45,678.5元', changed: false }],
unsupported: [{ metric: 'gmv', input: 'vars.kpi.daily', reason: '列表或对象不能直接修改,也没有对应的查询结果可以排除行' }] }
}
if (body?.metric === 'fx') {
// 空态:原式里没有引用任何输入(写死的常数)
return { ...base, metrics: [{ id: 'fx', name: '汇率', unit: '', old: 7.12, new: 7.12, delta: 0, rendered_old: '7.12',
rendered_new: '7.12', rendered_delta: null, changed: false, status: 'unchanged', reason: null, substituted: '7.12', inputs: [] }],
segments: [], unsupported: [] }
}
const def = METRICS[body?.metric]
const step = chainOf(def.sid)[0]
const views = inputsOf(def.sid).map((inp) => {
const row = inp.locator?.row
// row_span:这个输入实际用到的快照行,单格就是它那一行(后端 recompute._row_span)
const view = { path: inp.path, via: inp.via, node_id: inp.node_id, artifact: inp.artifact, locator: inp.locator,
row_span: [row, row], kind: 'number', editable: true, old: inp.value }
if (inp.path in inputs) return { ...view, new: inputs[inp.path], changed: inputs[inp.path] !== inp.value, touched: true }
if ((exclude[inp.artifact] ?? []).includes(row)) {
return { ...view, new: null, changed: true, excluded_rows: [row], touched: true, gone: true }
}
return { ...view, new: inp.value, changed: false }
})
const touched = views.some((v) => v.touched)
const gone = views.find((v) => v.gone)
let status = 'unchanged'; let value = step.value; let reason = null
if (touched && gone) {
status = 'excluded'; value = null; reason = `排除后无法计算:${gone.path} 所在的第 ${gone.locator.row + 1} 行已排除`
} else if (touched) {
status = 'ok'; value = def.calc(views.map((v) => v.new))
}
const delta = value == null ? null : Math.round((value - step.value) * 10) / 10
const rendered = value == null ? '—' : def.render(value)
const metric = { id: step.metric, name: def.name, unit: def.unit, old: step.value, new: value, delta,
rendered_old: step.rendered, rendered_new: rendered, rendered_delta: delta ? def.delta(delta) : null,
changed: value !== step.value, status, reason, substituted: status === 'ok' ? `(推演代入式 ${views.map((v) => v.new).join('、')})` : step.substituted,
inputs: views.map(({ touched: _t, gone: _g, ...v }) => v) }
return { ...base, metrics: [metric], unsupported: [], affected_cards: changed ? AFFECTED : [],
segments: [{ report: 'write', unit: fx.segments[def.sid].unit.id, sid: def.sid, metric: step.metric,
rendered_old: step.rendered, rendered_new: rendered, changed: rendered !== step.rendered }] }
}
/** 勾行接口:按夹具里 Q3 的快照给一页(phone 列在夹具里已经写成「已遮罩」) */
function rowsReply(url) {
const artifact = url.searchParams.get('artifact')
const offset = Number(url.searchParams.get('offset') ?? 0)
const limit = Number(url.searchParams.get('limit') ?? 50)
if (artifact !== Q3) return { status: 422, json: { detail: '这份查询快照不属于这次运行,或不在封存范围内,不能用于推演', code: 'whatif_bad_input' } }
const picked = SNAP.rows.slice(offset, offset + limit)
return { json: { run_id: RUN, artifact, node_id: 'fetch', tool: 'db_query__shop', source: 'shop', columns: SNAP.columns,
rows: picked, row_offset: offset, row_index: picked.map((_, i) => offset + i), total_rows: SNAP.rows.length,
truncated: false, masked: ['phone'], hash_ok: true, sealed: true } }
}
// ---------------------------------------------------------------- 页面
const browser = await chromium.launch({ executablePath: CHROME })
/**
* 开一页:片段接口按夹具答,推演接口按 whatifReply 答(reply 给了就由它改:延迟、出错、未封存),记下每次推演的
* 请求体和时刻。别的非 GET 一律拦掉,别的 GET 放行
*/
async function open(syn, { width = 1280, height = 900, theme = 'dark', reply = null } = {}) {
const ctx = await browser.newContext({ viewport: { width, height }, colorScheme: theme, timezoneId: 'Asia/Shanghai' })
ctx.setDefaultTimeout(6000)
const page = await ctx.newPage()
const sent = []
const pages = []
const errors = []
page.on('pageerror', (e) => errors.push(e.message))
page.on('dialog', (d) => { errors.push(`原生对话框:${d.message()}`); void d.dismiss() })
await page.route((u) => new URL(u).pathname.startsWith('/api/'), async (route) => {
const req = route.request()
const url = new URL(req.url())
if (req.method() === 'POST' && url.pathname === `/api/runs/${RUN}/evidence/whatif`) {
const body = req.postDataJSON()
sent.push({ body, at: Date.now() })
const out = reply ? await reply(body, sent.length) : { json: whatifReply(body) }
return route.fulfill({ status: out.status ?? 200, json: out.json })
}
if (req.method() !== 'GET') return route.abort()
if (url.pathname === `/api/runs/${RUN}/evidence/whatif/rows`) {
pages.push(Object.fromEntries(url.searchParams))
const out = rowsReply(url)
return route.fulfill({ status: out.status ?? 200, json: out.json })
}
const seg = url.pathname.match(new RegExp(`/api/runs/${RUN}/evidence/segments/([^/]+)$`))
if (seg) return route.fulfill({ json: segmentReply(decodeURIComponent(seg[1])) })
return route.continue()
})
await page.goto(`${WEB}/preview.html?syn=${syn}&theme=${theme}`, { waitUntil: 'networkidle' })
await page.waitForSelector('[data-evidence-doc]')
return { ctx, page, sent, pages, errors }
}
/** 点开一个片段,等指标步骤和「推演」开关出来 */
async function openMetric(page, sid) {
await page.click(`[data-seg="${sid}"]`)
await page.waitForSelector('[data-ev-metric] [data-whatif-toggle]')
}
/** 展开推演,等第一份答复画出来 */
async function openWhatIf(page) {
await page.click('[data-whatif-toggle]')
await page.waitForSelector('[data-whatif-result="unchanged"], [data-whatif-result="ok"]')
}
const settle = (page, ms = 700) => page.waitForTimeout(ms)
const text = (page, sel) => page.locator(sel).first().innerText()
/** 这个元素整个在面板正文(窄屏抽屉、宽屏侧栏都是 [data-ev-body] 在滚)和窗口的可见范围里 */
const inView = (page, sel) => page.evaluate((s) => {
const el = document.querySelector(s)
if (!el) return false
const body = document.querySelector('[data-ev-body]')?.getBoundingClientRect() ?? { top: 0, bottom: innerHeight }
const r = el.getBoundingClientRect()
return r.top >= Math.max(0, body.top) - 1 && r.bottom <= Math.min(innerHeight, body.bottom) + 1
}, sel)
const shot = async (page, name) => {
if (!SHOTS) return
mkdirSync(SHOTS, { recursive: true })
await page.screenshot({ path: `${SHOTS}/${name}.png`, fullPage: false })
}
await section('打开推演', async () => {
const { ctx, page, sent, errors } = await open('whatif')
await openMetric(page, 's12')
const toggle = page.locator('[data-whatif-toggle]')
check('指标步骤上有「推演」,默认收起', (await toggle.getAttribute('aria-expanded')) === 'false')
check('不推演时查询步骤里没有勾选框', await page.locator('[data-whatif-rows], [data-whatif-row] input').count() === 0)
await openWhatIf(page)
check('展开后开关标为展开、指向推演区', (await toggle.getAttribute('aria-expanded')) === 'true'
&& (await page.locator(`#${await toggle.getAttribute('aria-controls')}[data-whatif]`).count()) === 1)
check('顶上醒目写着「推演,非出具」', (await text(page, '[data-whatif-banner]')).trim() === BANNER)
check('第一次请求不带改动', JSON.stringify(sent[0]?.body) === JSON.stringify(
{ report: 'write', card: 'caliber', metric: 'wow', overrides: { inputs: {}, exclude_rows: {} } }), JSON.stringify(sent[0]?.body))
check('原值 → 原值,标「无变化」', (await text(page, '[data-whatif-new]')) === '8.7%'
&& (await text(page, '[data-whatif-delta]')) === '无变化')
const fields = await page.locator('[data-whatif-field]').count()
check('两个数值输入都能改,框里是原值', fields === 2
&& await page.locator('[data-whatif-input="vars.kpi.gmv"] [data-whatif-field]').inputValue() === '45678.5')
check('取自查询的输入给「去勾选要排除的行」', await page.locator('[data-whatif-pick]').count() === 2)
check('输入落在的两个查询步骤里出现勾选框,都是这个指标用到的行、可勾', await page.locator('[data-whatif-rows]').count() === 2
&& await page.locator('[data-whatif-row] input[type="checkbox"]').count() === 2
&& await page.locator('[data-whatif-row] input[type="checkbox"]:disabled').count() === 0)
check('报告里引用它的一处不受影响', (await text(page, '[data-whatif-segments-none]')).includes('1 处不受影响'))
check('「恢复原值」在没有改动时不可点', await page.locator('[data-whatif-reset]').isDisabled())
await shot(page, 'open-dark')
check('页面没有报错', errors.length === 0, errors.join(';'))
await ctx.close()
})
await section('改一个输入', async () => {
const { ctx, page, sent } = await open('whatif')
await openMetric(page, 's12')
await openWhatIf(page)
const field = page.locator('[data-whatif-input="vars.kpi.gmv"] [data-whatif-field]')
await field.fill('')
const before = sent.length
await field.pressSequentially('50000', { delay: 40 })
await page.waitForTimeout(150)
check('边打字不发请求', sent.length === before)
await page.waitForSelector('[data-whatif-result="ok"]')
check('停顿之后只发一次', sent.length === before + 1, `${sent.length - before} 次`)
check('请求体带着改动的输入', JSON.stringify(sent.at(-1).body.overrides) === JSON.stringify({ inputs: { 'vars.kpi.gmv': 50000 }, exclude_rows: {} }),
JSON.stringify(sent.at(-1).body.overrides))
check('显示新值和变化量', (await text(page, '[data-whatif-new]')) === '19.0%'
&& (await text(page, '[data-whatif-delta]')) === '变化 +10.3 个百分点', await text(page, '[data-whatif-result]'))
check('报告里会变的那一处:8.7% → 19.0%,可定位', (await text(page, '[data-whatif-segment="s12"]')).includes('19.0%')
&& await page.locator('[data-whatif-locate="s12"]').count() === 1)
check('横幅一直在', (await text(page, '[data-whatif-banner]')).trim() === BANNER)
// 回车立刻提交,不等停顿
await field.fill('60000')
const t0 = Date.now()
await field.press('Enter')
await page.waitForFunction(() => document.querySelector('[data-whatif-new]')?.textContent === '42.8%')
check('回车立刻提交', sent.at(-1).body.overrides.inputs['vars.kpi.gmv'] === 60000 && sent.at(-1).at - t0 < 300,
`${sent.at(-1).at - t0}ms`)
// 写的不是数:提示,保留上一次的结果
await field.fill('六万')
await settle(page)
check('不是数:提示「请输入数值」、不发请求', (await page.locator('[data-whatif-input="vars.kpi.gmv"]').innerText()).includes('请输入数值')
&& sent.at(-1).body.overrides.inputs['vars.kpi.gmv'] === 60000)
// Esc 退回已提交的值,面板不关
await field.press('Escape')
check('Esc 退回已提交的值,面板还开着', await field.inputValue() === '60000' && await page.locator('[data-evidence-panel]').count() === 1)
// 定位:焦点回到正文里那一处,推演不收起
await page.click('[data-whatif-locate="s12"]')
await page.waitForTimeout(200)
check('定位到正文里那一处,推演照旧展开', await page.evaluate(() => document.activeElement?.getAttribute('data-seg')) === 's12'
&& await page.locator('[data-whatif]').count() === 1 && (await text(page, '[data-whatif-new]')) === '42.8%')
await ctx.close()
})
await section('勾掉一行', async () => {
const { ctx, page, sent } = await open('whatif')
await openMetric(page, 's12')
await openWhatIf(page)
const box = page.locator(`[data-ev-query="${Q4}"] [data-whatif-row="0"] input[type="checkbox"]`)
check('勾选框的读屏名从 1 数', (await box.getAttribute('aria-label')) === '排除第 1 行')
await box.check()
await page.waitForSelector('[data-whatif-result="excluded"]')
check('请求体带 exclude_rows(快照工件 id → 从 0 数的行号)',
JSON.stringify(sent.at(-1).body.overrides) === JSON.stringify({ inputs: {}, exclude_rows: { [Q4]: [0] } }), JSON.stringify(sent.at(-1).body.overrides))
check('这一行划掉', await page.locator(`[data-ev-query="${Q4}"] [data-whatif-row="0"][data-excluded]`).count() === 1)
check('排除后无法计算:写明原因、新值是「—」', (await text(page, '[data-whatif-reason]')).startsWith('排除后无法计算')
&& (await text(page, '[data-whatif-new]')) === '—')
check('输入下写明排除了哪一行', (await text(page, `[data-whatif-input="cell(nodes.pull, 0, 'gmv')"] [data-whatif-excluded]`)) === '已排除第 1 行')
check('结果窗口下写明已排除几行', (await text(page, `[data-ev-query="${Q4}"] [data-whatif-excluded-count]`)) === '已排除 1 行')
await shot(page, 'excluded-dark')
// 恢复原值:输入框、勾选框、结果都回去
await page.locator('[data-whatif-input="vars.kpi.gmv"] [data-whatif-field]').fill('50000')
await page.locator('[data-whatif-input="vars.kpi.gmv"] [data-whatif-field]').press('Enter')
await settle(page, 300)
await page.click('[data-whatif-reset]')
await page.waitForSelector('[data-whatif-result="unchanged"]')
check('恢复原值:结果回到原值', (await text(page, '[data-whatif-new]')) === '8.7%')
check('恢复原值:输入框回到原值、勾选框都放开',
await page.locator('[data-whatif-input="vars.kpi.gmv"] [data-whatif-field]').inputValue() === '45678.5'
&& !(await box.isChecked()) && await page.locator('[data-whatif-row][data-excluded]').count() === 0)
check('恢复原值后按钮不可点', await page.locator('[data-whatif-reset]').isDisabled())
// 收起:勾选框跟着收起,结果窗口换回原来的表格
await page.click('[data-whatif-toggle]')
check('收起后推演区和勾选框都没了,查询结果照常显示', await page.locator('[data-whatif], [data-whatif-rows]').count() === 0
&& await page.locator(`[data-ev-query="${Q4}"] table`).count() === 1)
await ctx.close()
})
await section('多行快照与遮罩', async () => {
const { ctx, page, sent } = await open('whatif')
await openMetric(page, 's70')
await openWhatIf(page)
const rows = page.locator(`[data-ev-query="${Q3}"] [data-whatif-row]`)
check('窗口里每行一个勾选框', await rows.count() === chainOf('s70').find((s) => s.step === 'query').rows.length)
check('遮罩列照旧写「已遮罩」', await page.locator(`[data-ev-query="${Q3}"] [data-whatif-rows] td[data-masked]`).count() > 0
&& (await page.locator(`[data-ev-query="${Q3}"] [data-whatif-rows] td[data-masked]`).first().innerText()).trim() === '已遮罩')
await page.locator(`[data-ev-query="${Q3}"] [data-whatif-row="5"] input`).check()
await page.waitForSelector('[data-whatif-result="excluded"]')
check('勾掉第 6 行:请求里是行号 5', JSON.stringify(sent.at(-1).body.overrides.exclude_rows) === JSON.stringify({ [Q3]: [5] }))
await ctx.close()
})
await section('只让这个指标用到的行可勾', async () => {
const { ctx, page, sent } = await open('whatif')
await openMetric(page, 's70')
await openWhatIf(page)
const row = (n) => page.locator(`[data-ev-query="${Q3}"] [data-whatif-row="${n}"]`)
check('用到的第 6、12 行可勾', !(await row(5).locator('input').isDisabled()) && !(await row(11).locator('input').isDisabled()))
const unused = await page.locator(`[data-ev-query="${Q3}"] [data-whatif-row][data-whatif-row-unused]`).count()
check('前后几行上下文不能勾,悬停写明没用到', unused === 6 && await row(4).locator('input').isDisabled()
&& (await row(4).locator('td').first().getAttribute('title')) === '这个指标没有用到这一行,排除它不影响结果', `${unused} 行`)
const before = sent.length
await row(4).locator('input').click({ force: true })
await settle(page, 300)
check('点了不起作用的行也不发请求', sent.length === before && !(await row(4).locator('input').isChecked()))
check('表格下面说明只有用到的行能勾', (await text(page, `[data-ev-query="${Q3}"] [data-whatif-rows]`)).includes('没有用到的行不能勾选'))
await ctx.close()
})
await section('整份结果作输入:推演区里勾行', async () => {
const { ctx, page, sent, pages } = await open('whatif')
await openMetric(page, 's18')
await openWhatIf(page)
check('证据链里没有它的查询步骤', await page.locator('[data-ev-query]').count() === 0)
const toggle = page.locator('[data-whatif-input="vars.orders.rows"] [data-whatif-pick-here]')
check('输入下面给「勾选要排除的行(共 12 行)」', (await toggle.innerText()).includes('勾选要排除的行(共 12 行)'))
await toggle.click()
await page.waitForSelector('[data-whatif-snapshot] [data-whatif-row]')
check('按页取这份快照,从第 0 行起', pages[0]?.artifact === Q3 && pages[0]?.offset === '0', JSON.stringify(pages[0]))
const rows = page.locator('[data-whatif-snapshot] [data-whatif-row]')
check('12 行都在、都能勾', await rows.count() === 12
&& await page.locator('[data-whatif-snapshot] [data-whatif-row] input:disabled').count() === 0)
check('遮罩列写「已遮罩」', await page.locator('[data-whatif-snapshot] td[data-masked]').count() === 12)
check('写明是第几行到第几行', (await text(page, '[data-whatif-snapshot-range]')) === '第 1–12 行,共 12 行')
await page.locator('[data-whatif-snapshot] [data-whatif-row="7"] input').check()
await page.waitForSelector('[data-whatif-result="ok"]')
check('请求体带 exclude_rows:第 8 行是行号 7',
JSON.stringify(sent.at(-1).body.overrides) === JSON.stringify({ inputs: {}, exclude_rows: { [Q3]: [7] } }), JSON.stringify(sent.at(-1).body.overrides))
check('新值随之变化:12单 → 11单', (await text(page, '[data-whatif-result] [data-whatif-new]')) === '11单'
&& (await text(page, '[data-whatif-result] [data-whatif-delta]')) === '变化 -1单')
check('勾行的表格底下带着推演结果', (await text(page, '[data-whatif-snapshot] [data-whatif-summary]')).includes('11单'))
check('输入下写明排除了哪一行', (await text(page, '[data-whatif-input="vars.orders.rows"] [data-whatif-excluded]')) === '已排除第 8 行')
check('报告里引用它的那一处跟着变', (await text(page, '[data-whatif-segment="s18"]')).includes('11单'))
await shot(page, 'table-input-dark')
await ctx.close()
})
await section('勾行后结果就在手边', async () => {
const { ctx, page } = await open('whatif')
await openMetric(page, 's12')
await openWhatIf(page)
await page.locator(`[data-whatif-input="cell(nodes.pull, 0, 'gmv')"] [data-whatif-pick]`).click()
await page.locator(`[data-ev-query="${Q4}"] [data-whatif-row="0"] input`).check()
await page.waitForSelector(`[data-ev-query="${Q4}"] [data-whatif-summary="excluded"]`)
const summary = await text(page, `[data-ev-query="${Q4}"] [data-whatif-summary]`)
check('勾了行,表格底下就写着新值和原因', summary.includes('—') && summary.includes('排除后无法计算'), summary)
await page.waitForTimeout(200)
check('答复回来后,表格底下这份结果整个在视野里', await inView(page, `[data-ev-query="${Q4}"] [data-whatif-summary]`),
JSON.stringify(await page.evaluate((s) => {
const r = document.querySelector(s)?.getBoundingClientRect()
const b = document.querySelector('[data-ev-body]')?.getBoundingClientRect()
return { top: r?.top, bottom: r?.bottom, bodyTop: b?.top, bodyBottom: b?.bottom, h: innerHeight }
}, `[data-ev-query="${Q4}"] [data-whatif-summary]`)))
await page.click(`[data-ev-query="${Q4}"] [data-whatif-back]`)
await page.waitForTimeout(250)
check('「回到推演结果」:焦点回到推演结果、滚进视野', await page.evaluate(() => document.activeElement?.hasAttribute('data-whatif-result'))
&& await inView(page, '[data-whatif-result]'))
await ctx.close()
})
await section('不支持的输入', async () => {
const { ctx, page } = await open('whatif')
await openMetric(page, 's8')
await openWhatIf(page)
check('不支持推演的输入列出原因', (await text(page, '[data-whatif-unsupported-input="vars.kpi.region"]'))
.includes('不是数值,不能修改'))
check('文本输入照实显示、不给输入框;数值输入照常能改', await page.locator('[data-whatif-field]').count() === 1
&& (await text(page, '[data-whatif-input="vars.kpi.region"] [data-whatif-value]')).includes('华东')
&& await page.locator('[data-whatif-input="vars.kpi.order_cnt"] [data-whatif-field]').count() === 1)
check('指标照常推演:原值 → 原值,标「无变化」', (await text(page, '[data-whatif-new]')) === '1,234单'
&& (await text(page, '[data-whatif-delta]')) === '无变化')
check('能改的那一格所在的查询步骤里出现勾选框', await page.locator(`[data-ev-query="${Q1}"] [data-whatif-row="0"] input:not(:disabled)`).count() === 1)
await ctx.close()
const bare = await open('whatif')
await openMetric(bare.page, 's6')
await openWhatIf(bare.page)
check('加工过的列表:列出原因、不给输入框', (await text(bare.page, '[data-whatif-unsupported-input="vars.kpi.daily"]'))
.includes('列表或对象不能直接修改') && await bare.page.locator('[data-whatif-field]').count() === 0
&& (await text(bare.page, '[data-whatif-input="vars.kpi.daily"] [data-whatif-value]')).includes('[7 项]'))
check('没有能改的输入、也没有能勾的行:说一句为什么', (await text(bare.page, '[data-whatif-nothing]')).includes('没有可以修改的输入'))
await bare.ctx.close()
})
/** 整个指标推演不了:展开推演,等结果区写出原因。交回结果区的字(压成一行,好写进检查项的说明) */
async function openWhole(page) {
await page.click('[data-whatif-toggle]')
await page.waitForSelector('[data-whatif-result="whole"]')
return (await text(page, '[data-whatif-result]')).replace(/\s+/g, ' ').trim()
}
await section('整个指标推演不了:输入还原不了', async () => {
const { ctx, page, sent, errors } = await open('whatif')
await openMetric(page, 's22')
const result = await openWhole(page)
check('一打开就写明哪个输入还原不了、为什么', result.includes(LOST), result)
check('不写「无变化」,也不画「→」', !result.includes('无变化') && !result.includes('→'), result)
check('本来能改的数也不给输入框,不列输入、不支持的输入、报告中会变的地方',
await page.locator('[data-whatif-field], [data-whatif-inputs], [data-whatif-unsupported], [data-whatif-segments]').count() === 0)
check('「恢复原值」不可点,只发过一次不带改动的请求', await page.locator('[data-whatif-reset]').isDisabled() && sent.length === 1
&& JSON.stringify(sent[0].body.overrides) === JSON.stringify({ inputs: {}, exclude_rows: {} }))
check('横幅照旧在', (await text(page, '[data-whatif-banner]')).trim() === BANNER)
await shot(page, 'whole-lost-dark')
check('页面没有报错', errors.length === 0, errors.join(';'))
await ctx.close()
})
await section('整个指标推演不了:用到了遮罩列', async () => {
const { ctx, page } = await open('whatif')
await openMetric(page, 's10')
const result = await openWhole(page)
check('一打开就写明用到了遮罩列', result.includes(MASKED_METRIC), result)
check('不写「无变化」,也不画「→」', !result.includes('无变化') && !result.includes('→'), result)
check('本来能改的订单数也不给输入框', await page.locator('[data-whatif-field], [data-whatif-inputs]').count() === 0)
check('查询步骤里不出勾选框,结果窗口照常显示(遮罩列写「已遮罩」)', await page.locator('[data-whatif-rows], [data-whatif-row]').count() === 0
&& await page.locator(`[data-ev-query="${Q1}"] table`).count() === 1
&& (await text(page, `[data-ev-query="${Q1}"] table`)).includes('已遮罩'))
check('不说报告里引用它的地方「不受影响」', await page.locator('[data-whatif-segments], [data-whatif-segments-none]').count() === 0)
await ctx.close()
})
await section('整个指标推演不了:口径卡没记输入', async () => {
const { ctx, page } = await open('whatif')
await openMetric(page, 's16')
const result = await openWhole(page)
check('只说原因:口径卡没有记录输入', result.includes('口径卡没有记录输入,不能推演'), result)
check('不写「无变化」,也不说「没有引用任何输入」', !result.includes('无变化') && !result.includes('→')
&& await page.locator('[data-whatif-empty], [data-whatif-inputs], [data-whatif-unsupported]').count() === 0)
check('不画勾选框', await page.locator('[data-whatif-rows]').count() === 0)
await ctx.close()
})
await section('空态', async () => {
const { ctx, page } = await open('whatif')
await openMetric(page, 's24')
await openWhatIf(page)
check('原式没有引用输入:说清无可推演,不画空列表', (await text(page, '[data-whatif-empty]')).includes('无可推演')
&& await page.locator('[data-whatif-input]').count() === 0)
check('没有报告引用时不画「报告中会变的地方」', await page.locator('[data-whatif-segments]').count() === 0)
await ctx.close()
})
await section('加载、失败、未封存', async () => {
let release
const gate = new Promise((r) => { release = r })
const slow = await open('whatif', { reply: async (body, n) => {
if (n === 1) await gate
return { json: whatifReply(body) }
} })
await openMetric(slow.page, 's12')
await slow.page.click('[data-whatif-toggle]')
await slow.page.waitForSelector('[data-whatif-loading]')
check('答复回来之前显示「推演中」,横幅已经在', (await text(slow.page, '[data-whatif-loading]')).includes('推演中')
&& (await text(slow.page, '[data-whatif-banner]')).trim() === BANNER)
release()
await slow.page.waitForSelector('[data-whatif-result="unchanged"]')
check('答复回来后加载提示消失', await slow.page.locator('[data-whatif-loading]').count() === 0)
await slow.ctx.close()
const flaky = await open('whatif', { reply: async (body, n) => (n === 1
? { status: 500, json: { detail: '推演服务暂时不可用' } } : { json: whatifReply(body) }) })
await openMetric(flaky.page, 's12')
await flaky.page.click('[data-whatif-toggle]')
await flaky.page.waitForSelector('[data-whatif] [role="alert"]')
check('失败时给出原因和「重试」', (await text(flaky.page, '[data-whatif] [role="alert"]')).includes('重试'))
await flaky.page.locator('[data-whatif] [role="alert"]').getByRole('button', { name: '重试' }).click()
await flaky.page.waitForSelector('[data-whatif-result="unchanged"]')
check('重试之后正常显示', await flaky.page.locator('[data-whatif] [role="alert"]').count() === 0)
await flaky.ctx.close()
const open_ = await open('whatif', { reply: async (body) => ({ json: { ...whatifReply(body), sealed: false, seal: { sealed: false, ok: null } } }) })
await openMetric(open_.page, 's12')
await openWhatIf(open_.page)
check('运行未封存时提示数据可能还会变', (await text(open_.page, '[data-whatif-unsealed]')) === '运行未封存,数据可能还会变')
await open_.ctx.close()
const broken = await open('whatif', { reply: async (body) => ({ json: { ...whatifReply(body), sealed: false, seal: { sealed: true, ok: false } } }) })
await openMetric(broken.page, 's12')
await openWhatIf(broken.page)
check('封存核对未通过时照实说', (await text(broken.page, '[data-whatif-unsealed="broken"]')) === '封存核对未通过,推演所依据的数据可能已被改动')
await broken.ctx.close()
})
await section('加载中、失败后不留上一次的答复', async () => {
let release
const gate = new Promise((r) => { release = r })
const { ctx, page } = await open('whatif', { reply: async (body, n) => {
if (n === 2) await gate
if (n === 3) return { status: 500, json: { detail: '推演服务暂时不可用' } }
return { json: whatifReply(body) }
} })
await openMetric(page, 's12')
await openWhatIf(page)
await page.locator(`[data-ev-query="${Q4}"] [data-whatif-row="0"] input`).check()
await page.waitForSelector('[data-whatif-segments="loading"]')
check('答复回来之前:报告中会变的地方变淡、标为忙,结果也是', (await page.locator('[data-whatif-segments]').getAttribute('aria-busy')) === 'true'
&& await page.locator('[data-whatif-result="loading"]').count() === 1)
release()
await page.waitForSelector('[data-whatif-result="excluded"]')
check('答复回来后按这一次画:排除标记、下游口径卡', await page.locator('[data-whatif-excluded]').count() === 1
&& await page.locator('[data-whatif-affected=""]').count() === 1)
const field = page.locator('[data-whatif-input="vars.kpi.gmv"] [data-whatif-field]')
await field.fill('50000')
await field.press('Enter')
await page.waitForSelector('[data-whatif] [role="alert"]')
check('请求失败:上一次的结果、排除标记、报告中会变的地方、下游口径卡都不再显示',
await page.locator('[data-whatif-result], [data-whatif-excluded], [data-whatif-segments], [data-whatif-affected]').count() === 0)
check('输入框还在,能接着改', await page.locator('[data-whatif-field]').count() === 2)
await ctx.close()
})
/** 页面和面板正文都没有横向滚动(表格自己的横向滚动条不算:那是表格容器里的) */
async function overflow(page) {
return page.evaluate(() => {
const doc = document.documentElement
const body = document.querySelector('[data-ev-body]')
const box = document.querySelector('[data-whatif]')
return { page: doc.scrollWidth - doc.clientWidth, body: body ? body.scrollWidth - body.clientWidth : 0,
whatif: box ? box.scrollWidth - box.clientWidth : 0 }
})
}
await section('窄屏', async () => {
for (const theme of ['dark', 'light']) {
const { ctx, page, errors } = await open('whatif', { width: 390, height: 844, theme })
await openMetric(page, 's12')
check(`390px(${theme}):面板从底部抽出`, await page.locator('[data-evidence-panel="drawer"]').count() === 1)
await openWhatIf(page)
await page.locator('[data-whatif-input="vars.kpi.gmv"] [data-whatif-field]').fill('50000')
await page.locator('[data-whatif-input="vars.kpi.gmv"] [data-whatif-field]').press('Enter')
await page.waitForSelector('[data-whatif-result="ok"]')
await page.locator(`[data-ev-query="${Q4}"] [data-whatif-row="0"] input`).check()
await page.waitForSelector('[data-whatif-result="excluded"]')
const o = await overflow(page)
check(`390px(${theme}):推演展开、勾了行也没有横向溢出`, o.page <= 0 && o.body <= 1 && o.whatif <= 1, JSON.stringify(o))
await shot(page, `narrow-${theme}`)
// 推演区里另给的勾行表格(四列,带遮罩列)在窄屏里同样不撑宽
// 先关上抽屉再点另一处:抽屉盖着正文下半截
await page.locator('[data-evidence-panel] button[aria-label="关闭证据"]').click()
await openMetric(page, 's18')
await openWhatIf(page)
await page.click('[data-whatif-pick-here]')
await page.waitForSelector('[data-whatif-snapshot] [data-whatif-row]')
const t = await overflow(page)
check(`390px(${theme}):推演区里的勾行表格不横向溢出`, t.page <= 0 && t.body <= 1 && t.whatif <= 1, JSON.stringify(t))
// 整个指标推演不了:结果区只有原值和原因,原因里的输入路径长也要折行
await page.locator('[data-evidence-panel] button[aria-label="关闭证据"]').click()
await openMetric(page, 's22')
await openWhole(page)
const w = await overflow(page)
check(`390px(${theme}):整个指标推演不了时不横向溢出`, w.page <= 0 && w.body <= 1 && w.whatif <= 1, JSON.stringify(w))
await shot(page, `narrow-whole-${theme}`)
check(`390px(${theme}):页面没有报错`, errors.length === 0, errors.join(';'))
await ctx.close()
}
const rail = await open('whatif-rail', { width: 1100, height: 900 })
await openMetric(rail.page, 's70')
check('360px 画布右栏:面板栏内展开', await rail.page.locator('[data-evidence-panel="inline"]').count() === 1)
await openWhatIf(rail.page)
const o = await rail.page.evaluate(() => {
const box = document.querySelector('[data-fixture="whatif-rail"]')
const panel = document.querySelector('[data-whatif]')
return { rail: box.scrollWidth - box.clientWidth, whatif: panel.scrollWidth - panel.clientWidth }
})
check('360px 画布右栏:推演区不撑宽右栏', o.rail <= 0 && o.whatif <= 1, JSON.stringify(o))
await shot(rail.page, 'rail-dark')
await rail.ctx.close()
})
/** 两个颜色的对比度(WCAG):颜色是 getComputedStyle 给的 rgb / rgba / color(srgb …),半透明的叠在底色上 */
function contrast(fg, bg, base) {
const parse = (c) => {
const m = c.match(/color\(srgb ([\d.]+) ([\d.]+) ([\d.]+)(?: \/ ([\d.]+))?\)/)
if (m) return [m[1] * 255, m[2] * 255, m[3] * 255, m[4] == null ? 1 : Number(m[4])]
const n = c.match(/rgba?\(([\d.]+),\s*([\d.]+),\s*([\d.]+)(?:,\s*([\d.]+))?\)/)
return n ? [Number(n[1]), Number(n[2]), Number(n[3]), n[4] == null ? 1 : Number(n[4])] : null
}
const over = (top, under) => top.slice(0, 3).map((v, i) => v * top[3] + under[i] * (1 - top[3]))
const lum = ([r, g, b]) => {
const f = (v) => { const s = v / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4 }
return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b)
}
const b0 = parse(base); const b1 = parse(bg); const f0 = parse(fg)
if (!b0 || !b1 || !f0) return 0
const under = over(b1, b0.slice(0, 3))
const a = lum(over(f0, under)); const b = lum(under)
return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05)
}
await section('深浅色可读', async () => {
for (const theme of ['dark', 'light']) {
const { ctx, page } = await open('whatif', { theme })
await openMetric(page, 's12')
await openWhatIf(page)
const c = await page.evaluate(() => {
const banner = document.querySelector('[data-whatif-banner]')
const panel = document.querySelector('[data-evidence-panel]')
const s = getComputedStyle(banner)
return { fg: s.color, bg: s.backgroundColor, base: getComputedStyle(panel).backgroundColor,
weight: Number(s.fontWeight) }
})
const ratio = contrast(c.fg, c.bg, c.base)
check(`${theme}:横幅文字对比度 ≥ 4.5`, ratio >= 4.5, `${ratio.toFixed(2)}(${c.fg} on ${c.bg})`)
check(`${theme}:横幅加粗`, c.weight >= 500, String(c.weight))
await shot(page, `open-${theme}`)
await ctx.close()
// 整个指标推演不了时,结果区里只剩一句原因:它就是要人读的那句
const whole = await open('whatif', { theme })
await openMetric(whole.page, 's10')
await openWhole(whole.page)
const r = await whole.page.evaluate(() => {
const reason = document.querySelector('[data-whatif-reason]')
const panel = document.querySelector('[data-evidence-panel]')
return { fg: getComputedStyle(reason).color, base: getComputedStyle(panel).backgroundColor }
})
const reasonRatio = contrast(r.fg, r.base, r.base)
check(`${theme}:整个指标推演不了的原因对比度 ≥ 4.5`, reasonRatio >= 4.5, `${reasonRatio.toFixed(2)}(${r.fg} on ${r.base})`)
await shot(whole.page, `whole-masked-${theme}`)
await whole.ctx.close()
}
})
await browser.close()
console.log(failed ? `\n✗ 数字推演:${failed} 项未通过` : '\n✓ 数字推演:全部通过')
process.exit(failed ? 1 : 0)