From b90d235d6418007c6e4701699508793c27c80a23 Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Sat, 3 Oct 2026 09:56:21 +0800 Subject: [PATCH] =?UTF-8?q?=E6=95=B0=E6=8D=AE=E7=9B=AE=E5=BD=95=E9=98=B6?= =?UTF-8?q?=E6=AE=B5=201C=EF=BC=9A=E5=89=8D=E7=AB=AF=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=E5=B1=82=E4=B8=8E=E7=B1=BB=E5=9E=8B=EF=BC=8C=E8=A1=A8=E6=B8=85?= =?UTF-8?q?=E5=8D=95=E3=80=81=E5=8D=95=E8=A1=A8=E8=AF=A6=E6=83=85=E3=80=81?= =?UTF-8?q?=E6=95=B4=E4=BB=BD=E6=8F=90=E4=BA=A4=E3=80=81=E5=8D=95=E9=A1=B9?= =?UTF-8?q?=E5=AE=A1=E9=98=85=E3=80=81=E8=B5=B7=E8=8D=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- frontend/src/api/client.ts | 31 ++++++- frontend/src/types.ts | 175 +++++++++++++++++++++++++++++++++++++ 2 files changed, 205 insertions(+), 1 deletion(-) diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index 031f64be..163ce524 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -1,5 +1,6 @@ import type { - ActivateSnapshotBody, ActivateSnapshotOut, AiPreview, CommitOut, CurrentRecipe, EditPreview, EditRequest, ImportRecord, + ActivateSnapshotBody, ActivateSnapshotOut, AiPreview, CatalogDetail, CatalogDraftOut, CatalogList, CatalogNotes, + CatalogReviewAction, CommitOut, CurrentRecipe, EditPreview, EditRequest, ImportRecord, ManifestOut, PurgeRawBody, PurgeRawOut, QuestionAnswer, Recipe, RedraftRulesOut, RemovePeriodBody, RemovePeriodOut, RevokeAcceptanceBody, RevokeAcceptanceOut, SnapshotOut, Staging, } from '../types' @@ -649,6 +650,34 @@ export const api = { post(`/datasources/${encodeURIComponent(sourceId)}/imports/${encodeURIComponent(importId)}/purge-raw`, body), }, + /** + * 业务数据目录(每个数据源一份,按表存)。写操作都带读到的版本(if_version,这张表还没有目录时为 0):别人在这期间 + * 改过时回 409,detail 是给人看的话(「表「x」的数据目录刚被修改过,请重新载入后再提交」);格式不对回 422;源或表 + * 不存在回 404。署名走请求头 X-Actor(request 统一带上) + */ + dataCatalog: { + /** 表清单:表结构里的每张表各一行,使用次数多的在前;没有表结构时 tables 为空、schema_note 写明原因 */ + list: (sourceId: string, opts?: RequestOptions) => + get(`/datasources/${encodeURIComponent(sourceId)}/catalog`, opts), + /** 单表目录连同表结构 */ + get: (sourceId: string, table: string, opts?: RequestOptions) => + get(`/datasources/${encodeURIComponent(sourceId)}/catalog/${encodeURIComponent(table)}`, opts), + /** 整份提交:值改过的项、新填的项记为人工填写、已确认;提交里没有的项删掉 */ + put: (sourceId: string, table: string, notes: CatalogNotes, ifVersion: number) => + put(`/datasources/${encodeURIComponent(sourceId)}/catalog/${encodeURIComponent(table)}`, + { notes, if_version: ifVersion }), + /** 单项审阅。path:表级项写字段名(grain);列级项 columns.<列名>.<字段>;关系 relations.<编号> */ + review: (sourceId: string, table: string, body: { path: string; action: CatalogReviewAction; if_version: number }) => + post(`/datasources/${encodeURIComponent(sourceId)}/catalog/${encodeURIComponent(table)}/review`, body), + /** + * 同步起草(注释、外键、命名推断;use_model 时再请助手的模型起草)。不给 tables 时按使用次数取前 20 张。 + * 人工确认、驳回过的项不动。没有表结构时回 409 + */ + draft: (sourceId: string, body: { tables?: string[]; use_model: boolean }, opts?: RequestOptions) => + request(`/datasources/${encodeURIComponent(sourceId)}/catalog/draft`, + { method: 'POST', body: JSON.stringify(body), ...opts }), + }, + runs: { /** * status 可以给多个(逗号连接);q 按工作流名模糊匹配;before 是翻页游标 diff --git a/frontend/src/types.ts b/frontend/src/types.ts index c250a8bd..2efc1e0c 100644 --- a/frontend/src/types.ts +++ b/frontend/src/types.ts @@ -2477,3 +2477,178 @@ export interface EvidenceProvenance { cell_source: ProvenanceCellSource | null checks: ProvenanceCheck[] } + +// =========================================================================== +// 业务数据目录(/api/datasources/{id}/catalog,后端 app/data/catalog.py)。 +// 每张表一份业务说明:中文名、粒度、业务主键、列的含义和度量类型、表与表的关联关系……每一项都注明来源和状态。 +// 目录只记数据事实,不放计算公式(公式在口径卡里)。 +// =========================================================================== + +/** 项的来源:数据库注释、外键约束、命名推断、数据剖析、模型起草、人工填写 */ +export type CatalogSource = 'comment' | 'fk' | 'name' | 'profile' | 'llm' | 'human' +/** 项的状态:推断、已验证(外键约束、数据剖析)、已确认(人工)、已驳回(人工) */ +export type CatalogStatus = 'proposed' | 'verified' | 'confirmed' | 'rejected' +/** 表类型:明细(事实)、维度、快照、日志、配置 */ +export type CatalogTableKind = 'fact' | 'dimension' | 'snapshot' | 'log' | 'config' +/** 列的度量类型:可累加(流量)、存量、比率、标识、状态、属性 */ +export type CatalogMeasure = 'flow' | 'stock' | 'ratio' | 'identifier' | 'status' | 'attribute' +/** 关系的基数(从本表看过去) */ +export type CatalogCardinality = 'many_to_one' | 'one_to_one' | 'one_to_many' + +/** 目录里的一项:值连同来源、状态 */ +export interface CatalogItem { + value: T + source: CatalogSource + status: CatalogStatus + note?: string + updated_at?: string +} + +/** 业务日期:按哪一列算,规则和时区写成文字 */ +export interface CatalogBusinessDate { + column: string + rule?: string + timezone?: string +} + +/** 一列的目录 */ +export interface CatalogColumnNotes { + label?: CatalogItem + meaning?: CatalogItem + unit?: CatalogItem + measure?: CatalogItem + /** 码值 → 含义 */ + codes?: CatalogItem> +} + +/** 一条关联关系。编号由两端的表和列算出来,改了指向就是另一条 */ +export interface CatalogRelation { + id: string + columns: string[] + to_table: string + to_columns: string[] + cardinality: CatalogCardinality | null + /** 0 到 1:本表这几列的值在被指向表里找得到的比例(数据剖析给出) */ + coverage: number | null + source: CatalogSource + status: CatalogStatus + note?: string + updated_at?: string +} + +/** 一张表的目录(notes)。字段固定,服务端不认识的一律拒收 */ +export interface CatalogNotes { + label?: CatalogItem + description?: CatalogItem + grain?: CatalogItem + keys?: CatalogItem + kind?: CatalogItem + business_date?: CatalogItem + /** SQL 条件片段 */ + valid_filter?: CatalogItem + dedup?: CatalogItem + columns?: Record + relations?: CatalogRelation[] +} + +/** 各状态的项数(表级项、列级项、关系都算),四种状态都有键 */ +export type CatalogCounts = Record + +/** 表清单的一行。表结构里的每张表各一行(没有目录的也列);目录还在、表已不在的 in_schema 为 false,排在最后 */ +export interface CatalogTableRow { + table_name: string + qualified: string + is_view: boolean + in_schema: boolean + /** 中文名(被驳回的不算) */ + label: string | null + label_status: CatalogStatus | null + kind: CatalogTableKind | null + counts: CatalogCounts + /** 没被驳回的关联关系条数 */ + relations: number + /** 被运行查询过的次数(同一次运行里结果相同的重复查询只算一次) */ + usage: number + /** 这张表还没有目录时为 0 */ + version: number + updated_at: string | null + updated_by: string | null +} + +/** GET /datasources/{id}/catalog */ +export interface CatalogList { + /** 使用次数多的在前 */ + tables: CatalogTableRow[] + /** 导入表格的源:表和列的说明由系统按核对结果生成,只读 */ + system_notes: boolean + /** 没有表结构时的原因(「尚未探查结构」「结构探查失败:…」);有表结构时为 null */ + schema_note: string | null +} + +/** 表结构里的一列 */ +export interface CatalogStructureColumn { + name: string + type: string + pk: boolean + not_null: boolean + /** 数据库注释;导入表格的源是系统按核对结果生成的说明 */ + comment: string | null +} + +export interface CatalogForeignKey { + columns: string[] + to_table: string + to_columns: string[] +} + +export interface CatalogStructure { + qualified: string | null + is_view: boolean + /** 表注释;导入表格的源是系统按核对结果生成的说明 */ + comment: string | null + columns: CatalogStructureColumn[] + primary_key: string[] + /** 升级前探查的缓存里没有:null 表示不知道,空列表表示读过、没有 */ + foreign_keys: CatalogForeignKey[] | null + unique: string[][] | null +} + +/** GET /datasources/{id}/catalog/{table};PUT、审阅也返回这个形状 */ +export interface CatalogDetail { + table_name: string + in_schema: boolean + notes: CatalogNotes + version: number + updated_at: string | null + updated_by: string | null + /** 表结构里已经没有这张表时为 null */ + structure: CatalogStructure | null + system_notes: boolean + usage: number +} + +/** 单项审阅:确认、驳回、撤销审阅(回到来源的初始状态;人工填写的项直接删掉) */ +export type CatalogReviewAction = 'confirm' | 'reject' | 'reset' + +/** 起草结果里的一张表 */ +export interface CatalogDraftRow { + table_name: string + added: number + updated: number + removed: number + version: number + /** 这张表没有起草(表结构里没有、写入一直冲突) */ + error: string | null + /** 只是模型那部分失败,其余来源照常写入 */ + model_error: string | null +} + +/** POST /datasources/{id}/catalog/draft */ +export interface CatalogDraftOut { + tables: CatalogDraftRow[] + total: { added: number; updated: number; removed: number } + model_used: boolean + model: string | null + /** 模型整体用不了(没有配置、已停用……):只按注释、外键和命名起草 */ + model_error: string | null +}