@guandata/guancli 1.0.31 → 1.0.33

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## @guandata/guancli 1.0.33 - 2026-06-09
+
+- `ds search` 支持按数据集 ID 精确解析，修复按 ID 搜索时无法稳定命中资源的问题。
+- 资源详情查询补充相关解析兼容处理，提升数据集排查稳定性。
+
+## @guandata/guancli 1.0.32 - 2026-06-04
+
+- `metric` 增加指标创建、编辑和删除能力，并补充原子指标、派生指标、复合指标等配置参考。
+- `metric` 支持公共维度查询与配置辅助，便于按主题准备指标口径。
+- 数据集详情输出补充字段信息，页面详情会标记 backlog 卡片，资源诊断信息更完整。
+- 补充指标命令、数据集字段解析和页面渲染相关测试覆盖。
+
 ## @guandata/guancli 1.0.31 - 2026-06-03
 
 - `card preview` 会按卡片值格式设置输出展示值，支持小数位、百分比、千分位、前后缀等常见格式。

package/README.md

@@ -38,6 +38,18 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.33
+
+- `ds search` 支持按数据集 ID 精确解析，修复按 ID 搜索时无法稳定命中资源的问题。
+- 资源详情查询补充相关解析兼容处理，提升数据集排查稳定性。
+
+### @guandata/guancli 1.0.32
+
+- `metric` 增加指标创建、编辑和删除能力，并补充原子指标、派生指标、复合指标等配置参考。
+- `metric` 支持公共维度查询与配置辅助，便于按主题准备指标口径。
+- 数据集详情输出补充字段信息，页面详情会标记 backlog 卡片，资源诊断信息更完整。
+- 补充指标命令、数据集字段解析和页面渲染相关测试覆盖。
+
 ### @guandata/guancli 1.0.31
 
 - `card preview` 会按卡片值格式设置输出展示值，支持小数位、百分比、千分位、前后缀等常见格式。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.31",
+  "version": "1.0.33",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
   "bin": {
     "guancli": "bin/run.js"
@@ -35,7 +35,7 @@
     "node": ">=14"
   },
   "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
   }
 }

package/skills/guancli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: guancli
-description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据、指标 metric、指标树归因 metric_attribution、指标泛化查询参数，或给出 ETL ID、dsId、page ID、card ID、metric ID、metric tree ID 想看现有内容/查询数据时，主动使用这个 skill。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds""帮我查这个指标""生成指标泛化查询命令"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是只读分析（Form 表单填报例外，支持 CRUD）。修改 ETL 走 guanetl；新建/改 Card/Page 走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot；管理员级 SVC SQL / 动态码走 guanadmin。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 skill。
+description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据、指标 metric、公共维度 public dimension、指标树归因 metric_attribution、指标泛化查询参数，或给出 ETL ID、dsId、page ID、card ID、metric ID、metric tree ID、公共维度 ID 想看现有内容/查询数据时，主动使用这个 skill。用户要创建、新建、编辑、删除指标或公共维度，尤其是“创建原子指标”“创建复合指标”“创建衍生指标”“新增 metric”“基于数据集建指标”“用两个指标算一个指标”“做同比/环比/最近N天/累计/期末值指标”“新建公共维度”“把几个数据集字段关联成公共维度”时，也要使用这个 skill 并读取对应写操作指引。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds""帮我查这个指标""生成指标泛化查询命令""帮我创建一个原子指标""帮我创建一个复合指标""帮我创建一个同比指标""帮我创建一个公共维度"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是 BI 查询分析 + 表单填报 CRUD + 指标/公共维度写操作引导。修改 ETL 走 guanetl；新建/改 Card/Page 走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot；管理员级 SVC SQL / 动态码走 guanadmin。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 skill。
 compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancli.
 ---
 
@@ -15,6 +15,8 @@ compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancl
 - 用户需要对表单填报(Form)数据进行 CRUD 操作（查询/插入/更新/删除）。
 - 用户要直接用 ChatBI 主题做 L1 问数或 L2 洞察，而不是打开网页手工操作。
 - 用户要搜索指标、获取指标详情、查询指标数据、查看指标目录、执行指标树归因，或让你生成/解释指标泛化查询命令。
+- 用户要创建、新建、编辑或删除指标；当前指标写操作指引先覆盖原子指标、复合指标、衍生指标的创建和编辑前校验。
+- 用户要查询、新建、编辑、转移责任人或删除指标公共维度。
 
 如果用户只想生成页面 PNG 截图成品，不要用本 skill，改用 `guanvis screenshot`。页面截图不要再走 `guanexport`；移动端页面/卡片导出仍暂用 `guanexport` legacy 功能。
 
@@ -78,7 +80,7 @@ ChatBI 统一复用当前 profile 的 `base_url` 和 `uIdToken`。
 
 ## 能力边界
 
-guancli 是 BI 资源的**只读分析入口**（Form 表单填报例外）。写入类任务由专用 skill 负责：
+guancli 是 BI 资源的**查询分析入口**，并支持少量明确边界的写操作（Form 表单填报 CRUD、指标写操作引导）。其他写入类任务由专用 skill 负责：
 
 | 任务 | 应使用的工具 |
 |------|-------------|
@@ -102,12 +104,23 @@ guancli 是 BI 资源的**只读分析入口**（Form 表单填报例外）。
 
 - 指标与指标树全量命令：`references/metric-commands.md`
 - 指标泛化查询参数与示例：`references/metric-generic-query.md`
+- 指标新建 / 编辑 / 删除入口：`references/metric-mutation.md`
+- 指标通用写入配置：`references/metric-common-fields.md`
+- 指标表达式 / 计算公式支持范围：`references/metric-expression-rules.md`
+- 原子指标写入细节：`references/metric-atomic-mutation.md`
+- 复合指标写入细节：`references/metric-composite-mutation.md`
+- 衍生指标写入细节：`references/metric-derived-mutation.md`
+- 指标删除细节：`references/metric-delete-mutation.md`
+- 公共维度查询与写入：`references/metric-public-dimension.md`
 
 关键规则：
 
 - 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、`--filter`、排序、列筛选、输出格式等。
 - 只要传入 `--compare`、`--compare-value`、`--xtd`、`--last`、`--recent`、`--recent-base`、`--percentage`、`--percentage-dim`、`--rank-top`、`--rank-order`、`--rank-dim`、`--adv-calc-json` 任一参数，就进入指标泛化查询模式。
 - 泛化查询要求 BI 版本 `>= 8.2.1`；如需确认环境版本，先执行 `guancli server-version --profile <profile>`。
+- 当用户要创建或编辑原子指标、复合指标、衍生指标时，先读取 `references/metric-mutation.md` 判断类型，再读取 `references/metric-common-fields.md`，最后只读取对应类型文件：原子指标读 `references/metric-atomic-mutation.md`，复合指标读 `references/metric-composite-mutation.md`，衍生指标读 `references/metric-derived-mutation.md`。如果涉及原子指标表达式 `formulaField.fdFormula`、复合指标 `formula` 或组合衍生 `deriveSetting.formula`，必须同时读取 `references/metric-expression-rules.md`，按当前前后端支持的表达式形态生成。默认使用当前已登录环境，不询问 profile；按必填项、数据格式 `format` 和启用的指标业务属性配置逐步查询/确认，生成 JSON 文件并先做 dry-run/人工摘要。用户确认后仍需按 Web 同款保存前校验执行：原子指标上线前跑 save-precheck，编辑态跑 validate-update-impact；复合指标和衍生指标编辑态跑 validate-update-impact。校验通过或二次确认后才真实提交。
+- 当用户要删除指标时，读取 `references/metric-delete-mutation.md`。删除必须先跑 `validate-delete-impact`；如果存在下游指标或卡片，按 Web 行为阻断删除并展示影响资源；只有无影响且用户明确确认后，才执行真实删除。
+- 当用户要查询、新建、编辑或删除公共维度时，读取 `references/metric-public-dimension.md`。公共维度写入字段为 `name`、`businessOwner`、`relatedFields[{dsId,fdId}]`；关联字段必须同类型。删除前先跑 depend-check，若已有指标使用，需要提示会影响指标计算准确性，用户明确确认后才删除。
 
 ## 标准分析流程
 
@@ -126,12 +139,13 @@ guancli etl search                     # 搜索所有 ETL
 guancli etl search 关键词              # 按关键词搜索
 guancli etl search 关键词 -d <dir_id>  # 在指定目录中搜索
 guancli ds search 关键词               # 搜索数据集
-guancli ds search --id <dsId>          # 按数据集 ID 精确查找
+guancli ds search --limit 500 --offset 500  # 分页扫描数据集
+guancli ds search --id <dsId>          # 按数据集 ID 精确查找并返回单个数据集详情
 guancli ds search 关键词 --id <dsId>   # 按名称 + ID 组合查找
 guancli page search 关键词             # 搜索页面
 ```
 
-`ds search --id` 使用 `/api/dataset/search` 接口做精确匹配，支持 `--limit` 和 `--offset` 分页。
+`ds search` 默认返回前 500 条，环境数据集较多时用 `--limit` 和 `--offset` 分页扫描；`ds search --id` 会直接按数据集 ID 获取单个数据集详情，`--limit` 和 `--offset` 在 `--id` 模式下忽略。
 
 ### 3. 获取详情（含血缘）
 

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

@@ -0,0 +1,210 @@
+# 原子指标创建与编辑
+
+原子指标用于在单个数据集字段或数据集字段表达式上定义指标口径，例如“订购金额 = SUM(订单金额)”。
+
+## 触发场景
+
+- 用户说“创建原子指标”“基于数据集建指标”“用某个字段求和/计数/平均”。
+- 用户给出数据集、字段、聚合方式。
+- 用户要编辑一个 `subType=ATOMIC` 的指标。
+
+## 创建必填信息
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `projectId` | 主题 ID | 指标所属主题 |
+| `subType` | 指标类型 | 固定 `ATOMIC` |
+| `dsId` | 数据集 ID | 指标来源数据集 |
+| `name` | 指标名称 | 最长 50 |
+| `desc` | 业务口径 | 最长 1000 |
+| `applicableDims` | 适用维度 | 数据集字段 ID 数组，不能为空 |
+| `parentDirId` | 保存至/所属文件夹 | 指标目录 ID |
+| `businessOwner` | 责任人 | 用户 ID |
+| `publish` | 保存方式 | `true` 上线，`false` 草稿 |
+
+计算方式二选一：
+
+| 模式 | 必填字段 | 说明 |
+| --- | --- | --- |
+| 来源字段 + 聚合方式 | `fdId` + `aggrType` | 最常见；来源字段是数据集字段 ID |
+| 表达式 | `formulaField.fdFormula` | 例如 `SUM([fd_amount]) + SUM([fd_tax])`；不要同时传 `fdId/aggrType`；支持范围见 `metric-expression-rules.md` |
+
+## 原子专属可选字段
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `timeDim` | 时间维度 | 如果适用维度中包含时间字段，优先让用户指定一个时间维度字段 ID |
+| `sourceMetricId` | 来源指标 ID | 复制/快捷等高级场景才传 |
+
+通用可选字段见 `metric-common-fields.md`。
+
+## 聚合方式
+
+| `aggrType` | 中文 |
+| --- | --- |
+| `SUM` | 求和 |
+| `MIN` | 最小值 |
+| `MAX` | 最大值 |
+| `AVG` | 平均值 |
+| `CNT` | 计数 |
+| `CNT_DISTINCT` | 去重计数 |
+| `NUL` | 无处理 |
+
+字段判断：
+
+- 用户只给字段中文名时，先用 `guancli ds get <dsId> --brief` 查字段和 `fdId`。
+- 来源字段是维度字段时，常用计数、去重计数、最大值、最小值、无处理。
+- 来源字段是指标/数值字段时，常用求和、平均值、最大值、最小值、计数、去重计数。
+
+## 表达式限制
+
+当用户选择“使用表达式”时，先读取 `metric-expression-rules.md`。默认只生成当前前后端明确支持的聚合表达式形态：
+
+- `SUM([fd_id])`、`COUNT([fd_id])`
+- 多个聚合项加减：`SUM([fd_a]) - SUM([fd_b])`
+- 条件聚合：`SUM(CASE WHEN ... THEN ... ELSE ... END)`
+- 一个顶层比值：`SUM([fd_a]) / COUNT([fd_b])` 或 `(SUM([fd_a]) + SUM([fd_b])) / SUM([fd_c])`
+
+不要把 `AVG/MAX/MIN/FIRST/LAST/ANY_VALUE` 主动写进 `formulaField.fdFormula`；如果用户要平均值、最大值、最小值，优先走“来源字段 + `aggrType`”。表达式中字段必须写 `[fdId]`，不要提交字段中文名。
+
+## 信息收集
+
+如果用户只说“帮我创建一个原子指标”，先收集：
+
+1. 指标主题和保存目录。
+2. 来源数据集和来源字段。
+3. 计算方式：来源字段 + 聚合方式，还是表达式；如果是表达式，按 `metric-expression-rules.md` 校验支持形态。
+4. 指标名称、业务口径、适用维度、时间维度、是否保存并上线。
+5. 数据格式：默认、数值、货币、百分比；如需指定，确认小数位、千分位、货币符号/前后缀、数量级单位、百分比是否除以 100。
+6. 责任人是否用当前登录用户。
+7. 指标业务属性中启用且必填的 `bizAttrs`。
+
+## JSON 模板：字段聚合
+
+```json
+{
+  "projectId": "<metric_project_id>",
+  "subType": "ATOMIC",
+  "dsId": "<ds_id>",
+  "name": "订购金额",
+  "engName": "order_amount",
+  "fdId": "<source_fd_id>",
+  "aggrType": "SUM",
+  "applicableDims": ["<dim_fd_id_1>", "<dim_fd_id_2>"],
+  "timeDim": "<time_dim_fd_id>",
+  "format": {
+    "formatType": "CURRENCY",
+    "decimalPlaces": 2,
+    "useThousandsSeparator": true,
+    "prefix": "￥",
+    "prefixUnit": null,
+    "showPrefixUnit": true,
+    "suffix": ""
+  },
+  "desc": "统计订单明细中的订购金额总和，用于分析销售规模。",
+  "parentDirId": "<metric_dir_id>",
+  "businessOwner": "<user_id>",
+  "publish": false
+}
+```
+
+没有时间维度时删除 `timeDim`；没有英文名称时删除 `engName`；未指定数据格式时删除 `format` 或传 `{}`。
+
+## JSON 模板：表达式
+
+```json
+{
+  "projectId": "<metric_project_id>",
+  "subType": "ATOMIC",
+  "dsId": "<ds_id>",
+  "name": "含税销售额",
+  "formulaField": {
+    "fdFormula": "SUM([fd_amount]) + SUM([fd_tax])"
+  },
+  "applicableDims": ["<dim_fd_id_1>", "<dim_fd_id_2>"],
+  "format": {
+    "formatType": "NUMBER",
+    "decimalPlaces": 2,
+    "useThousandsSeparator": true,
+    "prefixUnit": null,
+    "showPrefixUnit": true,
+    "prefix": "",
+    "suffix": ""
+  },
+  "desc": "销售金额与税额之和。",
+  "parentDirId": "<metric_dir_id>",
+  "businessOwner": "<user_id>",
+  "publish": false
+}
+```
+
+## 创建步骤
+
+1. 生成 `/tmp/atomic_metric.json`。
+2. 先 dry-run：
+
+```bash
+guancli metric create --file /tmp/atomic_metric.json --dry-run
+```
+
+3. 按 `metric-common-fields.md` 向用户摘要并确认。
+4. 如果 `publish=true`，先跑 save-precheck：
+
+```bash
+guancli fetch POST /api/metric-platform/metrics/atomic-metrics/save-precheck --stdin < /tmp/atomic_metric.json
+```
+
+5. 如果返回 `conflicts` 且非空，展示冲突指标、冲突口径、适用维度差异，等待用户二次确认。
+6. 校验通过或二次确认后提交：
+
+```bash
+guancli metric create --file /tmp/atomic_metric.json -f json
+```
+
+7. 响应返回指标 ID 后回读：
+
+```bash
+guancli metric get <metric_id> --brief
+```
+
+## 编辑步骤
+
+编辑原子指标时复用 Web 顺序：必要时先口径冲突校验，再影响校验，最后提交。
+
+1. 读取当前详情：
+
+```bash
+guancli metric get <metric_id> -f json
+```
+
+2. 生成 patch 或完整 payload，先 dry-run：
+
+```bash
+guancli metric edit <metric_id> --file /tmp/atomic_metric_update.json --dry-run
+```
+
+3. 如果 `publish=true`，调用 save-precheck。编辑态请求体需要带 `metricId`：
+
+```bash
+guancli fetch POST /api/metric-platform/metrics/atomic-metrics/save-precheck --stdin < /tmp/atomic_metric_update_precheck.json
+```
+
+其中 precheck JSON 等于编辑 payload 加：
+
+```json
+{ "metricId": "<metric_id>" }
+```
+
+4. 如果存在 `conflicts`，展示后等待二次确认。
+5. 调用编辑影响校验：
+
+```bash
+guancli fetch POST /api/metric-platform/metrics/atomic-metrics/<metric_id>/validate-update-impact --stdin < /tmp/atomic_metric_update.json
+```
+
+6. 如果返回 `hasChanged=true` 且 `affectedMetrics` 或 `affectedCards` 非空，展示影响并等待二次确认。
+7. 提交真实编辑：
+
+```bash
+guancli metric edit <metric_id> --file /tmp/atomic_metric_update.json -f json
+```

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

@@ -34,6 +34,10 @@ guancli metric [command]
 | `get` | 获取指标详情 |
 | `query` | 查询指标数据 |
 | `tree` | 获取指标目录树 |
+| `create` | 新建原子指标（JSON 文件驱动） |
+| `edit` | 编辑原子指标（JSON patch / replace） |
+| `delete` | 删除指标（先执行删除影响校验） |
+| `public-dim` | 公共维度查询、新建、编辑、删除 |
 
 ### metric project
 
@@ -155,6 +159,96 @@ guancli metric tree --profile default -f json
 guancli metric tree --profile default --raw
 ```
 
+### metric create
+
+新建原子指标。写入流程先读 `metric-mutation.md` 和 `metric-common-fields.md`，原子字段、问询流程和 JSON 模板见 `metric-atomic-mutation.md`。复合指标和衍生指标创建当前使用 `guancli fetch POST /api/metric-platform/metrics/<type>-metrics --stdin`，分别见 `metric-composite-mutation.md` 和 `metric-derived-mutation.md`。
+
+```bash
+guancli metric create --profile default --file atomic_metric.json --dry-run
+guancli metric create --profile default --file atomic_metric.json -f json
+```
+
+专属参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--file string` | 指标请求体 JSON 文件 |
+| `--stdin` | 从 stdin 读取指标请求体 JSON |
+| `--set key=value` | 覆盖字段；支持点路径；可重复 |
+| `--dry-run` | 只输出请求方法、路径和请求体，不提交 |
+
+### metric edit
+
+编辑原子指标。默认先读取现有详情，再将 JSON 文件/stdin 和 `--set` 作为 patch 合并；`--replace` 直接提交输入 JSON。复合指标和衍生指标编辑当前使用 `guancli fetch POST /api/metric-platform/metrics/<type>-metrics/<metric_id> --stdin`，写入流程先读 `metric-mutation.md` 和 `metric-common-fields.md`，再按类型读取对应细节文档。
+
+```bash
+guancli metric edit <metric_id> --profile default --file patch.json --dry-run
+guancli metric edit <metric_id> --profile default --set name=新名称
+guancli metric edit <metric_id> --profile default --file full.json --replace
+```
+
+专属参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--file string` | 指标 patch/full JSON 文件 |
+| `--stdin` | 从 stdin 读取指标 patch/full JSON |
+| `--set key=value` | 覆盖字段；支持点路径；可重复 |
+| `--replace` | 直接提交输入 JSON，不先读取现有详情并合并 |
+| `--dry-run` | 只输出请求方法、路径和请求体，不提交 |
+
+### metric delete
+
+删除指标。命令与 Web 删除弹窗一致：先调用删除影响校验；如果存在下游指标或卡片，则阻断删除并输出影响列表。未传 `--confirm` 时只输出校验结果，不真实删除。详细流程见 `metric-delete-mutation.md`。
+
+```bash
+guancli metric delete <metric_id> --profile default
+guancli metric delete <metric_id> --profile default --confirm
+guancli metric delete <metric_id> --profile default --confirm --dry-run
+```
+
+专属参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--confirm` | 确认删除；未设置时只执行删除影响校验 |
+| `--dry-run` | 只输出将执行的删除校验和删除请求，不提交 |
+
+### metric public-dim
+
+公共维度相关操作。详细字段、问询流程和 JSON 模板见 `metric-public-dimension.md`。
+
+```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 public_dim.json --dry-run
+guancli metric public-dim edit <public_dim_id> --file 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
+```
+
+别名：
+
+```bash
+guancli metric public-dimension ...
+guancli metric pubdim ...
+```
+
+常用参数：
+
+| 子命令 | 参数 | 说明 |
+| --- | --- | --- |
+| `list` | `--limit` | 返回条数，默认 50 |
+| `list` | `--offset` | 分页偏移，默认 0 |
+| `list` | `--order-by` | `utimeDesc` 或 `utimeAsc` |
+| `create/edit` | `--file`、`--stdin`、`--set`、`--dry-run` | JSON 文件驱动写入 |
+| `edit` | `--replace` | 直接提交输入 JSON，不读取详情合并 |
+| `owner` | `--business-owner` | 新责任人用户 ID |
+| `delete` | `--confirm` | 确认删除；未设置时只执行依赖检查 |
+| `delete` | `--dry-run` | 输出依赖检查和删除请求，不提交 |
+
 ## metric_attribution
 
 入口：

package/skills/guancli/references/metric-common-fields.md

@@ -0,0 +1,166 @@
+# 指标通用配置
+
+本文记录原子指标、复合指标、衍生指标共享的写操作规则、通用字段和业务属性处理方式。处理任一指标创建/编辑任务时，都应先读取本文，再读取对应类型文档。
+
+## 环境与查询
+
+- 默认使用用户当前已登录环境，不询问“创建到哪个 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": ["用于经营分析月报"] }
+]
+```
+
+## 保存与确认
+
+- 先生成 JSON 文件并做 dry-run 或人工摘要，不直接提交。
+- 摘要至少包含：当前环境、主题、目录、指标类型、名称、核心计算方式、适用维度/时间维度、数据格式、业务属性、保存方式。
+- 用户确认后按类型执行 save-precheck 或 validate-update-impact。
+- 如果校验返回冲突或影响下游资源，展示冲突指标、受影响指标、受影响卡片，并等待二次确认。
+- 写入成功后回读 `guancli metric get <metric_id> --brief`。
+
+## 发布状态判断
+
+- 用户说“先别上线”“保存草稿”：`publish=false`。
+- 用户说“直接上线”“发布”：`publish=true`，提交前提醒会创建或更新在线指标。
+- 不要把 `publish=true` 自动当成用户已经确认所有冲突；冲突/影响校验仍需要单独二次确认。