# 指标通用配置

本文记录原子指标、复合指标、衍生指标共享的写操作规则、通用字段和业务属性处理方式。处理任一指标创建/编辑任务时，都应先读取本文，再读取对应类型文档。

## 环境与查询

- 默认使用用户当前已登录环境，不询问“创建到哪个 profile”。可先执行 `guancli auth status` 确认登录态。
- 只有用户明确指定其它环境时，才统一追加 `--profile <profile>`。
- 用户只给中文名称时，先查询并展示候选；查不到或有多个候选再向用户确认。
- 常用查询：
  - 指标主题：`guancli metric project [keyword] -f json`
  - 指标目录：`guancli metric tree -f json`
  - 指标：`guancli metric search <keyword> -f json`
  - 指标详情：`guancli metric get <metric_id> --brief`
  - 数据集：`guancli ds search <keyword>`、`guancli ds get <dsId> --brief`

## 通用字段

| 字段 | 中文 | 适用范围 | 说明 |
| --- | --- | --- | --- |
| `projectId` | 主题 ID | 创建/编辑 | 指标所属主题 |
| `subType` | 指标类型 | 创建/编辑 | `ATOMIC`、`COMPOSITE`、`DERIVED` |
| `name` | 指标名称 | 创建/编辑 | 最长 50；仅中文、字母、数字、下划线 |
| `engName` | 英文名称 | 可选 | 最长 50；仅字母、数字、下划线 |
| `desc` | 业务口径 | 创建/编辑 | 最长 1000；必须能解释业务含义 |
| `format` | 数据格式 | 可选 | 指标数值展示格式；省略或传 `{}` 表示默认格式 |
| `parentDirId` | 保存至/所属文件夹 | 创建必填 | 指标目录 ID |
| `businessOwner` | 责任人 | 创建必填 | 用户 ID，默认可用当前登录用户 |
| `publish` | 保存方式 | 创建/编辑 | `true` 保存并上线；`false` 保存为草稿 |
| `bizMetricId` | 关联业务字典 ID | 可选 | 关联后业务口径/业务属性通常会同步 |
| `bizAttrs` | 业务属性 | 条件必填 | 由环境中的指标属性配置决定 |
| `filter` | 业务限定/筛选 | 可选或条件必填 | 业务限定衍生指标必填 |
| `dynamicParameters` | 动态参数默认值 | 可选 | 表达式或最近 N 配置引用动态参数时使用 |

## 数据格式 `format`

`format` 是指标数值的展示格式，创建和编辑原子指标、复合指标、衍生指标时都可设置。保存指标时写入 Web 表单使用的 UI 配置，不要写转换后的 d3 `specifier`、Excel format 或预览接口返回值。

省略 `format` 或传 `{}` 表示使用默认格式。用户没有明确要求时，不要为了补全字段强行设置格式；用户提到“保留两位小数”“显示百分比”“人民币”“万元”“不要千分位”“加后缀”等，再按下面字段生成。

| 字段 | 中文 | 说明 |
| --- | --- | --- |
| `formatType` | 格式类型 | `NUMBER` 数值、`CURRENCY` 货币、`PERCENTAGE` 百分比、`ADVANCED` 高级自定义 |
| `decimalPlaces` | 小数位数 | `null` 表示 0 位；也可传 `1` 到 `15` |
| `useThousandsSeparator` | 是否使用千分位 | `true/false` |
| `prefix` | 前缀/货币符号 | 货币常用 `￥`、`$`、`€`、`£`；后端兼容旧字段 `currencySymbol`，新建优先写 `prefix` |
| `suffix` | 后缀 | 如 `元`、`人`、`单`、`次`；没有则省略或传空字符串 |
| `prefixUnit` | 数量级单位 | `null` 无，`K`、`M`、`万`、`亿` 或 `auto` 自动 |
| `showPrefixUnit` | 是否展示数量级单位 | 数值/货币格式可用；`prefixUnit=auto` 时应为 `true` |
| `divideDataBy` | 百分比是否除以 100 | 百分比格式可用；`1` 适合底层值是比例小数如 `0.85`，`100` 适合底层值已是百分数如 `85` |
| `customFormat` | 高级自定义格式 | `formatType=ADVANCED` 时使用；除非用户给出现成格式串，否则不要主动生成 |
| `suffixSizePercent` | 后缀字号比例 | 部分卡片展示场景使用，指标创建/编辑通常不需要 |

常用模板：

```jsonc
// 默认格式：省略 format 或传 {}
"format": {}

// 数值：千分位，保留 2 位小数
"format": {
  "formatType": "NUMBER",
  "decimalPlaces": 2,
  "useThousandsSeparator": true,
  "prefixUnit": null,
  "showPrefixUnit": true,
  "prefix": "",
  "suffix": ""
}

// 货币：人民币，千分位，保留 2 位小数
"format": {
  "formatType": "CURRENCY",
  "decimalPlaces": 2,
  "useThousandsSeparator": true,
  "prefix": "￥",
  "prefixUnit": null,
  "showPrefixUnit": true,
  "suffix": ""
}

// 百分比：底层值为 0.85 时展示为 85.00%
"format": {
  "formatType": "PERCENTAGE",
  "decimalPlaces": 2,
  "divideDataBy": 1,
  "useThousandsSeparator": false,
  "prefix": "",
  "suffix": ""
}

// 百分比：底层值为 85 时展示为 85.00%
"format": {
  "formatType": "PERCENTAGE",
  "decimalPlaces": 2,
  "divideDataBy": 100,
  "useThousandsSeparator": false,
  "prefix": "",
  "suffix": ""
}

// 数值：按万元展示
"format": {
  "formatType": "NUMBER",
  "decimalPlaces": 2,
  "useThousandsSeparator": true,
  "prefixUnit": "万",
  "showPrefixUnit": true,
  "prefix": "",
  "suffix": "元"
}
```

## 业务属性 `bizAttrs`

`bizAttrs` 是管理员配置的指标自定义业务属性，不是固定字段。创建或编辑指标前读取当前环境配置：

```bash
guancli fetch GET /api/metric-attr-config
```

响应关键字段：

| 字段 | 中文 | 说明 |
| --- | --- | --- |
| `id` | 属性 ID | 写入 `bizAttrs[].id` |
| `name` | 属性名称 | 用于向用户提问 |
| `description` | 属性描述 | 可作为输入提示 |
| `valueType` | 属性值类型 | `ENUM_SINGLE`、`ENUM_MULTIPLE`、`TEXT`、`TEXT_AREA` |
| `defaultValue` | 默认值 | 用户未指定且允许默认时可采用 |
| `optionValue` | 枚举选项 | 枚举单选/多选必须从这里选择 |
| `required` | 是否必填 | `true` 且 `enabled=true` 时必须收集 |
| `enabled` | 是否启用 | 只处理启用的属性 |

处理规则：

- 只展示和写入 `enabled=true` 的属性；其中 `required=true` 是必填项。
- `ENUM_SINGLE`：`values` 只能有一个值，且必须来自 `optionValue`。
- `ENUM_MULTIPLE`：`values` 可以有多个值，且都必须来自 `optionValue`。
- `TEXT`：写入 `values[0]`，Web 单项最大 50 个字符。
- `TEXT_AREA`：写入 `values[0]`，Web 单项最大 200 个字符。
- 如果关联了业务字典 `bizMetricId`，业务口径和业务属性通常由业务字典同步；仍需确认最终 payload 中 `desc` 和 `bizAttrs` 已有值。

示例：

```json
"bizAttrs": [
  { "id": "attr_region", "values": ["华东"] },
  { "id": "attr_tags", "values": ["销售", "核心"] },
  { "id": "attr_owner_note", "values": ["用于经营分析月报"] }
]
```

## 保存与确认

- 先输出“指标创建计划”让用户 review；计划确认前不生成最终提交 JSON，不执行真实创建。
- 用户确认计划后，再生成 JSON 文件并做 dry-run 或人工摘要，不直接提交。
- 计划/摘要至少包含：当前环境、主题、目录、指标类型、名称、核心计算方式、依赖顺序、复用/新建指标、适用维度/时间维度、数据格式、业务属性、保存方式。
- 如果适用维度中存在时间字段但时间维度为空，计划必须标记为待确认，不能继续提交。
- 用户确认后按类型执行 save-precheck 或 validate-update-impact。
- 如果校验返回冲突或影响下游资源，展示冲突指标、受影响指标、受影响卡片，并等待二次确认。
- 写入成功后回读 `guancli metric get <metric_id> --brief`。

## 发布状态判断

- 用户说“先别上线”“保存草稿”：`publish=false`。
- 用户说“直接上线”“发布”：`publish=true`，提交前提醒会创建或更新在线指标。
- 不要把 `publish=true` 自动当成用户已经确认所有冲突；冲突/影响校验仍需要单独二次确认。