@guandata/guancli 1.0.31 → 1.0.32

package/skills/guancli/references/metric-composite-mutation.md

@@ -0,0 +1,146 @@
+# 复合指标创建与编辑
+
+复合指标用于通过公式组合已有指标，例如“客单价 = 销售额 / 订单数”。
+
+## 触发场景
+
+- 用户说“创建复合指标”“基于多个指标算一个指标”。
+- 用户描述的口径是已有指标之间的四则运算。
+- 用户要编辑一个 `subType=COMPOSITE` 的指标。
+
+## 创建必填信息
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `projectId` | 主题 ID | 指标所属主题 |
+| `subType` | 指标类型 | 固定 `COMPOSITE` |
+| `name` | 指标名称 | 最长 50 |
+| `formula` | 计算公式 | 使用已有指标 ID，形如 `[metric_sales] / [metric_orders]` |
+| `useExpressionMetricCommonDims` | 是否沿用公式指标共有维度 | Web 默认 `true` |
+| `applicableDims` | 适用维度 | 引用指标的共有维度字段 ID 数组；手动选择时不能为空 |
+| `desc` | 业务口径 | 最长 1000 |
+| `parentDirId` | 保存至/所属文件夹 | 创建时需要 |
+| `businessOwner` | 责任人 | 创建时需要 |
+| `publish` | 保存方式 | `true` 上线，`false` 草稿 |
+
+专属可选字段：
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `timeDim` | 时间维度 | 最终适用维度中存在时间字段时选择一个 |
+
+通用可选字段见 `metric-common-fields.md`。
+
+## 公式与引用指标
+
+复合指标公式在最终 payload 中使用指标 ID，而不是指标中文名：
+
+```text
+[metric_sales_amount] / [metric_order_count]
+```
+
+处理规则：
+
+- 涉及复合指标 `formula` 时，先读取 `metric-expression-rules.md`。
+- 先用 `guancli metric search <关键词> -d <projectId> -f json` 查询公式中的指标，再用 `guancli metric get <metric_id> --brief` 核对名称、类型、状态和适用维度。
+- 公式只能引用数值型指标；不要引用当前正在编辑的指标本身。
+- 公式支持 `+`、`-`、`*`、`/`、括号、数字和 `[指标ID]`；不要主动生成函数、窗口函数或 SQL 片段。
+- 公式中的 `[xxx]` 会被后端解析为上游指标 ID，并参与循环引用校验。
+- 如果用户用中文名描述公式，先转换成 ID 公式，再把“中文公式”和“ID 公式”都展示给用户确认。
+
+## 适用维度
+
+复合指标的适用维度来自公式中引用指标的共有维度：
+
+- `useExpressionMetricCommonDims=true`：沿用表达式中指标的共用维度。需要根据引用指标详情整理共有维度；如果没有共有维度，Web 会报“计算公式来源指标无共有适用维度，请检查”。
+- `useExpressionMetricCommonDims=false`：从共有维度中手动选择 `applicableDims`，至少选择一个。
+- 如果最终适用维度中有时间类型字段，需要选择一个 `timeDim`。
+- 不要把某个上游指标独有的维度写进 `applicableDims`。
+
+## 信息收集
+
+如果用户只说“帮我创建一个复合指标”，先收集：
+
+1. 指标主题和保存目录。
+2. 公式中要引用哪些已有指标；中文名先搜索确认唯一指标。
+3. 计算公式，转换成 `[metric_id]` 形式。
+4. 是否沿用共有维度；如果手动选择，确认具体维度和时间维度。
+5. 数据格式：默认、数值、货币、百分比；如需指定，确认小数位、千分位、货币符号/前后缀、数量级单位、百分比是否除以 100。
+6. 指标名称、业务口径、是否保存并上线。
+7. 责任人和必填 `bizAttrs`。
+
+## JSON 模板
+
+```json
+{
+  "projectId": "<metric_project_id>",
+  "subType": "COMPOSITE",
+  "name": "客单价",
+  "engName": "avg_order_value",
+  "formula": "[<sales_amount_metric_id>] / [<order_count_metric_id>]",
+  "useExpressionMetricCommonDims": true,
+  "applicableDims": ["<common_dim_fd_id_1>", "<common_dim_fd_id_2>"],
+  "timeDim": "<time_dim_fd_id>",
+  "format": {
+    "formatType": "NUMBER",
+    "decimalPlaces": 2,
+    "useThousandsSeparator": true,
+    "prefixUnit": null,
+    "showPrefixUnit": true,
+    "prefix": "",
+    "suffix": ""
+  },
+  "desc": "销售金额除以订单数，用于衡量平均每笔订单贡献的销售额。",
+  "parentDirId": "<metric_dir_id>",
+  "businessOwner": "<user_id>",
+  "publish": false
+}
+```
+
+没有时间维度时删除 `timeDim`；没有英文名称时删除 `engName`；未指定数据格式时删除 `format` 或传 `{}`。如需业务属性，按 `metric-common-fields.md` 补充 `bizAttrs`。
+
+## 创建步骤
+
+`guancli metric create` 当前是原子指标专用 endpoint；复合指标创建使用 `guancli fetch`。
+
+1. 生成 `/tmp/composite_metric.json`。
+2. 本地/人工检查 JSON、公式引用指标、共有适用维度、必填业务属性。
+3. 按 `metric-common-fields.md` 向用户摘要并确认。
+4. 用户确认后，不调用原子指标 `save-precheck`；复合指标 Web 创建没有 save-precheck。
+5. 提交真实创建：
+
+```bash
+guancli fetch POST /api/metric-platform/metrics/composite-metrics --stdin < /tmp/composite_metric.json
+```
+
+6. 响应返回指标 ID 后回读：
+
+```bash
+guancli metric get <metric_id> --brief
+```
+
+## 编辑步骤
+
+复合指标没有原子指标的 save-precheck；主要校验公式或筛选变化是否影响下游指标/卡片。
+
+1. 读取当前详情：
+
+```bash
+guancli metric get <metric_id> -f json
+```
+
+2. 基于当前详情生成完整编辑 payload，例如 `/tmp/composite_metric_update.json`。至少包含 `projectId`、`subType`、`name`、`formula`、`useExpressionMetricCommonDims`、`applicableDims`、`desc`、`publish`。
+3. 如果修改了 `formula` 或 `filter`，先调用影响校验：
+
+```bash
+guancli fetch POST /api/metric-platform/metrics/composite-metrics/<metric_id>/validate-update-impact --stdin < /tmp/composite_metric_update.json
+```
+
+4. 如果返回 `hasChanged=true` 且 `affectedMetrics` 或 `affectedCards` 非空，展示受影响指标和卡片，等待用户二次确认。
+5. 提交真实编辑：
+
+```bash
+guancli fetch POST /api/metric-platform/metrics/composite-metrics/<metric_id> --stdin < /tmp/composite_metric_update.json
+```
+
+6. 保存后回读确认。

package/skills/guancli/references/metric-delete-mutation.md

@@ -0,0 +1,70 @@
+# 指标删除
+
+指标删除适用于原子指标、复合指标、衍生指标和快捷引用指标。删除流程是通用的，不需要按指标类型走不同 endpoint。
+
+## Web 同款行为
+
+Web 的单指标删除弹窗会先做删除影响校验：
+
+```bash
+guancli fetch GET /api/metric-platform/metrics/<metric_id>/validate-delete-impact
+```
+
+响应结构与编辑影响校验一致：
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `hasChanged` | 是否存在变更影响 | 删除校验通常为 `true` |
+| `affectedMetrics` | 下游指标 | 仍引用该指标的指标列表 |
+| `affectedCards` | 下游指标卡片 | 仍引用该指标的卡片列表 |
+
+如果 `affectedMetrics` 或 `affectedCards` 非空，Web 会提示“指标已被以下资源使用，暂无法删除”，只允许用户查看影响并关闭弹窗，不会提交删除。
+
+只有影响列表为空时，Web 才展示“删除后无法恢复”的确认弹窗；用户确认后调用：
+
+```bash
+guancli fetch POST /api/metric-platform/metrics/<metric_id>/delete
+```
+
+## CLI 推荐流程
+
+优先使用封装命令：
+
+```bash
+guancli metric delete <metric_id>
+```
+
+该命令默认只执行删除影响校验并输出结果，不会真实删除。输出 `deletable=true` 时，再向用户确认“删除后无法恢复”。
+
+用户明确确认后执行：
+
+```bash
+guancli metric delete <metric_id> --confirm
+```
+
+`--confirm` 也会先重新执行删除影响校验；如果此时发现下游指标或卡片，仍然阻断删除，不会调用 delete 接口。
+
+## 信息收集
+
+如果用户只说“帮我删除一个指标”，先收集或查询：
+
+1. 指标 ID；如果只给名称，先用 `guancli metric search <关键词> -f json` 查候选。
+2. 用 `guancli metric get <metric_id> --brief` 核对指标名称、类型、主题、目录和状态。
+3. 运行 `guancli metric delete <metric_id>` 查看删除影响。
+4. 如果可删除，向用户确认删除对象和“删除后无法恢复”。
+5. 用户明确确认后执行 `guancli metric delete <metric_id> --confirm`。
+
+## 影响展示
+
+影响校验返回下游资源时，需要向用户展示：
+
+- 下游指标：`id`、`name`、`subType`；若有 `linkMetricId`，说明是快捷引用关联的原始指标。
+- 下游卡片：`id`、`name`。
+
+存在下游资源时不要提供 `--confirm` 继续删除的建议；应提示用户先调整或删除引用关系。
+
+## 常见判断
+
+- 删除是不可恢复操作，即使 `publish=false` 的草稿也要明确确认。
+- 不要把“删除影响校验通过”说成已经删除成功。
+- 删除成功后可尝试 `guancli metric get <metric_id> --brief` 或重新搜索确认资源已不可见；如果后端返回已删除/不存在，视为删除完成。

package/skills/guancli/references/metric-derived-mutation.md

@@ -0,0 +1,384 @@
+# 衍生指标创建与编辑
+
+衍生指标用于在基础指标之上配置同比/环比、最近 N、累计、期末值、业务限定，或通过组合衍生公式引用多个指标。
+
+## 触发场景
+
+- 用户说“创建衍生指标”“做同比/环比”“最近 N 天/周/月”“本月累计/年累计”“期末值”“业务限定”。
+- 用户要编辑一个 `subType=DERIVED` 的指标。
+
+## 创建必填信息
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `projectId` | 主题 ID | 指标所属主题 |
+| `subType` | 指标类型 | 固定 `DERIVED` |
+| `name` | 指标名称 | 最长 50 |
+| `deriveSetting` | 衍生配置 | 见下方细节 |
+| `desc` | 业务口径 | 最长 1000 |
+| `parentDirId` | 保存至/所属文件夹 | 创建时需要 |
+| `businessOwner` | 责任人 | 创建时需要 |
+| `publish` | 保存方式 | `true` 上线，`false` 草稿 |
+
+普通衍生还需要：
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `baseMetricId` | 衍生自/基础指标 ID | 不能是快捷引用指标；先用 `metric search/get` 确认 |
+
+组合衍生不选择单个 `baseMetricId`，核心配置在 `deriveSetting.formula`。
+
+通用可选字段见 `metric-common-fields.md`。`BIZ_CONDITION` 类型必须提供顶层 `filter`。
+
+## 衍生类型
+
+| `advType` / `deriveType` | 中文 | 说明 |
+| --- | --- | --- |
+| `COMPARATIVE` | 同比/环比 | 需要基础指标有时间维度；配置本期、对比期和输出值类型 |
+| `RECENT_X` | 最近 N | 只能衍生自原子指标；如最近 7 天、最近 3 月 |
+| `XTD` | 累计计算 | 周/月/季/年至今累计，或近 N 个粒度累计 |
+| `LAST` | 期末值 | 按基础指标时间维度取期末值 |
+| `BIZ_CONDITION` | 业务限定 | 在基础指标上附加业务筛选，顶层 `filter` 必填 |
+| `deriveType=COMPOSITE` | 组合衍生 | 通过 `deriveSetting.formula` 引用多个指标 |
+
+## `deriveSetting` 通用结构
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `deriveType` | 衍生大类 | 普通衍生为 `ORDINARY`；组合衍生为 `COMPOSITE` |
+| `advType` | 衍生方式 | 普通衍生必填；组合衍生提交前可删除 |
+| `advValue` | 衍生方式配置 | 普通衍生必填；组合衍生可为 `null` 或不传 |
+| `formula` | 组合衍生公式 | 组合衍生必填，使用 `[metric_id]` 引用指标 |
+
+时间粒度 `granularity` 常用值：
+
+| 值 | 中文 |
+| --- | --- |
+| `DAY` | 日 |
+| `WEEK` | 周 |
+| `MONTH` | 月 |
+| `QUARTER` | 季度 |
+| `YEAR` | 年 |
+| `NONE` | 历史数据 |
+| `YEARBYWEEK` | 年同比按周 |
+| `ENDOFMONTH` | 上月末 |
+| `ENDOFQUARTER` | 上季度末 |
+| `ENDOFYEAR` | 上年末 |
+
+基准日期 `baseline` 常用值：
+
+| 值 | 中文 |
+| --- | --- |
+| `DATE_RANGE_PARAM_LEFT` | 基于日期筛选：开始日期 |
+| `DATE_RANGE_PARAM_RIGHT` | 基于日期筛选：结束日期 |
+
+## 同比/环比 `COMPARATIVE`
+
+用于描述本期时间范围、上期/对比期时间范围、输出值类型。
+
+字段明细：
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `advValue.advType` | 高级计算类型 | 固定 `COMPARATIVE` |
+| `dateFdId` | 日期字段 ID | 来自基础指标时间维度；必填 |
+| `dateFdName` | 日期字段名称 | 建议带上 |
+| `granularity` | 时间粒度 | `DAY/WEEK/MONTH/QUARTER/YEAR` |
+| `window` | 本期时间范围 | Web 默认常见为 `{ "offset": 0 }` |
+| `offsetType` | 对比方式粒度 | 如 `MONTH` 月环比、`YEAR` 年同比、`ENDOFMONTH` 上月末 |
+| `offset` | 偏移量 | 同环比默认 `1`；自定义偏移可大于 1 |
+| `fixedBase` | 固定对比期 | 自定义时间范围时使用 |
+| `valueType` | 数值设置 | `VALUE`、`RATE`、`RAWDATA`、`CUSTOM` |
+| `growthRateType` | 增长率算法 | `RATE` 时必填：`NORMAL` 或 `ABS` |
+| `formulaSetting` | 自定义公式 | `CUSTOM` 时必填，由公式编辑器生成 |
+
+`window` 写法：
+
+| 形态 | JSON | 说明 |
+| --- | --- | --- |
+| 当前粒度本期 | `{ "offset": 0 }` | 当前日/周/月/季/年 |
+| 上一个粒度区间 | `{ "offset": 1 }` | 上日/上周/上月等 |
+| 相对日期 | `{ "offset": 3 }` | 相对本期前 3 个粒度 |
+| 固定区间 | `{ "withMacro": false, "period": ["2026-05-01", "2026-05-31"] }` | 固定日期范围 |
+| 时间宏 | `{ "withMacro": true, "period": ["{{{}}}", "{{{}}}"] }` | 使用时间宏表达式 |
+
+数值设置：
+
+| `valueType` | 中文 | 额外字段 |
+| --- | --- | --- |
+| `VALUE` | 增长值 | 无，含义为本期数据 - 上期数据 |
+| `RATE` | 增长率 | `growthRateType` 必填 |
+| `RAWDATA` | 对比值 | 无，直接输出上期/对比期数据 |
+| `CUSTOM` | 自定义公式 | `formulaSetting` 必填 |
+
+示例：月环比增长率：
+
+```json
+"deriveSetting": {
+  "deriveType": "ORDINARY",
+  "advType": "COMPARATIVE",
+  "advValue": {
+    "advType": "COMPARATIVE",
+    "dateFdId": "<time_fd_id>",
+    "dateFdName": "订单日期",
+    "granularity": "MONTH",
+    "window": { "offset": 0 },
+    "offsetType": "MONTH",
+    "offset": 1,
+    "valueType": "RATE",
+    "growthRateType": "NORMAL"
+  }
+}
+```
+
+## 最近 N `RECENT_X`
+
+只能衍生自原子指标。
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `advValue.advType` | 高级计算类型 | 固定 `RECENT_X` |
+| `granularity` | 时间粒度 | `DAY/WEEK/MONTH/QUARTER/YEAR` |
+| `baseline` | 基准日期 | `DATE_RANGE_PARAM_LEFT` 或 `DATE_RANGE_PARAM_RIGHT` |
+| `baselineOffset` | 起止偏移 | 二元数组 `[startOffset, endOffset]` |
+| `baselineOffsetDynamicParameters` | 动态参数偏移 | 如 `[DYNAMIC_PARAMS.N]`，非空时优先于 `baselineOffset` |
+| `aggrType` | 计算方式 | 通常 `SUM/MIN/MAX/AVG/CNT/CNT_DISTINCT/NUL` |
+
+偏移示例：
+
+- `[6,0]` + `DAY`：以基准日期为结束，最近 7 天。
+- `[29,0]` + `DAY`：最近 30 天。
+- `[3,1]` + `MONTH`：基准日期前第 3 个月到前第 1 个月。
+- 动态参数：把对应位置的 `baselineOffset` 置为 `-1`，在 `baselineOffsetDynamicParameters` 写 `[DYNAMIC_PARAMS.xxx]`，同时在顶层 `dynamicParameters` 填默认值。
+
+示例：
+
+```json
+"deriveSetting": {
+  "deriveType": "ORDINARY",
+  "advType": "RECENT_X",
+  "advValue": {
+    "advType": "RECENT_X",
+    "granularity": "DAY",
+    "baseline": "DATE_RANGE_PARAM_RIGHT",
+    "baselineOffset": [6, 0],
+    "aggrType": "SUM"
+  }
+}
+```
+
+## 累计计算 `XTD`
+
+用于“周/月/季/年至今累计”或“近 N 个粒度累计”。
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `advValue.advType` | 高级计算类型 | 固定 `XTD` |
+| `granularity` | 累计范围 | `WEEK/MONTH/QUARTER/YEAR/NONE` |
+| `baseline` | 基准日期 | `DATE_RANGE_PARAM_LEFT` 或 `DATE_RANGE_PARAM_RIGHT` |
+| `baselineOffset` | 自定义累计偏移 | 可选数字；例如 `1` 表示近 2 个粒度累计 |
+| `includeCurrentValue` | 是否包含基准日期当前值 | `true/false` |
+
+示例：月累计：
+
+```json
+"deriveSetting": {
+  "deriveType": "ORDINARY",
+  "advType": "XTD",
+  "advValue": {
+    "advType": "XTD",
+    "granularity": "MONTH",
+    "baseline": "DATE_RANGE_PARAM_RIGHT",
+    "includeCurrentValue": true
+  }
+}
+```
+
+限制：基础指标是复合指标时，不支持部分自定义累计方式；特别是“当年累计”这类年累计自定义配置需谨慎，Web 会拦截不支持组合。
+
+## 期末值 `LAST`
+
+```json
+"deriveSetting": {
+  "deriveType": "ORDINARY",
+  "advType": "LAST",
+  "advValue": {
+    "advType": "LAST",
+    "dateFdId": "<time_fd_id>"
+  }
+}
+```
+
+`dateFdId` 必须来自基础指标时间维度。
+
+## 业务限定 `BIZ_CONDITION`
+
+业务限定必须提供顶层 `filter`。
+
+```json
+"deriveSetting": {
+  "deriveType": "ORDINARY",
+  "advType": "BIZ_CONDITION",
+  "advValue": {
+    "advType": "BIZ_CONDITION"
+  }
+},
+"filter": {
+  "combineType": "AND",
+  "conditions": []
+}
+```
+
+`filter` 结构复杂时，优先参考同环境已有指标详情或由 Web 配置后复制 payload，不凭空拼复杂筛选。
+
+## 组合衍生 `COMPOSITE`
+
+组合衍生通过公式引用多个指标，不选择单个 `baseMetricId`：
+
+```json
+"deriveSetting": {
+  "deriveType": "COMPOSITE",
+  "formula": "[<metric_id_1>] / [<metric_id_2>]"
+}
+```
+
+引用规则：
+
+- 涉及组合衍生 `deriveSetting.formula` 时，先读取 `metric-expression-rules.md`。
+- 公式支持 `+`、`-`、`*`、`/`、括号、数字和 `[指标ID]`；不要主动生成函数、窗口函数或 SQL 片段。
+- 可引用原子指标。
+- 可引用普通衍生里的 `RECENT_X`、`XTD`、`LAST`。
+- 不要引用复合指标、组合衍生、快捷引用指标或当前正在编辑的指标。
+- 组合衍生需要公式引用指标存在共有时间维度；没有共有时间维度时 Web 会提示不可配置衍生指标。
+
+## 基础指标选择规则
+
+- 普通衍生可衍生自原子指标或复合指标；不能衍生自快捷引用指标。
+- `RECENT_X` 只能衍生自原子指标。
+- `COMPARATIVE` 和 `LAST` 需要基础指标有时间维度。
+- `COMPARATIVE` 可基于最近 N、累计、期末值、组合衍生继续衍生。
+- `BIZ_CONDITION` 可基于非业务限定的任意其它衍生指标。
+
+## 信息收集
+
+如果用户只说“帮我创建一个衍生指标”，先收集：
+
+1. 指标主题和保存目录。
+2. 衍生类型：同比/环比、最近 N、累计、期末值、业务限定、组合衍生。
+3. 普通衍生的基础指标，或组合衍生要引用的指标与公式。
+4. 时间粒度、时间偏移、是否包含当天、数值设置等衍生配置。
+5. 业务限定的筛选条件 `filter`。
+6. 数据格式：默认沿用/复制基础指标格式，或指定为数值、货币、百分比；如需指定，确认小数位、千分位、货币符号/前后缀、数量级单位、百分比是否除以 100。
+7. 指标名称、业务口径、是否保存并上线。
+8. 责任人和必填 `bizAttrs`。
+
+衍生指标常见做法：
+
+- 用户说“跟基础指标格式一样”时，先 `guancli metric get <baseMetricId> -f json` 读取基础指标 `format` 并复制。
+- 同比/环比增长率、转化率、占比类指标通常使用 `PERCENTAGE`。
+- 最近 N、累计、期末值通常复制基础指标 `format`；如果用户没有明确要求，也可以省略 `format` 使用默认。
+
+## JSON 模板：最近 7 天
+
+```json
+{
+  "projectId": "<metric_project_id>",
+  "subType": "DERIVED",
+  "name": "最近7天销售额",
+  "engName": "sales_amount_recent_7d",
+  "baseMetricId": "<atomic_metric_id>",
+  "deriveSetting": {
+    "deriveType": "ORDINARY",
+    "advType": "RECENT_X",
+    "advValue": {
+      "advType": "RECENT_X",
+      "granularity": "DAY",
+      "baseline": "DATE_RANGE_PARAM_RIGHT",
+      "baselineOffset": [6, 0],
+      "aggrType": "SUM"
+    }
+  },
+  "format": {
+    "formatType": "CURRENCY",
+    "decimalPlaces": 2,
+    "useThousandsSeparator": true,
+    "prefix": "￥",
+    "prefixUnit": null,
+    "showPrefixUnit": true,
+    "suffix": ""
+  },
+  "desc": "统计筛选日期结束日前最近7天的销售额。",
+  "parentDirId": "<metric_dir_id>",
+  "businessOwner": "<user_id>",
+  "publish": false
+}
+```
+
+## JSON 模板：组合衍生
+
+```json
+{
+  "projectId": "<metric_project_id>",
+  "subType": "DERIVED",
+  "name": "组合衍生客单价",
+  "deriveSetting": {
+    "deriveType": "COMPOSITE",
+    "formula": "[<recent_sales_metric_id>] / [<recent_order_metric_id>]"
+  },
+  "format": {
+    "formatType": "NUMBER",
+    "decimalPlaces": 2,
+    "useThousandsSeparator": true,
+    "prefixUnit": null,
+    "showPrefixUnit": true,
+    "prefix": "",
+    "suffix": ""
+  },
+  "desc": "使用多个衍生指标组合计算客单价。",
+  "parentDirId": "<metric_dir_id>",
+  "businessOwner": "<user_id>",
+  "publish": false
+}
+```
+
+## 创建步骤
+
+`guancli metric create` 当前是原子指标专用 endpoint；衍生指标创建使用 `guancli fetch`。
+
+1. 生成 `/tmp/derived_metric.json`。
+2. 本地/人工检查 JSON、基础指标或公式引用指标、时间维度、衍生配置、必填业务属性。
+3. 按 `metric-common-fields.md` 向用户摘要并确认。
+4. 用户确认后，不调用原子指标 `save-precheck`；衍生指标 Web 创建没有 save-precheck。
+5. 提交真实创建：
+
+```bash
+guancli fetch POST /api/metric-platform/metrics/derived-metrics --stdin < /tmp/derived_metric.json
+```
+
+6. 响应返回指标 ID 后回读确认。
+
+## 编辑步骤
+
+衍生指标没有原子指标的 save-precheck；主要校验基础指标、衍生配置或筛选变化是否影响下游指标/卡片。
+
+1. 读取当前详情：
+
+```bash
+guancli metric get <metric_id> -f json
+```
+
+2. 基于当前详情生成完整编辑 payload，例如 `/tmp/derived_metric_update.json`。至少包含 `projectId`、`subType`、`name`、`baseMetricId`（普通衍生）、`deriveSetting`、`desc`、`publish`。
+3. 如果修改了 `baseMetricId`、`deriveSetting` 或 `filter`，先调用影响校验：
+
+```bash
+guancli fetch POST /api/metric-platform/metrics/derived-metrics/<metric_id>/validate-update-impact --stdin < /tmp/derived_metric_update.json
+```
+
+4. 如果返回 `hasChanged=true` 且 `affectedMetrics` 或 `affectedCards` 非空，展示受影响指标和卡片，等待用户二次确认。
+5. 提交真实编辑：
+
+```bash
+guancli fetch POST /api/metric-platform/metrics/derived-metrics/<metric_id> --stdin < /tmp/derived_metric_update.json
+```
+
+6. 保存后回读确认。