Article body
正文
同一家公司里，财务按开票计算收入，销售按签约计算收入，运营又按回款计算收入。ChatBI 面对“本月收入是多少”时，如果只看到字段名，它可能选择最像的一列并生成一条可以运行的 SQL。指标定义才负责保证口径正确。
指标是一份可执行合同
企业需要为每个指标记录名称、计算逻辑、时间粒度、适用维度、数据来源、负责人和权限。HQL 用接近分析语义的表达式定义聚合、计算、时间和过滤逻辑。分析师定义一次“活跃客户数”，看板、API 和 Agent 都引用同一个指标对象。底层表结构变化时，平台维护指标实现，上层消费方继续使用稳定名称。
指标语义层还要管理同义词与歧义词。业务人员说“营收”“收入”或“销售收入”时，系统先匹配候选指标，再根据部门、应用和当前上下文缩小范围。无法确定时，Agent 应展示指标定义并请用户选择，把错误拦在查询执行之前。
一份指标合同可以用元数据描述：
name: paid_customer_count
display_name: 付费客户数
description: 统计周期内完成付款的去重客户数
owner: 销售运营数据团队
dimensions:
- region
- product_line
- order_date
aliases:
- 付费客户
- 成交客户数
permission_policy: sales_metrics_read这段 YAML 是指标元数据示例，HQL 只负责其中的计算表达式。
HQL 提供受控的分析自由
SQL 面向表与字段，HQL 面向分析模型中的字段、维度和度量。用户可以组合指标、维度、筛选与时间窗口，平台再把表达式交给查询引擎执行。治理团队可以检查维度兼容性、权限和指标依赖。
基础聚合使用字段引用：
SUM({order_amount})条件聚合可以明确业务状态：
SUM(
CASE
WHEN {order_status} = 'completed' THEN {order_amount}
ELSE 0
END
)活跃客户数可以使用去重计数：
COUNTD(
CASE
WHEN {activity_status} = 'active' THEN {customer_id}
END
)按月观察收入时，图表或查询请求会把度量 SUM({order_amount}) 与月份维度 MONTH({order_date}) 组合。两者是独立的 HQL 表达式，分组关系由图表或查询定义，不写进度量公式。
需要滚动或对比计算时，可以使用窗口函数。具体函数与窗口边界要以部署版本的 HQL 参考为准：
AVG(SUM({order_amount})) OVER (
ORDER BY {order_date}
ROWS BETWEEN 6 PRECEDING AND CURRENT ROW
)这些表达式仍需放进明确的数据集与权限上下文。HQL 不替代指标元数据、数据模型或审批流程。
时间语义必须集中管理
同比、环比、滚动七日和财年至今都依赖日历规则。自然月、财务月、时区、补数策略与不完整周期处理如果散落在每次对话里，结果很难复核。团队应把规则放进指标定义和时间维度，让 Agent 选择已经治理的对象。
查询结果还需要携带上下文：指标版本、数据更新时间、筛选条件、时间范围与权限主体。用户看到的不只是一组数字，还能知道系统按哪个口径计算。
Headless 语义层服务多个入口
企业的数据消费入口包括 BI 门户、CRM、供应链系统、移动端、API 和 Agent。Headless 语义层通过 API 与 CLI 向这些入口提供一致的指标、权限和查询能力。界面可以变化，业务口径保持稳定。
| 消费入口 | 语义层提供的能力 | 需要保留的上下文 |
|---|---|---|
| 仪表盘与报表 | 指标、维度、筛选、格式 | 指标版本、刷新时间 |
| ChatBI | 候选指标、同义词、查询计划 | 用户、会话、权限 |
| Data Agent | 查询、建模和资源操作契约 | 计划、审批、工具回执 |
| 业务系统 API | 稳定指标与数据服务 | 租户、应用、调用方 |
这套架构也适合 ISV。软件厂商可以把行业指标沉淀在自己的产品中，客户通过内嵌看板、ChatBI 或工作流调用同一语义层。ISV 控制用户体验，平台负责计算、权限和治理。
语义层给 AI 的上下文
Agent 不需要读取整个数据库 Schema。它可以先获取受权限约束的指标目录：
{
"name": "revenue",
"displayName": "营业收入",
"definition": "已确认收入订单的含税金额之和",
"dimensions": ["region", "product_line", "order_date"],
"aliases": ["营收", "销售收入"],
"dataType": "currency",
"owner": "财务数据团队"
}当用户问“昨天卖了多少”时，Agent 可以展示“营业收入”“订单量”和“商品件数”等候选项。用户确认后，Agent 再生成查询计划。候选约束与主动澄清比猜字段更可靠。
从十个指标开始
指标治理不需要一次覆盖全公司。团队可以选择一个经营主题，先定义十个高频指标，补齐负责人、口径、维度、时间和权限，再让 ChatBI 只回答这一可信区域的问题。
实施顺序可以压缩为四步：
- 盘点高频问题，选出十个能影响业务决策的指标。
- 由业务负责人和数据负责人共同确认定义、维度与时间规则。
- 用 HQL 实现计算表达式，并用历史报表做双算校验。
- 向看板、API 和 Agent 开放同一指标对象，记录歧义与失败查询。
每次修正都应回到指标库。随着可信范围扩展，Agent 可以承担更多分析与执行任务。
质量检查
| 检查项 | 检查规则 | 处理方式 |
|---|---|---|
| 命名规范 | 标识符稳定且可跨环境迁移 | 在发布前阻断不合规名称 |
| 口径冲突 | 同义指标是否存在不同定义 | 交给指标负责人裁决 |
| 循环依赖 | 指标是否形成引用环 | 阻断发布 |
| 空值与除零 | 表达式是否定义异常行为 | 显式补充条件或默认值 |
| 数据时效 | 是否声明刷新时间与延迟 | 在消费端展示时效 |
| 权限 | 指标、维度与行级权限是否一致 | 运行多角色回归测试 |