@guandata/guancli 1.0.31 → 1.0.32

package/skills/guancli/references/metric-expression-rules.md

@@ -0,0 +1,143 @@
+# 指标表达式 / 计算公式支持范围
+
+本文件用于创建或编辑指标时约束 AI 生成公式的形态，覆盖：
+
+- 原子指标 `formulaField.fdFormula`
+- 复合指标 `formula`
+- 衍生指标选择“组合衍生”时的 `deriveSetting.formula`
+
+## 总体原则
+
+- 用户给出中文字段名或指标名时，最终 payload 必须替换成 ID 引用：数据集字段写 `[fdId]`，指标写 `[metricId]`。
+- 优先生成 Web 编辑器明确支持的简单表达式；复杂函数、嵌套函数、窗口函数、自定义 SQL 函数不要主动生成。
+- 公式中使用英文半角符号：`+ - * / ( ) [ ]`。
+- 不要把指标中文名直接提交到后端；中文名只用于向用户展示“可读公式”。
+- 条件表达式优先使用 `CASE WHEN ... THEN ... ELSE ... END`。虽然底层数据集公式解析能识别部分 `IF(condition, trueValue, falseValue)` 写法，但 AI 生成指标表达式时默认转成 `CASE WHEN`，兼容性更稳定。
+- 如果用户坚持使用本文件未列出的公式形态，先提示可能被前端/后端校验拦截，建议用户在 Web 公式编辑器中校验或先保存草稿验证。
+
+## 原子指标表达式 `formulaField.fdFormula`
+
+原子指标选择“使用表达式”时，表达式走数据集公式编辑器和后端数据集派生字段校验。后端会把公式当成数据集计算字段检查，并要求最终字段是聚合表达式；没有聚合函数会报“原子指标表达式必须包含聚合函数”。
+
+### 推荐支持形态
+
+| 形态 | 示例 | 说明 |
+| --- | --- | --- |
+| 单聚合 | `SUM([fd_amount])` | 最常用 |
+| 计数 | `COUNT([fd_order_id])` | 计数类表达式 |
+| 聚合项加减 | `SUM([fd_amount]) - SUM([fd_refund])` | 多个聚合结果加减 |
+| 聚合内部加减 | `SUM([fd_price] + [fd_tax] - [fd_discount])` | 字段先加减再聚合 |
+| 条件聚合 | `SUM(CASE WHEN [fd_status] = 'paid' THEN [fd_amount] ELSE 0 END)` | 支持 `CASE WHEN`、比较、`AND/OR/NOT` |
+| 条件计数 | `COUNT(CASE WHEN [fd_status] = 'paid' THEN 1 ELSE 0 END)` | 条件计数 |
+| 顶层比值 | `SUM([fd_amount]) / COUNT([fd_order_id])` | 只建议一个顶层 `/` |
+| 分子/分母加减后相除 | `(SUM([fd_a]) + SUM([fd_b])) / (SUM([fd_c]) + COUNT([fd_d]))` | 分子、分母内部仅用加减和推荐聚合 |
+| 动态参数 | `SUM(CASE WHEN [fd_amount] > [DYNAMIC_PARAMS.N] THEN [fd_amount] ELSE 0 END)` | 同时在顶层 `dynamicParameters` 写默认值 |
+
+### 避免生成
+
+- 无聚合表达式：`[fd_amount] + [fd_tax]`。
+- 乘法：`SUM([fd_price] * [fd_qty])`、`SUM([fd_a]) * SUM([fd_b])`。
+- 非顶层除法：`SUM([fd_a]) + SUM([fd_b]) / SUM([fd_c])`。
+- 多重除法：`SUM([fd_a]) / SUM([fd_b]) / SUM([fd_c])`。
+- `AVG/MAX/MIN/FIRST/LAST/ANY_VALUE` 等聚合函数表达式；如果用户要平均值、最大值、最小值，优先走“来源字段 + `aggrType=AVG/MAX/MIN`”。
+- 窗口函数、子查询、跨数据集字段、字段中文名直接入参。
+
+## `IF` 语法转 `CASE WHEN`
+
+当用户用自然语言或公式写出 `if` / `IF` 条件语法时，不要照抄 `IF(...)` 到指标 payload，默认转换为 `CASE WHEN`：
+
+| 用户写法 | 生成写法 |
+| --- | --- |
+| `IF(condition, trueValue, falseValue)` | `CASE WHEN condition THEN trueValue ELSE falseValue END` |
+| `SUM(IF([fd_status] = 'paid', [fd_amount], 0))` | `SUM(CASE WHEN [fd_status] = 'paid' THEN [fd_amount] ELSE 0 END)` |
+| `COUNT(IF([fd_status] = 'paid', 1, NULL))` | `COUNT(CASE WHEN [fd_status] = 'paid' THEN 1 ELSE NULL END)` |
+| `IF(SUM([fd_a]) > 0, SUM([fd_b]), 0)` | `CASE WHEN SUM([fd_a]) > 0 THEN SUM([fd_b]) ELSE 0 END` |
+
+嵌套 `IF` 转多分支 `CASE WHEN`：
+
+```text
+IF(c1, v1, IF(c2, v2, v3))
+```
+
+转换为：
+
+```text
+CASE
+  WHEN c1 THEN v1
+  WHEN c2 THEN v2
+  ELSE v3
+END
+```
+
+转换注意事项：
+
+- 必须保留原条件里的比较、`AND/OR/NOT`、字符串字面量和动态参数。
+- 三个参数分别是条件、命中值、未命中值；遇到逗号嵌套在括号或字符串中时，不要错误拆分。
+- 原子指标表达式仍必须满足聚合要求：最终表达式要包含 `SUM` 或 `COUNT` 等聚合上下文。
+- 如果用户给出的 `IF` 结构无法可靠拆分，先向用户确认条件、命中值和未命中值，再生成 `CASE WHEN`。
+
+## 复合指标公式 `formula`
+
+复合指标公式组合已有指标。Web 公式编辑器会把 `[指标名称]` 转成 `[metricId]`；CLI 生成 payload 时必须直接使用 `[metricId]`。
+
+### 推荐支持形态
+
+| 形态 | 示例 |
+| --- | --- |
+| 单指标引用 | `[metric_sales]` |
+| 加减乘除 | `[metric_sales] / [metric_orders]` |
+| 数字常量 | `[metric_sales] * 2 + 100` |
+| 括号分组 | `([metric_sales] - [metric_refund]) / [metric_orders]` |
+
+### 引用限制
+
+- 可引用已上线且当前用户可使用的原子指标、复合指标。
+- 不要引用当前正在编辑的指标本身。
+- 不要引用快捷引用指标（有 `linkMetricId` 的指标）。
+- 公式中的 `[xxx]` 会被后端识别为上游指标 ID，并参与循环引用校验。
+- 复合指标适用维度必须来自公式中引用指标的共有维度；没有共有维度时会报错。
+
+### 避免生成
+
+- 指标中文名入参：`[销售额] / [订单数]` 只能用于展示，payload 必须替换成 `[metricId] / [metricId]`。
+- 数据集字段引用：`[fd_amount]`。
+- 复杂函数、窗口函数、SQL 片段、字符串拼接。
+
+## 衍生指标：组合衍生 `deriveSetting.formula`
+
+组合衍生公式也是指标公式，但引用范围比复合指标更窄。
+
+### 推荐支持形态
+
+同复合指标：`+ - * / ( )`、数字常量、`[metricId]`。
+
+示例：
+
+```text
+[metric_recent_sales] / [metric_recent_orders]
+([metric_xtd_sales] - [metric_xtd_refund]) / [metric_last_inventory]
+```
+
+### 引用限制
+
+- 可引用原子指标。
+- 可引用普通衍生指标中 `RECENT_X`（最近 N）、`XTD`（累计计算）、`LAST`（期末值）。
+- 不要引用组合衍生指标。
+- 不要引用复合指标、快捷引用指标或当前正在编辑的指标。
+- 公式引用的指标必须存在共有时间维度；没有共有时间维度时 Web 会提示“源指标没有共有时间维度，不可配置衍生指标”。
+
+### 避免生成
+
+- 任意数据集字段引用。
+- 函数、窗口函数、SQL 片段。
+- 引用同比/环比、业务限定、组合衍生等不在允许范围内的衍生指标。
+
+## 后端公式合法性校验的安全子集
+
+部分场景（例如指标树归因的贡献分析）会使用更严格的后端公式合法性校验。为了让新建指标后尽量兼容这些场景，AI 默认按以下安全子集生成：
+
+- 原子表达式：`SUM`、`COUNT`、加减、条件表达式；如果有除法，整个表达式必须是一个顶层 `分子 / 分母`，且分子分母分别满足前述规则。
+- 复合指标：最终展开到原子指标后，也应能落到上述安全子集。
+- 衍生组合：优先只做指标间的四则运算；需要参与归因时，优先避免乘法和非顶层除法。
+
+如果用户明确不需要归因/贡献分析，可以按 Web 创建表单的基础限制放宽，但仍应先保存草稿或 dry-run/校验。

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

@@ -0,0 +1,67 @@
+# 指标新建 / 编辑 / 删除指引
+
+本文是指标写操作的入口索引，用于指导 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 天/本月累计/华东限定”：通常是衍生指标。
+
+## 总体流程
+
+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. 生成 JSON 文件，先做 dry-run 或人工摘要，向用户确认当前环境、目标目录、指标口径、计算配置、业务属性和保存方式。
+5. 用户确认后，仍需按 Web 同款交互执行保存前校验或影响校验。
+6. 校验通过、无对应校验，或用户对冲突/影响完成二次确认后，才提交真实创建或编辑。
+7. 写入成功后用 `guancli metric get <metric_id> --brief` 回读确认。
+
+不要把“dry-run 成功”“precheck 通过”或“影响校验无阻塞”描述成指标已经创建/编辑成功。
+
+## 校验入口速查
+
+| 操作 | 校验规则 |
+| --- | --- |
+| 原子创建，`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` 才会在无下游依赖时提交删除。

package/skills/guancli/references/metric-public-dimension.md

@@ -0,0 +1,151 @@
+# 公共维度查询与写入
+
+公共维度用于把多个数据集中的同一业务维度字段关联起来，让跨指标、跨数据集的适用维度能够按同一逻辑维度对齐。
+
+## 命令入口
+
+```bash
+guancli metric public-dim list [keyword]
+guancli metric public-dim get <public_dim_id>
+guancli metric public-dim fd-map <ds_id>
+guancli metric public-dim create --file /tmp/public_dim.json --dry-run
+guancli metric public-dim edit <public_dim_id> --file /tmp/public_dim_patch.json
+guancli metric public-dim owner <public_dim_id> --business-owner <user_id>
+guancli metric public-dim delete <public_dim_id>
+guancli metric public-dim delete <public_dim_id> --confirm
+```
+
+`public-dim` 也可写成 `public-dimension` 或 `pubdim`。
+
+## 通用原则
+
+- 默认使用当前已登录环境，不询问 profile；只有用户明确指定其它环境时才追加 `--profile <profile>`。
+- 用户只给公共维度名称时，先用 `guancli metric public-dim list <keyword>` 搜索候选。
+- 用户只给数据集/字段中文名时，先用 `guancli ds search`、`guancli ds get <dsId> --brief` 查询 `dsId` 和 `fdId`。
+- 新建/编辑前先生成 JSON，并用 `--dry-run` 或人工摘要让用户确认。
+- 公共维度删除是不可恢复操作，必须先做依赖检查，再让用户确认。
+
+## 查询
+
+列表：
+
+```bash
+guancli metric public-dim list 日期 --limit 50 --offset 0 --order-by utimeDesc
+```
+
+详情：
+
+```bash
+guancli metric public-dim get <public_dim_id>
+```
+
+查询某个数据集字段是否已被公共维度占用：
+
+```bash
+guancli metric public-dim fd-map <ds_id>
+```
+
+`fd-map` 返回 `fdId -> { id, name }`，用于新建/编辑公共维度时避免选择已被其它公共维度使用的字段。
+
+## 新建/编辑入参
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `name` | 公共维度名称 | 必填；最长 50；仅支持中文、字母、数字、下划线 |
+| `businessOwner` | 责任人 ID | 必填；公共维度业务侧解释对象 |
+| `relatedFields` | 关联的数据集字段 | 必填，至少一个；元素为 `{ "dsId": "...", "fdId": "..." }` |
+
+`relatedFields` 规则：
+
+- 每个元素都必须同时有 `dsId` 和 `fdId`。
+- 同一个公共维度里的字段类型必须兼容/相同；后端会校验，不同类型会失败。
+- Web 会禁用已被其它公共维度使用的字段；CLI 创建前应对每个涉及的数据集调用 `fd-map`，发现字段已归属其它公共维度时先向用户说明并重新选择。
+- 同一个公共维度内不要重复选择同一数据集的同一字段。
+
+## JSON 模板
+
+```json
+{
+  "name": "日期",
+  "businessOwner": "<user_id>",
+  "relatedFields": [
+    { "dsId": "<ds_id_1>", "fdId": "<date_fd_id_1>" },
+    { "dsId": "<ds_id_2>", "fdId": "<date_fd_id_2>" }
+  ]
+}
+```
+
+## 新建流程
+
+1. 收集公共维度名称、责任人、要关联的数据集字段。
+2. 对每个数据集运行 `guancli ds get <dsId> --brief` 核对字段存在和字段类型。
+3. 对每个数据集运行 `guancli metric public-dim fd-map <dsId>`，确认字段未被其它公共维度使用。
+4. 生成 JSON 文件并 dry-run：
+
+```bash
+guancli metric public-dim create --file /tmp/public_dim.json --dry-run
+```
+
+5. 向用户摘要名称、责任人、关联字段、字段类型；用户确认后提交：
+
+```bash
+guancli metric public-dim create --file /tmp/public_dim.json
+```
+
+## 编辑流程
+
+1. 先获取详情：
+
+```bash
+guancli metric public-dim get <public_dim_id>
+```
+
+2. 基于现有详情生成 patch 或完整 JSON。默认 `edit` 会把详情转换成提交 payload 后合并 patch。
+3. 如果修改关联字段，重新检查字段类型和 `fd-map` 占用。
+4. dry-run：
+
+```bash
+guancli metric public-dim edit <public_dim_id> --file /tmp/public_dim_patch.json --dry-run
+```
+
+5. 用户确认后提交：
+
+```bash
+guancli metric public-dim edit <public_dim_id> --file /tmp/public_dim_patch.json
+```
+
+只转移责任人时可用：
+
+```bash
+guancli metric public-dim owner <public_dim_id> --business-owner <user_id>
+```
+
+## 删除流程
+
+删除前先执行依赖检查：
+
+```bash
+guancli metric public-dim delete <public_dim_id>
+```
+
+该命令会调用：
+
+```text
+GET /api/metric-platform/public-dimensions/depend-check/<public_dim_id>
+```
+
+如果返回 `isDepended=true`，说明已有指标在使用该公共维度。Web 的行为是提示“删除后将影响有公共维度的指标计算准确性”，用户确认后仍允许删除。
+
+用户明确确认后执行：
+
+```bash
+guancli metric public-dim delete <public_dim_id> --confirm
+```
+
+提交删除接口：
+
+```text
+POST /api/metric-platform/public-dimensions/delete/<public_dim_id>
+```
+
+不要把“依赖检查通过/已提示风险”描述成已经删除成功；只有 delete 接口成功返回后才算删除完成。