From 60cd5a47bb43f39cbac1e3977e2c93b317b76404 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Mon, 5 Oct 2026 03:26:43 +0800 Subject: [PATCH 01/12] =?UTF-8?q?=E5=8F=A3=E5=BE=84=E5=8D=A1=E7=BB=99?= =?UTF-8?q?=E5=AE=B9=E5=99=A8=E5=9E=8B=20vars=20=E8=BE=93=E5=85=A5?= =?UTF-8?q?=E5=8F=A6=E5=AD=98=E5=AE=8C=E6=95=B4=E5=80=BC=EF=BC=88value=5Fa?= =?UTF-8?q?rtifact=EF=BC=89=EF=BC=8C=E4=BE=9B=E6=95=B0=E5=AD=97=E6=8E=A8?= =?UTF-8?q?=E6=BC=94=E9=87=8D=E7=AE=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 卡里的输入对列表、字典只记「[12 项]」这样的大概,事后要排除几行、改一个数再算一遍,手里没有完整的值。 nodes.*、input.* 的完整值在那个节点封存的产出工件里,agent 字段能按出处从查询快照还原;vars 是谁写的、 写进去的是不是节点产出本身说不准,只能在口径卡算的那一刻存下。 - 此后容器型 vars.* 输入落一份 metric_input 工件 {path, value}(put_json,随运行封存),输入里记下 value_artifact; id 写在内容寻址的指标集里,不另起台账条目 - 大过 4 MB 的不存,写失败也不存:口径卡照常算出来,只是这个输入以后推演不了 - 金样测试(改动之前的代码真跑出来的工件):只有标量输入的卡逐字节相同、工件 id 不变;带容器型 vars 输入的卡 去掉新键后和以前一字不差 --- backend/app/engine/nodes/metrics.py | 33 +++ .../tests/fixtures/whatif/golden_cards.json | 208 ++++++++++++++++++ backend/tests/test_metric_value_artifact.py | 138 ++++++++++++ 3 files changed, 379 insertions(+) create mode 100644 backend/tests/fixtures/whatif/golden_cards.json create mode 100644 backend/tests/test_metric_value_artifact.py diff --git a/backend/app/engine/nodes/metrics.py b/backend/app/engine/nodes/metrics.py index 0d9f7105..096aeed8 100644 --- a/backend/app/engine/nodes/metrics.py +++ b/backend/app/engine/nodes/metrics.py @@ -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 diff --git a/backend/tests/fixtures/whatif/golden_cards.json b/backend/tests/fixtures/whatif/golden_cards.json new file mode 100644 index 00000000..b2c13128 --- /dev/null +++ b/backend/tests/fixtures/whatif/golden_cards.json @@ -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 + } + ] + } + } +} diff --git a/backend/tests/test_metric_value_artifact.py b/backend/tests/test_metric_value_artifact.py new file mode 100644 index 00000000..4117cef6 --- /dev/null +++ b/backend/tests/test_metric_value_artifact.py @@ -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"] From fb15805ead8e4c3558c20aec3b575f130d663ce8 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Mon, 5 Oct 2026 03:44:29 +0800 Subject: [PATCH 02/12] =?UTF-8?q?=E6=95=B0=E5=AD=97=E6=8E=A8=E6=BC=94?= =?UTF-8?q?=E7=9A=84=E9=87=8D=E7=AE=97=EF=BC=88engine/recompute.py?= =?UTF-8?q?=EF=BC=89=EF=BC=9A=E6=94=B9=E8=BE=93=E5=85=A5=E3=80=81=E6=8E=92?= =?UTF-8?q?=E9=99=A4=E5=BF=AB=E7=85=A7=E8=A1=8C=EF=BC=8C=E6=8C=89=E5=8F=A3?= =?UTF-8?q?=E5=BE=84=E5=8D=A1=E5=90=8C=E4=B8=80=E5=A5=97=E8=A7=84=E5=88=99?= =?UTF-8?q?=E7=AE=97=E5=87=BA=E6=96=B0=E5=80=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 纯函数,不读库、不写工件。口径卡怎么算的这里就怎么算:同一条原式、同一个求值器,浮点按卡上的小数位 round,渲染走 render_metric。重算前先还原每个输入当时的值: - 标量(含 cell() 的格、agent 的单格字段和数组元素)用卡上记的值;它们落在快照的哪一行记在 locator 里,排除了那一行 就当缺失,指标标「排除后无法计算」 - 容器只记了「[12 项]」:agent 数组字段从节点产出的 data 还原、按 locator.rows 去掉被排除的行;nodes.* / input.* 从 口径卡执行前那个节点的产出还原;vars.* 只认 value_artifact,老运行照实说当时没有保存完整值;和某份快照 rows 一样 的容器(整份查询结果赋给了变量)排除行就去掉那几行 - 遮罩列取来的输入不给值、不能改、它的指标不重算:新值和原值一比就能算出遮住的那一格 - 嵌在下标、cell() 行列里的引用决定取哪一格,不能直接改 只重算碰到改动的指标;不合法的改动(路径不存在、值不是数、行号越界、快照不在封存范围、改容器或文本)抛 WhatIfError。 另有报告里引用这些指标的片段会写成什么(按片段自己的换算渲染)、引用了这张卡的下游口径卡(只标不重算)。 比率、百分数的变化量写「个百分点」。 --- backend/app/engine/recompute.py | 729 ++++++++++++++++++++++++++++++++ backend/tests/test_recompute.py | 381 +++++++++++++++++ 2 files changed, 1110 insertions(+) create mode 100644 backend/app/engine/recompute.py create mode 100644 backend/tests/test_recompute.py diff --git a/backend/app/engine/recompute.py b/backend/app/engine/recompute.py new file mode 100644 index 00000000..12eda73d --- /dev/null +++ b/backend/app/engine/recompute.py @@ -0,0 +1,729 @@ +"""数字推演的重算:在一张口径卡上改几个输入的值、排除查询快照里的几行,算出指标会变成多少。 + +推演永远不是出具。这里只算数:不读库、不写工件、不追加事件。接口(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 一模一样的列表):排除行就去掉那几行 +- 遮罩列取来的输入不给值、也不拿来推演:改一个输入、排除一行,新值和原值一比就能算出遮住的那一格 + +同一张口径卡的指标不能互相引用(算这张卡时卡上的值还不存在),所以只有用到了被改的输入、被排除的行的指标需要重算, +别的原样交回。 +""" +from __future__ import annotations + +import ast +import copy +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 = "排除后无法计算" + +#: 卡上给容器记的大概(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:查询快照 → 要遮的列(小写):查询当时记下的加数据源现在设的 + """ + + load: Callable[[str], Any] + queries: tuple[str, ...] = () + outputs: Mapping[str, str] = field(default_factory=dict) + masked: Mapping[str, frozenset[str]] = 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 + #: 出现在别的输入的下标、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 + + +# -------------------------------------------------------------------------- +# 入口 +# -------------------------------------------------------------------------- + + +def whatif(card: dict[str, Any], changes: Changes, sources: Sources, *, metric: str | None = None) -> dict[str, Any]: + """在一张口径卡上推演:{metrics: [每个指标的旧值、新值、输入…], unsupported: [不能用于推演的输入和原因]}。 + + metric 给了就只推演这一个指标。改动不合法时抛 WhatIfError,一个指标都不算。没碰到改动的指标不重算, + 原值原样交回(status: unchanged);unsupported 不论有没有改动都列全,界面一打开就能说清哪些输入不能动。 + """ + 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) + return {"metrics": [_outcome(p, changes) for p in plans], "unsupported": _unsupported(plans)} + + +def recompute(metric: dict[str, Any], changes: Changes, sources: Sources) -> dict[str, Any]: + """重算一个指标,不管改动碰没碰到它,也不校验改动。核对还原是否忠实时用:什么都不改,重算出来应当和卡上记的一样。""" + return _outcome(_plan(metric, _Store(sources)), changes, force=True) + + +# -------------------------------------------------------------------------- +# 还原输入 +# -------------------------------------------------------------------------- + + +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, nested = _refs(tree) + remaining = _remaining(metric.get("substituted"), [*tops, *nested]) + 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, nested, store) + plan = _Plan(metric, tree, tops, inputs) + 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], set[str]]: + """表达式引用的值:(最外层的引用, 嵌在别的引用里面的)。和 leaf_refs 按同一套规则认引用,只多分一下里外: + vars.rows[vars.i] 里的 vars.i、cell(nodes.q, vars.r, 'gmv') 里的 vars.r 是嵌在里面的,它们决定取哪一格。""" + top: list[str] = [] + inner: set[str] = set() + + def add(node: ast.AST, nested: bool) -> None: + path = ast.unparse(node) + if nested: + inner.add(path) + elif path not in top: + top.append(path) + + def visit(node: ast.AST, nested: bool) -> None: + if _cell_call(node): + add(node, nested) + for arg in node.args[1:]: + visit(arg, True) + return + if isinstance(node, (ast.Attribute, ast.Subscript, ast.Name)) and _chain_root(node): + add(node, nested) + cur: ast.AST = node + while isinstance(cur, (ast.Attribute, ast.Subscript)): + if isinstance(cur, ast.Subscript): + visit(cur.slice, True) + cur = cur.value + return + for child in ast.iter_child_nodes(node): + visit(child, nested) + + visit(tree, False) + return top, inner + + +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 + 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..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 + 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: + return is_number(value) and math.isfinite(value) + + +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 _number(value): + raise WhatIfError(f"输入「{path}」的新值需要是数值,当前为「{_shown(value)}」") + if any(i.masked for i in found): + raise WhatIfError(f"输入「{path}」取自设置了遮罩的列,不能用于推演") + 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: + text = str(value) + return 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 and isinstance(inp.value, list): + first, last = inp.rows + hit = sorted(r for r in excluded if first <= r <= last) + kept = [v for k, v in enumerate(inp.value) if first + k not in excluded] + return (kept, hit, False) if hit else (inp.value, None, 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, *, force: bool = False) -> dict[str, Any]: + 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) + if not touched and not force: + return _result(plan, "unchanged", plan.metric.get("value"), None, values, notes) + status, new, reason = _compute(plan, values, notes, changes) + return _result(plan, status, new, reason, values, notes) + + +def _compute(plan: _Plan, values: dict[str, Any], notes: dict[str, list[int]], + changes: Changes) -> tuple[str, Any, str | None]: + """(status, 新值, 原因)。还原不了的、遮罩的、排除后缺了的先说,都没有才求值。""" + if plan.problem: + return "unsupported", None, plan.problem + for path in plan.tops: + if plan.inputs[path].problem: + return "unsupported", None, f"无法推演:{path}({plan.inputs[path].problem})" + if any(inp.masked for inp in plan.inputs.values()): + return "masked", None, MASKED_METRIC + for path, inp in plan.inputs.items(): + if inp.row is not None and path in notes and path not in changes.inputs: + return "excluded", None, f"{EXCLUDED}:{path} 所在的第 {inp.row + 1} 行已排除" + value, reason = _evaluate(plan, values) + 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 + 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 + 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": old, "new": 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) 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 _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) -> bool: + return inp.shape == "scalar" and not inp.masked and not inp.selector \ + and (inp.value is None or _number(inp.value)) + + +def _input_view(inp: _Input, values: dict[str, Any], notes: dict[str, list[int]]) -> dict[str, Any]: + """一个输入在推演里的样子:原值、新值、排除了哪几行。遮罩列取来的不给值。容器写大概(「[12 项]」)。""" + item = inp.item + 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 {}), + "kind": _kind(inp), "editable": _editable(inp)} + if inp.masked: + return {**view, "old": None, "new": None, "changed": False, "masked": 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 + changed = inp.problem is None and not _same(old, new) + else: + old, new = item.get("value"), 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]]: + """不能用于推演的输入和原因:遮罩的、完整值找不回来的、决定取哪一格的。卡本身没记输入的,整个指标一条。""" + out: list[dict[str, Any]] = [] + for plan in plans: + metric_id = plan.metric.get("id") + if plan.problem: + out.append({"metric": metric_id, "input": None, "reason": plan.problem}) + continue + for inp in plan.inputs.values(): + 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 None + if reason: + out.append({"metric": metric_id, "input": inp.path, "reason": reason}) + return out + + +# -------------------------------------------------------------------------- +# 报告里引用的地方、下游口径卡 +# -------------------------------------------------------------------------- + + +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) -> list[dict[str, Any]]: + """引用了这张口径卡的下游口径卡(直接的和经别的卡间接的):[{node_id, artifact, caliber, version, metrics, direct}]。 + + 只标「可能受影响」,不重算:下游卡怎么用这张卡的值(取第几个指标、和别的什么一起算)要整条链重放才说得准。 + 认引用看下游指标的输入从哪个节点来(node_id,或者 nodes.<卡> 这样的路径)。同一张卡执行过几次的按最后一次。 + """ + 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 + + flagged: dict[str, dict[str, Any]] = {} + frontier, direct = {str(node_id)}, True + while frontier: + reached: set[str] = set() + for nid, (artifact, card) in latest.items(): + if nid in flagged or not (metrics := uses(card, frontier)): + continue + flagged[nid] = {"node_id": nid, "artifact": artifact, "caliber": card.get("caliber") or "", + "version": card.get("caliber_version") or "", "metrics": metrics, "direct": direct} + reached.add(nid) + frontier, direct = reached, False + return [flagged[nid] for nid in latest if nid in flagged] diff --git a/backend/tests/test_recompute.py b/backend/tests/test_recompute.py new file mode 100644 index 00000000..6d30757c --- /dev/null +++ b/backend/tests/test_recompute.py @@ -0,0 +1,381 @@ +"""数字推演的重算(engine/recompute.py):纯函数,口径卡怎么算的这里就怎么算。 + +卡、查询快照、节点产出都是照 metrics.py 的形状手写的虚构数据;工件库换成一个字典。守的是: +- 不改任何输入时,每个能还原的指标重算出来和卡上记的一模一样 +- 改输入、排除快照里的行,结果和手算一致;排除了 cell() 那一格所在的行,指标标「排除后无法计算」 +- 容器输入的还原:agent 数组字段(按 locator.rows 去掉被排除的行)、nodes.* 从节点产出、vars.* 只认 value_artifact +- 遮罩列取来的输入既不给值、也不能拿来推演 +- 不合法的请求抛 WhatIfError(接口回 422),说清哪里不对 +""" +from __future__ import annotations + +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 m in result["metrics"]) + 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")] + assert ("n2", "vars.kpi.items") not in unsupported and ("n3", "nodes.fetch.items") not in unsupported + # 遮罩列的值不给 + [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 + # 能改的只有数值标量 + 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} + + +# -------------------------------------------------------------------------- +# 改输入、排除行:和手算一致 +# -------------------------------------------------------------------------- + + +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 all(m["status"] == "unchanged" for k, m in metrics.items() if k != "wow") + + +def test_excluding_rows_drops_them_from_an_agent_array_field(): + result = whatif(CARD, Changes(exclude={S1: frozenset({1})}), sources()) + 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_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) + assert [(u["input"], "遮罩" in u["reason"]) for u in baseline["unsupported"]] == [("vars.res.rows", True)] + 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}, + ] From 9852e4d33a97e3217b6e596e5bdd2585f3cfbb6b Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Mon, 5 Oct 2026 03:44:29 +0800 Subject: [PATCH 03/12] =?UTF-8?q?=E6=95=B0=E5=AD=97=E6=8E=A8=E6=BC=94?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=20POST=20/api/runs/{run=5Fid}/evidence/whati?= =?UTF-8?q?f?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 证据面板点开口径卡上的一个数,改输入的值、排除它背后查询结果的几行,看指标和报告里引用它的地方会变成多少。 推演不是出具:不追加事件(last_seq 不变)、不落工件、不改报告。 - 只认这次运行封存范围内的工件:沿用证据接口的 _sealed / _sealed_loader 白名单,另加封存的节点产出和封存的指标集 里写着的 value_artifact;排除行只认封存范围内的查询快照 - 口径卡按台账(一期以前按节点产出)找,循环里算过几次的取报告引用的那一份;nodes.* 按口径卡那次执行之前的产出还原 - 遮罩和证据面板查询步骤同一套:查询当时记下的加数据源现在设的,合并查询按它合并的数据源算 - 未封存(停在审批、还在跑)的运行也能推演,sealed 为假;封存核对没过的同样标出 - 请求形状不对回 422 whatif_bad_request,改动不合法回 422 whatif_bad_input(中文说明),卡、指标、报告不存在回 404 - 只在确有指标变化时列出引用了这张卡的下游口径卡 --- backend/app/api/whatif.py | 221 ++++++++++++++- backend/tests/test_whatif_api.py | 446 +++++++++++++++++++++++++++++++ 2 files changed, 665 insertions(+), 2 deletions(-) create mode 100644 backend/tests/test_whatif_api.py diff --git a/backend/app/api/whatif.py b/backend/app/api/whatif.py index 364ee3e1..98357945 100644 --- a/backend/app/api/whatif.py +++ b/backend/app/api/whatif.py @@ -1,9 +1,226 @@ """数字推演:在一次运行的基础上改动输入,推演指标会怎样变化,不改原运行。 -目前只登记了路由前缀,接口由数字推演的工作包补上。路径挂在 /api/runs/{run_id}/… 下面。 +POST /api/runs/{run_id}/evidence/whatif:证据面板里点开口径卡上的一个数,改某个输入的值、或者排除它背后查询结果里的 +几行,看这个指标和报告里引用它的地方会变成多少。推演永远不是出具:不追加任何事件(last_seq 不变)、不落工件、 +不改报告,结果只交回给发请求的人。 + +只认这次运行封存范围内的工件,和证据接口同一套白名单(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 dataclasses import replace +from typing import Any + +from fastapi import APIRouter, Body + +from app.api.coded import CodedHTTPException +from app.api.evidence import ( + REPORT_NOT_FOUND, + _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 + + +@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) + loader = _loader(sealed, cards) + sources = recompute.Sources(load=loader, queries=tuple(sealed.queries), + outputs=_outputs_before(sealed, started), masked=await _hidden(sealed, loader)) + 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: + # 纯计算,连同读工件放进线程:快照大的时候不挡住同一进程里别的请求 + 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 = any(m.get("changed") for m in result["metrics"]) + 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) if changed else [], + } + + +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 _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 _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 + + +async def _hidden(sealed: _Sealed, loader: Any) -> dict[str, frozenset[str]]: + """封存范围内每份查询快照要遮的列(小写):查询当时记下的加数据源现在设的,合并查询按它合并的那几个数据源算。 + 和证据面板查询步骤的遮罩同一套(api/evidence.py 的 _query_step)。取不回来、被改过的快照不算:重算也不会用它。 + 快照经推演用的同一个 loader 取,读过的重算时不再读盘。""" + masks = _Masks() + out: dict[str, frozenset[str]] = {} + for artifact, info in sealed.queries.items(): + try: + snap = loader(artifact) + except ValueError: + continue + if not isinstance(snap, dict): + continue + if snap.get("source") == MERGE_SOURCE: + hidden, _ = await _merge_masks(snap, masks) + else: + hidden = (await masks.of(info.get("source") or snap.get("source")))[0] | _recorded_masks(snap) + if hidden: + out[artifact] = frozenset(hidden) + return out diff --git a/backend/tests/test_whatif_api.py b/backend/tests/test_whatif_api.py new file mode 100644 index 00000000..d340a6e9 --- /dev/null +++ b/backend/tests/test_whatif_api.py @@ -0,0 +1,446 @@ +"""数字推演接口: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 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 + reasons = {(u["metric"], u["input"]): u["reason"] for u in body["unsupported"]} + assert "遮罩" in reasons[("amount5", AMOUNT5)] and "遮罩" in reasons[("cnt", "vars.res.rows")] + + 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"] == "unchanged" + + +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 }}"}]))) + 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 + 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_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"] == [] + 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) From cf038c95f5e2d3e2f55cd7a3ae8744db29cfe4e5 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Mon, 5 Oct 2026 04:04:30 +0800 Subject: [PATCH 04/12] =?UTF-8?q?=E8=AF=81=E6=8D=AE=E9=9D=A2=E6=9D=BF?= =?UTF-8?q?=E5=8A=A0=E6=95=B0=E5=AD=97=E6=8E=A8=E6=BC=94=EF=BC=9A=E6=8C=87?= =?UTF-8?q?=E6=A0=87=E6=AD=A5=E9=AA=A4=E4=B8=8A=E3=80=8C=E6=8E=A8=E6=BC=94?= =?UTF-8?q?=E3=80=8D=EF=BC=8C=E6=94=B9=E8=BE=93=E5=85=A5=E3=80=81=E5=8B=BE?= =?UTF-8?q?=E6=8E=89=E6=9F=A5=E8=AF=A2=E7=BB=93=E6=9E=9C=E9=87=8C=E7=9A=84?= =?UTF-8?q?=E8=A1=8C=EF=BC=8C=E7=9C=8B=E8=BF=99=E4=B8=AA=E6=95=B0=E5=92=8C?= =?UTF-8?q?=E6=8A=A5=E5=91=8A=E6=80=8E=E4=B9=88=E5=8F=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - run/WhatIf.tsx:推演区。顶上醒目横幅「推演,非出具:不会写进运行记录,也不会改动报告」,运行未封存另行提示; 旧值 → 新值和变化量(比率、百分数写「个百分点」)、推演代入式、输入(数值可改:停顿 450 毫秒或回车、失焦才提交, 写的不是数提示并保留上次的结果,Esc 退回)、不支持推演的输入和原因、报告中会变的地方(可定位)、可能受影响的 下游口径卡、恢复原值;加载、失败(可重试)、空态都有。新改动来了旧请求直接丢掉,答复按请求体缓存 - EvidencePanel.tsx:MetricPart 挂「推演」开关和推演区;QueryPart 只在推演时把结果窗口换成带勾选框的表(WhatIfRows), 勾掉的行划掉、遮罩列照旧写「已遮罩」。草稿按(运行、报告、口径卡、指标)认,同一个指标的几处引用之间来回切不清空 - 接口 api.whatif.run、推演相关类型(types.ts 末尾独立一段)、WHATIF_TEXT 文案 - 预览用例 ?syn=whatif / whatif-rail 和 check-whatif.mjs(54 项,用 page.route 假接口):请求体、防抖、回车、排除行、 恢复原值、收起、不支持的输入、遮罩列、加载 / 失败 / 未封存、390px 与 360px 右栏不横向溢出、深浅色横幅对比度 --- frontend/src/api/whatif.ts | 16 +- frontend/src/dev/fixtures/whatif.tsx | 33 ++ frontend/src/lib/terms.ts | 40 ++- frontend/src/run/EvidencePanel.tsx | 65 +++- frontend/src/run/WhatIf.tsx | 457 +++++++++++++++++++++++++++ frontend/src/types.ts | 113 +++++++ scripts/check-all.mjs | 2 +- scripts/check-whatif.mjs | 427 ++++++++++++++++++++++++- 8 files changed, 1133 insertions(+), 20 deletions(-) create mode 100644 frontend/src/dev/fixtures/whatif.tsx create mode 100644 frontend/src/run/WhatIf.tsx diff --git a/frontend/src/api/whatif.ts b/frontend/src/api/whatif.ts index 3afce99f..f7ecb7a5 100644 --- a/frontend/src/api/whatif.ts +++ b/frontend/src/api/whatif.ts @@ -1,7 +1,19 @@ /** - * 数字推演的接口(/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 } from '../types' +import { request } from './http' + +export const whatif = { + /** + * 在一次运行的口径卡上推演。signal 用来丢掉过时的请求:输入还在改、又发了新的一次时,上一次的答复不再要。 + * 取消照旧抛 AbortError(request 不把它当成连不上服务端) + */ + run: (runId: string, body: WhatIfRequest, opts?: { signal?: AbortSignal }) => + request(`/runs/${encodeURIComponent(runId)}/evidence/whatif`, { + method: 'POST', body: JSON.stringify(body), signal: opts?.signal, + }), +} diff --git a/frontend/src/dev/fixtures/whatif.tsx b/frontend/src/dev/fixtures/whatif.tsx new file mode 100644 index 00000000..ef36d400 --- /dev/null +++ b/frontend/src/dev/fixtures/whatif.tsx @@ -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 ( + + ) +} + +export const cases: Record JSX.Element> = { + whatif: () => ( +
+ ), + 'whatif-rail': () => ( +
+ +
+ ), +} diff --git a/frontend/src/lib/terms.ts b/frontend/src/lib/terms.ts index 57e85bf3..68e05972 100644 --- a/frontend/src/lib/terms.ts +++ b/frontend/src/lib/terms.ts @@ -2758,9 +2758,47 @@ export const INQUIRY_TEXT = { title: '审批质询', } -/** 数字推演:在一次运行的基础上改动输入,推演指标的变化 */ +/** + * 数字推演:在一次运行的基础上改动输入,推演指标的变化(证据面板里口径卡上的数,run/WhatIf.tsx)。 + * 推演永远不是出具:横幅要说清不会写进运行记录、不会改动报告。行号对人一律从 1 数(和查询结果表格的 # 列一致) + */ export const WHATIF_TEXT = { title: '数字推演', + open: '推演', + openHint: '改动输入或排除查询结果中的行,查看这个数和报告会如何变化', + close: '收起推演', + banner: '推演,非出具:不会写进运行记录,也不会改动报告', + unsealed: '运行未封存,数据可能还会变', + sealBroken: '封存核对未通过,推演所依据的数据可能已被改动', + loading: '推演中…', + result: '推演结果', + unchanged: '无变化', + delta: (text: string) => `变化 ${text}`, + substituted: '推演代入式', + inputs: '输入', + original: (value: string) => `原值 ${value}`, + inputLabel: (path: string) => `${path} 的推演值`, + notNumber: '请输入数值', + masked: '已遮罩', + excludedRows: (rows: number[]) => `已排除第 ${rows.map((r) => r + 1).join('、')} 行`, + pickRows: (alias: string) => `在查询 ${alias} 中勾选要排除的行`, + rowsHint: '勾选的行在推演中视为不存在', + excludeHead: '排除', + excludeRow: (row: number) => `排除第 ${row + 1} 行`, + excludedCount: (n: number) => `已排除 ${n} 行`, + segments: '报告中会变的地方', + segmentsNone: (n: number) => `报告中引用这个指标的 ${n} 处不受影响`, + segmentsUnknown: '这个指标无法推演,报告中引用它的地方会如何变化无法确定', + locate: '定位', + inReport: (node: string) => `另一份报告(${node})`, + unsupported: '不支持推演的输入', + wholeMetric: '整个指标', + affected: '可能受影响的下游口径卡', + affectedHint: '这些口径卡引用了本卡的指标,推演不会重算它们', + affectedCard: (caliber: string, version: string) => `口径卡「${caliber || '未命名'}」${version ? ` ${version}` : ''}`, + indirect: '间接引用', + reset: '恢复原值', + empty: '这个指标的计算式没有引用任何输入,无可推演', } /** 双盲复算节点:节点库说明、检查器和运行结果 */ diff --git a/frontend/src/run/EvidencePanel.tsx b/frontend/src/run/EvidencePanel.tsx index b4b9dd14..0f98a344 100644 --- a/frontend/src/run/EvidencePanel.tsx +++ b/frontend/src/run/EvidencePanel.tsx @@ -30,6 +30,7 @@ import { useEvidenceHost } from './evidenceHost' import { EvidenceProvenance } from './EvidenceProvenance' import { CopyChip } from './Markdown' import { SqlCheckList } from './SqlChecks' +import { WhatIf, WhatIfRows, WhatIfToggle, useWhatIfDraft } from './WhatIf' /** * 证据面板:点开报告里的一个片段,看它从哪来。 @@ -63,6 +64,9 @@ import { SqlCheckList } from './SqlChecks' * Excel 导入期 4:上传表格的单元格多三节——数据版本、推断的来源、相关核对(EvidenceProvenance)。只在片段是单元格 * 引用、且片段接口的查询步骤带 provenance: true 时请求推断来源接口;推断来源的缓存只在面板开着期间有效。 * + * 数字推演(WhatIf.tsx):指标步骤上的「推演」展开推演区,改输入的值、在查询步骤里勾掉几行,看这个数和报告会变成 + * 多少。推演不是出具,不写运行记录、不改报告。勾选框只在推演时出现在查询步骤的结果窗口里。 + * * 四种摆法:side 从右侧弹出(宽屏),drawer 从底部抽出(窄屏),inline 在 360px 的 * 画布右栏里直接栏内展开,dock 放进页面给的一块常驻位置(记录页的「证据」页签)。 * 都不是模态的:开着面板照样能在正文里走。 @@ -161,7 +165,7 @@ export function EvidencePanel({ id, mode, doc, artifact, runId, runClass, view, ? : found ? + unit={found.unit} block={found.block} onViolations={onViolations} onLocate={onLocate} /> : claimAt ? @@ -205,11 +209,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 +301,22 @@ 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` + // 能勾行的查询步骤:指标的输入(单元格取数、Agent 字段)落在它上面。合并查询的输入步骤不给——指标引用的是合并结果 + const pickable = new Set(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 +391,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 && whatifCard && whatifMetric && ( + + )} + )} {isMetric && inputs.some(notableInput) && ( @@ -396,7 +424,10 @@ function SegmentBody({ panelId, doc, artifact, runId, runClass, seg, unit, block )} {queries.map((q, i) => ( - + whatif.toggleRow(q.artifact!, row) } + : undefined} /> ))} {provenanceOn && runId && } @@ -1073,8 +1104,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 inputs: EvidenceInput[] @@ -1090,6 +1121,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 +1166,7 @@ function MetricPart({ step, entry, inputs, runId, seal, pending, failed, resolve {EVIDENCE_TEXT.sqlCheckFailed} )} + {whatif && } {(caliber || version || artifact || from) && (
@@ -1194,6 +1230,7 @@ function MetricPart({ step, entry, inputs, runId, seal, pending, failed, resolve {pending ? EVIDENCE_TEXT.chainPending : failed || (runId ? EVIDENCE_TEXT.chainMissing : EVIDENCE_TEXT.noRun)}

)} + {children} ) } @@ -1322,7 +1359,11 @@ 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[] + /** 推演时:结果窗口每行前面加勾选框,勾掉的行在推演里视为不存在 */ + pick?: { excluded: number[]; onToggle: (row: number) => void } +}) { const host = useEvidenceHost() const win = useMemo(() => queryWindow(step), [step]) const [open, setOpen] = useState(false) @@ -1412,9 +1453,13 @@ function QueryPart({ id, step, seal, masked }: { id: string; step: EvidenceStep; )} {win.columns.length > 0 && win.rows.length > 0 && (
0 && 'mt-1.5')}> - + {pick && win.index + ?
)} {!win.rows.length && ( diff --git a/frontend/src/run/WhatIf.tsx b/frontend/src/run/WhatIf.tsx new file mode 100644 index 00000000..e17d0223 --- /dev/null +++ b/frontend/src/run/WhatIf.tsx @@ -0,0 +1,457 @@ +import { useCallback, useEffect, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from 'react' +import clsx from 'clsx' +import { CornerDownRight, FlaskConical, LocateFixed, RotateCcw } from 'lucide-react' +import { api } from '../api/client' +import { ErrorNotice, Spinner, isComposing } from '../components/ui' +import { evidenceValue as valueText, type queryWindow } from '../lib/evidence' +import { NONE } from '../lib/format' +import { WHATIF_TEXT } from '../lib/terms' +import type { WhatIfInput, WhatIfMetric, WhatIfOverrides, WhatIfRequest, WhatIfResult } from '../types' + +/** + * 数字推演:证据面板里点开口径卡上的一个数,改某个输入的值、或者在查询结果里勾掉几行,立即看到这个指标和报告里 + * 引用它的地方会变成多少(POST …/evidence/whatif,后端 engine/recompute.py 按口径卡同一套规则重算)。 + * + * 推演永远不是出具:不写进运行记录、不改报告。顶上的横幅一直在,运行没封存时另说「数据可能还会变」。 + * + * 三样东西分开放: + * - useWhatIfDraft:改动的草稿(输入框里的原文、提交了的新值、勾掉的行)。放在证据面板的片段那一层(SegmentBody), + * 推演区和查询步骤的勾选框共用一份;同一个指标的几处引用之间来回切不清空,换了指标才清空 + * - WhatIf:推演区。输入框停顿一会儿(或回车、失焦)才提交,勾行立刻提交;请求在路上时上一次的结果变淡留着, + * 新的改动来了旧请求直接丢掉。答复按请求体缓存,「恢复原值」回到原来那份不再请求 + * - WhatIfRows:推演时查询步骤里的结果窗口换成它,每行前面多一个勾选框 + * + * 不能改的输入(文本、列表、遮罩列、决定取哪一格的下标)照实显示,原因列在「不支持推演的输入」里。 + */ + +/** 输入框停顿多久提交一次:边打字边请求,结果跟着抖 */ +const SETTLE_MS = 450 + +interface DraftState { + scope: string + open: boolean + /** 输入框里的原文。没碰过的输入不在里面,框里显示原值 */ + text: Record + /** 已提交的新值:请求按它发 */ + inputs: Record + /** 勾掉的行:查询快照的工件 id → 快照里的行号(从 0 数) */ + exclude: Record +} + +const freshDraft = (scope: string, open = false): DraftState => ({ scope, open, text: {}, inputs: {}, exclude: {} }) + +export interface WhatIfDraft { + open: boolean + toggle: () => void + text: Record + /** 输入框改了:停顿一会儿才提交。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): Record { + const out: Record = {} + 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(() => freshDraft(scope)) + // 换了一个指标(另一张卡、另一个数,或者不是指标了):推演收起、改动清空 + const state = stored.scope === scope ? stored : freshDraft(scope) + if (stored.scope !== scope) setState(state) + const timer = useRef>(undefined) + const olds = useRef>({}) + 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, + } +} + +/** 指标步骤上的「推演」开关 */ +export function WhatIfToggle({ open, onToggle, controls }: { open: boolean; onToggle: () => void; controls: string }) { + return ( + + ) +} + +type Slot = { key: string; status: 'loading' | 'ok' | 'error'; data?: WhatIfResult; error?: unknown; last?: WhatIfResult } + +/** 推演区:横幅、结果、输入、不支持的输入、报告里会变的地方、下游口径卡、恢复原值 */ +export function WhatIf({ id, runId, report, card, metric, draft, queryOf, onLocate }: { + id: string + runId: string + /** 正文这份报告的撰写节点 id:按它选口径卡算过的那一份,报告里会变的地方也只列它的(都能定位) */ + report?: string + /** 口径卡节点 id */ + card: string + metric: string + draft: WhatIfDraft + /** 输入落在哪个查询步骤上:有的话给「在查询 Qn 中勾选要排除的行」,点一下跳过去 */ + queryOf: (artifact?: string) => { alias: string; go: () => void } | undefined + /** 定位到正文里的一个片段 */ + onLocate?: (segId: string) => void +}) { + const body: WhatIfRequest = useMemo(() => ({ ...(report ? { report } : {}), card, metric, overrides: draft.overrides }), + [report, card, metric, draft.overrides]) + const key = JSON.stringify(body) + const [slot, setSlot] = useState({ key: '', status: 'loading' }) + const [nonce, setNonce] = useState(0) + const cache = useRef(new Map()) + useEffect(() => { + const hit = cache.current.get(key) + if (hit) { + setSlot({ key, status: 'ok', data: hit, last: hit }) + return + } + const ctrl = new AbortController() + setSlot((s) => ({ key, status: 'loading', last: s.last })) + api.whatif.run(runId, JSON.parse(key) as WhatIfRequest, { signal: ctrl.signal }).then((data) => { + cache.current.set(key, data) + setSlot({ key, status: 'ok', data, last: data }) + }, (error: unknown) => { + if ((error as { name?: string } | null)?.name === 'AbortError') return + setSlot((s) => ({ key, status: 'error', error, last: s.last })) + }) + return () => ctrl.abort() + }, [runId, key, nonce]) + + // 改动之后、请求还没发出去的那一下也算在路上:别拿上一次的答复当这次的 + const status = slot.key === key ? slot.status : 'loading' + const data = status === 'ok' ? slot.data : slot.last + const loading = status === 'loading' + const m: WhatIfMetric | undefined = data?.metrics.find((x) => x.id === metric) ?? data?.metrics[0] + const unsupported = (data?.unsupported ?? []).filter((u) => u.metric === metric) + const unknown = !!m && m.rendered_new == null + const changedSegs = (data?.segments ?? []).filter((s) => s.changed) + + return ( +
+ {/* 醒目靠底色、左边的色条和图标;字用正文色:提醒色的字压在同色的浅底上,浅色主题下对比度不到 4.5 */} +

+ + {WHATIF_TEXT.banner} +

+ {data && !data.sealed && ( +

+ {data.seal.sealed && data.seal.ok === false ? WHATIF_TEXT.sealBroken : WHATIF_TEXT.unsealed} +

+ )} + + {status === 'error' && setNonce((n) => n + 1)} />} + {!data && loading && ( +

{WHATIF_TEXT.loading}

+ )} + + {m && status !== 'error' && ( +
+
{WHATIF_TEXT.result}
+
+ {m.rendered_old} + → + {m.rendered_new ?? NONE} + {m.rendered_delta + ? {WHATIF_TEXT.delta(m.rendered_delta)} + : m.changed === false && {WHATIF_TEXT.unchanged}} + {loading && } +
+ {m.reason &&

{m.reason}

} + {m.status === 'ok' && m.changed && m.substituted && ( +
+
{WHATIF_TEXT.substituted}
+ + {m.substituted} + +
+ )} +
+ )} + + {m && ( +
+
{WHATIF_TEXT.inputs}
+ {m.inputs.length ? ( +
    + {m.inputs.map((inp, i) => ( + + ))} +
+ ) :

{WHATIF_TEXT.empty}

} +
+ )} + + {unsupported.length > 0 && ( +
+
{WHATIF_TEXT.unsupported}
+
    + {unsupported.map((u) => ( +
  • + {u.input ?? WHATIF_TEXT.wholeMetric} + :{u.reason} +
  • + ))} +
+
+ )} + + {m && !!data?.segments.length && ( +
+
{WHATIF_TEXT.segments}
+ {unknown ?

{WHATIF_TEXT.segmentsUnknown}

+ : changedSegs.length ? ( +
    + {changedSegs.map((s) => ( +
  • + {s.rendered_old} + → + {s.rendered_new} + {onLocate && (!report || s.report === report) + ? ( + + ) + : {WHATIF_TEXT.inReport(s.report)}} +
  • + ))} +
+ ) :

{WHATIF_TEXT.segmentsNone(data.segments.length)}

} +
+ )} + + {!!data?.affected_cards.length && ( +
+
{WHATIF_TEXT.affected}
+

{WHATIF_TEXT.affectedHint}

+
    + {data.affected_cards.map((c) => ( +
  • + {WHATIF_TEXT.affectedCard(c.caliber, c.version)} + {!c.direct && · {WHATIF_TEXT.indirect}} +
  • + ))} +
+
+ )} + +
+ + {loading && data && {WHATIF_TEXT.loading}} +
+
+ ) +} + +/** 一个输入:能改的给输入框(原值写在旁边),别的照实显示;排除了几行、去哪一步勾行,写在下面 */ +function InputRow({ id, input, draft, link }: { + id: string; input: WhatIfInput; draft: WhatIfDraft; link?: { alias: string; go: () => void } +}) { + 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) => { + 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 fromQuery = !!link && !input.masked && (input.kind === 'container' || !!input.locator) + return ( +
  • +
    {input.path}
    + {input.masked ? ( +

    {WHATIF_TEXT.masked}

    + ) : input.editable ? ( +
    + draft.type(input.path, e.target.value, input.old)} + onKeyDown={onKeyDown} onBlur={draft.commit} data-whatif-field="" /> + {WHATIF_TEXT.original(valueText(input.old))} + {invalid && {WHATIF_TEXT.notNumber}} +
    + ) : ( +

    + {valueText(input.old)} + {input.changed && <> → {valueText(input.new)}} +

    + )} + {!!input.excluded_rows?.length && ( +

    + {WHATIF_TEXT.excludedRows(input.excluded_rows)} +

    + )} + {fromQuery && ( + + )} +
  • + ) +} + +/** + * 推演时查询步骤里的结果窗口:每行前面一个勾选框,勾掉的行在推演里视为不存在(划掉、变淡)。只有知道每一行 + * 在快照里是第几行时才画(index);被遮罩的列照样写「已遮罩」,高亮的格和平时一样描边 + */ +export function WhatIfRows({ win, hidden, excluded, onToggle }: { + win: ReturnType; hidden: string[]; excluded: number[]; onToggle: (row: number) => void +}) { + 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 ( +
    +
    + + + + {/* 勾选框和行号两列只占自己的宽度:表格撑满窄栏时多出来的宽度留给数据列 */} + + + {win.columns.map((c) => )} + + + + {win.rows.map((row, i) => { + const n = index[i] + const off = excluded.includes(n) + const hit = marked.has(i) + return ( + + + + {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 ( + + ) + })} + + ) + })} + +
    {WHATIF_TEXT.excludeHead}#{c}
    + onToggle(n)} + aria-label={WHATIF_TEXT.excludeRow(n)} /> + {n + 1} + {mask ? {WHATIF_TEXT.masked} + : cell == null ? null + : typeof cell === 'object' ? JSON.stringify(cell) : String(cell)} +
    +
    +
    + {WHATIF_TEXT.rowsHint} + {excluded.length > 0 && ( + {WHATIF_TEXT.excludedCount(excluded.length)} + )} +
    +
    + ) +} diff --git a/frontend/src/types.ts b/frontend/src/types.ts index f37b6540..37d2353c 100644 --- a/frontend/src/types.ts +++ b/frontend/src/types.ts @@ -3020,3 +3020,116 @@ export interface SqlCheckItem { relation_id?: string sql_excerpt?: string } + +// =========================================================================== +// 数字推演(后端 app/api/whatif.py、app/engine/recompute.py):在一次运行的口径卡上改输入、排除查询快照里的行, +// 看指标和报告里引用它的地方会变成多少。推演不是出具:不写运行记录、不改报告 +// =========================================================================== + +/** 推演的改动:输入路径 → 新值;查询快照的工件 id → 要排除的行号(快照里的行号,从 0 数) */ +export interface WhatIfOverrides { + inputs: Record + exclude_rows: Record +} + +/** 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 & {}) + /** 数值(或原本缺失)的标量、不是遮罩列、不决定取哪一格:可以改 */ + editable: boolean + /** 原值、推演用的值。容器写大概(「[12 项]」);遮罩列的一律是 null */ + old?: unknown + new?: unknown + changed?: boolean + /** 起了作用的被排除行(快照里的行号,从 0 数) */ + excluded_rows?: number[] + masked?: boolean +} + +/** + * unchanged:没碰到改动,原值原样交回;ok:重算了;excluded:排除行后缺了输入,算不出来;error:新值让计算出错(除以零……); + * unsupported:有输入的完整值找不回来,推演不了;masked:用到了遮罩列,不推演 + */ +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:整个指标都推演不了(口径卡没记输入) */ + input: string | null + reason: string +} + +/** 引用了这张口径卡的下游口径卡:只标可能受影响,不重算 */ +export interface WhatIfAffectedCard { + node_id: string + artifact: string + caliber: string + version: string + metrics: string[] + /** 直接引用(false 是经别的卡间接引用) */ + direct: boolean +} + +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[] +} diff --git a/scripts/check-all.mjs b/scripts/check-all.mjs index 2002181e..2ea23576 100644 --- a/scripts/check-all.mjs +++ b/scripts/check-all.mjs @@ -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: 1, whatif: 1, + schedules: 1, compare: 1, verify: 1, inquiry: 1, bundle: 1, whatif: 25, } // 最慢的两项按段拆成几份。用的是它们自己的段过滤:最后一份用 *_SKIP 兜住「其余全部」,以后新加的段 // 不用改这里也跑得到(拆出去的那几份要是一段都没对上,那一份会报「一项都没跑」)。 diff --git a/scripts/check-whatif.mjs b/scripts/check-whatif.mjs index eb9cae7b..8f57c164 100644 --- a/scripts/check-whatif.mjs +++ b/scripts/check-whatif.mjs @@ -1,8 +1,423 @@ -// 数字推演的检查。现在只是占位:功能还在开发,这里只打一行通过,让 check-all 的清单先排上它。 -// 数字推演的工作包把它换成真检查:沿用别的检查的输出格式——每项缩进两格、以 ✓ / ✗ 开头,最后顶格一行 -// 总结,没过的退出码非 0(check-all 按缩进的 ✓ / ✗ 计数)。 +// 数字推演(证据面板里口径卡上的数,run/WhatIf.tsx)的回归检查。 +// +// 守的是这些「看着没坏、其实用不了」的地方:横幅没了或者不醒目(推演被当成出具)、边打字边发请求、请求体里的 +// 输入路径和行号不对(行号对人从 1 数,对接口从 0 数)、勾选框在不推演时也冒出来、恢复原值之后还留着一行没勾回去、 +// 不支持的输入一声不吭、窄屏(390px)被推演区撑出横向滚动、浅色主题下横幅看不清。 +// +// 跑在预览页上:/preview.html?syn=whatif(宽屏右侧弹出、窄屏底部抽出)和 ?syn=whatif-rail(360px 画布右栏)。 +// 文档是 frontend/src/run/__tests__/evidence-query.json 里后端 compose_doc 真跑出来的(只用通用名);片段接口 +// 按它的 segments 作答,推演接口按后端 engine/recompute.py 的规则在这里算(只覆盖用到的三个指标),非 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 改成老运行的容器输入(推演不了的那种) */ +function segmentReply(sid) { + const body = structuredClone(fx.segments[sid]) + if (sid === 's22') { + body.chain[0] = { ...body.chain[0], expression: 'sum(vars.adjust.items)', substituted: 'sum(vars.adjust.items)' } + body.chain[1] = { step: 'input', path: 'vars.adjust.items', value: '[4 项]', node_id: 'adjust', via: 'code', + field: 'items', role: 'compute', 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 thousands1 = (v) => v.toLocaleString('en-US', { minimumFractionDigits: 1, maximumFractionDigits: 1 }) + +/** 推演接口在这里按后端的规则算:给了新值的用新值;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: [] } + if (body?.metric === 'adj') { + return { ...base, metrics: [{ id: 'adj', name: '调整后销售额', unit: '元', old: 44000, new: 44000, delta: 0, + rendered_old: '44,000.0元', rendered_new: '44,000.0元', rendered_delta: null, changed: false, status: 'unchanged', + reason: null, substituted: 'sum(vars.adjust.items)', + inputs: [{ path: 'vars.adjust.items', via: 'code', node_id: 'adjust', kind: 'container', editable: false, + old: '[4 项]', new: '[4 项]', changed: false }] }], + segments: [{ report: 'write', unit: 'u4', sid: 's22', metric: 'adj', rendered_old: '44,000.0元', rendered_new: '44,000.0元', changed: false }], + unsupported: [{ metric: 'adj', input: 'vars.adjust.items', reason: '无法推演:当时没有保存这个输入的完整值' }] } + } + const def = METRICS[body?.metric] + const step = chainOf(def.sid)[0] + const views = inputsOf(def.sid).map((inp) => { + const row = inp.locator?.row + const view = { path: inp.path, via: inp.via, node_id: inp.node_id, artifact: inp.artifact, locator: inp.locator, + 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: [], + 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 }] } +} + +// ---------------------------------------------------------------- 页面 + +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 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() + 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, 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() +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) + 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 } = await open('whatif') + await openMetric(page, 's22') + await openWhatIf(page) + check('不支持推演的输入列出原因', (await text(page, '[data-whatif-unsupported-input="vars.adjust.items"]')) + .includes('无法推演:当时没有保存这个输入的完整值')) + check('容器输入不给输入框', await page.locator('[data-whatif-field]').count() === 0 + && (await text(page, '[data-whatif-input="vars.adjust.items"] [data-whatif-value]')).includes('[4 项]')) + 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() +}) + +/** 页面和面板正文都没有横向滚动(表格自己的横向滚动条不算:那是表格容器里的) */ +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}`) + 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() + } +}) + +await browser.close() +console.log(failed ? `\n✗ 数字推演:${failed} 项未通过` : '\n✓ 数字推演:全部通过') +process.exit(failed ? 1 : 0) From cb141cea88353f13278a4a794c5a7a3d50ba9a19 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Mon, 5 Oct 2026 04:13:33 +0800 Subject: [PATCH 05/12] =?UTF-8?q?=E6=95=B0=E5=AD=97=E6=8E=A8=E6=BC=94?= =?UTF-8?q?=EF=BC=9A=E7=94=A8=E5=88=B0=E9=81=AE=E7=BD=A9=E5=88=97=E7=9A=84?= =?UTF-8?q?=E6=8C=87=E6=A0=87=E4=B8=8D=E7=BB=99=E4=BB=A3=E5=85=A5=E5=BC=8F?= =?UTF-8?q?=EF=BC=9B=E7=9C=9F=E5=8D=A1=E4=B8=8A=E6=A0=B8=E5=AF=B9=E8=BF=98?= =?UTF-8?q?=E5=8E=9F=E6=98=AF=E5=90=A6=E5=BF=A0=E5=AE=9E=E3=80=81=E5=B0=81?= =?UTF-8?q?=E5=AD=98=E5=90=8E=E6=8F=92=E8=BF=9B=E6=9D=A5=E7=9A=84=E5=8D=A1?= =?UTF-8?q?=E4=B8=8D=E8=AE=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 代入式里代进去的就是遮罩列的那一格:用到遮罩列的指标,推演结果里的 substituted 一律为空(输入值本来就不给) - 测试:真跑出来的每张卡(cell() 取数、整份查询结果、nodes.* 容器、agent 数组字段的两种引用、下游口径卡),什么都不改 强制重算,值和卡上记的一模一样 - 测试:封存之后插进来的 node.finished 指向一张伪造的指标集,推演照旧用封存范围内的那张 --- backend/app/engine/recompute.py | 2 ++ backend/tests/test_recompute.py | 2 ++ backend/tests/test_whatif_api.py | 52 ++++++++++++++++++++++++++++++++ 3 files changed, 56 insertions(+) diff --git a/backend/app/engine/recompute.py b/backend/app/engine/recompute.py index 12eda73d..bf2bc524 100644 --- a/backend/app/engine/recompute.py +++ b/backend/app/engine/recompute.py @@ -540,6 +540,8 @@ def _result(plan: _Plan, status: str, new: Any, reason: str | None, values: dict 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 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, diff --git a/backend/tests/test_recompute.py b/backend/tests/test_recompute.py index 6d30757c..83081459 100644 --- a/backend/tests/test_recompute.py +++ b/backend/tests/test_recompute.py @@ -147,6 +147,8 @@ def test_a_baseline_lists_what_cannot_be_used_without_recomputing_anything(): # 遮罩列的值不给 [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} diff --git a/backend/tests/test_whatif_api.py b/backend/tests/test_whatif_api.py index d340a6e9..13b90b59 100644 --- a/backend/tests/test_whatif_api.py +++ b/backend/tests/test_whatif_api.py @@ -214,6 +214,52 @@ async def test_changing_an_input_of_one_metric(client, monkeypatch): 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) + loader = api_whatif._loader(sealed, cards) + sources = recompute.Sources(load=loader, queries=tuple(sealed.queries), + outputs=api_whatif._outputs_before(sealed, started), + masked=await api_whatif._hidden(sealed, loader)) + for metric in card["metrics"]: + again = 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) @@ -315,6 +361,7 @@ async def test_masked_columns_are_neither_shown_nor_used(client, monkeypatch, sh 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")] @@ -367,6 +414,7 @@ async def test_node_containers_come_from_the_sealed_node_output(client, monkeypa 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) @@ -417,6 +465,8 @@ async def test_agent_array_fields_follow_the_excluded_rows(client, monkeypatch): 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 @@ -439,6 +489,8 @@ async def test_downstream_cards_are_flagged_only_when_something_changes(client, {"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"] From 24fc21cb566ca5016213843d9645b99dbff35d39 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Mon, 5 Oct 2026 04:14:56 +0800 Subject: [PATCH 06/12] =?UTF-8?q?=E6=95=B0=E5=AD=97=E6=8E=A8=E6=BC=94?= =?UTF-8?q?=EF=BC=9A=E7=AE=97=E5=87=BA=E6=97=A0=E7=A9=B7=E5=A4=A7=E3=80=81?= =?UTF-8?q?=E9=9D=9E=E6=95=B0=E6=97=B6=E8=AF=B4=E6=B8=85=E7=AE=97=E4=B8=8D?= =?UTF-8?q?=E5=87=BA=E6=9D=A5=EF=BC=8C=E4=B8=8D=E8=AE=A9=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=E5=9C=A8=20JSON=20=E7=BC=96=E7=A0=81=E6=97=B6=20500?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 改了输入之后溢出成无穷大(或算出非数),以前照 ok 交回,Starlette 编 JSON 时拒收这种浮点数,整个请求 500。 现在按计算出错处理(status: error,写明原因);老卡上本来就记着无穷大的值和输入,交回时换成 null(口径卡渲染成「—」)。 --- backend/app/engine/recompute.py | 12 ++++++++++-- backend/tests/test_recompute.py | 15 +++++++++++++++ 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/backend/app/engine/recompute.py b/backend/app/engine/recompute.py index bf2bc524..8636d24e 100644 --- a/backend/app/engine/recompute.py +++ b/backend/app/engine/recompute.py @@ -473,6 +473,9 @@ def _compute(plan: _Plan, values: dict[str, Any], notes: dict[str, list[int]], if inp.row is not None and path in notes and path not in changes.inputs: return "excluded", None, f"{EXCLUDED}:{path} 所在的第 {inp.row + 1} 行已排除" value, reason = _evaluate(plan, values) + if reason is None and isinstance(value, float) and not math.isfinite(value): + # 溢出成无穷大、算出非数:口径卡渲染成「—」,这里也说清算不出来(JSON 里也放不下这种值) + reason = "计算结果不是有限的数值(溢出或非数),无法推演" return ("ok", value, None) if reason is None else ("error", None, reason) @@ -545,7 +548,7 @@ def _result(plan: _Plan, status: str, new: Any, reason: str | None, values: dict 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": old, "new": new, "delta": delta, + "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, @@ -562,6 +565,11 @@ def _render(metric: dict[str, Any], value: Any, conv: str | None = None) -> str: return MISSING +def _finite(value: Any) -> Any: + """无穷大、非数换成 None:老卡上可能记着(口径卡渲染成「—」),JSON 里放不下。""" + return None if isinstance(value, float) and not math.isfinite(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)) @@ -620,7 +628,7 @@ def _input_view(inp: _Input, values: dict[str, Any], notes: dict[str, list[int]] new = _outline(values.get(inp.path), inp.table) if inp.problem is None else None changed = inp.problem is None and not _same(old, new) else: - old, new = item.get("value"), values.get(inp.path) + 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: diff --git a/backend/tests/test_recompute.py b/backend/tests/test_recompute.py index 83081459..1b9b6594 100644 --- a/backend/tests/test_recompute.py +++ b/backend/tests/test_recompute.py @@ -218,6 +218,21 @@ def test_division_by_zero_is_explained(): assert wow["status"] == "error" and wow["new"] is None and wow["reason"] == "除以零" +def test_an_overflow_is_an_error_not_a_crash(): + """算出无穷大:说清算不出来;老卡上记着无穷大的也不往外送(JSON 放不下,接口会 500)。""" + import json + + 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, From ca09aed6120ceb59badfc483eadb0c5104c57dd3 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Mon, 5 Oct 2026 04:16:01 +0800 Subject: [PATCH 07/12] =?UTF-8?q?check-whatif=20=E8=A1=A5=E7=A9=BA?= =?UTF-8?q?=E6=80=81=EF=BC=9A=E5=8E=9F=E5=BC=8F=E6=B2=A1=E6=9C=89=E5=BC=95?= =?UTF-8?q?=E7=94=A8=E8=BE=93=E5=85=A5=E6=97=B6=E8=AF=B4=E6=B8=85=E6=97=A0?= =?UTF-8?q?=E5=8F=AF=E6=8E=A8=E6=BC=94=EF=BC=8C=E4=B8=8D=E7=94=BB=E7=A9=BA?= =?UTF-8?q?=E5=88=97=E8=A1=A8=EF=BC=8C=E4=B9=9F=E4=B8=8D=E7=94=BB=E3=80=8C?= =?UTF-8?q?=E6=8A=A5=E5=91=8A=E4=B8=AD=E4=BC=9A=E5=8F=98=E7=9A=84=E5=9C=B0?= =?UTF-8?q?=E6=96=B9=E3=80=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- scripts/check-whatif.mjs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/scripts/check-whatif.mjs b/scripts/check-whatif.mjs index 8f57c164..4933764e 100644 --- a/scripts/check-whatif.mjs +++ b/scripts/check-whatif.mjs @@ -83,6 +83,12 @@ function whatifReply(body) { segments: [{ report: 'write', unit: 'u4', sid: 's22', metric: 'adj', rendered_old: '44,000.0元', rendered_new: '44,000.0元', changed: false }], unsupported: [{ metric: 'adj', input: 'vars.adjust.items', 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) => { @@ -301,6 +307,16 @@ await section('不支持的输入', async () => { 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 }) From 09237a4c9947248e6802a814a7a90a5a9d9b4cb3 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Mon, 5 Oct 2026 05:43:17 +0800 Subject: [PATCH 08/12] =?UTF-8?q?=E6=95=B0=E5=AD=97=E6=8E=A8=E6=BC=94?= =?UTF-8?q?=E5=A4=8D=E6=A0=B8=E4=BF=AE=E6=AD=A3=EF=BC=88=E7=AC=AC=201=20?= =?UTF-8?q?=E8=BD=AE=EF=BC=8C=E5=90=8E=E7=AB=AF=EF=BC=89=EF=BC=9A=E6=8E=92?= =?UTF-8?q?=E9=99=A4=E8=A1=8C=E6=97=B6=E8=AF=B4=E4=B8=8D=E5=87=86=E7=9A=84?= =?UTF-8?q?=E6=8C=87=E6=A0=87=E4=B8=8D=E5=86=8D=E6=8A=A5=E3=80=8C=E6=97=A0?= =?UTF-8?q?=E5=8F=98=E5=8C=96=E3=80=8D=EF=BC=8C=E5=BF=AB=E7=85=A7=E8=AF=BB?= =?UTF-8?q?=E4=B8=8D=E5=87=BA=E6=9D=A5=E6=97=B6=E4=B8=8D=E7=BB=99=E5=80=BC?= =?UTF-8?q?=EF=BC=8C=E9=81=AE=E7=BD=A9=E6=8C=89=E7=94=A8=E5=88=B0=E7=9A=84?= =?UTF-8?q?=E5=BF=AB=E7=85=A7=E5=9C=A8=E7=BA=BF=E7=A8=8B=E9=87=8C=E7=AE=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 排除了行,指标却有输入对不上任何快照(老运行没存完整值的容器、加工过的结果、按位置从整份结果里取的一格、由查询结果 算出来的数):以前一律报「无变化」、报告引用处报「不受影响」,或者拿原值算出一个不对应任何一份数据的数。现在回 unsupported 并写明是哪个输入说不准;写它的节点在那份快照交回之前就跑完的影响不到它,照常不算(按事件序号比先后)。 卡上没记全输入的指标,有任何改动都标 unsupported - 查询快照文件不在、内容与哈希不一致时,落在它上面的 cell()、agent 字段不给值、不能改、不给代入式,用到它的指标推演 不了;遮罩照样按台账记的数据源算,不再因为快照坏了就失效 - 遮罩改成用到哪份快照才算哪份:读快照放进重算的工作线程,查库交回事件循环。以前每次请求都在事件循环里把这次运行的 全部快照读一遍、复验一遍哈希 - 输入带 row_span(实际用到的快照行);新增 GET …/evidence/whatif/rows,按页取封存范围内一份快照的行(遮罩列写 「已遮罩」,只读)。界面据此给整份结果勾行、只让用到的行可勾 - 不能改、也没有行可勾的输入(对不上快照的列表、文本)列进「不支持推演的输入」并写明原因 - 下游口径卡顺着画布的边找,经中间节点用到卡上值的也标;改动碰到了指标、它却推演不了时也标「可能受影响」 - 超大整数不再让接口 500:新值超出可计算范围回 422,算出浮点放不下的整数按「不是有限的数值」说明;非法值的说明不露出 None、单引号这些 Python 写法 - 补测试并逐个做过变异:封存核对没过、事后加的遮罩、合并查询的遮罩、指标集被改(409)、两份报告、循环里先算卡后算 产出、手写事件核对取哪次执行和边界、重算的几处保护、勾行接口。取整和口径卡逐个对拍(含二进制半中间的数、负小数位): metrics.py 只许加 value_artifact,取整没法抽成共用函数,先用对拍守着 --- backend/app/api/whatif.py | 188 ++++++++++++-- backend/app/engine/recompute.py | 200 +++++++++++--- backend/tests/test_recompute.py | 241 ++++++++++++++++- backend/tests/test_whatif_api.py | 345 ++++++++++++++++++++++++- backend/tests/test_whatif_selection.py | 87 +++++++ 5 files changed, 989 insertions(+), 72 deletions(-) create mode 100644 backend/tests/test_whatif_selection.py diff --git a/backend/app/api/whatif.py b/backend/app/api/whatif.py index 98357945..adb2f29d 100644 --- a/backend/app/api/whatif.py +++ b/backend/app/api/whatif.py @@ -4,6 +4,9 @@ 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 为假: @@ -15,6 +18,7 @@ vars.* 的完整值(value_artifact)只认封存的指标集里写着的。 from __future__ import annotations import asyncio +from collections.abc import Iterator, Mapping from dataclasses import replace from typing import Any @@ -22,7 +26,10 @@ 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, @@ -50,6 +57,10 @@ BAD_REQUEST_TEXT = ("请求格式有误:card 应为口径卡节点的 ID;rep 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") @@ -69,17 +80,18 @@ async def evidence_whatif(run_id: str, payload: Any = Body(None)) -> dict[str, A 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) - loader = _loader(sealed, cards) - sources = recompute.Sources(load=loader, queries=tuple(sealed.queries), - outputs=_outputs_before(sealed, started), masked=await _hidden(sealed, loader)) + 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 = any(m.get("changed") for m in result["metrics"]) + # 改动可能改变了某个指标——算出来变了,或者碰到了它却推演不了(还原不了、遮罩),新值不知道——下游才可能受影响 + maybe = any(m.get("changed") is not False for m in result["metrics"]) + 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 "", @@ -91,11 +103,66 @@ async def evidence_whatif(run_id: str, payload: Any = Body(None)) -> dict[str, A "metrics": result["metrics"], "segments": segments, "unsupported": result["unsupported"], - # 下游口径卡只在这次推演确实改变了指标时才标:什么都没变,下游也不会变 - "affected_cards": recompute.downstream_cards(cards, card_node) if changed else [], + # 什么都没变,下游也不会变;顺着画布的边找,经中间节点用到卡上值的下游卡也标 + "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]]]: @@ -170,6 +237,16 @@ def _card_of(sealed: _Sealed, cards: list[tuple[str, str, dict[str, Any]]], node 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] = {} @@ -181,6 +258,33 @@ def _outputs_before(sealed: _Sealed, started: int) -> dict[str, str]: 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——写在内容寻址、又在封存范围内的指标集里,属于封存链的延伸)。 @@ -204,23 +308,53 @@ def _loader(sealed: _Sealed, cards: list[tuple[str, str, dict[str, Any]]]) -> An return loader -async def _hidden(sealed: _Sealed, loader: Any) -> dict[str, frozenset[str]]: - """封存范围内每份查询快照要遮的列(小写):查询当时记下的加数据源现在设的,合并查询按它合并的那几个数据源算。 - 和证据面板查询步骤的遮罩同一套(api/evidence.py 的 _query_step)。取不回来、被改过的快照不算:重算也不会用它。 - 快照经推演用的同一个 loader 取,读过的重算时不再读盘。""" - masks = _Masks() - out: dict[str, frozenset[str]] = {} - for artifact, info in sealed.queries.items(): - try: - snap = loader(artifact) - except ValueError: - continue - if not isinstance(snap, dict): - continue - if snap.get("source") == MERGE_SOURCE: - hidden, _ = await _merge_masks(snap, masks) - else: - hidden = (await masks.of(info.get("source") or snap.get("source")))[0] | _recorded_masks(snap) - if hidden: - out[artifact] = frozenset(hidden) - return out +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()) diff --git a/backend/app/engine/recompute.py b/backend/app/engine/recompute.py index 8636d24e..2463e5c5 100644 --- a/backend/app/engine/recompute.py +++ b/backend/app/engine/recompute.py @@ -15,14 +15,18 @@ round(和 metrics.run_metrics 一样只 round 浮点),渲染走 evidence.r - vars.*:有 value_artifact(口径卡当时另存的完整值)才还原得出来;老运行照实说当时没有保存 - 容器本身是一份查询结果(带 artifact 的 {columns, rows},或者和某份快照的 rows 一模一样的列表):排除行就去掉那几行 - 遮罩列取来的输入不给值、也不拿来推演:改一个输入、排除一行,新值和原值一比就能算出遮住的那一格 +- 落在读不出来(文件不在、与哈希不一致)的查询快照上的输入同样不给值、不推演:那一格遮没遮核对不了,宁可多遮 同一张口径卡的指标不能互相引用(算这张卡时卡上的值还不存在),所以只有用到了被改的输入、被排除的行的指标需要重算, -别的原样交回。 +别的原样交回。排除行时有一种例外:指标的某个输入对不上任何快照(完整值找不回来的容器、加工过的结果、按位置从结果里 +取的一格、由查询结果算出来的数),它可能就是从被排除了行的那份结果来的,重算不了,只能说不知道(unsupported), +不能报「无变化」。写它的节点在那份快照交回之前就跑完了的,影响不到它,照常不算。 """ from __future__ import annotations import ast import copy +import json import math import re from collections.abc import Callable, Iterable, Mapping @@ -50,6 +54,16 @@ MASKED_TABLE = "这份查询结果里有设置了遮罩的列,不能用于推 MASKED_METRIC = "这个指标用到了设置了遮罩的列,不能推演" SELECTOR = "这个输入决定取哪一行、哪一项,修改它需要重新取数,不能推演" EXCLUDED = "排除后无法计算" +UNREADABLE = "查询快照无法读取" +TAMPERED = "查询快照与哈希不一致,疑似被修改" +#: 不能改、也没有行可勾的输入(_fixed) +FIXED_CONTAINER = "列表或对象不能直接修改,也没有对应的查询结果可以排除行" +NOT_NUMBER = "不是数值,不能修改" +#: 排除了行,却说不准这个输入受不受影响(_doubt) +DOUBT = "排除行对 {path} 的影响无法确定:{why}" +DOUBT_UNMATCHED = "它对不上任何查询快照,可能是由查询结果加工而来" +DOUBT_DERIVED = "它不是直接取自查询结果的格,可能由查询结果算出" +NOT_FINITE = "计算结果不是有限的数值(溢出或非数),无法推演" #: 卡上给容器记的大概(metrics._brief):「[12 项]」「{3 个字段}」 _BRIEF = re.compile(r"^(?:\[\d+ 项\]|\{\d+ 个字段\})$") @@ -77,13 +91,18 @@ class Sources: (artifact_store.load 的约定) - queries:封存范围内的查询快照,按在事件里第一次出现的顺序。排除行只认这些快照;容器按内容对快照时也按这个顺序 - outputs:节点 id → 口径卡执行之前它最后一次的产出工件(nodes.*、input.* 的容器、agent 的数组字段从这里还原) - - masked:查询快照 → 要遮的列(小写):查询当时记下的加数据源现在设的 + - 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: @@ -127,6 +146,8 @@ class _Input: rows: tuple[int, int] | None = None table: bool = False masked: bool = False + #: 落在的查询快照读不出来(文件不在、与哈希不一致):遮没遮核对不了,值不给,也不拿来推演 + unreadable: bool = False #: 出现在别的输入的下标、cell() 的行列里:它决定取哪一格,改它要重新取数 selector: bool = False @@ -150,7 +171,8 @@ def whatif(card: dict[str, Any], changes: Changes, sources: Sources, *, metric: """在一张口径卡上推演:{metrics: [每个指标的旧值、新值、输入…], unsupported: [不能用于推演的输入和原因]}。 metric 给了就只推演这一个指标。改动不合法时抛 WhatIfError,一个指标都不算。没碰到改动的指标不重算, - 原值原样交回(status: unchanged);unsupported 不论有没有改动都列全,界面一打开就能说清哪些输入不能动。 + 原值原样交回(status: unchanged);unsupported 不论有没有改动都列全(遮罩的、还原不了的、不能改也没有行可勾的), + 界面一打开就能说清哪些输入不能动。 """ store = _Store(sources) metrics = [m for m in card.get("metrics") or [] if isinstance(m, dict) and m.get("id") is not None] @@ -160,12 +182,12 @@ def whatif(card: dict[str, Any], changes: Changes, sources: Sources, *, metric: raise WhatIfError(f"口径卡中没有指标「{metric}」") plans = [_plan(m, store) for m in metrics] _check(changes, plans, store, metric=metric) - return {"metrics": [_outcome(p, changes) for p in plans], "unsupported": _unsupported(plans)} + return {"metrics": [_outcome(p, changes, sources) for p in plans], "unsupported": _unsupported(plans)} def recompute(metric: dict[str, Any], changes: Changes, sources: Sources) -> dict[str, Any]: """重算一个指标,不管改动碰没碰到它,也不校验改动。核对还原是否忠实时用:什么都不改,重算出来应当和卡上记的一样。""" - return _outcome(_plan(metric, _Store(sources)), changes, force=True) + return _outcome(_plan(metric, _Store(sources)), changes, sources, force=True) # -------------------------------------------------------------------------- @@ -256,6 +278,13 @@ def _restore(item: dict[str, Any], remaining: set[str], nested: set[str], store: 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 @@ -311,7 +340,7 @@ def _table_of(value: Any, store: _Store) -> str | None: 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 + return artifact # 快照读不读得出来由 _restore 核对 rows = value["rows"] elif isinstance(value, list): rows = value @@ -373,7 +402,14 @@ def _span(rows: Any) -> tuple[int, int] | None: def _number(value: Any) -> bool: - return is_number(value) and math.isfinite(value) + """算得动的数: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: @@ -385,10 +421,14 @@ def _check(changes: Changes, plans: list[_Plan], store: _Store, *, metric: str | 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}」的新值需要是数值,当前为「{_shown(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": @@ -411,8 +451,11 @@ def _check(changes: Changes, plans: list[_Plan], store: _Store, *, metric: str | def _shown(value: Any) -> str: - text = str(value) - return text if len(text) <= 40 else text[:40] + "…" + """不合法的新值写给人看:空值写「空值」,文本照原样,别的按 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] + '…'}」" # -------------------------------------------------------------------------- @@ -444,7 +487,7 @@ def _apply(inp: _Input, changes: Changes) -> tuple[Any, list[int] | None, bool]: return inp.value, None, False -def _outcome(plan: _Plan, changes: Changes, *, force: bool = False) -> dict[str, Any]: +def _outcome(plan: _Plan, changes: Changes, sources: Sources, *, force: bool = False) -> dict[str, Any]: values: dict[str, Any] = {} notes: dict[str, list[int]] = {} touched = False @@ -453,15 +496,47 @@ def _outcome(plan: _Plan, changes: Changes, *, force: bool = False) -> dict[str, if excluded: notes[path] = excluded touched = touched or overridden or bool(excluded) - if not touched and not force: + doubt = _doubt(plan, changes, sources) + # 卡上没记全输入的指标:不知道它用了什么,有任何改动都说不准它变不变 + touched = touched or (plan.problem is not None and bool(changes.inputs or changes.exclude)) + if not touched and doubt is None and not force: return _result(plan, "unchanged", plan.metric.get("value"), None, values, notes) - status, new, reason = _compute(plan, values, notes, changes) + status, new, reason = _compute(plan, values, notes, changes, doubt) return _result(plan, status, new, reason, values, notes) -def _compute(plan: _Plan, values: dict[str, Any], notes: dict[str, list[int]], - changes: Changes) -> tuple[str, Any, str | None]: - """(status, 新值, 原因)。还原不了的、遮罩的、排除后缺了的先说,都没有才求值。""" +def _doubt(plan: _Plan, changes: Changes, sources: Sources) -> str | None: + """排除了行,这个指标却有输入说不准受不受影响:返回原因;没排除行、或者输入都对得上号的返回 None。 + + 对得上号的输入(cell() 那一格、agent 的单格字段和数组字段、整份查询结果)排除行怎么影响它是确定的,_apply 照办。 + 别的输入——完整值找不回来的容器、对不上任何快照的容器(加工过的结果)、不是直接取自快照的数(按位置从整份结果里 + 取的一格、transform 由查询结果算出来的数)——都可能来自被排除了行的那份结果,又重算不了,只能说不知道,不能拿 + 原值算出一个「无变化」或者一个不对应任何一份数据的数。给了新值的以新值为准;写它的节点在那份快照交回之前就跑完了 + 的,影响不到它(_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: + 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, 新值, 原因)。还原不了的、遮罩的、排除后缺了的、说不准受不受影响的先说,都没有才求值。""" if plan.problem: return "unsupported", None, plan.problem for path in plan.tops: @@ -472,10 +547,12 @@ def _compute(plan: _Plan, values: dict[str, Any], notes: dict[str, list[int]], for path, inp in plan.inputs.items(): if inp.row is not None and path in notes and path not in changes.inputs: return "excluded", None, f"{EXCLUDED}:{path} 所在的第 {inp.row + 1} 行已排除" + if doubt: + return "unsupported", None, doubt value, reason = _evaluate(plan, values) - if reason is None and isinstance(value, float) and not math.isfinite(value): - # 溢出成无穷大、算出非数:口径卡渲染成「—」,这里也说清算不出来(JSON 里也放不下这种值) - reason = "计算结果不是有限的数值(溢出或非数),无法推演" + 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) @@ -543,8 +620,8 @@ def _result(plan: _Plan, status: str, new: Any, reason: str | None, values: dict 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 for inp in plan.inputs.values()): - substituted = 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, @@ -566,8 +643,8 @@ def _render(metric: dict[str, Any], value: Any, conv: str | None = None) -> str: def _finite(value: Any) -> Any: - """无穷大、非数换成 None:老卡上可能记着(口径卡渲染成「—」),JSON 里放不下。""" - return None if isinstance(value, float) and not math.isfinite(value) else value + """无穷大、非数、浮点放不下的整数换成 None:老卡上可能记着(口径卡渲染成「—」),JSON 里放不下或界面读不准。""" + return None if is_number(value) and not _number(value) else value def _same(a: Any, b: Any) -> bool: @@ -610,19 +687,37 @@ def _kind(inp: _Input) -> str: def _editable(inp: _Input) -> bool: - return inp.shape == "scalar" and not inp.masked and not inp.selector \ + return 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: + """这个输入实际用到的快照行(含两端):单格一行、数组字段一段、整份结果全部。排除别的行影响不到它,界面据此只让 + 这几行可勾。遮罩的、快照读不出来的不给:排除它们的行什么也推演不出来。""" + if inp.snapshot is None or inp.masked or inp.unreadable: + return None + if inp.row is not None: + return inp.row, inp.row + 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]]) -> dict[str, Any]: - """一个输入在推演里的样子:原值、新值、排除了哪几行。遮罩列取来的不给值。容器写大概(「[12 项]」)。""" + """一个输入在推演里的样子:原值、新值、排除了哪几行、用到快照的哪几行(row_span)。遮罩列取来的、落在读不出来的 + 快照上的不给值。容器写大概(「[12 项]」)。""" item = inp.item + span = _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)} 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 @@ -644,7 +739,8 @@ def _outline(value: Any, table: bool) -> Any: def _unsupported(plans: list[_Plan]) -> list[dict[str, Any]]: - """不能用于推演的输入和原因:遮罩的、完整值找不回来的、决定取哪一格的。卡本身没记输入的,整个指标一条。""" + """不能用于推演的输入和原因:遮罩的、完整值找不回来的(含快照读不出来的)、决定取哪一格的、既不能改也没有行可勾的。 + 卡本身没记输入的,整个指标一条。""" out: list[dict[str, Any]] = [] for plan in plans: metric_id = plan.metric.get("id") @@ -654,12 +750,20 @@ def _unsupported(plans: list[_Plan]) -> list[dict[str, Any]]: for inp in plan.inputs.values(): 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 None + 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 + + # -------------------------------------------------------------------------- # 报告里引用的地方、下游口径卡 # -------------------------------------------------------------------------- @@ -703,11 +807,15 @@ def _cites(seg: dict[str, Any], cite: dict[str, Any], entry: dict[str, Any]) -> 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) -> list[dict[str, Any]]: - """引用了这张口径卡的下游口径卡(直接的和经别的卡间接的):[{node_id, artifact, caliber, version, metrics, direct}]。 +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.<卡> 这样的路径)。同一张卡执行过几次的按最后一次。 + 认引用看下游指标的输入从哪个节点来(node_id,或者 nodes.<卡> 这样的路径):直接来自这张卡的标 direct。 + 经别的卡间接用到的也标;给了画布上的边(edges)时,从这张卡顺着边走得到的节点也算上游——下游卡经 transform 之类 + 的中间节点用到卡上的值(输入写的是 vars.t.g,来自中间节点),同样可能受影响。循环的回边会让循环里的节点都走得到, + 宁可多标。同一张卡执行过几次的按最后一次。 """ latest: dict[str, tuple[str, dict[str, Any]]] = {} for nid, artifact, card in cards: @@ -725,15 +833,33 @@ def downstream_cards(cards: Iterable[tuple[str, str, dict[str, Any]]], node_id: break return found + upstream = {str(node_id)} | _reach(edges, str(node_id)) flagged: dict[str, dict[str, Any]] = {} - frontier, direct = {str(node_id)}, True - while frontier: - reached: set[str] = set() + grew = True + while grew: + # 标出来的卡本身也成了上游:经它间接用到的再标一轮,直到没有新的 + grew = False for nid, (artifact, card) in latest.items(): - if nid in flagged or not (metrics := uses(card, frontier)): + 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": direct} - reached.add(nid) - frontier, direct = reached, False + "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 diff --git a/backend/tests/test_recompute.py b/backend/tests/test_recompute.py index 1b9b6594..1e9779c5 100644 --- a/backend/tests/test_recompute.py +++ b/backend/tests/test_recompute.py @@ -143,7 +143,8 @@ def test_a_baseline_lists_what_cannot_be_used_without_recomputing_anything(): assert "完整值" in unsupported[("n", "vars.kpi.items")] assert "遮罩" in unsupported[("phone_len", "cell(nodes.crm, 0, 'phone')")] assert "取哪" in unsupported[("pick", "vars.kpi.i")] - assert ("n2", "vars.kpi.items") not in unsupported and ("n3", "nodes.fetch.items") not in unsupported + # 还原得出的容器不算「完整值找不回来」,只是不能直接改、也没有行可勾 + 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 @@ -173,7 +174,8 @@ def test_changing_an_input_recomputes_only_the_metrics_that_use_it(): def test_excluding_rows_drops_them_from_an_agent_array_field(): - result = whatif(CARD, Changes(exclude={S1: frozenset({1})}), sources()) + # 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 @@ -396,3 +398,238 @@ def test_downstream_cards_that_use_this_card_are_flagged_not_recomputed(): {"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"] == "unchanged" and mix["changed"] is False + + +def test_a_container_matching_no_snapshot_is_doubted_when_rows_are_excluded(): + """能还原、却对不上任何快照的容器(加工过的结果):排除行后它会不会变说不准。""" + card = 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) + [mixed] = whatif(card, 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 行的值——不能算出一个 + 不对应任何一份数据的数。""" + card = 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) + assert recompute(card["metrics"][0], Changes(), sources())["new"] == round(120.5 / 4, 2) == 30.12 + [share] = whatif(card, 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_inputs_written_before_the_snapshot_came_back_are_not_doubted(): + """写这个输入的节点在快照交回之前就跑完了:排除这份快照里的行影响不到它。""" + early = sources(returned={S1: 10}, finished={"parse": 5, "fetch": 5}) + [mix] = whatif(OLD_MIX, Changes(exclude={S1: frozenset({2})}), early)["metrics"] + assert mix["status"] == "unchanged" and mix["changed"] is False + late = sources(returned={S1: 10}, finished={"parse": 12}) + [mix] = whatif(OLD_MIX, Changes(exclude={S1: frozenset({2})}), late)["metrics"] + assert mix["status"] == "unsupported" + + +def test_a_metric_without_lineage_is_unsupported_once_anything_changes(): + legacy = {"id": "old", "name": "旧指标", "unit": "", "value": 3, "expression": "vars.x + 1"} + card = {**CARD, "metrics": [legacy, CARD["metrics"][0]]} + metrics = by_id(whatif(card, Changes(), sources())) + assert metrics["old"]["status"] == "unchanged" + for changes in (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"] + + +# -------------------------------------------------------------------------- +# 查询快照读不出来:值不给、不推演 +# -------------------------------------------------------------------------- + + +@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), "哈希"), +]) +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 east["substituted"] is None and "120.5" not in str(east["inputs"]) + str(east["substituted"]) + [(input_path, reason)] = [(u["input"], u["reason"]) for u in result["unsupported"]] + assert input_path == path and words in reason + with pytest.raises(WhatIfError, match="快照"): + whatif(CARD, Changes(inputs={path: 100}), sources(load=broken), metric="east") + # 别的指标照样推演,只是用到这份快照的推演不了 + total = by_id(whatif(CARD, Changes(inputs={"vars.kpi.gmv": 50000}), sources(load=broken)))["total"] + assert total["status"] == "unchanged" and "120.5" not in str(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 + + +# -------------------------------------------------------------------------- +# 超大的数、给人看的值 +# -------------------------------------------------------------------------- + + +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"] + import json + 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)])]} + 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 + + +# -------------------------------------------------------------------------- +# 还原时的几处保护 +# -------------------------------------------------------------------------- + + +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}] diff --git a/backend/tests/test_whatif_api.py b/backend/tests/test_whatif_api.py index 13b90b59..1c7bdeb5 100644 --- a/backend/tests/test_whatif_api.py +++ b/backend/tests/test_whatif_api.py @@ -216,7 +216,7 @@ async def test_changing_an_input_of_one_metric(client, monkeypatch): async def faithful(run_id: str) -> list[tuple]: """真跑出来的每张卡、每个指标,什么都不改、强制重算一遍:(卡, 指标, 状态, 重算值, 卡上的值)。 - 输入的还原(标量、cell()、整份查询结果、agent 数组、nodes.*)是否忠实,在真卡上对一遍。""" + 输入的还原(标量、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 @@ -226,12 +226,9 @@ async def faithful(run_id: str) -> list[tuple]: 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) - loader = api_whatif._loader(sealed, cards) - sources = recompute.Sources(load=loader, queries=tuple(sealed.queries), - outputs=api_whatif._outputs_before(sealed, started), - masked=await api_whatif._hidden(sealed, loader)) + sources = api_whatif._sources(sealed, cards, started, asyncio.get_running_loop()) for metric in card["metrics"]: - again = recompute.recompute(metric, recompute.Changes(), sources) + 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 @@ -496,3 +493,339 @@ async def test_downstream_cards_are_flagged_only_when_something_changes(client, [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_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_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"] + + +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] == [] diff --git a/backend/tests/test_whatif_selection.py b/backend/tests/test_whatif_selection.py new file mode 100644 index 00000000..18e13ff5 --- /dev/null +++ b/backend/tests/test_whatif_selection.py @@ -0,0 +1,87 @@ +"""数字推演取哪一份:同一张口径卡执行过几次时推演哪一次、那次执行之前各节点的产出和跑完的时刻、快照什么时候交回。 + +照 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} From 633af950dbb1c5023723aafa079c38317b88b981 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Mon, 5 Oct 2026 05:43:17 +0800 Subject: [PATCH 09/12] =?UTF-8?q?=E6=95=B0=E5=AD=97=E6=8E=A8=E6=BC=94?= =?UTF-8?q?=E5=A4=8D=E6=A0=B8=E4=BF=AE=E6=AD=A3=EF=BC=88=E7=AC=AC=201=20?= =?UTF-8?q?=E8=BD=AE=EF=BC=8C=E7=95=8C=E9=9D=A2=EF=BC=89=EF=BC=9A=E6=95=B4?= =?UTF-8?q?=E4=BB=BD=E7=BB=93=E6=9E=9C=E5=9C=A8=E6=8E=A8=E6=BC=94=E5=8C=BA?= =?UTF-8?q?=E9=87=8C=E5=8B=BE=E8=A1=8C=EF=BC=8C=E5=8F=AA=E8=AE=A9=E7=94=A8?= =?UTF-8?q?=E5=88=B0=E7=9A=84=E8=A1=8C=E5=8F=AF=E5=8B=BE=EF=BC=8C=E5=8B=BE?= =?UTF-8?q?=E5=AE=8C=E7=BB=93=E6=9E=9C=E5=B0=B1=E5=9C=A8=E6=89=8B=E8=BE=B9?= =?UTF-8?q?=EF=BC=8C=E5=8A=A0=E8=BD=BD=E4=B8=AD=E5=92=8C=E5=A4=B1=E8=B4=A5?= =?UTF-8?q?=E5=90=8E=E4=B8=8D=E6=91=86=E4=B8=8A=E4=B8=80=E6=AC=A1=E7=9A=84?= =?UTF-8?q?=E7=AD=94=E5=A4=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 整份结果、数组字段作输入时,输入下面给「勾选要排除的行(共 N 行)」,按页取整份快照来勾:证据链里没有它的查询步骤、 或者查询步骤只给前后 2 行时也勾得全 - 查询步骤里的勾行表格只让这个指标用到的行可勾(row_span),别的行禁用并说明没用到,勾了也不发请求 - 勾行表格底下带推演结果(旧值 → 新值或原因)和「回到推演结果」;勾完、答复回来后各把它带进视野一次(答复回来时上面 的内容会变高,把表格往下挤) - 推演的请求和答复提到片段那一层,推演区和查询步骤共用一份;答复回来之前随改动变的部分变淡、标为忙,请求失败时结果、 排除标记、报告中会变的地方、下游口径卡都不显示,不拿上一次的答复充数 - 整个指标推演不了(口径卡没记输入)时只说原因,不再同时写「无可推演」和「无变化」,也不画勾选框 - 快照读不出来的输入写「查询快照无法核对,不显示原值」;没有能改的输入、也没有能勾的行时说一句为什么 - check-whatif 补对应检查:整份结果勾行、上下文行不能勾、勾完结果整个在视野里、封存核对未通过、加载中和失败后、整个 指标推演不了、窄屏里的勾行表格;ESTIMATE 按实测改成 28 秒 --- frontend/src/api/whatif.ts | 9 +- frontend/src/lib/terms.ts | 14 +- frontend/src/run/EvidencePanel.tsx | 48 +++- frontend/src/run/WhatIf.tsx | 447 ++++++++++++++++++++++------- frontend/src/types.ts | 29 ++ scripts/check-all.mjs | 2 +- scripts/check-whatif.mjs | 211 +++++++++++++- 7 files changed, 635 insertions(+), 125 deletions(-) diff --git a/frontend/src/api/whatif.ts b/frontend/src/api/whatif.ts index f7ecb7a5..a076a6ec 100644 --- a/frontend/src/api/whatif.ts +++ b/frontend/src/api/whatif.ts @@ -4,8 +4,8 @@ * 请求函数(get / post / del……)和 ApiError 从 ./http 导入,不要从 ./client 导入:client.ts 要导入 * 这个文件把它挂到 api 上,反过来导入就成了循环(见 http.ts 开头的说明)。 */ -import type { WhatIfRequest, WhatIfResult } from '../types' -import { request } from './http' +import type { WhatIfRequest, WhatIfResult, WhatIfRowsPage } from '../types' +import { get, request } from './http' export const whatif = { /** @@ -16,4 +16,9 @@ export const whatif = { request(`/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(`/runs/${encodeURIComponent(runId)}/evidence/whatif/rows?${new URLSearchParams({ + artifact, offset: String(page.offset), limit: String(page.limit), + })}`, { signal: opts?.signal }), } diff --git a/frontend/src/lib/terms.ts b/frontend/src/lib/terms.ts index 68e05972..9845df76 100644 --- a/frontend/src/lib/terms.ts +++ b/frontend/src/lib/terms.ts @@ -2771,6 +2771,7 @@ export const WHATIF_TEXT = { unsealed: '运行未封存,数据可能还会变', sealBroken: '封存核对未通过,推演所依据的数据可能已被改动', loading: '推演中…', + failed: '推演失败', result: '推演结果', unchanged: '无变化', delta: (text: string) => `变化 ${text}`, @@ -2780,12 +2781,22 @@ export const WHATIF_TEXT = { inputLabel: (path: string) => `${path} 的推演值`, notNumber: '请输入数值', masked: '已遮罩', + withheld: '查询快照无法核对,不显示原值', excludedRows: (rows: number[]) => `已排除第 ${rows.map((r) => r + 1).join('、')} 行`, pickRows: (alias: string) => `在查询 ${alias} 中勾选要排除的行`, - rowsHint: '勾选的行在推演中视为不存在', + 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: '这个指标无法推演,报告中引用它的地方会如何变化无法确定', @@ -2793,6 +2804,7 @@ export const WHATIF_TEXT = { inReport: (node: string) => `另一份报告(${node})`, unsupported: '不支持推演的输入', wholeMetric: '整个指标', + nothingToAdjust: '这个指标没有可以修改的输入,也没有可以排除的查询行', affected: '可能受影响的下游口径卡', affectedHint: '这些口径卡引用了本卡的指标,推演不会重算它们', affectedCard: (caliber: string, version: string) => `口径卡「${caliber || '未命名'}」${version ? ` ${version}` : ''}`, diff --git a/frontend/src/run/EvidencePanel.tsx b/frontend/src/run/EvidencePanel.tsx index 0f98a344..608a8380 100644 --- a/frontend/src/run/EvidencePanel.tsx +++ b/frontend/src/run/EvidencePanel.tsx @@ -30,7 +30,10 @@ import { useEvidenceHost } from './evidenceHost' import { EvidenceProvenance } from './EvidenceProvenance' import { CopyChip } from './Markdown' import { SqlCheckList } from './SqlChecks' -import { WhatIf, WhatIfRows, WhatIfToggle, useWhatIfDraft } from './WhatIf' +import { + WhatIf, WhatIfRows, WhatIfSummary, WhatIfToggle, focusResult, inSpans, pickMetric, usableRows, useWhatIfDraft, + useWhatIfResult, wholeReason, +} from './WhatIf' /** * 证据面板:点开报告里的一个片段,看它从哪来。 @@ -65,7 +68,8 @@ import { WhatIf, WhatIfRows, WhatIfToggle, useWhatIfDraft } from './WhatIf' * 引用、且片段接口的查询步骤带 provenance: true 时请求推断来源接口;推断来源的缓存只在面板开着期间有效。 * * 数字推演(WhatIf.tsx):指标步骤上的「推演」展开推演区,改输入的值、在查询步骤里勾掉几行,看这个数和报告会变成 - * 多少。推演不是出具,不写运行记录、不改报告。勾选框只在推演时出现在查询步骤的结果窗口里。 + * 多少。推演不是出具,不写运行记录、不改报告。勾选框只在推演时出现在查询步骤的结果窗口里,只有这个指标用到的行能勾, + * 表格底下带着推演结果。 * * 四种摆法:side 从右侧弹出(宽屏),drawer 从底部抽出(窄屏),inline 在 360px 的 * 画布右栏里直接栏内展开,dock 放进页面给的一块常驻位置(记录页的「证据」页签)。 @@ -311,8 +315,17 @@ function SegmentBody({ panelId, doc, artifact, runId, runClass, seg, unit, block const whatifReady = !!runId && !docIssue && !!metricStep && !!whatifCard && !!whatifMetric const whatifOpen = whatif.open && whatifReady const whatifId = `${panelId}-whatif` - // 能勾行的查询步骤:指标的输入(单元格取数、Agent 字段)落在它上面。合并查询的输入步骤不给——指标引用的是合并结果 - const pickable = new Set(inputs.map((inp) => inp.artifact).filter((a): a is string => !!a)) + // 推演的请求和答复也放在这一层:查询步骤里勾行的表格底下要带着推演结果,和推演区是同一份 + 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 @@ -393,8 +406,8 @@ function SegmentBody({ panelId, doc, artifact, runId, runClass, seg, unit, block linkOf={linkOf} workflowName={workflowName(pinnedWorkflow(metricStep))} whatif={whatifReady ? { open: whatifOpen, onToggle: whatif.toggle, controls: whatifId } : undefined}> - {whatifOpen && runId && whatifCard && whatifMetric && ( - )} @@ -425,8 +438,15 @@ function SegmentBody({ panelId, doc, artifact, runId, runClass, seg, unit, block {queries.map((q, i) => ( whatif.toggleRow(q.artifact!, row) } + 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: focusResult(whatifId)} />, + busy: whatifView.status === 'loading', + } : undefined} /> ))} @@ -1361,8 +1381,13 @@ function SourcesPart({ inputs, linkOf }: { inputs: EvidenceInput[]; linkOf: (inp */ function QueryPart({ id, step, seal, masked, pick }: { id: string; step: EvidenceStep; seal?: EvidenceSeal; masked: string[] - /** 推演时:结果窗口每行前面加勾选框,勾掉的行在推演里视为不存在 */ - pick?: { excluded: number[]; onToggle: (row: number) => void } + /** + * 推演时:结果窗口每行前面加勾选框,勾掉的行在推演里视为不存在。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]) @@ -1454,7 +1479,8 @@ function QueryPart({ id, step, seal, masked, pick }: { {win.columns.length > 0 && win.rows.length > 0 && (
    0 && 'mt-1.5')}> {pick && win.index - ?