@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guanmetric/references/metric-batch-status.md

@@ -0,0 +1,71 @@
+# 指标批量上线 / 下线
+
+## 命令
+
+```bash
+# 重复 --id
+guanmetric batch online --id metric_1 --id metric_2 --dry-run
+guanmetric batch offline --id metric_1 --id metric_2 --dry-run
+
+# JSON 文件；与 --id 互斥
+guanmetric batch online --file metric_ids.json --dry-run
+guanmetric batch offline --file metric_ids.json --dry-run
+```
+
+`metric_ids.json`：
+
+```json
+{"ids":["metric_1","metric_2"]}
+```
+
+输入顺序会保留，重复 ID 按首次出现去重。至少需要一个非空 ID。
+
+## 执行语义
+
+### 批量上线
+
+服务端没有批量上线端点。CLI 按输入顺序对每个指标执行：
+
+1. `GET /api/metric-platform/metrics/{id}?fromDraft=true` 读取草稿。
+2. 根据 `subType` 识别 `ATOMIC`、`COMPOSITE` 或 `DERIVED`，将详情映射为对应完整更新请求并设置 `publish=true`。
+3. 原子指标调用 `POST /api/metric-platform/metrics/atomic-metrics/{id}/save-precheck`。
+4. 调用对应类型的 `POST /api/metric-platform/metrics/{type}/{id}/validate-update-impact`。
+5. 调用对应类型的 `POST /api/metric-platform/metrics/{type}/{id}` 原地更新。
+
+快捷引用指标没有可编辑草稿，不支持上线。save-precheck 发现口径冲突、或影响校验发现下游资源时，该项默认返回 `blocked`，不提交更新；用户看过汇总并明确确认后，才可追加 `--confirm`。`--confirm` 只越过这两类客户端确认门禁，不绕过服务端权限、资源状态、审批或业务校验。
+
+### 批量下线
+
+CLI 按输入顺序逐项调用 `POST /api/metric-platform/metrics/{id}/offline`，以便为每个 ID 返回准确结果。BI 后端另有 `POST /api/metric-platform/metrics/batchOffline`，但其失败响应只聚合错误，无法提供稳定的 ID 级失败映射；两者的业务语义均为 best-effort，部分成功不回滚。
+
+### 完整性、顺序与一致性
+
+- completeness：每个去重后的输入 ID 恰好产生一个 `items` 结果。
+- ordering：串行执行并保持输入顺序；依赖指标需由调用者按基础指标到下游指标排序。
+- consistency：不是事务；某项失败不会回滚先前成功项，命令继续处理后续项。
+- failure：存在 `failed`，或上线存在 `blocked` 时，JSON 仍完整输出，但进程以非零状态退出。
+- approval：更新请求被服务端接受不代表最终已经上线；启用审批时应等待审批并回读状态。
+
+## JSON 机器契约
+
+新增契约版本为 `schemaVersion: "1.0"`，顶层固定字段：
+
+- `operation`: `online` 或 `offline`
+- `dryRun`: 是否仅规划
+- `requested`: 去重后的输入数
+- `succeeded` / `failed` / `blocked` / `planned`: 各状态计数
+- `items`: 与输入同序的逐项结果
+
+逐项 `status` 为 `planned`、`succeeded`、`failed` 或 `blocked`；`stage` 标识失败或阻断阶段。`message` 是人类诊断文案，不作为稳定错误码解析；`detail` 保留服务端预检或影响数据。新增后端字段不会改变顶层固定契约。
+
+## Domain and Contract / PAT
+
+权威路由来自 `guandata-core` 的 `MetricManagementNgController`：
+
+- `GET /metric-platform/metrics/{id}`：`METRIC_PLATFORM.READ`
+- `POST /metric-platform/metrics/{id}/offline`：`METRIC_PLATFORM.UPDATE`
+- `POST /metric-platform/metrics/{type}/{id}`：`METRIC_PLATFORM.UPDATE`
+- `POST /metric-platform/metrics/atomic-metrics/{id}/save-precheck`：`METRIC_PLATFORM.UPDATE`
+- `POST /metric-platform/metrics/{type}/{id}/validate-update-impact`：`METRIC_PLATFORM.UPDATE`
+
+客户端路径统一增加 `/api`，由代理剥离。PAT scope 目录 `modules/server/resources/cli_pat_scope.json` 中 `metric_platform` 默认包含 `read`、`update`，覆盖上述操作；真实环境仍需用同一用户的登录态与 PAT 分别验证有权、无权和资源不存在，以及写入后的回读结果。

package/skills-bundle/guanmetric/references/metric-business-dictionary-api-contract-examples.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": "1.0",
+  "source": {
+    "environment": "test153",
+    "capturedAt": "2026-09-21",
+    "authentication": "account-password",
+    "note": "由隔离临时业务字典真实 CRUD 请求采集后脱敏；PAT 未验证，示例 ID 不可用于调用。"
+  },
+  "createRequest": {"name": "销售额", "desc": "订单实付金额汇总", "dirId": "business_dir_root", "bizAttrs": []},
+  "createResponse": {"result": "ok", "response": "business_dictionary_example"},
+  "updateRequest": {"name": "含税销售额", "desc": "订单含税实付金额汇总", "dirId": "business_dir_root", "bizAttrs": []},
+  "updateResponse": {"result": "ok", "response": "business_dictionary_example"},
+  "detailResponse": {
+    "result": "ok",
+    "response": {
+      "id": "business_dictionary_example",
+      "domId": "example_domain",
+      "dirId": "business_dir_root",
+      "name": "含税销售额",
+      "desc": "订单含税实付金额汇总",
+      "bizAttrs": [],
+      "creator": "user_example",
+      "creatorName": "示例用户",
+      "ctime": "2026-09-21 14:04:11",
+      "utime": "2026-09-21 14:04:30",
+      "associatedMetrics": []
+    }
+  },
+  "listResponse": {
+    "result": "ok",
+    "response": {
+      "list": [{
+        "id": "business_dictionary_example",
+        "domId": "example_domain",
+        "dirId": "business_dir_root",
+        "name": "含税销售额",
+        "desc": "订单含税实付金额汇总",
+        "bizAttrs": [],
+        "creator": "user_example",
+        "creatorName": "示例用户",
+        "ctime": "2026-09-21 14:04:11",
+        "utime": "2026-09-21 14:04:30",
+        "associatedMetrics": []
+      }],
+      "total": 1
+    }
+  },
+  "treeResponse": {
+    "result": "ok",
+    "response": {"children": [{"dirId": "business_dir_root", "dirName": "根目录", "parentDirId": "", "children": []}]}
+  },
+  "deleteResponse": {"result": "ok", "response": true}
+}

package/skills-bundle/guanmetric/references/metric-business-dictionary-api-contract.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://guandata.example/schemas/metric-business-dictionary-api-contract.schema.json",
+  "title": "GuanData metric business dictionary API contracts",
+  "$defs": {
+    "nonEmptyString": {"type": "string", "minLength": 1},
+    "bizAttr": {"type": "object", "required": ["id", "values"], "properties": {"id": {"type": "string"}, "values": {"type": "array", "items": {"type": "string"}}}, "additionalProperties": true},
+    "writeRequest": {
+      "type": "object",
+      "required": ["name", "desc"],
+      "properties": {"name": {"$ref": "#/$defs/nonEmptyString"}, "desc": {"type": "string"}, "dirId": {"type": "string"}, "bizAttrs": {"type": "array", "items": {"$ref": "#/$defs/bizAttr"}}},
+      "additionalProperties": false
+    },
+    "mutationResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"$ref": "#/$defs/nonEmptyString"}}, "additionalProperties": true},
+    "dictionary": {
+      "type": "object",
+      "required": ["id", "domId", "name", "desc", "bizAttrs", "creator", "creatorName", "ctime", "utime", "associatedMetrics"],
+      "properties": {"id": {"type": "string"}, "domId": {"type": "string"}, "dirId": {"type": "string"}, "name": {"type": "string"}, "desc": {"type": "string"}, "bizAttrs": {"type": "array"}, "creator": {"type": "string"}, "creatorName": {"type": "string"}, "ctime": {"type": "string"}, "utime": {"type": "string"}, "associatedMetrics": {"type": "array"}},
+      "additionalProperties": true
+    },
+    "detailResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"$ref": "#/$defs/dictionary"}}, "additionalProperties": true},
+    "listResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"type": "object", "required": ["list", "total"], "properties": {"list": {"type": "array", "items": {"$ref": "#/$defs/dictionary"}}, "total": {"type": "number"}}, "additionalProperties": true}}, "additionalProperties": true},
+    "treeResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"type": "object", "required": ["children"], "properties": {"children": {"type": "array"}}, "additionalProperties": true}}, "additionalProperties": true},
+    "deleteResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"type": "boolean"}}, "additionalProperties": true}
+  }
+}

package/skills-bundle/guanmetric/references/metric-business-dictionary.md

@@ -0,0 +1,76 @@
+# 业务字典管理
+
+业务字典在后端接口和代码中也称 `BusinessMetric`，CLI 使用面向产品语义的命令名 `business-dict`，并兼容 `business-metric`、`biz-dict` 别名。
+
+构造或解析请求和响应前先读取 `metric-business-dictionary-api-contract-examples.json` 与 `metric-business-dictionary-api-contract.schema.json`。样例于 2026-09-21 在 test153 使用隔离临时业务字典和账号密码认证完成 create、detail/list、edit、delete 后脱敏；PAT 尚未验证。仓库测试会按 Schema 校验真实快照的必需字段和类型，同时允许后端新增可选字段。
+
+真实响应外层统一为 `{ "result": "ok", "response": ... }`：创建和编辑成功时 `response` 是业务字典 ID 字符串；详情包含 `id/domId/dirId/name/desc/bizAttrs/creator/creatorName/ctime/utime/associatedMetrics`；搜索返回 `response.list/total`；删除成功返回布尔值。详情是读模型，编辑只白名单提交 `name/desc/dirId/bizAttrs`。
+
+## 查询
+
+```bash
+guanmetric business-dict list
+guanmetric business-dict list 销售 --order-by utimeDesc
+guanmetric business-dict list --desc 收入 --dir-id <dir_id>
+guanmetric business-dict list --associated
+guanmetric business-dict list --associated=false
+guanmetric business-dict list --biz-attr region=华东,华南 --biz-attr channel=直营
+guanmetric business-dict list -f table
+guanmetric business-dict get <business_dict_id>
+guanmetric business-dict tree
+```
+
+搜索接口无分页，`list` 返回全部匹配项。支持的排序为 `nameAsc`、`nameDesc`、`ctimeAsc`、`ctimeDesc`、`utimeAsc`、`utimeDesc`。`--associated` 仅查已关联指标的字典，显式传 `--associated=false` 仅查未关联字典；不传时不按关联状态过滤。
+
+业务属性搜索中，文本类属性由服务端执行不区分大小写的包含匹配，枚举类属性执行精确匹配。禁用或不存在的属性由服务端返回业务错误；不可搜索的属性不会匹配结果，通常表现为空列表。
+
+## 新建
+
+请求体字段：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `name` | 是 | 名称；trim 后不能为空、同域唯一、最长 250 字符 |
+| `desc` | 是 | 业务口径 |
+| `dirId` | 否 | `BUSINESS_METRIC` 目录 ID；用 `business-dict tree` 查询 |
+| `bizAttrs` | 否 | `[{"id":"<attr_id>","values":["<value>"]}]` |
+
+```bash
+guanmetric business-dict create --file business_dict.json --dry-run
+guanmetric business-dict create --file business_dict.json
+```
+
+示例请求体：
+
+```json
+{
+  "name": "销售额",
+  "desc": "订单实付金额汇总，不含退款",
+  "dirId": "dir_xxx",
+  "bizAttrs": [
+    {"id": "attr_region", "values": ["华东"]}
+  ]
+}
+```
+
+## 编辑
+
+```bash
+guanmetric business-dict edit <business_dict_id> --set name=含税销售额 --dry-run
+guanmetric business-dict edit <business_dict_id> --file patch.json
+guanmetric business-dict edit <business_dict_id> --file full.json --replace
+```
+
+默认会先读取线上详情，只保留 `name`、`desc`、`dirId`、`bizAttrs` 四个可提交字段，再合并 patch 并原地更新。`--replace` 仅用于调用方已经提供完整请求体的场景。严禁通过删除后新建同名字典模拟编辑。
+
+## 删除
+
+```bash
+guanmetric business-dict delete <business_dict_id>
+guanmetric business-dict delete <business_dict_id> --confirm
+guanmetric business-dict delete <business_dict_id> --confirm --dry-run
+```
+
+第一次执行只读取详情，展示是否存在 `associatedMetric`，不提交删除。追加 `--confirm` 后才调用删除接口。
+
+删除采用逻辑删除。如果字典已关联指标，服务端会先清空正式指标与草稿中的 `bizMetricId`，并把字典的 `desc` 和 `bizAttrs` 留存在指标上，再删除字典。该行为不同于“有依赖即阻断删除”，所以确认提示必须明确说明解除关联和保留字段的影响。

package/skills-bundle/guanmetric/references/metric-common-fields.md

@@ -0,0 +1,246 @@
+# 指标通用配置
+
+本文记录原子指标、复合指标、衍生指标共享的写操作规则、通用字段和业务属性处理方式。处理任一指标创建/编辑任务时，都应先读取本文，再读取对应类型文档。
+
+## 环境与查询
+
+- 默认使用用户当前已登录环境，不询问“创建到哪个 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 配置引用动态参数时使用 |
+
+`guanmetric create/edit` 和指标定义类 `fetch POST` 会在提交前统一校验 `name`、`engName`、`desc`；标准 Excel 的原子、复合、衍生指标行使用相同规则。长度按 Web 表单的 JavaScript UTF-16 计数语义计算，因此 emoji 等非 BMP 字符计为 2，避免 CLI 校验通过但 Web 编辑页报超长。
+
+## 筛选条件 `filter`（WebFilterData）
+
+原子指标筛选、复合指标筛选、衍生指标业务限定和查询加速筛选共用同一套 `WebFilterData` 协议。合法节点只有：
+
+| `type` | `value` | 说明 |
+| --- | --- | --- |
+| `condition` | 字段筛选对象 | 规范化后必须包含 `dsId`、`fdId`、`name`、`fdType`、`metaType`、`filterType`；按筛选类型提供 `filterValue` |
+| `operator` | `and` 或 `or` | 只能出现在 `composition.value` 的两个条件节点之间 |
+| `composition` | WebFilterData 数组 | 按“条件、运算符、条件”交替排列；同一 composition 内运算符必须一致，可递归嵌套 |
+
+CLI 接受可无损转换的 `not: true` 作为兼容输入，但提交前会将其改写成明确的反向筛选类型，例如 `IN` 改为 `NI`、`CONTAINS` 改为 `NOT_CONTAINS`；组合节点按德摩根定律展开。Web 编辑器不会可靠读取节点上的 `not` 字段，因此规范化后的请求始终使用 `not: false`。遇到没有明确反向类型的条件（例如区间 `BT`）时，CLI 会拒绝提交，避免保存后语义与回显不一致。
+
+单条件示例：
+
+```json
+"filter": {
+  "type": "condition",
+  "not": false,
+  "value": {
+    "dsId": "ds_sales",
+    "fdId": "fd_region",
+    "name": "区域",
+    "fdType": "STRING",
+    "metaType": "DIM",
+    "filterType": "IN",
+    "filterValue": ["华东"]
+  }
+}
+```
+
+嵌套条件示例，表示“区域属于华东，并且（城市为空或城市包含杭州）”：
+
+```json
+"filter": {
+  "type": "composition",
+  "not": false,
+  "value": [
+    {
+      "type": "condition",
+      "not": false,
+      "value": { "dsId": "ds_sales", "fdId": "fd_region", "name": "区域", "fdType": "STRING", "metaType": "DIM", "filterType": "IN", "filterValue": ["华东"] }
+    },
+    { "type": "operator", "value": "and" },
+    {
+      "type": "composition",
+      "not": false,
+      "value": [
+        {
+          "type": "condition",
+          "not": false,
+          "value": { "dsId": "ds_sales", "fdId": "fd_city", "name": "城市", "fdType": "STRING", "metaType": "DIM", "filterType": "IS_NULL", "filterValue": [] }
+        },
+        { "type": "operator", "value": "or" },
+        {
+          "type": "condition",
+          "not": false,
+          "value": { "dsId": "ds_sales", "fdId": "fd_city", "name": "城市", "fdType": "STRING", "metaType": "DIM", "filterType": "CONTAINS", "filterValue": ["杭州"] }
+        }
+      ]
+    }
+  ]
+}
+```
+
+禁止使用下面这类其它系统的分组结构：
+
+```json
+{ "type": "group", "value": { "combineType": "AND", "conditions": [] } }
+```
+
+后端可能宽松接收这类 JSON，但 Web 指标编辑器只识别 `condition/operator/composition`，保存后会出现业务限定不回显。条件的 `fdId` 还必须存在于当前可筛选字段中：原子指标使用数据集字段；业务限定衍生指标使用基础指标 `applicableDims`。指标编辑和业务限定写入会优先从指标详情补齐缺少的字段元数据；查询加速条件必须自行提供完整元数据。
+
+兼容输入会在提交前规范化：`EMPTY -> IS_NULL`、`NOT_EMPTY -> NOT_NULL`、`LIKE -> CONTAINS`、`NOT_LIKE -> NOT_CONTAINS`。`IS_NULL/NOT_NULL` 必须携带空数组 `filterValue: []`；其它普通筛选类型必须携带非空数组。不要把这些兼容别名直接写进最终请求。
+
+## 数据格式 `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
+guanmetric 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 创建/编辑 payload 包含非空 `bizAttrs` 时，CLI 会先读取当前环境的 `GET /api/metric-attr-config`，再按属性 ID 对 `TEXT` / `TEXT_AREA` 执行上述 50/200 长度校验。因此，这类请求（包括 `--dry-run`）需要有效登录态；不包含业务属性时，原子指标 `create --dry-run` 仍可只做本地字段校验。
+
+示例：
+
+```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` 自动当成用户已经确认所有冲突；冲突/影响校验仍需要单独二次确认。

package/skills-bundle/guanmetric/references/metric-composite-mutation.md

@@ -0,0 +1,165 @@
+# 复合指标创建与编辑
+
+复合指标用于通过公式组合已有指标，例如“客单价 = 销售额 / 订单数”。
+
+创建/编辑请求、真实详情响应和读写映射见 `metric-api-contracts.md`；机器样例见
+`metric-api-contract-examples.json`。
+
+## 触发场景
+
+- 用户说“创建复合指标”“基于多个指标算一个指标”。
+- 用户描述的口径是已有指标之间的四则运算。
+- 用户给出数据集字段计算表达式后，确认希望先创建/复用基础原子指标，再创建复合指标。
+- 用户要编辑一个 `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` 核对名称、类型、状态和适用维度。
+- 如果用户只提供数据集字段级公式，先询问是否要创建复合指标。用户确认后，再识别公式里的基础度量，创建或复用基础原子指标，并把公式改写为 `[metricId]`。
+- 如果输入来自标准 Excel，字段级公式需要读取 `公式来源数据集ID` / `公式来源数据集名称` 和 `公式字段映射`。没有这些映射时，不要根据 `repr / total_buyer` 这类裸 token 猜测字段或指标；应要求用户补齐或确认。
+- 公式只能引用数值型原子指标或复合指标；不要引用衍生指标、快捷引用指标或当前正在编辑的指标本身。创建计划和提交前都要读取引用指标详情并核对 `subType`。
+- 公式支持 `+`、`-`、`*`、`/`、括号、数字和 `[指标ID]`；不要主动生成函数、窗口函数或 SQL 片段。
+- 公式中的 `[xxx]` 会被后端解析为上游指标 ID，并参与循环引用校验。
+- 如果用户用中文名描述公式，先转换成 ID 公式，再把“中文公式”和“ID 公式”都展示给用户确认。
+
+用户确认创建复合指标后的字段公式改写示例：
+
+| 用户口径 | 建模方式 |
+| --- | --- |
+| `SUM([销售额字段]) / COUNT([订单ID字段])` | 先建“销售额”“订单数”原子指标，再建复合指标 `[metric_sales] / [metric_order_count]` |
+| `SUM([归因销售额字段]) / SUM([广告花费字段])` | 先建“归因销售额”“广告花费”原子指标，再建复合指标 ROAS |
+| `SUM([点击量字段]) / SUM([曝光量字段])` | 先建“点击量”“曝光量”原子指标，再建复合指标 CTR |
+| `COUNT(CASE WHEN ... THEN 1 ELSE NULL END) / COUNT([ID字段])` | 优先把分子建为条件计数原子指标，再创建复合比率指标；业务限定衍生指标不能作为复合指标上游 |
+
+如果用户给出的公式依赖衍生指标，不要把它直接提交为复合指标：
+
+- 组合“最近 N、累计、期末值”等受支持衍生结果时，评估改建为组合衍生指标。
+- 表达“某个复合口径的同比/环比”时，通常先创建原子/复合基础口径，再基于该复合指标创建普通衍生指标。
+- 两种改写可能改变业务语义，例如“比率的同比”不等于“两个同比增长率相除”；创建计划必须展示改模方案并让用户确认。
+
+## 适用维度
+
+复合指标的适用维度来自公式中引用指标的共有维度：
+
+- `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`。
+
+## 创建步骤
+
+单个复合指标使用 `guanmetric composite create`；对话式批量创建或公式引用本批指标时，优先按 `metric-flow.md` 使用 `guanmetric flow`。
+
+1. 先输出指标创建计划，按 `metric-mutation.md` 的“指标创建计划”要求展示环境、主题、目录、将复用或新建的基础指标、复合公式、共有适用维度/时间维度、格式、业务属性和保存方式。
+2. 用户确认计划后，生成 `/tmp/composite_metric.json`。
+3. 本地/人工检查 JSON、公式引用指标、共有适用维度、必填业务属性；逐个读取引用指标详情，确认 `subType` 仅为 `ATOMIC` 或 `COMPOSITE`。`guanmetric composite create` 也会在提交前执行同一类型检查。
+4. 按 `metric-common-fields.md` 向用户摘要并确认。
+5. 用户确认后，不调用原子指标 `save-precheck`；复合指标 Web 创建没有 save-precheck。
+6. 提交真实创建：
+
+```bash
+guanmetric composite create --file /tmp/composite_metric.json --dry-run
+guanmetric composite create --file /tmp/composite_metric.json
+```
+
+7. 响应返回指标 ID 后回读：
+
+```bash
+guancli metric get <metric_id> --brief
+```
+
+## 编辑步骤
+
+复合指标没有原子指标的 save-precheck；主要校验公式或筛选变化是否影响下游指标/卡片。
+
+1. 准备只包含本次变更字段的 patch，例如 `/tmp/composite_metric_patch.json`；不要复制或回写详情读模型。
+2. 先 dry-run。命令会读取当前详情，按复合指标 Update DTO 白名单构造完整写模型并输出影响校验和更新步骤：
+
+```bash
+guanmetric composite edit <metric_id> --file /tmp/composite_metric_patch.json --dry-run
+```
+
+3. 提交真实编辑。命令自动调用 `validate-update-impact`；存在下游影响时会阻断并返回影响清单，用户确认后才追加 `--confirm`：
+
+```bash
+guanmetric composite edit <metric_id> --file /tmp/composite_metric_patch.json
+guanmetric composite edit <metric_id> --file /tmp/composite_metric_patch.json --confirm
+```
+
+4. 命令保存后自动回读，校验名称、口径、公式及维度等已提交字段；`useExpressionMetricCommonDims=true` 时适用维度由后端按引用指标共有维度重算，不做输入数组逐项相等判断。
+
+编辑命令内部读取后端详情，但只通过白名单生成写模型；`referencedMetrics`、`creator`、`statisticsData`、对象数组 `applicableDims`、对象 `timeDim` 等读模型字段绝不能原样提交。