独立语义指标库与文档一键拆解:支持多表参数化 SQL 模板、后台进度与 Oracle 方言

- 新增独立语义指标模型(SemanticMetric)与 metric_query 内置工具,同时支持单表聚合表达式(expression)与跨表 JOIN / CTE 参数化模板(sql_template)
- 新增后台口径文档一键拆解任务(SemanticDecomposeJob),支持实时阶段进度、转后台执行、中途取消,串联知识库红线归档、盲列数据目录补丁、指标试算与标准实体绑定四层资产一键落库
- 完善多数据库方言确定性编译(重点补齐 Oracle 顶层 WITH + ROWNUM 限流、标识符引号规整、DATE 字面量与 TO_CHAR 时间粒度转换)
This commit is contained in:
ThearchyHelios
2026-11-12 12:58:24 +08:00
parent e15e94f93e
commit f144ef16d2
14 changed files with 6078 additions and 145 deletions
+3
View File
@@ -42,6 +42,7 @@ import { blueprints, files, personal, templates } from './blueprints'
// 问数据的一轮在服务端跑(编排完善第 1 波):发起、看、停,实时流在 chatTurns.ts 的 streamChatTurn
import { chatTurns } from './chatTurns'
import { ontology } from './ontology'
import { semanticMetrics } from './semanticMetrics'
// 请求层搬到了 http.ts(见那边的说明)。原先从这里导出的照旧从这里导出,调用方不用改;
// 请求函数也一并转出,给不在 api/ 下、又想直接发请求的地方用。api/ 下的命名空间文件请直接从 http.ts 导入
@@ -1009,6 +1010,8 @@ export const api = {
chatTurns,
// 业务本体:标准业务实体与跨口径指标拓扑
ontology,
// 独立语义指标库(SemanticMetric):即存即生效指标卡片、在线试算与智能提取
semanticMetrics,
}
/**
+283
View File
@@ -0,0 +1,283 @@
/**
* 独立语义指标库(SemanticMetric)与后台文档一键拆解工作流 REST 客户端(服务端 backend/app/api/semantic_metrics.py)。
*
* 与工作流受管口径(caliberLedger)互补:
* - 单表模式(expression):绑定「数据源 + 物理表 + 单表聚合 SQL 表达式」;
* - 多表 / 参数化模式(sql_template):支持跨表 JOIN、WITH CTE 预聚合与 {{select_dims}}、{{and_where}}、{{period_days}} 等安全槽位;
* - 后台一键拆解任务(decomposeJobs):喂入业务文档后在后台分阶段拆解「字段目录补丁 + 单表/多表指标口径 + 标准业务实体 + 知识库归档」。
*/
import { del, get, post, put, qs, upload, type RequestOptions, type UploadOptions } from './http'
export type MetricCalcMode = 'expression' | 'sql_template'
export interface SemanticMetricDimension {
key: string
label: string
column: string
entity_key?: string
}
export interface SemanticMetric {
id: string
key: string
name: string
aliases: string[]
description: string
unit: string
source_id: string
source_name?: string
calc_mode?: MetricCalcMode | string
table_name: string
sql_expression: string
sql_template?: string
aggregation_type: string
date_column: string
filter_sql: string
dimensions: SemanticMetricDimension[]
default_time_grain: string
status: 'enabled' | 'disabled' | 'draft' | string
source: 'human' | 'ai' | 'doc' | string
version: number
created_by?: string | null
updated_by?: string | null
created_at?: string | null
updated_at?: string | null
}
export interface SemanticMetricInput {
key: string
name: string
aliases?: string[]
description?: string
unit?: string
source_id: string
calc_mode?: MetricCalcMode | string
table_name?: string
sql_expression?: string
sql_template?: string
date_column?: string
filter_sql?: string
dimensions?: SemanticMetricDimension[]
default_time_grain?: string
status?: string
source?: string
expected_version?: number
exists_in_db?: boolean
}
export interface SemanticMetricPreviewIn {
metric_id?: string
definition?: Record<string, unknown>
date_from?: string | null
date_to?: string | null
group_by_date?: boolean
time_grain?: string | null
group_by?: string[]
filters?: Record<string, unknown>
limit?: number
}
export interface SemanticMetricPreviewOut {
sql: string
source_name: string
columns: string[]
rows: unknown[][]
row_count: number
truncated: boolean
elapsed_ms: number
entity_alignments: Record<string, unknown>[]
latest_available_date?: string | null
}
export interface SemanticMetricSuggestOut {
source_id: string
source_name: string
model_id?: string | null
documents_used: string[]
candidates: SemanticMetricInput[]
skipped: { key: string; reason: string }[]
}
export interface DecomposeAttachmentOut {
attachment_id: string
title: string
mime: string
char_count: number
chunk_count: number
saved_to_kb: boolean
document_id?: string | null
collection?: string | null
}
export interface SemanticDecomposeStep {
key: string
label: string
status: 'pending' | 'running' | 'succeeded' | 'skipped' | 'failed' | string
detail: string
count: number
elapsed_ms: number
}
export interface SemanticCatalogChangeItem {
id: string
table: string
path: string
slot_label: string
before: unknown
after: unknown
value: unknown
reason: string
state: string
}
export interface SemanticCatalogPatchTable {
table: string
if_version: number
changes: SemanticCatalogChangeItem[]
}
export interface SemanticEntityChange {
id: string
op: string
entity_key: string
entity_label: string
summary: string
before: unknown
after: unknown
reason: string
op_payload: Record<string, unknown>
}
export interface SemanticGuardrailNote {
title: string
rule: string
category: string
}
export interface SemanticDecomposeAppliedRecord {
applied_at: string
applied_by?: string | null
catalog_applied_count: number
catalog_errors: string[]
metrics_created_count: number
metrics_updated_count: number
metric_errors: { key: string; reason: string }[]
entities_applied_count: number
entity_errors: string[]
}
export interface SemanticDecomposeResult {
model_id?: string | null
kb_documents?: { id: string; title: string; created_now: boolean }[]
guardrail_notes?: SemanticGuardrailNote[]
catalog_patches?: SemanticCatalogPatchTable[]
catalog_skipped?: string[]
metric_candidates?: SemanticMetricInput[]
metric_skipped?: { key: string; reason: string }[]
entity_changes?: SemanticEntityChange[]
entity_skipped?: string[]
applied?: SemanticDecomposeAppliedRecord | null
}
export interface SemanticDecomposeJob {
id: string
status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | string
source_id: string
source_name: string
scopes: string[]
document_ids: string[]
attachment_ids: string[]
doc_title: string
has_doc_text: boolean
save_to_kb: boolean
note: string
phase: string
phase_label: string
progress: number
steps: SemanticDecomposeStep[]
summary: Record<string, unknown>
result?: SemanticDecomposeResult
error?: string | null
started_by?: string | null
started_at?: string | null
finished_at?: string | null
created_at?: string | null
updated_at?: string | null
}
export interface SemanticDecomposeCreateIn {
source_id: string
scopes?: string[]
table_names?: string[]
document_ids?: string[]
attachment_ids?: string[]
doc_title?: string
doc_text?: string
save_to_kb?: boolean
note?: string
}
export interface SemanticDecomposeApplyIn {
catalog_patches?: { table: string; changes: { path: string; value: unknown; reason: string }[] }[]
metrics?: SemanticMetricInput[]
entity_operations?: Record<string, unknown>[]
overwrite_existing_metrics?: boolean
}
export const semanticMetrics = {
list: (params?: { source_id?: string; status?: string; q?: string }, opts?: RequestOptions) =>
get<{ items: SemanticMetric[]; total: number }>(
`/semantic-metrics${qs({
source_id: params?.source_id,
status: params?.status,
q: params?.q,
})}`,
opts,
),
get: (id: string, opts?: RequestOptions) =>
get<{ metric: SemanticMetric }>(`/semantic-metrics/${encodeURIComponent(id)}`, opts),
create: (body: SemanticMetricInput) =>
post<{ metric: SemanticMetric }>('/semantic-metrics', body),
batchCreate: (items: SemanticMetricInput[]) =>
post<{ created: SemanticMetric[]; skipped: { key: string; reason: string }[] }>('/semantic-metrics/batch', { items }),
update: (id: string, body: Partial<SemanticMetricInput>) =>
put<{ metric: SemanticMetric }>(`/semantic-metrics/${encodeURIComponent(id)}`, body),
remove: (id: string) =>
del(`/semantic-metrics/${encodeURIComponent(id)}`),
preview: (body: SemanticMetricPreviewIn) =>
post<SemanticMetricPreviewOut>('/semantic-metrics/preview', body),
suggest: (body: { source_id: string; table_names?: string[]; document_ids?: string[]; note?: string }) =>
post<SemanticMetricSuggestOut>('/semantic-metrics/suggest', body),
uploadAttachment: (file: File, opts?: { save_to_kb?: boolean; collection?: string } & UploadOptions) => {
const form = new FormData()
form.append('file', file)
if (opts?.save_to_kb !== undefined) form.append('save_to_kb', String(opts.save_to_kb))
if (opts?.collection) form.append('collection', opts.collection)
return upload<DecomposeAttachmentOut>('/semantic-metrics/attachments', form, opts)
},
decomposeJobs: {
active: (sourceId?: string, opts?: RequestOptions) =>
get<{ active: SemanticDecomposeJob | null; latest: SemanticDecomposeJob | null }>(
`/semantic-metrics/decompose-jobs/active${qs({ source_id: sourceId })}`,
opts,
),
list: (sourceId?: string, limit = 10, opts?: RequestOptions) =>
get<{ items: SemanticDecomposeJob[] }>(
`/semantic-metrics/decompose-jobs${qs({ source_id: sourceId, limit })}`,
opts,
),
create: (body: SemanticDecomposeCreateIn) =>
post<{ job: SemanticDecomposeJob }>('/semantic-metrics/decompose-jobs', body),
get: (jobId: string, opts?: RequestOptions) =>
get<{ job: SemanticDecomposeJob }>(`/semantic-metrics/decompose-jobs/${encodeURIComponent(jobId)}`, opts),
cancel: (jobId: string) =>
post<{ job: SemanticDecomposeJob }>(`/semantic-metrics/decompose-jobs/${encodeURIComponent(jobId)}/cancel`, {}),
apply: (jobId: string, body: SemanticDecomposeApplyIn) =>
post<{
job_id: string
applied: SemanticDecomposeAppliedRecord
created_metrics: SemanticMetric[]
updated_metrics: SemanticMetric[]
}>(`/semantic-metrics/decompose-jobs/${encodeURIComponent(jobId)}/apply`, body),
},
}