Semantic Plane（语义治理面）技术参考¶

本文档定位

本文档是 Semantic Plane 的 完整技术参考手册，面向 Data Product Owner、Data Steward 和 Backend Developer。涵盖三层治理模型、所有资产类型 Schema 详解、命名与版本规范、运行时消费模式、CI 校验门控及发布流程。

1. 概述¶

Semantic Plane 是 TTD 系统的 治理中枢。它将业务语义转化为结构化 YAML 资产，通过 Git 版本控制存储，驱动整个 NL2SQL 翻译流程：

graph LR
    A[Business Domain Knowledge] --> B[YAML Assets]
    B --> C[CI Validation]
    C --> D[Git Merge]
    D --> E["ttd-publish-sp<br/>(发布到 S3)"]
    E --> F[Admin Backend<br/>semantic_plane agent]
    F --> G["Engine 1 (R) — Relational"]
    F --> H["Engine 3 (G) — Graph/AGE"]
    F --> J["Engine 2 (V) — pgvector"]
    G & H & J --> K[Backend Agents]
    K --> L[SQL Generation & Guardrails]

核心设计原则：

原则	说明
Git as Source of Truth	所有元数据以 YAML 存储于 `semantic-plane/`，变更经 PR 审批
三层治理分离	Layer 1 规范、Layer 2 术语、Layer 3 业务知识各有独立生命周期
双语强制	所有 `_zh` / `_en` 字段必须成对出现
Schema 强校验	JSON Schema v7 + CI 自动校验，合并前必须通过
三引擎同步	R（关系表）+ V（向量）+ G（图谱）三引擎协同

2. 三层治理模型¶

Semantic Plane 采用 三层治理模型，每层有独立的所有权边界和审批流程：

层级	范围	目录	资产类型	所有者
Layer 1 规范元数据	表、列、指标、关联、示例、术语基础	`domains/`, `terms/`, `few_shots/`, `join_rules/`	`table_asset`, `column_asset`, `metric_asset`, `join_rule`, `few_shot_example`, `business_term`（基础）	Data Product Owner
Layer 2 术语治理	术语生命周期、消歧、关系网络	`terms/`, `term_relationships/`	`business_term`（扩展：`ambiguity_matrix`, `lifecycle`）, `term_relationship`	Data Steward
Layer 3 业务知识	业务规则、上下文假设、约束	`business_rules/`, `business_contexts/`	`business_rule`, `business_context`	Domain SME + Data Steward

2.1 层级间依赖关系¶

graph TB
    L3[Layer 3: Business Knowledge] --> L2[Layer 2: Terminology]
    L3 --> L1[Layer 1: Metadata Contracts]
    L2 --> L1

    L3 -.- BR[business_rule]
    L3 -.- BC[business_context]
    L2 -.- TR[term_relationship]
    L2 -.- BT_ext["business_term (extended)"]
    L1 -.- TA[table_asset]
    L1 -.- MA[metric_asset]
    L1 -.- JR[join_rule]
    L1 -.- FS[few_shot_example]
    L1 -.- BT_basic["business_term (basic)"]

跨层引用规则

Layer 3 的 bound_assets 只能引用 Layer 1 资产 ID
Layer 3 的 bound_terms 只能引用 Layer 2 术语 ID
Layer 2 的 mapped_asset_id 只能引用 Layer 1 资产 ID
validate_cross_layer_refs.py 自动检测悬空引用和循环替换链

2.2 审批矩阵¶

变更类型	审批者	备注
Layer 1 PATCH/MINOR	DPO	自动合并（CI 通过后）
Layer 1 MAJOR	DPO + Governance Lead	需影响分析
Layer 2 任何变更	Data Steward	术语一致性审查
Layer 3 PATCH/MINOR	Domain SME	规则逻辑审查
Layer 3 MAJOR	Domain SME + Data Steward + Governance Lead	需影响分析

3. 目录结构¶

semantic-plane/
├── schemas/                          # JSON Schema v7 校验器（8 个文件）
│   ├── table_asset.schema.json       # 表资产 Schema
│   ├── metric_asset.schema.json      # 指标资产 Schema
│   ├── join_rule.schema.json         # Join 规则 Schema
│   ├── business_term.schema.json     # 业务术语 Schema
│   ├── few_shot_example.schema.json  # Few-shot 示例 Schema
│   ├── term_relationship.schema.json # 术语关系 Schema
│   ├── business_rule.schema.json     # 业务规则 Schema
│   └── business_context.schema.json  # 业务上下文 Schema
├── domains/                          # Layer 1: 按业务域组织的表与指标
│   └── hm_fashion/                   # H&M 时尚域
│       ├── dim_article.yaml          # 商品维度表
│       ├── dim_customer.yaml         # 客户维度表
│       ├── fact_transaction.yaml     # 交易事实表
│       └── metrics/                  # 指标资产
│           ├── transaction_count.yaml
│           ├── unique_customer_count.yaml
│           ├── avg_transaction_price.yaml
│           ├── repeat_purchase_rate.yaml
│           └── unique_article_purchased.yaml
├── terms/                            # Layer 1+2: 业务术语
│   └── hm_fashion_terms.yaml
├── few_shots/                        # Layer 1: NL2SQL 训练示例
│   └── hm_fashion_examples.yaml
├── join_rules/                       # Layer 1: 表间关联规则
│   └── hm_fashion_joins.yaml
├── business_rules/                   # Layer 3: 业务规则
│   └── hm_fashion_rules.yaml
├── business_contexts/                # Layer 3: 业务上下文
│   └── hm_fashion_contexts.yaml
├── term_relationships/               # Layer 2: 术语语义网络
│   └── hm_fashion_relationships.yaml
└── sample_questions.json             # 按路由类别的测试问题集

文件组织原则

每个业务域 (domain) 对应 domains/ 下的一个子目录
每张表对应一个独立 YAML 文件
指标放在域目录下的 metrics/ 子目录
术语、规则、上下文按域组织为单个 YAML 文件（内含数组）

4. 资产类型详解¶

4.1 Table Asset（表资产）¶

表资产描述一张分析表的完整元数据，包含列定义、安全策略、质量评分和认证状态。

Schema 字段¶

必填字段 (Required)可选字段 (Optional)

字段	类型	说明
`table_id`	`string`	稳定唯一标识符
`technical_name`	`string`	物理表全限定名
`business_name_zh`	`string`	中文业务名称
`business_name_en`	`string`	英文业务名称
`description_zh`	`string` (≥10 chars)	中文业务描述
`description_en`	`string` (≥10 chars)	英文业务描述
`domain`	`string`	业务域
`owner`	`string` (email)	业务负责人
`certification_status`	`enum`	治理生命周期状态
`sensitivity_profile`	`enum`	最高敏感度等级
`version`	`string`	语义版本号

字段	类型	说明
`steward`	`string` (email)	Data Steward
`quality_score`	`integer` (0-100)	量化质量分数
`refresh_frequency`	`enum`	刷新频率
`primary_time_column`	`string\\|null`	主时间列
`usage_scope`	`enum`	使用范围（full/read_only/safe_view_only）
`default_grain`	`string`	默认分析粒度
`common_filters`	`array[string]`	常用过滤列
`typical_questions`	`array[string]`	典型问题示例（双语）
`anti_patterns`	`array[string]`	已知误用模式
`columns`	`array[column_asset]`	列级元数据

ID Pattern¶

^tbl_[a-z][a-z0-9_]*$

H&M 示例¶

table_asset:
  table_id: "tbl_hm_fact_transaction"
  technical_name: "gold_hm.fact_transaction"
  business_name_zh: "H&M 交易事实表"
  business_name_en: "H&M Transaction Fact Table"
  description_zh: >
    记录 H&M 全部购买交易记录，粒度为每笔交易行...
  domain: "hm_fashion"
  owner: "data-team@hm.com"
  certification_status: "certified"
  quality_score: 93
  sensitivity_profile: "internal"
  version: "1.0.0"

运行时消费¶

引擎	消费方式
R (Relational)	`SELECT * FROM metadata.table_assets WHERE domain = 'hm_fashion'` — 用于 Schema Exploration Skill
V (Vector)	表描述文本向量化，用于 RAG Skill 的 top-K 相似度检索
G (Graph)	表节点 (`:TableAsset`) + 列边 (`:HAS_COLUMN`) + Join 边 (`:JOINS_TO`)

4.2 Column Asset（列资产）¶

列资产嵌套在 table_asset.columns 数组中，描述单个列的语义信息和安全策略。

Schema 字段¶

必填字段 (Required)可选字段 (Optional)

字段	类型	说明
`column_id`	`string`	列稳定标识符
`column_name`	`string`	物理列名
`business_name_zh`	`string`	中文业务名称
`business_name_en`	`string`	英文业务名称
`description_zh`	`string`	中文列描述
`description_en`	`string`	英文列描述
`data_type`	`string`	物理数据类型
`is_nullable`	`boolean`	是否允许 NULL
`sensitivity_level`	`enum`	敏感度级别
`llm_exposure_policy`	`enum`	LLM 暴露策略

字段	类型	说明
`semantic_type`	`enum`	语义类型 (id/date/metric/dimension/...)
`alias_terms`	`array[string]`	别名/同义词（双语）
`enum_samples`	`array[string]`	枚举样本值
`unit`	`string`	单位 (CNY/USD/kg/...)
`allowed_aggregations`	`array[enum]`	允许的聚合函数
`join_role`	`enum`	Join 角色 (pk/fk/degenerate/none)
`pii_masking_rule`	`string`	PII 脱敏规则
`search_boost`	`number`	检索排名加权因子

ID Pattern¶

^col_[a-z][a-z0-9_]*$

LLM Exposure Policy¶

策略	说明	适用场景
`visible`	LLM 完全可见并可在 SQL 中使用	常规业务字段
`retrieval_only`	LLM 可用于检索匹配但不暴露原值	半敏感字段
`policy_filter_only`	仅用于策略过滤，不进入 prompt	权限控制字段
`hidden`	LLM 完全不可见，不参与 embedding	PII 字段

H&M 示例¶

columns:
  - column_id: "col_hm_txn_price"
    column_name: "price"
    business_name_zh: "归一化价格"
    business_name_en: "Normalised Price"
    description_zh: "交易价格（已除以最大值归一化至 0-1）"
    description_en: "Transaction price normalised to 0-1 by dividing by max"
    data_type: "DECIMAL(10,6)"
    semantic_type: "metric"
    is_nullable: false
    sensitivity_level: "internal"
    llm_exposure_policy: "visible"
    alias_terms: ["单价", "unit price", "商品价格"]
    allowed_aggregations: ["AVG", "MIN", "MAX"]
    unit: "normalised_ratio"

4.3 Metric Asset（指标资产）¶

指标资产定义业务指标的 SQL 口径、维度约束和易混淆指标对比。

Schema 字段¶

必填字段 (Required)可选字段 (Optional)

字段	类型	说明
`metric_id`	`string`	指标唯一标识符
`metric_name`	`string`	主指标名称
`business_definition_zh`	`string` (≥10 chars)	中文业务定义
`business_definition_en`	`string` (≥10 chars)	英文业务定义
`sql_definition`	`string` (≥5 chars)	标准 SQL 表达式
`owner`	`string` (email)	指标负责人
`certification_status`	`enum`	认证状态
`version`	`string`	语义版本号

字段	类型	说明
`default_grain`	`string`	默认聚合粒度
`allowed_dimensions`	`array[string]`	可用维度列表
`default_filters`	`array[string]`	默认 WHERE 条件
`similar_metrics`	`array[object]`	易混淆指标及区别
`counter_examples`	`array[string]`	反例声明（双语）
`common_questions`	`array[string]`	典型问题

ID Pattern¶

^met_[a-z][a-z0-9_]*$

H&M 示例¶

metric_asset:
  metric_id: "met_hm_transaction_count"
  metric_name: "Transaction Count"
  business_definition_zh: >
    交易次数，统计购买交易事实表中的总行数...
  sql_definition: >
    SELECT COUNT(*) FROM gold_hm.fact_transaction
  allowed_dimensions: ["t_dat", "sales_channel_id"]
  similar_metrics:
    - metric_id: "met_hm_unique_article_purchased"
      difference: "Unique article count uses COUNT(DISTINCT article_id)"
  counter_examples:
    - "交易次数 ≠ 订单数，这里没有订单概念"

运行时消费¶

SQL Generation Agent：从指标的 sql_definition 提取可执行 SQL 模板
Disambiguation Agent：使用 similar_metrics 和 counter_examples 区分易混淆指标
RAG Skill：business_definition_zh/en 向量化后用于 intent → metric 匹配

4.4 Join Rule（关联规则）¶

Join Rule 定义表间的合法 JOIN 路径、基数关系和 fanout 风险评估。

Schema 字段¶

字段	必填	类型	说明
`join_rule_id`	✅	`string`	Join 规则标识符
`left_table_id`	✅	`string`	左表 ID
`right_table_id`	✅	`string`	右表 ID
`join_type`	✅	`enum`	JOIN 类型
`join_keys`	✅	`array[{left, right}]`	JOIN 键对
`cardinality`	✅	`enum`	基数关系
`fanout_risk`	✅	`enum`	行膨胀风险
`allowed_for_nl2sql`	✅	`boolean`	是否允许 NL2SQL 使用
`required_filters`	❌	`array[string]`	使用此 JOIN 的必需过滤条件
`grain_alignment_notes`	❌	`string`	粒度对齐说明
`duplication_warning`	❌	`string`	行重复警告
`domain_constraints`	❌	`array[string]`	域约束
`version`	❌	`string`	版本号

ID Pattern¶

^jr_[a-z][a-z0-9_]*$

Cardinality 与 Fanout Risk¶

Cardinality	Fanout Risk	说明
`one-to-one`	`low`	安全 JOIN，无行膨胀
`many-to-one`	`low`	事实表 JOIN 维度表，安全
`one-to-many`	`medium`	可能产生行膨胀，需注意聚合
`many-to-many`	`high`	高风险，通常需要 `required_filters`

H&M 示例¶

join_rules:
  - join_rule_id: "jr_hm_txn_article"
    left_table_id: "tbl_hm_fact_transaction"
    right_table_id: "tbl_hm_dim_article"
    join_type: "LEFT JOIN"
    join_keys:
      - left: "article_id"
        right: "article_id"
    cardinality: "many-to-one"
    fanout_risk: "low"
    allowed_for_nl2sql: true
    grain_alignment_notes: >
      fact_transaction 粒度为交易行，dim_article 粒度为商品 SKU，
      多条交易关联同一商品，JOIN 不会产生行膨胀。

运行时消费¶

Graph Engine (AGE)：JOIN 规则转化为 (:TableAsset)-[:JOINS_TO {type, cardinality}]->(:TableAsset) 边
SQL Agent：通过 Cypher 查询找到两表间的最短合法 JOIN 路径
Guardrails：检查 fanout_risk: high 时是否满足 required_filters

4.5 Few-Shot Example（NL2SQL 示例）¶

Few-shot 示例提供 NL→SQL 训练对，用于 in-context learning 注入。

Schema 字段¶

字段	必填	类型	说明
`example_id`	✅	`string`	示例标识符
`question_text`	✅	`string` (≥5 chars)	自然语言问题
`language`	✅	`enum`	问题语言 (zh/en)
`grounded_assets`	✅	`array[string]`	引用的表资产 ID
`example_class`	✅	`enum`	示例分类
`intent_type`	❌	`enum`	查询意图分类
`reference_sql`	❌	`string\\|null`	参考 SQL（clarification 类可为 null）
`quality_status`	❌	`enum`	审核状态
`clarification_response`	❌	`string`	澄清类示例的回复文本
`version`	❌	`string`	版本号

ID Pattern¶

^fs_[a-z][a-z0-9_]*$

Example Class 分类¶

Class	说明	用途
`positive`	正例 — 正确的 NL→SQL 映射	注入 prompt 作为参考
`negative`	反例 — 常见错误的 SQL	教模型避免特定错误
`clarification`	澄清 — 需要追问的模糊问题	训练模型识别歧义

Intent Type 分类¶

H&M 示例¶

few_shot_examples:
  - example_id: "fs_hm_001"
    question_text: "各商品类型的交易次数是多少？"
    language: "zh"
    intent_type: "aggregation"
    grounded_assets: ["tbl_hm_fact_transaction", "tbl_hm_dim_article"]
    reference_sql: >
      SELECT a.product_type_name, COUNT(*) AS transaction_count
      FROM gold_hm.fact_transaction t
      LEFT JOIN gold_hm.dim_article a ON t.article_id = a.article_id
      GROUP BY a.product_type_name
      ORDER BY transaction_count DESC
    example_class: "positive"
    quality_status: "approved"

运行时消费¶

Few-shot Selection：基于 intent_type + grounded_assets 匹配，选取最相关的 3-5 个示例
RAG Skill：question_text 向量化后用于语义相似度匹配
SQL Generation Prompt：选中的 few-shot 以 Question → SQL 格式注入 system prompt

4.6 Business Term（业务术语）¶

业务术语是 Layer 1 和 Layer 2 的桥梁资产。基础字段属于 Layer 1（术语映射），扩展字段属于 Layer 2（治理生命周期、消歧矩阵）。

Schema 字段¶

Layer 1 基础字段 (Required)Layer 2 扩展字段 (Optional)

字段	类型	说明
`term_id`	`string`	术语唯一标识符
`canonical_term`	`string`	标准术语名
`language`	`enum`	标准术语语言 (zh/en)
`term_type`	`enum`	术语分类 (term/abbreviation/synonym/acronym)
`mapped_asset_type`	`enum`	映射资产类型 (table/column/metric)
`mapped_asset_id`	`string`	映射资产 ID

字段	类型	说明
`negative_synonyms`	`array[string]`	易混淆词（不应视为同义词）
`ambiguity_notes`	`string`	歧义说明
`term_lifecycle_status`	`enum`	治理生命周期状态
`confidence_score`	`number` (0-1)	准确度置信分
`ambiguity_matrix`	`array[object]`	歧义消解矩阵
`context_profiles`	`array[object]`	上下文特定配置
`synonym_strength`	`enum`	同义映射强度
`replacement_term_id`	`string`	替换术语 ID（deprecated 时必填）
`mutually_exclusive_group`	`string`	互斥分组名

ID Pattern¶

^term_[a-z][a-z0-9_]*$

Ambiguity Matrix 结构¶

ambiguity_matrix:
  - conflicting_term_id: "term_hm_order_count"
    trigger: "订单数"
    disambiguation_zh: "H&M 数据集无订单概念，只有购买行为计数"
    disambiguation_en: "No order concept in H&M; only purchase event count"
    preferred_term_id: "term_hm_transaction_count"

H&M 示例¶

business_terms:
  - term_id: "term_hm_price"
    canonical_term: "价格"
    language: "zh"
    term_type: "term"
    mapped_asset_type: "column"
    mapped_asset_id: "col_hm_txn_price"
    term_zh: "价格"
    term_en: "Price"
    negative_synonyms: ["实际价格", "revenue", "收入"]
    ambiguity_notes: >
      H&M price 已归一化（0~1），不代表实际货币金额。
    term_lifecycle_status: "certified"
    confidence_score: 0.95

运行时消费¶

Term Recognition Agent：用户输入 → 向量匹配 → 术语识别 → mapped_asset_id 解析
Disambiguation Agent：检测 negative_synonyms 命中时触发 ambiguity_matrix 中的澄清 prompt
Graph Engine：术语节点 (:BusinessTerm) 通过 :MAPS_TO 边连接资产节点

4.7 Term Relationship（术语关系）¶

术语关系定义术语间的语义网络，支持同义、层级、冲突和关联等关系类型。

Schema 字段¶

字段	必填	类型	说明
`relationship_id`	✅	`string`	关系标识符
`source_term_id`	✅	`string`	源术语 ID
`target_term_id`	✅	`string`	目标术语 ID
`relationship_type`	✅	`enum`	关系类型
`version`	✅	`string`	版本号
`strength`	❌	`enum`	关系强度 (strong/moderate/weak)
`context_constraint`	❌	`string`	上下文约束条件

ID Pattern¶

^tr_[a-z][a-z0-9_]*$

Relationship Types¶

类型	语义	AGE 边标签
`synonym_of`	A 是 B 的同义词	`:SYNONYM_OF`
`parent_of`	A 是 B 的上位概念	`:PARENT_OF`
`child_of`	A 是 B 的下位概念	`:CHILD_OF`
`conflicts_with`	A 与 B 冲突/互斥	`:CONFLICTS_WITH`
`replaces`	A 替换了 B	`:REPLACES`
`related_to`	A 与 B 关联	`:RELATED_TO`

H&M 示例¶

term_relationships:
  - relationship_id: "tr_hm_price_revenue_conflict"
    source_term_id: "term_hm_price"
    target_term_id: "term_hm_transaction_count"
    relationship_type: "conflicts_with"
    strength: "moderate"
    context_constraint: >
      price 已归一化，SUM(price) 不等于实际销售额/收入。

运行时消费¶

Graph Traversal：Cypher 查询 MATCH (t1:Term)-[r]->(t2:Term) WHERE ... 探索关系网络
Conflict Detection：conflicts_with 关系触发生成 SQL 前的约束检查
Hierarchy Expansion：parent_of / child_of 用于扩展用户意图（如"服装" → 展开为所有子类别）

4.8 Business Rule（业务规则）¶

业务规则定义对 SQL 生成的治理约束，包含规则表达式、绑定资产和反模式。

Schema 字段¶

必填字段 (Required)可选字段 (Optional)

字段	类型	说明
`rule_id`	`string`	规则标识符
`rule_name_zh`	`string` (≥2 chars)	中文规则名
`rule_name_en`	`string` (≥2 chars)	英文规则名
`description_zh`	`string` (≥10 chars)	中文描述
`description_en`	`string` (≥10 chars)	英文描述
`rule_type`	`enum`	规则类型
`rule_expression`	`string`	规则 SQL 表达式
`bound_assets`	`array[string]` (≥1)	绑定的 Layer 1 资产
`domain`	`string`	业务域
`owner`	`string`	规则负责人
`lifecycle_status`	`enum`	生命周期状态
`version`	`string`	版本号

字段	类型	说明
`priority`	`enum`	优先级 (critical/high/medium/low)
`bound_terms`	`array[string]`	关联 Layer 2 术语
`bound_contexts`	`array[string]`	关联 Layer 3 上下文
`applies_when`	`string`	触发条件
`exceptions`	`array[object]`	例外情况
`anti_patterns`	`array[string]`	反模式（双语）
`regulatory_tags`	`array[string]`	合规标签
`effective_from` / `effective_to`	`date`	有效期
`confidence_level`	`enum`	规则置信度
`review_frequency`	`enum`	审查频率

ID Pattern¶

^br_[a-z][a-z0-9_]*$

Rule Types¶

类型	说明	示例
`filter`	过滤约束	必须添加时间范围条件
`aggregation`	聚合约束	COUNT(*) vs COUNT(DISTINCT) 选择
`transformation`	转换约束	价格需要反归一化
`calculation`	计算约束	SUM(price) ≠ revenue

H&M 示例¶

business_rules:
  - rule_id: "br_hm_normalised_price"
    rule_name_zh: "归一化价格使用规则"
    rule_name_en: "Normalised Price Usage Rule"
    description_zh: >
      price 字段已归一化（0~1），SUM(price) 仅可用于相对比较...
    rule_type: "calculation"
    rule_expression: "price IS NORMALISED; SUM(price) ≠ revenue"
    bound_assets: ["tbl_hm_fact_transaction", "col_hm_txn_price"]
    bound_terms: ["term_hm_price"]
    domain: "hm_fashion"
    priority: "critical"
    applies_when: "用户提及价格、销售额、营收、收入等"
    anti_patterns:
      - "不要生成 SUM(price) AS revenue"
    lifecycle_status: "active"

运行时消费¶

Guardrails Check：SQL 生成后，检查 bound_assets 是否出现在 SQL 中 → 触发对应 rule_expression 校验
Prompt Injection：priority: critical 规则的 description 和 anti_patterns 直接注入 system prompt
Graph Engine：(:BusinessRule)-[:APPLIES_TO]->(:TableAsset) 边用于规则发现

4.9 Business Context（业务上下文）¶

业务上下文描述域级假设、约束和边界，为 LLM 提供背景知识。

Schema 字段¶

必填字段 (Required)可选字段 (Optional)

字段	类型	说明
`context_id`	`string`	上下文标识符
`context_name_zh`	`string` (≥2 chars)	中文名称
`context_name_en`	`string` (≥2 chars)	英文名称
`description_zh`	`string` (≥10 chars)	中文描述
`description_en`	`string` (≥10 chars)	英文描述
`context_type`	`enum`	上下文类型
`domain`	`string`	业务域
`owner`	`string`	负责人
`lifecycle_status`	`enum`	生命周期状态
`version`	`string`	版本号

字段	类型	说明
`assumptions`	`array[object]`	业务假设列表
`constraints`	`array[object]`	约束条件列表
`valid_markets`	`array[string]`	适用市场
`valid_domains`	`array[string]`	适用域
`effective_from` / `effective_to`	`date`	有效期
`bound_rules`	`array[string]`	关联业务规则
`bound_metrics`	`array[string]`	关联指标

ID Pattern¶

^bc_[a-z][a-z0-9_]*$

Context Types¶

类型	说明
`market`	市场/区域上下文
`entity`	实体/组织上下文
`time_period`	时间范围上下文
`regulatory`	监管/合规上下文
`operational`	运营/数据集上下文

H&M 示例¶

business_contexts:
  - context_id: "bc_hm_dataset_overview"
    context_name_zh: "H&M 时尚推荐数据集整体上下文"
    context_name_en: "H&M Fashion Recommendations Dataset Overview"
    context_type: "operational"
    domain: "hm_fashion"
    lifecycle_status: "active"
    assumptions:
      - description_zh: "价格字段已归一化，不可直接用于货币计算"
        description_en: "Price field is normalised, cannot be used for currency"
        confidence: "verified"
        impact_if_violated: "所有涉及金额的分析结果将产生误导"
    constraints:
      - description_zh: "数据集仅包含购买记录，不含退货"
        description_en: "Only purchase records, no returns"
    bound_metrics: ["met_hm_transaction_count", "met_hm_unique_customer_count"]
    bound_rules: ["br_hm_normalised_price", "br_hm_duplicate_row_counting"]

运行时消费¶

System Prompt：域匹配的 active 上下文的 description + assumptions 注入为背景知识
Explanation Agent：在生成回答解释时引用 assumptions 说明数据局限
Boundary Check：constraints 用于检查用户问题是否超出数据可回答范围

5. 命名与版本规范¶

5.1 ID 命名规则¶

资产类型	前缀	Pattern	示例
Table	`tbl_`	`^tbl_[a-z][a-z0-9_]*$`	`tbl_hm_fact_transaction`
Column	`col_`	`^col_[a-z][a-z0-9_]*$`	`col_hm_txn_price`
Metric	`met_`	`^met_[a-z][a-z0-9_]*$`	`met_hm_transaction_count`
Join Rule	`jr_`	`^jr_[a-z][a-z0-9_]*$`	`jr_hm_txn_article`
Few-shot	`fs_`	`^fs_[a-z][a-z0-9_]*$`	`fs_hm_001`
Term	`term_`	`^term_[a-z][a-z0-9_]*$`	`term_hm_price`
Relationship	`tr_`	`^tr_[a-z][a-z0-9_]*$`	`tr_hm_price_revenue_conflict`
Business Rule	`br_`	`^br_[a-z][a-z0-9_]*$`	`br_hm_normalised_price`
Business Context	`bc_`	`^bc_[a-z][a-z0-9_]*$`	`bc_hm_dataset_overview`

命名建议

域前缀建议统一：如 hm_ 表示 H&M Fashion 域
表前缀反映类型：fact_（事实表）、dim_（维度表）
指标命名反映度量行为：如 transaction_count、avg_price

5.2 语义版本管理 (SemVer)¶

采用 MAJOR.MINOR.PATCH 三段式版本号：

变更类型	版本变化	示例	触发条件
PATCH	`x.y.Z`	`1.0.0` → `1.0.1`	格式修正、typo、`reviewed_at` 更新
MINOR	`x.Y.0`	`1.0.1` → `1.1.0`	描述更新、新增同义词、exceptions、anti_patterns
MAJOR	`X.0.0`	`1.1.0` → `2.0.0`	SQL 逻辑、`rule_expression`、`bound_assets`、`lifecycle_status` 变更

5.3 CI 版本检查¶

check_version_bump.py 在 PR 中自动执行：

# 比较 base 与 head 分支的 version 字段
python scripts/check_version_bump.py --base origin/main --head HEAD

校验逻辑：

检测 semantic-plane/ 下所有变更的 YAML 文件
解析 base 分支和 head 分支中的 version 字段
验证 head 版本 > base 版本
未递增版本的文件报错并阻止合并

6. 运行时消费模式¶

Backend 通过 PG Supernode 三引擎架构 消费 Semantic Plane 资产：

graph TB
    subgraph "PG Supernode (Aurora PostgreSQL)"
        R["Engine 1: Relational<br/>Source of Truth"]
        V["Engine 2: pgvector<br/>Discovery & Recall"]
        G["Engine 3: Apache AGE<br/>Boundary Enforcement"]
    end

    subgraph "Backend Agents"
        RAG[RAG Skill]
        GRAPH[Graph Traversal]
        DIRECT[Direct Lookup]
        GUARD[Guardrails]
        FEWSHOT[Few-shot Selection]
    end

    V --> RAG
    G --> GRAPH
    R --> DIRECT
    R & G --> GUARD
    V & R --> FEWSHOT

6.1 RAG Skill（语义检索）¶

引擎：Engine 1 (Relational) + Engine 1b (R+) + Engine 2 (pgvector)

流程：

Query Understanding 节点使用 LLM 提取用户问题中的业务关键词（entities.terms、metric_candidates 等）
Engine 1：用 LLM 提取的关键词逐词对 semlayer.business_term 做 ILIKE 精确匹配
Engine 1b：通过 AliasDictionary 字典匹配列别名（alias_terms 字段）
Engine 2：用户问题 → DashScope text-embedding-v4 向量化 → pgvector cosine similarity 召回
术语绑定构建：命中的术语如有 mapped_asset_id，构建为 _term_bindings 视图
Engine R+ 无条件合并到 Engine 2 结果（不受 vector 命中数量约束）
返回 top-K 资产 + 术语绑定，注入后续管道节点

术语绑定 (Term Binding) 强路由

当业务术语绑定到物理列（如 term_hm_price → col_hm_txn_price），该绑定作为强约束贯穿：

Reranker：绑定列及其父表加分，非绑定表降权
Prompt Assembler：生成 必须使用 table.column 的强制指令
Guardrails Layer 2d：拦截将绑定列引用到错误表的 SQL
Corrective Retrieval：检测到违规时按绑定关系拉取正确的表和列

6.2 Graph Traversal（图谱遍历）¶

引擎：Engine 3 (Apache AGE)

典型查询：

-- 找到两表间的 JOIN 路径
SELECT * FROM cypher('ttd_governance', $$
  MATCH path = (t1:TableAsset {id: 'tbl_hm_fact_transaction'})
              -[:JOINS_TO*1..3]-
              (t2:TableAsset {id: 'tbl_hm_dim_article'})
  RETURN path
$$) AS (path agtype);

-- 术语冲突检测
SELECT * FROM cypher('ttd_governance', $$
  MATCH (t:BusinessTerm {id: 'term_hm_price'})
        -[:CONFLICTS_WITH]->(conflict)
  RETURN conflict.id, conflict.context_constraint
$$) AS (id agtype, constraint agtype);

6.3 Direct Lookup（精确查询）¶

引擎：Engine 1 (Relational)

场景：

JOIN 规则查询：SELECT * FROM join_rules WHERE left_table_id = $1 AND allowed_for_nl2sql = true
列元数据：SELECT * FROM column_assets WHERE table_id = $1 AND llm_exposure_policy != 'hidden'
指标 SQL 定义：SELECT sql_definition FROM metric_assets WHERE metric_id = $1

6.4 Business Rule Injection（规则注入）¶

引擎：Engine 1 + Engine 3

流程：

从生成的 SQL 中提取涉及的表和列 ID
查询 bound_assets 包含这些 ID 的 active 规则
按 priority 排序：critical > high > medium > low
critical + high 规则的 description 和 anti_patterns 注入为 guardrails
执行后置校验：检查 SQL 是否违反 rule_expression

6.5 Few-shot Selection（示例选择）¶

引擎：Engine 2 + Engine 1

流程：

用户问题向量化 → pgvector 相似度搜索 few-shot 问题文本
筛选条件：quality_status = 'approved' AND example_class = 'positive'
可选过滤：intent_type 匹配、grounded_assets 重叠度
选取 top 3-5 示例，格式化为 Question → SQL 对注入 prompt

7. 校验与质量门控¶

7.1 校验脚本总览¶

脚本	功能	触发时机
`validate_all_yaml.py`	JSON Schema v7 校验	PR CI
`validate_sql_definitions.py`	SQL 语法解析	PR CI
`validate_cross_layer_refs.py`	跨层引用完整性	PR CI
`check_version_bump.py`	SemVer 递增检查	PR CI
`analyze_metadata_diff.py`	变更影响分析	PR Review

7.2 validate_all_yaml.py¶

基于 JSON Schema Draft-07 的全量 YAML 校验：

python scripts/validate_all_yaml.py --base-dir .

校验逻辑：

扫描 semantic-plane/ 下所有 .yaml 文件
根据 YAML 根键（如 table_asset、metric_asset）匹配对应 Schema
使用 Draft7Validator 执行校验
报告所有违规字段和错误信息

目录→根键映射：

DIR_KEY_MAP = {
    "domains": ["table_asset", "metric_asset"],
    "terms": ["business_terms"],
    "few_shots": ["few_shot_examples"],
    "join_rules": ["join_rules"],
    "term_relationships": ["term_relationships"],
    "business_rules": ["business_rules"],
    "business_contexts": ["business_contexts"],
}

7.3 validate_sql_definitions.py¶

使用 sqlparse 库验证指标 sql_definition 字段的 SQL 语法：

python scripts/validate_sql_definitions.py --base-dir .

校验范围：

metric_asset.sql_definition — 必须是可解析的 SQL
few_shot_examples[].reference_sql — 必须是可解析的 SQL（非 null 时）

7.4 validate_cross_layer_refs.py¶

跨层引用完整性检查：

python scripts/validate_cross_layer_refs.py --base-dir .

检查项：

引用字段	目标	错误类型
`bound_assets`	Layer 1 (tbl_/col_/met_)	悬空引用
`bound_terms`	Layer 2 (term_)	悬空引用
`bound_rules`	Layer 3 (br_)	悬空引用
`bound_contexts`	Layer 3 (bc_)	悬空引用
`mapped_asset_id`	Layer 1	悬空引用
`replacement_term_id`	term_	循环替换链
`replacement_rule_id`	br_	循环替换链

7.5 CI Pipeline 集成¶

# .github/workflows/metadata-validation.yml (简化)
on:
  pull_request:
    paths: ['semantic-plane/**']

jobs:
  validate:
    steps:
      - run: python scripts/validate_all_yaml.py
      - run: python scripts/validate_sql_definitions.py
      - run: python scripts/validate_cross_layer_refs.py
      - run: python scripts/check_version_bump.py --base origin/main

门控策略

任何一项校验失败都会阻止 PR 合并。修复所有错误后重新推送触发重新校验。

8. 发布流程¶

8.1 端到端流程¶

sequenceDiagram
    participant Dev as Developer
    participant Git as GitHub
    participant CI as CI Pipeline
    participant S3 as S3 Bucket
    participant BE as Admin Backend
    participant DB as Aurora PostgreSQL

    Dev->>Git: Push YAML changes (PR)
    Git->>CI: Trigger validation
    CI->>CI: validate_all_yaml.py
    CI->>CI: validate_sql_definitions.py
    CI->>CI: validate_cross_layer_refs.py
    CI->>CI: check_version_bump.py
    CI-->>Git: ✅ All checks pass
    Dev->>Git: Merge PR
    Dev->>S3: ttd-publish-sp (task dp:publish-sp)
    BE->>S3: Poll manifest hash (auto-sync)
    BE->>BE: semantic_plane agent: R+V+G pipeline
    BE->>DB: Engine 1 (R): Relational upsert
    BE->>DB: Engine 3 (G): AGE graph MERGE
    BE->>DB: Engine 2 (V): pgvector embedding upsert
    BE-->>BE: ✅ Complete (soft-delete missing assets)

8.2 build_changeset.py¶

将 Git diff 转化为 JSON changeset（用于分析和审计）：

# 生成 changeset JSON
python scripts/build_changeset.py --base origin/main --head HEAD

8.3 Backend semantic_plane Agent¶

三引擎写入（Backend 内 LangGraph agent 执行）：

Engine 1 (Relational)：结构化字段 UPSERT 到 Aurora PG 表
Engine 3 (Graph)：节点和边 MERGE 到 Apache AGE 图 ttd_governance
Engine 2 (Vector)：调用 DashScope text-embedding-v4 生成向量并写入 pgvector

自动同步：Backend 定期轮询 S3 manifest hash，检测变更后自动执行全量导入。S3 快照中缺失的资产被标记 deleted_at（软删除）。

支持的资产类型：

Layer 1：table_asset, column_asset, metric_asset, few_shot_example
Layer 2：business_term（含同义词和消歧上下文）
Layer 3：business_rule, business_context

9. H&M 领域示例¶

9.1 域概览¶

H&M Fashion (hm_fashion) 是基于 Kaggle H&M Personalized Fashion Recommendations 竞赛数据集构建的示例域：

维度	数值
商品数	~105,000 SKUs
客户数	~1,370,000
交易量	~31,800,000
时间跨度	2018-09-20 — 2020-09-22

9.2 资产拓扑¶

graph LR
    subgraph "Layer 1: Tables"
        FACT[tbl_hm_fact_transaction]
        DIM_A[tbl_hm_dim_article]
        DIM_C[tbl_hm_dim_customer]
    end

    subgraph "Layer 1: Metrics"
        M1[met_hm_transaction_count]
        M2[met_hm_unique_customer_count]
        M3[met_hm_avg_transaction_price]
        M4[met_hm_repeat_purchase_rate]
        M5[met_hm_unique_article_purchased]
    end

    subgraph "Layer 1: Joins"
        J1[jr_hm_txn_article]
        J2[jr_hm_txn_customer]
    end

    FACT ---|"LEFT JOIN<br/>article_id"| DIM_A
    FACT ---|"LEFT JOIN<br/>customer_id"| DIM_C

    M1 -.- FACT
    M2 -.- FACT
    M3 -.- FACT
    M4 -.- FACT
    M5 -.- FACT

9.3 关键数据特征¶

H&M 数据集特殊约束

价格已归一化：price 字段值域 0~1，不是实际货币金额
无订单概念：每行 = 一次购买行为，无 order_id
重复行有意义：同客户同天同商品多行 = 多次购买
客户 ID 已哈希：SHA-256 匿名化，不可反向
仅含购买记录：无退货、退款或取消数据

9.4 资产协作示例¶

用户问题："各渠道的平均客单价是多少？"

Term Recognition：匹配 term_hm_price（价格）→ 触发 ambiguity_notes
Business Rule：br_hm_normalised_price (critical) → 注入约束说明
Few-shot Match：fs_hm_001 (aggregation + grounded on fact_transaction)
Join Rule：无需 JOIN（仅使用 fact_transaction）
Business Context：bc_hm_dataset_overview → assumptions 注入
SQL Generation：生成 SQL 并附带「价格已归一化」的用户说明

10. 编写指南¶

10.1 双语要求¶

所有面向用户和 LLM 的文本字段必须提供中英双语：

# ✅ 正确：双语成对
business_name_zh: "交易事实表"
business_name_en: "Transaction Fact Table"
description_zh: "记录所有购买交易..."
description_en: "Contains all purchase transactions..."

# ❌ 错误：缺少英文
business_name_zh: "交易事实表"
description_zh: "记录所有购买交易..."

描述质量要求

描述必须阐释 业务语义，不可仅描述物理存储。 description_zh / description_en 最少 10 个字符。

10.2 PII 与安全标记¶

# PII 字段 — LLM 不可见
- column_id: col_customer_name
  sensitivity_level: pii
  llm_exposure_policy: hidden
  pii_masking_rule: "suppress"

# 半敏感字段 — 仅检索可用
- column_id: col_postal_code
  sensitivity_level: restricted
  llm_exposure_policy: retrieval_only
  pii_masking_rule: "generalize"

# 常规字段 — LLM 可见
- column_id: col_order_id
  sensitivity_level: internal
  llm_exposure_policy: visible

10.3 Quality Score 使用指南¶

分段	含义	建议
90-100	优秀，可信赖	可直接用于生产 SQL
70-89	良好，小问题	建议附带数据质量说明
50-69	一般，需注意	生成 SQL 时附加 caveat
< 50	低质量	不建议用于 NL2SQL

10.4 Certification Status 生命周期¶

stateDiagram-v2
    [*] --> draft
    draft --> reviewing: 提交审核
    reviewing --> approved: DPO 批准
    approved --> certified: 质量达标 + 生产验证
    certified --> deprecated: 有替代方案
    deprecated --> retired: 完全下线
    reviewing --> draft: 退回修改
    certified --> reviewing: 重大变更

状态	对 NL2SQL 的影响
`draft`	不参与检索和 SQL 生成
`reviewing`	不参与检索和 SQL 生成
`approved`	参与检索，SQL 生成时标注为「待认证」
`certified`	完全参与，最高优先级
`deprecated`	仍参与但降低权重，提示迁移到替代资产
`retired`	完全不参与

10.5 常见错误与修复¶

错误	原因	修复
Schema 校验失败	缺少必填字段或类型错误	对照 `schemas/` 补全字段
Version bump 失败	修改了文件但未递增版本	按变更类型递增 PATCH/MINOR/MAJOR
Cross-layer ref 失败	`bound_assets` 引用了不存在的 ID	检查 ID 拼写或先创建被引用资产
SQL validation 失败	`sql_definition` 语法错误	用 `sqlparse` 本地测试 SQL
双语缺失	只写了中文没写英文	补全所有 `_en` 字段

10.6 本地开发工作流¶

# 1. 编辑 YAML 文件
vim semantic-plane/domains/hm_fashion/fact_transaction.yaml

# 2. 本地 Schema 校验
python scripts/validate_all_yaml.py

# 3. SQL 语法检查（仅指标）
python scripts/validate_sql_definitions.py

# 4. 跨层引用检查
python scripts/validate_cross_layer_refs.py

# 5. 版本检查（与 main 比较）
python scripts/check_version_bump.py --base origin/main

# 6. 本地发布到 S3 测试
task dp:publish-sp

# 7. 提交 PR
git add semantic-plane/
git commit -m "feat(semantic): add new metric for H&M domain"
git push origin feature/new-metric

附录 A: Certification Status 枚举值¶

draft → reviewing → approved → certified → deprecated → retired

附录 B: Sensitivity Level 枚举值¶

public < internal < restricted < pii < highly_restricted

附录 C: 完整 Schema 引用¶

所有 JSON Schema 源文件位于 semantic-plane/schemas/：

Schema 文件	对应资产
`table_asset.schema.json`	Table Asset + Column Asset
`metric_asset.schema.json`	Metric Asset
`join_rule.schema.json`	Join Rule
`business_term.schema.json`	Business Term
`few_shot_example.schema.json`	Few-shot Example
`term_relationship.schema.json`	Term Relationship
`business_rule.schema.json`	Business Rule
`business_context.schema.json`	Business Context