from __future__ import annotations import re from dataclasses import dataclass, field from typing import Any, Callable from app.engine.sql_problems import problem_clause, query_problems # -------------------------------------------------------------------------- # 出具校验:叙述里的每个数字必须能回指到指标集 # # 前提是派生边界已经收死:所有算术都发生在口径卡(metrics 节点)里, # 叙述层只能引用。所以这里不需要"验证模型算得对不对"——只需要验证 # "它写的每个数都在清单里"。集合外的数字没有合法来源,一律视为现编。 # -------------------------------------------------------------------------- # 数字 token:可带千分位逗号、小数,后缀 %/% 或 万/亿 # # 后瞻里刻意只排 ASCII 词字符,**不能**写成 (?{_CN_N})" rf"|(?P{_CN_N})分之(?P{_CN_N})" rf"|(?P一半)" rf"|(?P{_CN_N})(?P成|倍|个百分点|[余多来])?" ) #: 单字数字后面跟着这些,才算在报一个量 _CN_COUNT_UNIT = re.compile( r"(个月|个季度|个工作日|小时|分钟|万元|亿元|美元|公里|公斤|千克" r"|[家个名位人次笔单台件项条款种类批辆套份张户所座间天周年秒元块吨米克升岁页篇起宗例箱瓶包支只盒袋场轮届])" ) #: "从三个方面看":列举的是论述的结构,不是数据 _CN_STRUCTURAL = re.compile( r"个(方面|原因|问题|建议|要点|维度|阶段|步骤|部分|层面|角度|环节|关键|特点|优势|挑战|结论|措施)" ) def _cn_section(text: str) -> int | None: """万以内的一段:十二、两千五百、一百零五、两千五(省略写法 = 2500)。""" total, digit, last_unit, zero = 0, None, None, False for ch in text: if ch in ("零", "〇"): if digit is not None: return None zero = True elif ch in _CN_DIGIT: if digit is not None: # 两个数字挨着(一一、五一):不是数 return None digit = _CN_DIGIT[ch] elif ch in _CN_UNIT: unit = _CN_UNIT[ch] if last_unit is not None and unit >= last_unit: return None # 单位只能往下走:十百、百千都不是数 total += (1 if digit is None else digit) * unit # 开头的"十" = 一十 digit, last_unit, zero = None, unit, False else: return None if digit is not None: # 两千五 = 2500:单位后面省掉了下一级单位;有"零"隔开时(一百零五)才是个位 total += digit * (last_unit // 10 if last_unit and not zero else 1) return total def _cn_integer(text: str) -> int | None: for char, mult in _CN_BIG.items(): if char in text: head, tail = text.split(char, 1) if not head: # 光一个"万"是一万;"万一"不是一万一千,是"万一" return mult if not tail else None head_value = _cn_integer(head) if head_value is None: return None if len(tail) == 1 and tail in _CN_DIGIT: # 一万二 = 12000 tail_value: int | None = _CN_DIGIT[tail] * mult // 10 else: tail_value = _cn_integer(tail) if tail else 0 if tail_value is None: return None return head_value * mult + tail_value return _cn_section(text) def cn_to_number(text: str) -> float | None: """两千五百 → 2500,一万二 → 12000,三点五万 → 35000。不是数返回 None。""" integer, _, frac = text.partition("点") mult = 1 if frac and frac[-1] in _CN_BIG: mult, frac = _CN_BIG[frac[-1]], frac[:-1] value = _cn_integer(integer) if value is None or (not integer): return None if frac: return (value + float("0." + "".join(str(_CN_DIGIT[c]) for c in frac))) * mult return float(value * mult) def _cn_precision(text: str, value: float) -> float: """这个中文数字写到哪一位:三万 → 10000,两千五百 → 100,三点五万 → 1000。 中文不写末尾的零,最后一个数字落在哪一位,精度就是哪一位。十以内的整数 (十二、二十)按精确数处理——"十家"就是十家。 """ if "点" in text: integer, _, frac = text.partition("点") mult = _CN_BIG.get(frac[-1], 1) if frac else 1 digits = len(frac) - (1 if mult != 1 else 0) return 10 ** (-digits) * mult whole = int(value) if whole < 100: return 1 step = 1 while whole % (step * 10) == 0: step *= 10 return step @dataclass class NumberToken: raw: str value: float decimals: int is_percent: bool context: str start: int #: 回指时允许的偏差。缺省按写出的小数位数算;中文数字、带万亿后缀的数有自己的书写精度 tolerance: float | None = None @property def end(self) -> int: """raw 在原文里的结束位置。raw 只去掉了右侧空白,开头就是 start。""" return self.start + len(self.raw) @dataclass class TraceReport: matched: list[dict[str, Any]] = field(default_factory=list) unmatched: list[dict[str, Any]] = field(default_factory=list) @property def ok(self) -> bool: return not self.unmatched def _skip_spans(text: str) -> list[tuple[int, int]]: spans: list[tuple[int, int]] = [] for pattern in _SKIP_PATTERNS: for m in pattern.finditer(text): spans.append(m.span()) return spans def _context(text: str, start: int, end: int) -> str: return text[max(0, start - 18) : min(len(text), end + 18)].replace("\n", " ") def extract_numbers(text: str) -> list[NumberToken]: """抽出叙述里所有需要回指的数字,剔除日期、枚举序号、引用标记这类形态。""" skip = _skip_spans(text) tokens: list[NumberToken] = [] taken: list[tuple[int, int]] = [] for m in _NUM_RE.finditer(text): start, end = m.span() if any(s <= start < e for s, e in skip): continue raw_num = m.group(1).replace(",", "") suffix = m.group(2) or "" try: value = float(raw_num) except ValueError: continue decimals = len(raw_num.split(".")[1]) if "." in raw_num else 0 tolerance = None if suffix in _SUFFIX_MULT: value *= _SUFFIX_MULT[suffix] # 书写精度跟着后缀走:3.5万写到千位,容差 ±500,而不是 3.5 那一位小数的 ±0.05 tolerance = 0.5 * 10 ** (-decimals) * _SUFFIX_MULT[suffix] taken.append((start, end)) tokens.append( NumberToken( raw=m.group(0).strip(), value=value, decimals=decimals, is_percent=suffix in ("%", "%") or text[max(0, start - 3) : start] == "百分之", context=_context(text, start, end), start=start, tolerance=tolerance, ) ) tokens.extend(_cn_numbers(text, skip + taken)) tokens.sort(key=lambda t: t.start) return tokens def _cn_not_a_quantity(numeral: str, suffix: str, value: float, before: str, after: str) -> bool: """这串中文数字字是不是在报一个量。规则见文件头"中文数字"一节。""" if suffix in ("成", "倍", "个百分点"): return False # 三成、两倍:比例写法,单字也是量 if before.endswith("第"): return True # 第三 if before.endswith(("周", "星期", "礼拜")) and len(numeral) == 1: return True # 周三 if before[-1:] in ("几", "数", "上") or after.startswith("几"): return True # 几十、数百、上千、十几:虚指 if not suffix: if (after.startswith("月") and value <= 12) or (after.startswith(("日", "号")) and value <= 31): return True # 十二月、十五日 if after.startswith("季度"): return True # 三季度 = Q3("三个季度"不走这里) if numeral in ("十一", "五一") and after.startswith(("假", "长假", "期间", "黄金周")): return True if _CN_STRUCTURAL.match(after): return True # 从三个方面看 # 单字,或只有单位没有数字的(千万、百万):后面跟着计数单位才是量。 # "一"再加一道:一个问题、一次调用多半是冠词用法 bare = len(numeral) == 1 or not any(c in _CN_DIGIT for c in numeral) if bare and "点" not in numeral: if numeral == "一": return True if not _CN_COUNT_UNIT.match(after): return True # 五花八门、十分重要、千方百计、千万不要 return False def _cn_numbers(text: str, blocked: list[tuple[int, int]]) -> list[NumberToken]: tokens: list[NumberToken] = [] def add(m: re.Match[str], value: float, tolerance: float, *, is_percent: bool) -> None: tokens.append(NumberToken( raw=m.group(0), value=value, decimals=0, is_percent=is_percent, context=_context(text, m.start(), m.end()), start=m.start(), tolerance=tolerance, )) for m in _CN_RE.finditer(text): start, end = m.span() if any(s < end and start < e for s, e in blocked): continue if m.group("pct"): # 百分之三十:和 30% 同一个精度 value = cn_to_number(m.group("pct")) if value is not None: decimals = len(m.group("pct").partition("点")[2]) add(m, value, 0.5 * 10 ** -decimals, is_percent=True) continue if m.group("den"): # 三分之一:按百分数、±5 个点回指 den, numr = cn_to_number(m.group("den")), cn_to_number(m.group("numr")) if den and numr is not None: add(m, numr / den * 100, 5, is_percent=True) continue if m.group("half"): # 一半 add(m, 50, 5, is_percent=True) continue numeral, suffix = m.group("num"), m.group("suffix") or "" value = cn_to_number(numeral) if value is None: continue if _cn_not_a_quantity(numeral, suffix, value, text[max(0, start - 2) : start], text[end : end + 8]): continue if suffix == "成": # 三成 = 30%,口语精度半成 add(m, value * 10, 5, is_percent=True) elif suffix in ("余", "多", "来"): # 两千余 = [2000, 3000] step = 1 while value >= step * 10 and value % (step * 10) == 0: step *= 10 add(m, value + step / 2, step / 2, is_percent=False) else: add(m, value, 0.5 * _cn_precision(numeral, value), is_percent=suffix == "个百分点") return tokens def _tolerance(token: NumberToken) -> float: """按 token 写出的精度给舍入容差:写了 12.3 就允许 |Δ|≤0.05。""" if token.tolerance is not None: return token.tolerance return 0.5 * 10 ** (-token.decimals) def _close(a: float, b: float, tolerance: float) -> bool: return abs(a - b) <= tolerance + 1e-9 def _token_matches(token: NumberToken, metric_value: float) -> bool: tolerance = _tolerance(token) # 直接比对(含"叙述写百分数、指标本身就是百分数"的情形) if _close(token.value, metric_value, tolerance): return True if token.is_percent: # 指标存的是比率(0.123),叙述写成 12.3% if _close(token.value, metric_value * 100, tolerance): return True return False def number_allowance(allow: list[Any] | None) -> Callable[[NumberToken], bool]: """模板作者放行的字面量:写法相同,或者数值在这个 token 的书写精度内相等。 旧契约的回指和报告节点的裸数字检查共用这一条,两边放行的范围才一致。 """ allowed = {str(a).strip() for a in (allow or [])} values = set() for a in allowed: try: values.add(float(a.replace(",", "").rstrip("%%"))) except ValueError: pass def ok(token: NumberToken) -> bool: if token.raw in allowed or token.raw.rstrip("%%").strip() in allowed: return True return any(_close(token.value, v, _tolerance(token)) for v in values) return ok def trace_numbers( narrative: str, metrics: list[dict[str, Any]], *, allow: list[Any] | None = None, ) -> TraceReport: """叙述 vs 指标集的回指校验。 allow 是模板作者显式放行的字面量(比如报告标题里的期数)—— 白名单是配置的一部分,进版本、被审查,而不是校验器私藏的宽容。 """ # 值和指标成对取:以前值列表排掉了布尔、指标列表没排,一个布尔指标就让后面的全错位 numeric = [ (m, float(m["value"])) for m in metrics if isinstance(m.get("value"), (int, float)) and not isinstance(m.get("value"), bool) ] allowed = number_allowance(allow) report = TraceReport() for token in extract_numbers(narrative): if allowed(token): continue where = {"start": token.start, "end": token.end} # 同一个值可能同时对得上好几个指标(最典型的是一排兜底出来的 0)。以前取第一个 # 命中的,界面上所有的 0 都标成「来自指标 A」——出处不唯一就照实说不唯一 hits = list(dict.fromkeys(m.get("id") for m, mv in numeric if _token_matches(token, mv))) if len(hits) == 1: report.matched.append({"token": token.raw, "metric": hits[0], **where}) elif hits: report.matched.append({"token": token.raw, "metric": None, "candidates": hits, "ambiguous": True, **where}) else: report.unmatched.append({"token": token.raw, "context": token.context, **where}) return report def metrics_only(contract: Any) -> bool: """指标出具:契约写了「指标来自」,没写「报告来自」也没写「叙述」——出具的就是指标本身(纯指标看板,用户 2026-10-15 拍板)。三档的语义不变,核对的对象从叙述换成指标:必需指标缺了不予出具;成果字段里给人看的数要回指到指标集; 每个指标的输入要追到原始数据(engine/lineage),追不到的照实写进缺口、不盖完整出具。""" if not isinstance(contract, dict): return False sources = contract.get("metrics_from") or [] return bool(sources) and contract.get("report_from") in (None, "") \ and not str(contract.get("narrative") or "").strip() def decide_tier( *, missing_required: list[str], missing_expected: list[str], unmatched: list[dict[str, Any]], strict: bool, gaps: list[str] | None = None, unresolved: list[Any] | None = None, unsupported: list[Any] | int | None = None, uncited_claims: list[Any] | int | None = None, claims_policy: str | dict[str, Any] | None = None, ) -> str: """三档出具的判定。 withheld(不予出具):必需指标缺失,或 strict 下有未回指数字—— 结论的地基不完整,宁可不出。 degraded(降档出具):期望指标缺失、有未回指数字,或校验本身没能完整跑起来。 formal(完整出具):清单齐、数字全部可回指,**且校验确实发生过**。 最后那句是这个函数最容易出错的地方:missing/unmatched 全空既可能是 "查过了都对",也可能是"根本没查"——叙述模板里一个笔误让 narrative 渲染成 空串、metrics_from 指向不存在的节点,都会得到一模一样的空列表。 校验没发生就盖 formal 章,比漏检某个数字更糟:它让整套机制看起来在工作。 所以 gaps 用来承载"校验为什么不完整",非空就不允许 formal。 引用模式另有几样:unresolved 是解析不了的引用(报告里写了 [[m:gmvx]],目录里 没有),和未回指数字同等对待——那个位置上显示的不是一个有出处的数。 unsupported / uncited_claims 是结论句的判定,只在声明了 claims_policy 时才参与: 字符串(judge / require_citation)两样都按降档处理;对象形式可以分别写 on_unsupported / on_uncited 为 degrade、withhold 或 ignore。不声明就不管, 旧调用和没开结论检查的契约都不受影响。 """ if missing_required: return "withheld" if strict and (unmatched or unresolved): return "withheld" claims = _claims_effect(claims_policy, unsupported, uncited_claims) if claims == "withhold": return "withheld" if missing_expected or unmatched or unresolved or gaps or claims == "degrade": return "degraded" return "formal" def incomplete_gaps(metrics: list[dict[str, Any]]) -> list[str]: """契约收来的指标里结果不完整的(口径卡标了 incomplete:拿截断的查询结果整组算出来的),每个一句缺口。 交给 decide_tier 的 gaps:完整出具的前提是每个数都算全了。「前 1000 行的人次」不是「入园人次」, 数字照样回指得上口径卡,只看回指的话它会被盖上完整出具的章。原因用口径卡记下的那句,读的人 看得懂是哪个指标、为什么不完整。 """ return [f"指标「{m.get('name') or m.get('id')}」{m.get('incomplete_reason') or '结果不完整'}" for m in metrics if isinstance(m, dict) and m.get("incomplete")] def no_data_gaps(metrics: list[dict[str, Any]]) -> list[str]: """契约收来的指标里,输入取自「查询区间里这张表没有数据」的列的(口径卡标了 no_data,data/coverage.py),每个一句缺口。 数回指得上口径卡、复算也一致,可那个 0 是因为这段时间表里根本没有数据,不是真的是 0:盖完整出具的章等于替「上周到访 0 人」作保。原因用口径卡记下的那句(查询记下的区间和表里的范围)。""" return [f"指标「{m.get('name') or m.get('id')}」{m.get('no_data_reason') or '所依据的查询区间里这张表没有数据'}" for m in metrics if isinstance(m, dict) and m.get("no_data")] 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_check_findings 的那几句缺口(见下)。""" return [f["text"] for f in sql_check_findings(metrics, cited, label=label)] def sql_check_findings(metrics: list[dict[str, Any]], cited: dict[str, list[str]] | None = None, *, label: Callable[[str, str | None], str | None] | None = None) -> list[dict[str, Any]]: """没通过 SQL 检查(error 级:一对多关联后重复计算、存量跨期加总)的查询,每条一句缺口。 两处来历:契约收来的指标(口径卡标了 sql_check_failed,sql_check_sources 记着取数的查询快照),以及报告直接 引用的查询(cited:{查询快照 id: [引用的写法…]},单元格、表格、[[see:]] 依据)。数字照样回指得上,口径卡照样 复算一致,但算它的那条查询本身就把数算错了,盖完整出具的章等于替一个错数作保。 按出问题的那条查询归并(合并查询顺着输入找到源查询):同一条查询算出三个指标、报告又引用了它的格,也只记一句, 句子里列出受影响的引用。label(快照 id, 节点 id) 给出「查询「取数」(Q1)」这样的称呼,给不出就写「所依据的查询」。 指标标了 sql_check_failed、快照却读不出来(被清理、被改过)的,退回口径卡记下的那句:缺口不能因为读不到快照就消失。 每条一个 dict:text(缺口那句)、query(称呼)、artifact、node_id、problems、refs。出具声明里另存一份 sql_checks:报告页据此在显眼处说「因为 SQL 检查没通过而降档」,不用从缺口的中文里认。 """ groups: dict[str, dict[str, Any]] = {} fallback: list[dict[str, Any]] = [] 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({"text": f"{name}{m.get('sql_check_reason') or '所依据的查询未通过 SQL 检查'}", "query": None, "artifact": None, "node_id": None, "problems": [], "refs": [name]}) for artifact, refs in (cited or {}).items(): for ref in refs: add(artifact, ref) out = [] for artifact, group in groups.items(): problem = group["problem"] named = label(artifact, problem.node_id) if label else None who = named or "所依据的查询" refs = group["refs"] listed = "、".join(refs[:_SQL_REFS]) + (f"等 {len(refs)} 处" if len(refs) > _SQL_REFS else "") out.append({"text": f"{who}{problem_clause(problem.problems)};受影响的引用:{listed}", "query": named, "artifact": artifact, "node_id": problem.node_id, "problems": problem.problems, "refs": refs[:_SQL_REFS * 2]}) return out + fallback #: 一句 SQL 检查缺口里最多列出几处受影响的引用(计数照实) _SQL_REFS = 8 def _claims_effect( policy: str | dict[str, Any] | None, unsupported: list[Any] | int | None, uncited: list[Any] | int | None, ) -> str | None: """结论句对档位的影响:withhold / degrade / None。""" if isinstance(policy, dict): name = policy.get("policy") on_unsupported = policy.get("on_unsupported") or "degrade" on_uncited = policy.get("on_uncited") or "degrade" else: name, on_unsupported, on_uncited = policy, "degrade", "degrade" if not name or name == "off": return None def count(value: list[Any] | int | None) -> int: return value if isinstance(value, int) else len(value or []) effects = [on for on, n in ((on_unsupported, count(unsupported)), (on_uncited, count(uncited))) if n] if "withhold" in effects: return "withhold" if "degrade" in effects: return "degrade" return None