Metric Spec

表达业务指标的定义语义。运行时派生字段（如 id、currentValue、physicalColumnState）不应出现在此协议中。

资源类型与自然键

资源类型	自然键	说明
`Metric`	`${objectName}.${apiName}`	指标在所属对象下以 `apiName` 作为自然键；`apiName` 为空时默认使用 `name`

MetricSpecDTO

字段	类型	说明
`name`	string	名称，写入 `fd_ontology_metric.display_name`
`apiName`	string	API 名称，作为对象下指标的自然键；为空时默认使用 `name`
`displayName`	string	显示名称。当前写入服务使用 `name` 作为显示名称，此字段为协议占位。
`description`	string	描述
`objectRef`	ResourceRefDTO	所属对象引用，解析规则见下文
`metricType`	MetricTypeEnum	指标类型：`BASE` / `AGGREGATE` / `DERIVED` / `COMPOSITE`
`aggregationType`	AggregateTypeEnum	聚合类型：`COUNT` / `SUM` / `AVG` / `MIN` / `MAX` / `COUNT_DISTINCT`
`expression`	string	计算表达式，用于派生指标或组合指标定义计算逻辑
`relationPath`	string	关系路径，`AGGREGATE` 类型跨对象聚合时使用
`basePropertyApiName`	string	基础属性 API 名称，`BASE` / `AGGREGATE` 类型指向被聚合的属性
`filterExpression`	string	过滤表达式，对聚合前的数据行进行过滤
`timeGrainPropertyApiName`	string	时间粒度属性 API 名称，用于时序指标按时间维度聚合
`supportedDimensions`	List<string>	支持的维度属性 API 名称列表，指标可按这些维度下钻
`isDerived`	boolean	是否为派生指标
`derivedExpression`	string	派生表达式，`DERIVED` 类型时使用
`materializationStrategy`	MaterializationStrategyEnum	物化策略：`NONE` / `CACHE` / `VIEW` / `COLUMN`；默认 `NONE`
`format`	FormatSpecDTO	格式配置，序列化后写入 `format_config_json`

所属对象引用 (`objectRef`)

指标通过 objectRef 声明所属对象，使用 ResourceRefDTO：

字段	说明
`kind`	资源类型，固定填 `ObjectType`
`name`	对象类型名称（自然键），优先使用
`apiName`	API 名称，`name` 为空时回退使用

OntologyDomainProjectionAdapter.MetricProjectionHandler 解析 objectRef 得到 objectName 后，调用 ontologyApi.upsertMetric(objectName, spec, false)。

指标类型与字段组合

不同 metricType 的语义与常用字段组合：

类型	说明	典型字段
`BASE`	基础指标，直接对对象属性做聚合	`basePropertyApiName` + `aggregationType`
`AGGREGATE`	聚合指标，可跨关系路径聚合	`basePropertyApiName` + `aggregationType` + `relationPath`
`DERIVED`	派生指标，由表达式计算得到	`isDerived = true` + `derivedExpression` / `expression`
`COMPOSITE`	组合指标，由多个指标或表达式组合	`expression`

子结构消费说明

FormatSpecDTO

全部字段已消费：pattern / prefix / suffix / precision 被序列化后写入 format_config_json。

示例

基础计数指标

apiVersion: foundry.loambase.ai/v1alpha1
kind: Metric
metadata:
  name: count_account
spec:
  apiName: count_account
  name: 总账户数
  description: 对象 AmlAccount 下的总账户数
  metricType: BASE
  aggregationType: COUNT
  isDerived: false
  materializationStrategy: CACHE
  objectRef:
    kind: ObjectType
    name: AmlAccount

对属性去重计数

spec:
  apiName: distinct_account_id
  name: 去重账户数
  metricType: BASE
  aggregationType: COUNT_DISTINCT
  basePropertyApiName: account_id
  objectRef:
    kind: ObjectType
    name: AmlAccount

跨对象聚合指标

spec:
  apiName: account_total_amount
  name: 账户交易总额
  metricType: AGGREGATE
  aggregationType: SUM
  basePropertyApiName: amount
  relationPath: Transaction.accountHasTransactions
  filterExpression: status = 'SETTLED'
  objectRef:
    kind: ObjectType
    name: Account

派生指标

spec:
  apiName: avg_transaction_per_account
  name: 户均交易笔数
  metricType: DERIVED
  isDerived: true
  derivedExpression: total_transaction_count / distinct_account_count
  objectRef:
    kind: ObjectType
    name: Transaction

消费位置

foundry-ontology-biz: OntologyDefinitionWriteService.upsertMetric / createMetric / updateMetric 将字段投影到 fd_ontology_metric。
foundry-ontology-biz: OntologyDomainProjectionAdapter.MetricProjectionHandler 解析 objectRef 后调用 ontologyApi.upsertMetric。