diff --git a/frontend/src/lib/sqlcheck.ts b/frontend/src/lib/sqlcheck.ts new file mode 100644 index 00000000..bc1b9a1d --- /dev/null +++ b/frontend/src/lib/sqlcheck.ts @@ -0,0 +1,65 @@ +import type { SqlCheckCode, SqlCheckItem, SqlCheckLevel } from '../types' +import { SQL_CHECK_LEVEL_LABEL, SQL_CHECK_RULE_LABEL, SQL_CHECK_TEXT } from './terms' + +// =========================================================================== +// 基于数据目录的 SQL 检查(后端 data/sqlcheck.py)在界面上的读法:规则编号 → 中文规则名、级别 → 语义色, +// 以及从证据接口、助手自查、发布前检查的问题里读出一条检查。证据面板、运行时间线、助手面板、发布前检查共用。 +// =========================================================================== + +/** 七条规则的编号(服务端 CHECK_CODES),按严重程度大致排序 */ +export const SQL_CHECK_CODES: readonly SqlCheckCode[] = [ + 'fanout_sum', 'stock_summed', 'join_unconfirmed', 'ratio_aggregated', 'missing_valid_filter', 'unknown_code', 'wrong_date_column', +] + +export const isSqlCheckCode = (code: unknown): code is SqlCheckCode => + typeof code === 'string' && (SQL_CHECK_CODES as readonly string[]).includes(code) + +/** 级别:认不出的按「提示」(最轻的一档),不把拿不准的说重 */ +export const sqlCheckLevelOf = (v: unknown): SqlCheckLevel => (v === 'error' || v === 'warning' ? v : 'info') + +/** 规则的中文名;服务端新加、这里还不认识的规则统称「SQL 检查」,不露编号 */ +export const sqlRuleLabel = (code: unknown): string => (isSqlCheckCode(code) ? SQL_CHECK_RULE_LABEL[code] : SQL_CHECK_TEXT.unknownRule) + +/** 各级别的颜色(语义令牌) */ +export const SQL_CHECK_TONE: Record = { + error: 'var(--st-failed)', + warning: 'var(--st-waiting)', + info: 'var(--accent)', +} + +const LEVEL_RANK: Record = { error: 0, warning: 1, info: 2 } + +/** 错误在前,同级保持原来的顺序 */ +export function sortSqlChecks(list: T[]): T[] { + return list.map((c, i) => ({ c, i })) + .sort((a, b) => LEVEL_RANK[sqlCheckLevelOf(a.c.level)] - LEVEL_RANK[sqlCheckLevelOf(b.c.level)] || a.i - b.i) + .map((x) => x.c) +} + +/** 涉及的表和列:「orders.amount」「orders」 */ +export const sqlCheckWhere = (c: Pick): string => + (c.table ? (c.column ? `${c.table}.${c.column}` : c.table) : (c.column ?? '')) + +/** 从任意对象读一条检查(证据接口的 checks、助手自查和发布前检查的问题);不是 SQL 检查的返回 null */ +export function sqlCheckOf(v: unknown): SqlCheckItem | null { + if (!v || typeof v !== 'object') return null + const o = v as Record + if (!isSqlCheckCode(o.code)) return null + const str = (x: unknown) => (typeof x === 'string' && x ? x : undefined) + return { + code: o.code, + level: sqlCheckLevelOf(o.level), + message: String(o.message ?? ''), + table: str(o.table) ?? '', + ...(str(o.column) ? { column: str(o.column) } : {}), + ...(str(o.relation_id) ? { relation_id: str(o.relation_id) } : {}), + ...(str(o.sql_excerpt) ? { sql_excerpt: str(o.sql_excerpt) } : {}), + } +} + +/** 一条检查写成一行(时间线的展开区、交给助手再修的清单):「错误 · 一对多关联后重复计算:……(涉及 orders.amount)」 */ +export function sqlCheckLine(c: SqlCheckItem): string { + const where = sqlCheckWhere(c) + return `${SQL_CHECK_LEVEL_LABEL[sqlCheckLevelOf(c.level)]} · ${sqlRuleLabel(c.code)}:${c.message}` + + (where ? `(${SQL_CHECK_TEXT.where} ${where})` : '') +} diff --git a/frontend/src/lib/terms.ts b/frontend/src/lib/terms.ts index e6c4a6ec..d2d26ff8 100644 --- a/frontend/src/lib/terms.ts +++ b/frontend/src/lib/terms.ts @@ -44,7 +44,7 @@ import type { CatalogCardinality, CatalogMeasure, CatalogProfileNumberKey, CatalogSource, CatalogStatus, CatalogTableKind, NodeType, SnapshotReasonCode, - ToolTrust, + SqlCheckCode, SqlCheckLevel, ToolTrust, } from '../types' import { formatNumber } from './format' @@ -248,6 +248,9 @@ export const EVIDENCE_TEXT = { /** 指标拿截断的查询结果整组算出来(计数、求和……):值只算到了取回的那部分,出具按缺口降档 */ incomplete: '结果不完整', incompleteFallback: '基于被截断的查询结果计算,结果不完整', + /** 指标所依据的查询对照数据目录查出了错误级的问题:值照算,出具按缺口降档 */ + sqlCheckFailed: 'SQL 检查未通过', + sqlCheckFallback: '所依据的查询未通过 SQL 检查,结果不可靠', /** 输入是 Agent 交来、被截断切开的数组字段 */ inputTruncated: '查询结果已截断,该字段只含取回的部分行', unshowable: (value: string) => `有值(${value}),但无法按口径卡的格式显示`, @@ -2365,3 +2368,67 @@ export const CODES_TEXT = { save: '保存', cancel: '取消', } + +// =========================================================================== +// 基于数据目录的 SQL 检查(后端 data/sqlcheck.py) +// +// 术语: +// - 「SQL 检查」:对照数据目录找出能执行、数却可能不对的写法。七条规则,界面上写中文规则名,不露规则编号。 +// - 级别:错误(依据已确认,结果必然有误)、提醒(依据已确认,结果很可能有误)、提示(依据只是推断,仅供参考)。 +// 颜色走语义令牌:错误 --st-failed,提醒 --st-waiting,提示 --accent。 +// =========================================================================== + +export const SQL_CHECK_RULE_LABEL: Record = { + fanout_sum: '一对多关联后重复计算', + stock_summed: '存量跨期加总', + join_unconfirmed: '关联条件未经确认', + ratio_aggregated: '比率直接加总或平均', + missing_valid_filter: '未筛选有效记录', + unknown_code: '码值不在码值表中', + wrong_date_column: '未按业务日期统计', +} + +export const SQL_CHECK_RULE_HINT: Record = { + fanout_sum: '沿一对多方向关联后,对「一」那一侧的度量求和或计数,会按明细行数重复计算', + stock_summed: '对存量列求和却没有按业务日期分组,不同日期的存量被加在一起', + join_unconfirmed: '关联条件对不上数据目录中有确证的关系,可能连错了列', + ratio_aggregated: '对比率列直接求和或求平均,得不到正确的比率', + missing_valid_filter: '表定义了有效记录条件,查询没有按它筛选', + unknown_code: '按码值筛选时用了码值表中没有的值', + wrong_date_column: '表定义了业务日期,查询却按另一个时间列分组或筛选', +} + +export const SQL_CHECK_LEVEL_LABEL: Record = { + error: '错误', + warning: '提醒', + info: '提示', +} + +export const SQL_CHECK_LEVEL_HINT: Record = { + error: '依据已确认,结果必然有误', + warning: '依据已确认,结果很可能有误', + info: '依据尚未确认(推断),仅供参考', +} + +export const SQL_CHECK_TEXT = { + title: 'SQL 检查', + /** 规则编号不认识(服务端新加了规则)时的叫法 */ + unknownRule: 'SQL 检查', + listLabel: (n: number) => `SQL 检查发现 ${formatNumber(n)} 处问题`, + where: '涉及', + excerpt: 'SQL 片段', + catalogHint: '检查依据来自数据目录。依据有误时,请在数据目录中修正对应项。', + // ---- 运行时间线:指标所依据的查询没通过 SQL 检查(日志 metric_sql_check) + metricTitle: (name: string, n = 1) => + (n > 1 ? `指标「${name}」所依据的查询有 ${formatNumber(n)} 处未通过 SQL 检查` : `指标「${name}」所依据的查询未通过 SQL 检查`), + metricTitleAnon: '指标所依据的查询未通过 SQL 检查', + metricNext: '指标照常计算,但结果不可靠,出具按缺口降档。请在证据面板的查询步骤中查看问题,修改 SQL 后重新运行;' + + '检查依据有误时,请在数据目录中修正对应项', + // ---- 助手:搭图时查出的问题 + counts: (errors: number, warnings: number, infos: number) => + [errors ? `${formatNumber(errors)} 处错误` : '', warnings ? `${formatNumber(warnings)} 处提醒` : '', + infos ? `${formatNumber(infos)} 处提示` : ''].filter(Boolean).join('、'), + assistantTitle: (counts: string) => `SQL 检查:${counts}`, + assistantNext: '请打开对应节点,在「参数」中修改 SQL;检查依据有误时,请在数据目录中修正对应项', + assistantInfoNext: '这些检查的依据尚未确认,仅供参考。在数据目录中确认相关项后,检查结论更可靠', +} diff --git a/frontend/src/run/EvidencePanel.tsx b/frontend/src/run/EvidencePanel.tsx index a7b88294..4a5ff4ff 100644 --- a/frontend/src/run/EvidencePanel.tsx +++ b/frontend/src/run/EvidencePanel.tsx @@ -18,7 +18,7 @@ import { } from '../lib/evidence' import { humanizeError } from '../lib/errors' import { formatDateTime, formatNumber, NONE, shortId } from '../lib/format' -import { EVIDENCE_TEXT, JUDGE_TEXT, MERGE_TEXT, NODE_TYPE_LABEL, nodeTypeLabel } from '../lib/terms' +import { EVIDENCE_TEXT, JUDGE_TEXT, MERGE_TEXT, NODE_TYPE_LABEL, SQL_CHECK_TEXT, nodeTypeLabel } from '../lib/terms' import { useCatalog } from '../store/catalog' import { askKey, segmentKey, useEvidence, useExplore, useVerdicts } from '../store/evidence' import type { @@ -29,6 +29,7 @@ import { ArtifactViewer, ResultTable } from './AssistantStream' import { useEvidenceHost } from './evidenceHost' import { EvidenceProvenance } from './EvidenceProvenance' import { CopyChip } from './Markdown' +import { SqlCheckList } from './SqlChecks' /** * 证据面板:点开报告里的一个片段,看它从哪来。 @@ -1109,6 +1110,9 @@ function MetricPart({ step, entry, inputs, runId, seal, pending, failed, resolve // 拿截断的查询结果整组算出来的:值是真的算出来的,但只算到了取回的那部分,出具已按缺口降档 const incomplete = step?.incomplete === true || entry?.incomplete === true const incompleteReason = step?.incomplete_reason || entry?.incomplete_reason || EVIDENCE_TEXT.incompleteFallback + // 所依据的查询对照数据目录查出了错误级的问题:值照算,结果不可靠,出具同样按缺口降档。问题和改法在查询步骤里 + const sqlFailed = step?.sql_check_failed === true || entry?.sql_check_failed === true + const sqlReason = step?.sql_check_reason || entry?.sql_check_reason || EVIDENCE_TEXT.sqlCheckFallback return ( @@ -1121,6 +1125,12 @@ function MetricPart({ step, entry, inputs, runId, seal, pending, failed, resolve {EVIDENCE_TEXT.incomplete} )} + {sqlFailed && ( + + {EVIDENCE_TEXT.sqlCheckFailed} + + )} {(caliber || version || artifact || from) && (
@@ -1139,6 +1149,9 @@ function MetricPart({ step, entry, inputs, runId, seal, pending, failed, resolve {incomplete && (

{incompleteReason}

)} + {sqlFailed && ( +

{sqlReason}

+ )} {unshowable && (

{EVIDENCE_TEXT.unshowable(valueText(value))} @@ -1366,6 +1379,13 @@ function QueryPart({ id, step, seal, masked }: { id: string; step: EvidenceStep; {step.sql} )} + {!!step.checks?.length && ( + // 这次查询对照数据目录查出的问题:说明、涉及的表和列、SQL 片段。没查出问题时接口不给这个键 +

+
{SQL_CHECK_TEXT.title}
+ +
+ )} {!!step.merge?.warnings.length && (
{MERGE_TEXT.executionWarnings}
diff --git a/frontend/src/run/SqlChecks.tsx b/frontend/src/run/SqlChecks.tsx new file mode 100644 index 00000000..f82358c6 --- /dev/null +++ b/frontend/src/run/SqlChecks.tsx @@ -0,0 +1,74 @@ +import { Info, OctagonX, TriangleAlert } from 'lucide-react' +import type { LucideIcon } from 'lucide-react' +import clsx from 'clsx' +import type { SqlCheckItem, SqlCheckLevel } from '../types' +import { SQL_CHECK_LEVEL_HINT, SQL_CHECK_LEVEL_LABEL, SQL_CHECK_RULE_HINT, SQL_CHECK_TEXT } from '../lib/terms' +import { SQL_CHECK_TONE, isSqlCheckCode, sortSqlChecks, sqlCheckLevelOf, sqlCheckWhere, sqlRuleLabel } from '../lib/sqlcheck' + +// =========================================================================== +// SQL 检查的结果:级别标识(错误、提醒、提示,四通道:图标、文字、颜色、边框)、中文规则名、给人看的说明、涉及的表和列、 +// SQL 片段。证据面板的查询步骤和助手面板共用这一份。 +// =========================================================================== + +const LEVEL_ICON: Record = { error: OctagonX, warning: TriangleAlert, info: Info } + +/** 级别标识:图标 + 「错误 / 提醒 / 提示」,悬停写明依据的确证程度 */ +export function SqlLevelBadge({ level: raw, className }: { level: unknown; className?: string }) { + const level = sqlCheckLevelOf(raw) + const Icon = LEVEL_ICON[level] + const tone = SQL_CHECK_TONE[level] + return ( + + + {SQL_CHECK_LEVEL_LABEL[level]} + + ) +} + +/** 一条检查的正文:规则名、说明、涉及的表和列、SQL 片段 */ +export function SqlCheckBody({ check: c, excerpt = true }: { check: SqlCheckItem; excerpt?: boolean }) { + const where = sqlCheckWhere(c) + return ( + <> +
+ + + {sqlRuleLabel(c.code)} + + {where && ( + + {SQL_CHECK_TEXT.where} {where} + + )} +
+ {c.message &&

{c.message}

} + {excerpt && c.sql_excerpt && ( +
+          {c.sql_excerpt}
+        
+ )} + + ) +} + +/** 检查结果的清单:错误在前。每条一个淡色框,框的颜色跟级别走 */ +export function SqlCheckList({ checks, className }: { checks: SqlCheckItem[]; className?: string }) { + const list = sortSqlChecks(checks) + return ( +
    + {list.map((c, i) => { + const tone = SQL_CHECK_TONE[sqlCheckLevelOf(c.level)] + return ( +
  • + +
  • + ) + })} +
+ ) +} diff --git a/frontend/src/run/decode.ts b/frontend/src/run/decode.ts index f9ecb1ff..5494e74b 100644 --- a/frontend/src/run/decode.ts +++ b/frontend/src/run/decode.ts @@ -1,7 +1,7 @@ import type { RunEvent, TeamMember, TeamRound, TeamRun, ToolChange } from '../types' import type { NodeState, RunPhase } from './trace' import { formatDuration, formatNumber } from '../lib/format' -import { JUDGE_TEXT, MERGE_TEXT, TYPE_LABEL, claimTally, evidenceTally, issuanceLabel, nodeTypeLabel } from '../lib/terms' +import { JUDGE_TEXT, MERGE_TEXT, SQL_CHECK_TEXT, TYPE_LABEL, claimTally, evidenceTally, issuanceLabel, nodeTypeLabel } from '../lib/terms' import { claimCountsOf, isJudged, statsTally } from '../lib/evidence' // 泳道数据画布也要用(supervisor 节点要展开成协作矩阵),所以类型放在 @@ -775,6 +775,20 @@ function explainLog(code: string | undefined, message: string): Pick { incomplete?: boolean /** metric:不完整的原因(人话,「基于被截断的查询结果计算(只取回了前 1000 行),结果不完整」) */ incomplete_reason?: string + /** metric:所依据的查询没通过 SQL 检查(有错误级的问题),值照算,出具已按缺口降档 */ + sql_check_failed?: boolean + /** metric:没通过的原因(人话,「所依据的查询未通过 SQL 检查(…),结果不可靠」) */ + sql_check_reason?: string + /** query:这次查询对照数据目录查出的问题。没查出问题时没有这个键 */ + checks?: SqlCheckItem[] inputs?: EvidenceInput[] /** 口径卡钉在哪个工作流的哪一版(metric;方案第 5 节的写法,接口实际给在 source 上) */ caliber_from?: EvidenceCaliberSource | null