# 指标新建 / 编辑 / 删除指引

本文是指标写操作的入口索引，用于指导 AI 选择应加载的细分文档，避免一次性读取所有指标类型的长配置。当前覆盖原子指标、复合指标、衍生指标的创建/编辑预检查；删除的完整交互流程后续补充。

## 读取顺序

处理指标写操作时按需读取：

1. 先读本文，判断指标类型和整体保存流程。
2. 始终读取 `metric-common-fields.md`，获取当前环境、通用字段、业务属性 `bizAttrs`、发布/校验规则。
3. 只读取目标类型文档：
   - 原子指标：`metric-atomic-mutation.md`
   - 复合指标：`metric-composite-mutation.md`
   - 衍生指标：`metric-derived-mutation.md`
   - 删除指标：`metric-delete-mutation.md`
4. 如果用户意图不明确，先按“类型判断”问清楚，再加载对应类型文档。

## 类型判断

| 用户意图 | 指标类型 | 读取文档 |
| --- | --- | --- |
| 基于一个数据集字段求和、计数、平均、最大、最小、去重计数，或用数据集字段公式生成指标 | 原子指标 `ATOMIC` | `metric-atomic-mutation.md` |
| 用已有指标做公式，例如销售额 / 订单数、A + B、多个指标组合计算 | 复合指标 `COMPOSITE` | `metric-composite-mutation.md` |
| 同比、环比、最近 N 天/周/月、累计、期末值、业务限定、组合衍生 | 衍生指标 `DERIVED` | `metric-derived-mutation.md` |
| 删除、移除某个指标 | 通用删除流程 | `metric-delete-mutation.md` |

常见含混说法：

- “新建一个指标，基于某数据集/某字段”：通常是原子指标。
- “客单价 = 销售额 / 订单数”：通常是复合指标。
- “用数据集字段计算一个表达式指标”：先按下方“表达式建模确认”询问用户是否改为复合指标。
- “给销售额做月环比/最近 7 天/本月累计/华东限定”：通常是衍生指标。

## 表达式建模确认

只要用户要创建的是计算表达式指标，不要直接替用户决定用原子表达式还是复合指标。先向用户确认：

```text
这个指标需要计算表达式。是否希望我先创建/复用表达式中的基础原子指标，再创建一个复合指标？
如果选择否，我会按数据集字段表达式创建原子指标。
```

用户选择“是”时：

1. 拆出表达式中的基础度量。
2. 先搜索是否已有对应基础原子指标；已有则复用。
3. 缺失基础指标时，先按 `metric-atomic-mutation.md` 创建基础原子指标。
4. 再按 `metric-composite-mutation.md` 创建复合指标，公式使用 `[metricId]`，不要使用 `[fdId]`。

用户选择“否”或明确要求数据集字段表达式时，才走原子指标 `formulaField.fdFormula`。

## 总体流程

1. 使用当前已登录环境，不主动询问 profile；写操作前可执行 `guancli auth status`。
2. 信息不全时先查 ID，不凭空猜：
   - 指标主题：`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`
3. 读取启用的指标业务属性配置，补齐必填 `bizAttrs`。
4. 生成“指标创建计划”，让用户 review；用户确认计划前，不生成最终提交 JSON，不执行 dry-run/precheck/真实创建。
5. 用户确认计划后，生成 JSON 文件，先做 dry-run 或人工摘要，向用户确认当前环境、目标目录、指标口径、计算配置、业务属性和保存方式。
6. 用户确认后，仍需按 Web 同款交互执行保存前校验或影响校验。
7. 校验通过、无对应校验，或用户对冲突/影响完成二次确认后，才提交真实创建或编辑。
8. 写入成功后用 `guancli metric get <metric_id> --brief` 回读确认。

不要把“dry-run 成功”“precheck 通过”或“影响校验无阻塞”描述成指标已经创建/编辑成功。

## 指标创建计划

创建指标前必须先输出一个计划供用户 review，尤其是一个需求会创建多个基础原子指标和复合指标时。计划确认前不得提交真实创建请求。

计划至少包含：

- 当前环境和目标主题。
- 目标目录路径和目录 ID。
- 将创建的指标清单，按依赖顺序排序；每个指标标明临时序号、名称、类型、保存方式。
- 每个指标的核心口径：原子指标写数据集、字段、聚合方式或表达式；复合指标写中文公式和 `[metricId]` 公式草案；衍生指标写基础指标和衍生配置。
- 适用维度和时间维度；如果存在时间字段但时间维度为空，计划必须标记为待确认，不能进入提交步骤。
- 数据格式、业务负责人、必填业务属性。
- 将复用的已有指标和将新建的基础指标。
- 后续会执行的校验：dry-run、save-precheck、validate-update-impact 或本地引用检查。

计划示例：

```markdown
### 指标创建计划

环境：demo-guandata
主题：跨境电商指标体系 (ida4...)
目录：广告分析 / 投放效果 (dir_xxx)

| 步骤 | 动作 | 指标名称 | 类型 | 核心口径 | 时间维度 | 保存方式 |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | 复用 | 归因销售额 | 原子指标 | SUM(attributed_sales) | updated_at | 在线 |
| 2 | 复用 | 广告花费 | 原子指标 | SUM(spend_amount) | updated_at | 在线 |
| 3 | 新建 | ROAS | 复合指标 | [归因销售额] / [广告花费] | updated_at | 草稿 |

确认后我会生成 JSON、执行 dry-run/必要校验，再提交创建。
```

## 校验入口速查

| 操作 | 校验规则 |
| --- | --- |
| 原子创建，`publish=true` | 先 `POST /api/metric-platform/metrics/atomic-metrics/save-precheck` |
| 原子创建，`publish=false` | Web 跳过 save-precheck，可在用户确认后创建草稿 |
| 原子编辑，`publish=true` | 先 atomic `save-precheck`，请求体带 `metricId`；再跑 `validate-update-impact` |
| 原子编辑，`publish=false` | 跑 `validate-update-impact` |
| 复合创建 | Web 创建无 save-precheck；提交前做人工摘要和本地 JSON/引用检查 |
| 复合编辑 | 修改 `formula` 或 `filter` 时跑 `validate-update-impact` |
| 衍生创建 | Web 创建无 save-precheck；提交前做人工摘要和本地 JSON/引用检查 |
| 衍生编辑 | 修改 `baseMetricId`、`deriveSetting` 或 `filter` 时跑 `validate-update-impact` |
| 删除指标 | 先 `GET /api/metric-platform/metrics/{id}/validate-delete-impact`；有下游资源时阻断删除 |

## 命令能力边界

- `guancli metric create` 和 `guancli metric edit` 当前是原子指标专用命令。
- 复合指标和衍生指标创建/编辑使用 `guancli fetch POST ... --stdin < payload.json`。
- 指标删除使用 `guancli metric delete <metric_id>`；默认只做影响校验，追加 `--confirm` 才会在无下游依赖时提交删除。