diff --git a/backend/app/engine/evidence.py b/backend/app/engine/evidence.py index 44abc1bd..0bd84461 100644 --- a/backend/app/engine/evidence.py +++ b/backend/app/engine/evidence.py @@ -3044,6 +3044,23 @@ _PROMPT_HITS = 8 _PROMPT_HIT_CHARS = 300 +def _sql_check_note(artifact: Any, snaps: _Snapshots) -> str | None: + """这次查询(合并查询则是它的输入)没通过 SQL 检查时,写作目录里跟在它后面的那句提醒;没问题返回 None。 + + 口径卡的指标早就标「存疑」了,直接引用查询格子的写作者却看不到:报告照样把一对多关联后求和的数写成定论。 + 出具契约会按缺口降档(issuance.sql_check_gaps),这里先让写作者知道、引用时如实交代。 + """ + from app.engine.sql_problems import query_problems + + found = query_problems(artifact, loader=snaps.loader) + if not found: + return None + problems = list(dict.fromkeys(text for p in found for text in p.problems)) + who = "这次查询" if all(p.artifact == artifact for p in found) else "这次合并的输入查询" + return (f" ({who}未通过 SQL 检查:{';'.join(problems[:3]) or '有错误级的问题'}。其中的数存疑:" + "引用时须如实说明,不要当作确定的结论)") + + def _query_prompt(entry: dict[str, Any], snaps: _Snapshots, cells_allowed: bool) -> list[str]: """一次查询在写作目录里的样子:编号、来源、列,以及能引用的行(行号 + 渲染后的值)。 @@ -3058,6 +3075,8 @@ def _query_prompt(entry: dict[str, Any], snaps: _Snapshots, cells_allowed: bool) if snapshot.get("truncated") is True: lines.append(" (查询结果已截断:只取回了前面一部分行,库里还有更多。单格可以引用;" "不要把取回的行数当成总数,也不要据此写合计、全部之类的结论)") + if note := _sql_check_note(entry.get("artifact"), snaps): + lines.append(note) if not cells_allowed: return lines columns = [str(c) for c in snapshot.get("columns") or []][:_PROMPT_COLS] diff --git a/backend/app/engine/issuance.py b/backend/app/engine/issuance.py index 5b030f3a..c357cd07 100644 --- a/backend/app/engine/issuance.py +++ b/backend/app/engine/issuance.py @@ -4,6 +4,8 @@ import re from dataclasses import dataclass, field from typing import Any, Callable +from app.engine.sql_problems import problem_clause, query_problems + # -------------------------------------------------------------------------- # 出具校验:叙述里的每个数字必须能回指到指标集 # @@ -462,15 +464,54 @@ def incomplete_gaps(metrics: list[dict[str, Any]]) -> list[str]: for m in metrics if isinstance(m, dict) and m.get("incomplete")] -def sql_check_gaps(metrics: list[dict[str, Any]]) -> list[str]: - """契约收来的指标里来源查询没通过 SQL 检查的(口径卡标了 sql_check_failed:取数的那条 SQL 对照数据目录查出 - error 级问题,比如一对多关联之后对「一」那一侧求和),每个一句缺口。 +def sql_check_gaps(metrics: list[dict[str, Any]], cited: dict[str, list[str]] | None = None, *, + label: Callable[[str, str | None], str | None] | None = None) -> list[str]: + """没通过 SQL 检查(error 级:一对多关联后重复计算、存量跨期加总)的查询,每条一句缺口。 - 和 incomplete_gaps 同一个道理:数字照样回指得上口径卡,口径卡照样复算一致,但算它的那条查询本身就把数算错了 - (重复计算、存量跨期加总),盖完整出具的章等于替一个错数作保。原因用口径卡记下的那句,写明是哪条检查。 + 两处来历:契约收来的指标(口径卡标了 sql_check_failed,sql_check_sources 记着取数的查询快照),以及报告直接 + 引用的查询(cited:{查询快照 id: [引用的写法…]},单元格、表格、[[see:]] 依据)。数字照样回指得上,口径卡照样 + 复算一致,但算它的那条查询本身就把数算错了,盖完整出具的章等于替一个错数作保。 + + 按出问题的那条查询归并(合并查询顺着输入找到源查询):同一条查询算出三个指标、报告又引用了它的格,也只记一句, + 句子里列出受影响的引用。label(快照 id, 节点 id) 给出「查询「取数」(Q1)」这样的称呼,给不出就写「所依据的查询」。 + 指标标了 sql_check_failed、快照却读不出来(被清理、被改过)的,退回口径卡记下的那句:缺口不能因为读不到快照就消失。 """ - return [f"指标「{m.get('name') or m.get('id')}」{m.get('sql_check_reason') or '所依据的查询未通过 SQL 检查'}" - for m in metrics if isinstance(m, dict) and m.get("sql_check_failed")] + groups: dict[str, dict[str, Any]] = {} + fallback: list[str] = [] + + def add(artifact: Any, ref: str) -> bool: + found = query_problems(artifact) if isinstance(artifact, str) and artifact else [] + for problem in found: + group = groups.setdefault(problem.artifact, {"problem": problem, "refs": []}) + if group["problem"].node_id is None and problem.node_id: + group["problem"].node_id = problem.node_id + if ref not in group["refs"]: + group["refs"].append(ref) + return bool(found) + + for m in metrics: + if not (isinstance(m, dict) and m.get("sql_check_failed")): + continue + name = f"指标「{m.get('name') or m.get('id')}」" + hits = [add(src.get("artifact"), name) for src in m.get("sql_check_sources") or [] if isinstance(src, dict)] + if not any(hits): + fallback.append(f"{name}{m.get('sql_check_reason') or '所依据的查询未通过 SQL 检查'}") + for artifact, refs in (cited or {}).items(): + for ref in refs: + add(artifact, ref) + + out = [] + for artifact, group in groups.items(): + problem = group["problem"] + who = (label(artifact, problem.node_id) if label else None) or "所依据的查询" + refs = group["refs"] + listed = "、".join(refs[:_SQL_REFS]) + (f"等 {len(refs)} 处" if len(refs) > _SQL_REFS else "") + out.append(f"{who}{problem_clause(problem.problems)};受影响的引用:{listed}") + return out + fallback + + +#: 一句 SQL 检查缺口里最多列出几处受影响的引用(计数照实) +_SQL_REFS = 8 def _claims_effect( diff --git a/backend/app/engine/nodes/io.py b/backend/app/engine/nodes/io.py index 4d79ba03..c1be3d45 100644 --- a/backend/app/engine/nodes/io.py +++ b/backend/app/engine/nodes/io.py @@ -188,8 +188,9 @@ def _apply_contract( gaps.append(f"指标来源未解析:{'、'.join(unresolved[:5])}") # 拿截断的查询结果整组算出来的指标:数回指得上,但算的只是取回的那一截,不能完整出具 gaps.extend(incomplete_gaps(metrics)) - # 来源查询没通过 SQL 检查(error 级:重复计算、存量跨期加总)的指标:口径卡复算得一致,算的却是错数 - gaps.extend(sql_check_gaps(metrics)) + # 来源查询没通过 SQL 检查(error 级:重复计算、存量跨期加总):口径卡复算得一致,算的却是错数。 + # 报告直接引用的查询要等引用核对之后才知道,缺口放在这个位置,下面一起算 + sql_at = len(gaps) # 引用模式下,缺输入记成空值的指标(口径卡 on_missing=null)就是缺:报告里引用不了它, # 也不能因为 id 在清单里就算「齐了」。旧模式照旧只看 id,行为不变 @@ -222,13 +223,27 @@ def _apply_contract( ) unmatched = trace.unmatched if trace else [] + # 同一条查询算出几个指标、报告又引用了它的格,只记一句(按出问题的那条查询归并,列出受影响的引用) + titles = {n.id: n.title for n in ctx.run.spec.nodes} + aliases: dict[str, str] = cited.get("aliases") or {} + + def query_label(artifact: str, node_id: str | None) -> str: + from app.engine.sql_problems import node_of + + title = titles.get(node_id or node_of(artifact, state.get("evidence")) or "") + alias = aliases.get(artifact) + if title and alias: + return f"查询「{title}」({alias})" + return f"查询「{title}」" if title else (f"查询 {alias}" if alias else "") + + gaps[sql_at:sql_at] = sql_check_gaps(metrics, cited.get("queries"), label=query_label) + # 声明了 metrics_from 却一个指标都没收到,同样是"没查成" if sources and not metrics: gaps.append("指标集为空,叙述中的数字无法追溯") # 上游有协作团队用完轮数、按降档交付的:叙述里的话不是调度者认可的结论, # 数字全都对得上也不能盖「完整出具」 - titles = {n.id: n.title for n in ctx.run.spec.nodes} for node_id, payload in nodes.items(): if isinstance(payload, dict) and payload.get("exhausted"): gaps.append(f"协作团队「{titles.get(node_id, node_id)}」用完 {payload.get('rounds', '?')} " @@ -318,7 +333,7 @@ def _check_citations( out: dict[str, Any] = {"matched": [], "unmatched": [], "unresolved": [], "gaps": [], "doc_artifact": None, "stats": None, "claims_policy": None, "uncited": None, - "unsupported": None, "claims": None, "entities": None} + "unsupported": None, "claims": None, "entities": None, "queries": {}, "aliases": {}} gaps = out["gaps"] spec = ctx.run.spec node = spec.node_map().get(report_from) @@ -384,6 +399,8 @@ def _check_citations( out["entities"] = {"unknown": unknown[:_LISTED], "unverified": unverified[:_LISTED], "counted": governed and bool(unknown)} + out["queries"], out["aliases"] = _cited_queries(doc, catalog) + # 老前端要用的逐个数字出处,从复核通过的数字片段拼出来 for _, unit in iter_units(doc): for seg in unit.get("segments") or []: @@ -524,6 +541,46 @@ def _claims(out: dict[str, Any], contract: dict[str, Any], payload: dict[str, An } +def _cited_queries(doc: dict[str, Any], catalog: dict[str, Any]) -> tuple[dict[str, list[str]], dict[str, str]]: + """报告直接引用的查询:({查询快照 id: [引用的写法…]}, {目录里每个查询的快照 id: 编号})。 + + 单元格([[v:Q1.r0.gmv]],[[table:]] 展开后也是一格一格的引用)按查询数:一格写「Q1 第 1 行「gmv」」, + 几格写「Q1 的 3 格」;只拿它当依据([[see:Q1]])的写「Q1(结论依据)」。出具契约据此判这些查询有没有通过 + SQL 检查(issuance.sql_check_gaps)。 + """ + from app.engine.evidence import iter_units + + cells: dict[str, list[tuple[Any, Any]]] = {} + support: list[str] = [] + for _, unit in iter_units(doc): + for seg in unit.get("segments") or []: + cite = seg.get("cite") or {} + if cite.get("kind") == "cell" and cite.get("status") == "resolved" and cite.get("alias"): + loc = cite.get("locator") or {} + cells.setdefault(str(cite["alias"]), []) + if (loc.get("row"), loc.get("column")) not in cells[str(cite["alias"])]: + cells[str(cite["alias"])].append((loc.get("row"), loc.get("column"))) + for cite in unit.get("see") or []: + alias = str((cite or {}).get("alias") or "") + if (catalog.get(alias) or {}).get("kind") == "query" and alias not in support: + support.append(alias) + queries: dict[str, list[str]] = {} + # 目录里全部查询的编号:合并查询的输入没被直接引用,缺口里也要写得出它是 Q 几 + aliases = {str(e["artifact"]): str(e["alias"]) for e in catalog.values() + if isinstance(e, dict) and e.get("kind") == "query" and e.get("artifact") and e.get("alias")} + for alias in [*cells, *(a for a in support if a not in cells)]: + artifact = (catalog.get(alias) or {}).get("artifact") + if not isinstance(artifact, str) or not artifact: + continue + hit = cells.get(alias) or [] + if len(hit) == 1 and isinstance(hit[0][0], int): + ref = f"{alias} 第 {hit[0][0] + 1} 行「{hit[0][1]}」" + else: + ref = f"{alias} 的 {len(hit)} 格" if hit else f"{alias}(结论依据)" + queries.setdefault(artifact, []).append(ref) + return queries, aliases + + def _declare_citations( tier: str, cited: dict[str, Any], *, calibers: list[dict[str, str]], metrics: list[dict[str, Any]], gaps: list[str], missing_required: list[str], missing_expected: list[str], report_from: str, diff --git a/backend/app/engine/nodes/metrics.py b/backend/app/engine/nodes/metrics.py index 9e41cd4f..152f51f6 100644 --- a/backend/app/engine/nodes/metrics.py +++ b/backend/app/engine/nodes/metrics.py @@ -33,7 +33,7 @@ from app.engine.expressions import ( substitute, ) from app.engine.labels import field_label -from app.engine.merge_query import MERGE_SOURCE +from app.engine.sql_problems import QueryProblem, merge_problems, node_of, query_problems, reason_text from app.engine.state import GraphState, template_context @@ -75,8 +75,11 @@ async def run_metrics(state: GraphState, ctx: NodeContext) -> dict[str, Any]: metrics: list[dict[str, Any]] = [] errors: list[str] = [] - #: 查询快照工件 id → 它的 error 级检查结果。一张卡里多个指标常常取自同一次查询,快照只读一次 - checked: dict[str, list[dict[str, Any]]] = {} + #: 查询快照工件 id → 它(含合并查询的输入)没通过 SQL 检查的那几条查询。一张卡里多个指标常常取自同一次查询, + #: 快照只读一次 + checked: dict[str, list[QueryProblem]] = {} + #: 指标 id → 它没通过 SQL 检查的那几条来源查询。运行日志按查询归并(_emit_sql_check_logs) + failed_by: dict[str, list[QueryProblem]] = {} for definition in definitions: metric_id = str(definition.get("id") or "").strip() expr = str(definition.get("expression") or "").strip() @@ -138,7 +141,8 @@ async def run_metrics(state: GraphState, ctx: NodeContext) -> 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), "sql_check_sources": [{"artifact": artifact, "codes": list(dict.fromkeys( - str(c.get("code")) for c in found))} for artifact, found in failed]} + code for p in found for code in p.codes))} for artifact, found in failed]} + failed_by[metric_id] = [p for _, found in failed for p in found] metrics.append( { "id": metric_id, @@ -177,11 +181,11 @@ async def run_metrics(state: GraphState, ctx: NodeContext) -> dict[str, Any]: ] for m in metrics: if m.get("incomplete"): - ctx.emit(EventType.LOG, level="warn", code="metric_incomplete", metric=m["id"], + # 结构化字段(metric_name、reason、rows)给界面读,不让它从 message 里解析中文 + ctx.emit(EventType.LOG, level="warn", code="metric_incomplete", metric=m["id"], metric_name=m["name"], + reason=m["incomplete_reason"], rows=[s.get("rows") for s in m.get("truncated_sources") or []], message=f"指标「{m['name']}」{m['incomplete_reason']}") - if m.get("sql_check_failed"): - ctx.emit(EventType.LOG, level="warn", code="metric_sql_check", metric=m["id"], - message=f"指标「{m['name']}」{m['sql_check_reason']}") + _emit_sql_check_logs(metrics, failed_by, state, ctx) card = { "kind": "metric_set", "caliber": caliber, @@ -354,9 +358,10 @@ _LAST_STEP = re.compile(r"(?:\.[^.\[\]]+|\[[^\[\]]*\])$") def _failed_queries(inputs: list[dict[str, Any]], truncated: list[dict[str, Any]], paths: list[str], - tctx: dict[str, Any], checked: dict[str, list[dict[str, Any]]], - ) -> list[tuple[str, list[dict[str, Any]]]]: - """这个指标用到的查询里,SQL 检查有 error 的:[(查询快照工件 id, error 级检查结果)]。 + tctx: dict[str, Any], checked: dict[str, list[QueryProblem]], + ) -> list[tuple[str, list[QueryProblem]]]: + """这个指标用到的查询里,SQL 检查有 error 的:[(查询快照工件 id, 没通过检查的查询)]。合并查询的快照对应它出问题的 + 那几个输入(sql_problems.query_problems)。 用到了哪些查询,三处来历合起来认:输入的出处(cell() 取的格、Agent 经 cite_fields 交来的字段都带着快照 id)、 截断跟踪记下的整组、取值链上的查询结果本身(数据整形解析过的 vars.res.rows[0][0],往上找到 vars.res 那份 @@ -368,7 +373,7 @@ def _failed_queries(inputs: list[dict[str, Any]], truncated: list[dict[str, Any] out = [] for artifact in dict.fromkeys(a for a in artifacts if isinstance(a, str) and a): if artifact not in checked: - checked[artifact] = _error_checks(artifact) + checked[artifact] = query_problems(artifact) if checked[artifact]: out.append((artifact, checked[artifact])) return out @@ -394,41 +399,53 @@ def _result_artifact(path: str, tctx: dict[str, Any]) -> str | None: return None -def _error_checks(artifact: str, _seen: set[str] | None = None) -> list[dict[str, Any]]: - """这份查询快照对照数据目录查出的 error 级问题。 - - 合并查询的快照没有自己的 checks(它在内存 SQLite 上执行,不对照数据目录),但记着 inputs:顺着往下找。 - 不然源库那条查询一对多关联后重复计算了,经过一次合并,指标就看不出来、照样完整出具。 - """ - seen = _seen if _seen is not None else set() - if artifact in seen: - return [] - seen.add(artifact) - try: - snapshot = artifact_store.load(artifact) - except Exception: # noqa: BLE001 - 快照读不出来、被改过:这里不报,证据层另有说法 - return [] - if not isinstance(snapshot, dict): - return [] - checks = snapshot.get("checks") - found = [c for c in checks if isinstance(c, dict) and c.get("level") == "error"] if isinstance(checks, list) else [] - inputs = snapshot.get("inputs") if snapshot.get("source") == MERGE_SOURCE else None - for entry in inputs if isinstance(inputs, list) else []: - if isinstance(entry, dict) and isinstance(entry.get("artifact"), str): - found += _error_checks(entry["artifact"], seen) - return found +def _error_checks(artifact: str) -> list[dict[str, Any]]: + """这份查询快照对照数据目录查出的 error 级问题(合并查询顺着 inputs 往下找,见 sql_problems.query_problems)。""" + return [c for p in query_problems(artifact) for c in p.checks] -def _sql_check_reason(failed: list[tuple[str, list[dict[str, Any]]]]) -> str: +def _sql_check_reason(failed: list[tuple[str, list[QueryProblem]]]) -> str: """「所依据的查询未通过 SQL 检查(「订单」关联「订单明细」是一对多,对「订单」的「订单金额」求和会重复计算), 结果不可靠」:出具声明、运行日志、证据面板都用这句。只摘问题那半句,改法留在查询步骤里看。""" - problems = list(dict.fromkeys(str(c.get("message") or "").split("。")[0] for _, found in failed for c in found)) - problems = [p for p in problems if p] - if not problems: - return "所依据的查询未通过 SQL 检查,结果不可靠" - if len(problems) == 1: - return f"所依据的查询未通过 SQL 检查({problems[0]}),结果不可靠" - return f"所依据的查询有 {len(problems)} 处未通过 SQL 检查({problems[0]}等),结果不可靠" + return reason_text(list(dict.fromkeys(text for _, found in failed for p in found for text in p.problems))) + + +#: 运行日志里每条 SQL 检查结果交给界面的字段(data/sqlcheck.SqlCheck.as_dict 去掉给模型的那句 for_model) +_CHECK_FIELDS = ("code", "level", "message", "table", "column", "relation_id", "sql_excerpt") + + +def _emit_sql_check_logs(metrics: list[dict[str, Any]], failed_by: dict[str, list[QueryProblem]], + state: GraphState, ctx: NodeContext) -> None: + """没通过 SQL 检查的来源查询,一条一行运行日志(metric_sql_check),列出受它影响的指标。 + + 以前一个指标一行:同一条查询算出三个指标,时间线上同一句话重复三遍。现在按出问题的那条查询归并。 + 结构化字段给界面读,不让它从 message 里解析中文:metrics / metric_names(受影响的指标)、reason、problems、 + checks(不带 for_model)、query_artifact(出问题的查询快照)、source_node(跑这条查询的节点)、 + source_field(要改的那一栏:调用工具节点写死的 SQL 在 args.sql;Agent 自己写的 SQL 没有可定位的栏,不给)。 + 界面据 source_node / source_field 把「打开设置」落到来源查询节点的 SQL 上,而不是口径卡。 + """ + names = {m["id"]: m["name"] for m in metrics} + groups: dict[str, tuple[QueryProblem, list[str]]] = {} + for metric_id, found in failed_by.items(): + for problem in merge_problems(found): + held = groups.setdefault(problem.artifact, (problem, [])) + if metric_id not in held[1]: + held[1].append(metric_id) + nodes = ctx.run.spec.node_map() + for artifact, (problem, ids) in groups.items(): + source = problem.node_id or node_of(artifact, state.get("evidence")) + producer = nodes.get(source) if source else None + sql_in_args = producer is not None and str(producer.type) == "tool" \ + and isinstance((producer.config.get("args") or {}), dict) and "sql" in (producer.config.get("args") or {}) + reason = reason_text(problem.problems) + ctx.emit(EventType.LOG, level="warn", code="metric_sql_check", + metric=ids[0], metrics=ids, metric_names=[names.get(i, i) for i in ids], + reason=reason, problems=problem.problems, + checks=[{k: c[k] for k in _CHECK_FIELDS if k in c} for c in problem.checks], + query_artifact=artifact, + **({"source_node": source} if source else {}), + **({"source_field": "args.sql"} if sql_in_args else {}), + message="指标" + "".join(f"「{names.get(i, i)}」" for i in ids) + reason) def _truncated_field(path: str, state: GraphState, ctx: NodeContext) -> dict[str, Any] | None: diff --git a/backend/app/engine/sql_problems.py b/backend/app/engine/sql_problems.py new file mode 100644 index 00000000..1b1f9372 --- /dev/null +++ b/backend/app/engine/sql_problems.py @@ -0,0 +1,126 @@ +"""查询快照上的 SQL 检查问题:口径卡、出具契约、写作目录、运行日志共用一套读法。 + +数据源查询工具执行后对照数据目录检查 SQL,结果存在查询快照的 checks 里(data/sqlcheck.py)。error 级的 +(一对多关联后重复计算、存量跨期加总)意味着这条查询算出来的数不可靠: + +- 口径卡用它算出的指标标「存疑」(nodes/metrics.py); +- 报告直接引用它的格、或拿它当依据,出具同样降档(nodes/io.py); +- 写作目录里提醒写作者(engine/evidence.catalog_prompt)。 + +合并查询在内存 SQLite 上执行,不对照数据目录,它的快照没有自己的 checks,但记着 inputs:顺着往下找,问题记在 +出问题的那条源查询上。几个指标、几处引用出自同一条查询时,问题只算一次(problems_by_query 按快照 id 归并)。 +""" +from __future__ import annotations + +from collections.abc import Callable, Iterable +from dataclasses import dataclass, field +from typing import Any + +from app.core import artifact_store + +#: 合并查询快照的 source(engine/merge_query.MERGE_SOURCE)。这里写死同一个字面量,免得为一个常量引入执行器 +MERGE_SOURCE = "合并查询" +#: 一条链最多追几层合并:画布上不会无限嵌套,这只是防御坏快照 +_MAX_DEPTH = 8 + + +@dataclass +class QueryProblem: + """一条没通过 SQL 检查的查询快照。 + + artifact 是出问题的那条查询快照(合并查询的话是它的某个输入);node_id 是跑这条查询的节点,合并快照的 inputs + 里记着,直接查询的由调用方按证据台账补(node_of);checks 是 error 级的检查结果(快照里的原样)。 + """ + + artifact: str + node_id: str | None + checks: list[dict[str, Any]] = field(default_factory=list) + + @property + def problems(self) -> list[str]: + """每条检查的问题那半句(message 的第一句),去重。改法留在证据面板的查询步骤里看。""" + out = [str(c.get("message") or "").split("。")[0] for c in self.checks] + return list(dict.fromkeys(p for p in out if p)) + + @property + def codes(self) -> list[str]: + return list(dict.fromkeys(str(c.get("code")) for c in self.checks if c.get("code"))) + + +def _load(artifact: str, loader: Callable[[str], Any] | None) -> Any: + try: + return (loader or artifact_store.load)(artifact) + except Exception: # noqa: BLE001 - 快照读不出来、被改过:这里不报,证据层另有说法 + return None + + +def query_problems(artifact: Any, *, loader: Callable[[str], Any] | None = None, + _seen: set[str] | None = None, _node: str | None = None, _depth: int = 0) -> list[QueryProblem]: + """这份查询快照(或合并快照的各个输入)里有 error 级 SQL 检查的那几条查询,一条一个 QueryProblem。 + + 读不出来的快照、没有问题的快照都不出现。自引用、成环的坏快照不会卡死。 + """ + if not isinstance(artifact, str) or not artifact or _depth > _MAX_DEPTH: + return [] + seen = _seen if _seen is not None else set() + if artifact in seen: + return [] + seen.add(artifact) + snapshot = _load(artifact, loader) + if not isinstance(snapshot, dict): + return [] + out: list[QueryProblem] = [] + checks = snapshot.get("checks") + errors = [c for c in checks if isinstance(c, dict) and c.get("level") == "error"] if isinstance(checks, list) else [] + if errors: + out.append(QueryProblem(artifact, _node, errors)) + inputs = snapshot.get("inputs") if snapshot.get("source") == MERGE_SOURCE else None + for entry in inputs if isinstance(inputs, list) else []: + if isinstance(entry, dict) and isinstance(entry.get("artifact"), str): + node = entry.get("node_id") if isinstance(entry.get("node_id"), str) else None + out += query_problems(entry["artifact"], loader=loader, _seen=seen, _node=node, _depth=_depth + 1) + return out + + +def error_checks(artifact: Any, *, loader: Callable[[str], Any] | None = None) -> list[dict[str, Any]]: + """这份查询快照(含合并查询的输入)对照数据目录查出的全部 error 级检查结果,摊平成一个列表。""" + return [c for p in query_problems(artifact, loader=loader) for c in p.checks] + + +def node_of(artifact: str, ledger: Iterable[Any] | None) -> str | None: + """证据台账里交回这份查询快照的节点。台账里没有(老运行、Agent 没交台账)返回 None。""" + for entry in ledger or []: + if isinstance(entry, dict) and entry.get("kind") == "query" and entry.get("artifact") == artifact: + node = entry.get("node_id") + return node if isinstance(node, str) and node else None + return None + + +def problem_clause(problems: list[str]) -> str: + """「未通过 SQL 检查(…),结果不可靠」:前面接上是哪条查询(「所依据的查询」「查询「取数」(Q1)」)。""" + problems = [p for p in problems if p] + if not problems: + return "未通过 SQL 检查,结果不可靠" + if len(problems) == 1: + return f"未通过 SQL 检查({problems[0]}),结果不可靠" + return f"有 {len(problems)} 处未通过 SQL 检查({problems[0]}等),结果不可靠" + + +def reason_text(problems: list[str]) -> str: + """「所依据的查询未通过 SQL 检查(…),结果不可靠」:口径卡、出具声明、运行日志、证据面板都用这句。""" + return "所依据的查询" + problem_clause(problems) + + +def merge_problems(found: Iterable[QueryProblem]) -> list[QueryProblem]: + """按快照 id 归并:同一条查询经几条路径(直接引用、合并查询的输入)找到,只算一次。保持先后顺序。""" + out: dict[str, QueryProblem] = {} + for p in found: + if p.artifact not in out: + out[p.artifact] = QueryProblem(p.artifact, p.node_id, list(p.checks)) + elif out[p.artifact].node_id is None and p.node_id: + out[p.artifact].node_id = p.node_id + return list(out.values()) + + +__all__ = ["MERGE_SOURCE", "QueryProblem", "error_checks", "merge_problems", "node_of", "problem_clause", "query_problems", + "reason_text"] diff --git a/backend/tests/test_report_sqlcheck_cells.py b/backend/tests/test_report_sqlcheck_cells.py new file mode 100644 index 00000000..cd5b2f12 --- /dev/null +++ b/backend/tests/test_report_sqlcheck_cells.py @@ -0,0 +1,160 @@ +"""报告直接引用没通过 SQL 检查的查询时,出具同样降档;同一条查询的问题只记一次。 + +以前缺口只从口径卡的指标来:报告绕过口径卡、直接写 [[v:Q1.r0.gmv]] 引用一条一对多关联后求和的查询, +数字回指得上快照,出具照样盖「完整出具」的章;写作目录也只给指标标「存疑」,写作者不知道这条查询本身有问题。 +另一头,同一条查询算出三个指标时,运行时间线和降档原因里同一句话各重复三遍。 +""" +from __future__ import annotations + +import pytest + +import app.engine.issuance as issuance_mod +from app.core import artifact_store +from app.engine.issuance import sql_check_gaps +from app.engine.merge_query import MERGE_SOURCE as ENGINE_MERGE_SOURCE +from app.engine.runner import run_manager +from app.engine.sql_problems import MERGE_SOURCE, query_problems, reason_text +from tests.test_runtime_sqlcheck import ( # noqa: F401 - 夹具按名字引入 + CLEAN_SQL, + FANOUT_SQL, + GMV, + GMV2, + REASON, + Writer, + _drop_created_sources, + chain, + engine_up, + events, + node, + scenic_source, + wait, +) + +PROBLEM = "「订单」关联「订单明细」是一对多,对「订单」的「订单金额」求和会重复计算" + + +def test_the_merge_source_literal_matches_the_engine(): + assert MERGE_SOURCE == ENGINE_MERGE_SOURCE + assert reason_text([PROBLEM]) == REASON + + +def direct(source: str, sql: str, text: str) -> dict: + """报告不经口径卡,直接引用查询结果里的格。""" + return chain([ + node("start", "input"), + node("fetch", "tool", tool=f"db_query__{source}", args={"sql": sql}), + node("write", "report", instructions="写订单周报"), + node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}], + contract={"report_from": "write"}), + ]) + + +async def test_a_cell_cited_from_a_failing_query_degrades_the_issuance(scenic_source, engine_up, monkeypatch): + writer = Writer(monkeypatch, text="本周订单金额 [[v:Q1.r0.gmv]]。") + run = await run_manager.start(graph=direct(scenic_source, FANOUT_SQL, ""), input_payload={}) + row = await wait(run.id) + assert row.status == "succeeded", row.error + issuance = row.output["_issuance"] + assert issuance["tier"] == "degraded", issuance + [gap] = [g for g in issuance["gaps"] if "SQL 检查" in g] + assert gap.startswith("查询「fetch」(Q1)未通过 SQL 检查") and PROBLEM in gap + assert "受影响的引用:Q1 第 1 行「gmv」" in gap + # 写作目录里,这条查询本身就标着「存疑」:写作者引用它的格时知道要交代 + prompt = writer.prompts[0] + q1 = prompt[prompt.index("- Q1:"):] + assert "这次查询未通过 SQL 检查" in q1.split("\n例:")[0] and PROBLEM in q1 + + +async def test_the_same_report_on_a_clean_query_issues_formally(scenic_source, engine_up, monkeypatch): + writer = Writer(monkeypatch, text="本周订单金额 [[v:Q1.r0.gmv]]。") + run = await run_manager.start(graph=direct(scenic_source, CLEAN_SQL, ""), input_payload={}) + row = await wait(run.id) + assert row.status == "succeeded", row.error + assert row.output["_issuance"]["tier"] == "formal", row.output["_issuance"] + assert "未通过 SQL 检查" not in writer.prompts[0] + + +def three(source: str, sql: str) -> dict: + """同一条查询算出两个指标,报告又直接引用了它的一格、拿它当依据。""" + return chain([ + node("start", "input"), + node("fetch", "tool", tool=f"db_query__{source}", args={"sql": sql}), + node("parse", "transform", mode="json", template="{{ nodes.fetch }}", assign_to="res"), + node("card", "metrics", caliber="订单口径", caliber_version="v1", metrics=[GMV, GMV2]), + node("write", "report", instructions="写订单周报"), + node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}], + contract={"report_from": "write", "metrics_from": ["card"], "required": ["gmv"]}), + ]) + + +async def test_one_failing_query_is_one_gap_and_one_timeline_row(scenic_source, engine_up, monkeypatch): + Writer(monkeypatch, text="本周订单金额 [[m:gmv]],查询结果 [[v:Q1.r0.gmv]]。[[see:Q1]]") + run = await run_manager.start(graph=three(scenic_source, FANOUT_SQL), input_payload={}) + row = await wait(run.id) + assert row.status == "succeeded", row.error + issuance = row.output["_issuance"] + assert issuance["tier"] == "degraded" + [gap] = [g for g in issuance["gaps"] if "SQL 检查" in g] + assert gap.count(PROBLEM) == 1 + assert "指标「订单金额」" in gap and "指标「订单金额(整形后)」" in gap and "Q1 第 1 行「gmv」" in gap + + # 运行时间线:同一条查询的问题一行,列出受影响的指标;带着结构化字段,界面不用解析中文 + [log] = [e.data for e in await events(row.id, "log", "card") if e.data.get("code") == "metric_sql_check"] + assert log["metrics"] == ["gmv", "gmv2"] and log["metric_names"] == ["订单金额", "订单金额(整形后)"] + assert log["message"] == f"指标「订单金额」「订单金额(整形后)」{REASON}" + assert log["reason"] == REASON and log["problems"] == [PROBLEM] + assert log["source_node"] == "fetch" and log["source_field"] == "args.sql" + [check] = log["checks"] + assert check["code"] == "fanout_sum" and check["level"] == "error" and "for_model" not in check + [query_end] = [e.data for e in await events(row.id, "tool.end", "fetch")] + assert log["query_artifact"] == query_end["query_artifact"] + + +# -------------------------------------------------------------------------- +# 合并查询:问题记在出问题的那条源查询上,经几条路径找到都只算一次 +# -------------------------------------------------------------------------- + +FANOUT = {"code": "fanout_sum", "level": "error", "message": f"{PROBLEM}。改法:先汇总再关联"} + + +def _snap(checks=None, **extra): + snap = {"columns": ["日期", "门店", "销售额"], "rows": [["2026-05-01", "S01", 10]], "truncated": False, **extra} + return {**snap, "checks": checks} if checks else snap + + +@pytest.fixture +def snapshots(monkeypatch): + store = { + "sales": _snap([FANOUT]), + "visits": _snap(), + "merged": _snap(source=MERGE_SOURCE, inputs=[{"alias": "s", "node_id": "q_sales", "artifact": "sales"}, + {"alias": "v", "node_id": "q_visits", "artifact": "visits"}]), + } + monkeypatch.setattr(artifact_store, "load", lambda artifact: store.get(artifact)) + return store + + +def test_problems_are_recorded_on_the_input_that_failed(snapshots): + [problem] = query_problems("merged") + assert problem.artifact == "sales" and problem.node_id == "q_sales" and problem.problems == [PROBLEM] + + +def test_metrics_and_cells_through_a_merge_share_one_gap(snapshots): + metrics = [{"id": "gmv", "name": "销售额", "sql_check_failed": True, "sql_check_reason": REASON, + "sql_check_sources": [{"artifact": "merged", "codes": ["fanout_sum"]}]}, + {"id": "avg", "name": "店均销售额", "sql_check_failed": True, "sql_check_reason": REASON, + "sql_check_sources": [{"artifact": "merged", "codes": ["fanout_sum"]}]}] + labels = {"sales": "查询「取销售」(Q1)"} + gaps = sql_check_gaps(metrics, {"merged": ["Q2 第 1 行「销售额」"], "sales": ["Q1(结论依据)"]}, + label=lambda artifact, node: labels.get(artifact)) + assert gaps == [f"查询「取销售」(Q1)未通过 SQL 检查({PROBLEM}),结果不可靠;" + "受影响的引用:指标「销售额」、指标「店均销售额」、Q2 第 1 行「销售额」、Q1(结论依据)"] + + +def test_a_flagged_metric_whose_snapshot_is_gone_still_counts(monkeypatch): + """快照读不出来(被清理、被改过)时退回口径卡记下的那句:缺口不能因为读不到快照就消失。""" + monkeypatch.setattr(issuance_mod, "query_problems", lambda artifact, **_: []) + metrics = [{"id": "gmv", "name": "订单金额", "sql_check_failed": True, "sql_check_reason": REASON, + "sql_check_sources": [{"artifact": "gone", "codes": ["fanout_sum"]}]}] + assert sql_check_gaps(metrics) == [f"指标「订单金额」{REASON}"] + assert sql_check_gaps([{"id": "n", "name": "订单数", "value": 2}]) == [] diff --git a/backend/tests/test_runtime_sqlcheck.py b/backend/tests/test_runtime_sqlcheck.py index b84c9bb2..3d43395e 100644 --- a/backend/tests/test_runtime_sqlcheck.py +++ b/backend/tests/test_runtime_sqlcheck.py @@ -150,6 +150,7 @@ async def test_a_failing_or_slow_check_never_breaks_the_query(scenic_source, mon def test_sql_check_failures_become_readable_gaps(): + # 没记来源快照(或快照读不出来)时退回口径卡那句;按查询归并的写法见 test_report_sqlcheck_cells metrics = [{"id": "gmv", "name": "订单金额", "value": 1, "sql_check_failed": True, "sql_check_reason": REASON}, {"id": "n", "name": "订单数", "value": 2}] assert sql_check_gaps(metrics) == [f"指标「订单金额」{REASON}"] @@ -246,11 +247,13 @@ async def test_a_fanout_behind_a_contract_metric_degrades_the_issuance(scenic_so "codes": ["fanout_sum"]}] assert "(存疑:所依据的查询未通过 SQL 检查)" in card["text"] warns = [e.data for e in await events(row.id, "log", "card") if e.data.get("code") == "metric_sql_check"] - assert [w["message"] for w in warns] == [f"指标「订单金额」{REASON}", f"指标「订单金额(整形后)」{REASON}"] + # 同一条查询算出的两个指标:时间线上一行,降档原因里一句(按查询归并,列出受影响的指标) + assert [w["message"] for w in warns] == [f"指标「订单金额」「订单金额(整形后)」{REASON}"] issuance = row.output["_issuance"] assert issuance["tier"] == "degraded", issuance - assert f"指标「订单金额」{REASON}" in issuance["gaps"] + assert [g for g in issuance["gaps"] if "SQL 检查" in g] == [ + f"查询「fetch」(Q1){REASON.removeprefix('所依据的查询')};受影响的引用:指标「订单金额」、指标「订单金额(整形后)」"] # 写作目录提醒写作者:这个数存疑,引用时要说明 assert "所依据的查询未通过 SQL 检查,结果存疑" in writer.prompts[0]