@guandata/guanmetric 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## @guandata/guanmetric 0.1.15 - 2026-09-11
+
+- 新增 `batch online|offline` 指标批量上下线：可重复传入 `--id`，或用 `--file '{"ids":[...]}'` 一次提供，支持 `--dry-run` 先规划，逐项返回稳定结果。
+- 批量上线逐项读取草稿，原子指标执行 save-precheck、全部类型执行影响校验；预检发现口径冲突或下游影响时该项默认标记 `blocked`，需显式 `--confirm` 才提交。快捷引用指标不支持上线。
+- 批量输出 `schemaVersion: 1.0` 机器契约（`requested`/`succeeded`/`failed`/`blocked`/`planned` 与同序 `items`），存在失败或阻断时仍完整输出但非零退出；批量是 best-effort，单项失败不回滚已成功项，且上线请求成功不代表最终已上线，启用审批时需回读确认。
+
+## @guandata/guanmetric 0.1.14 - 2026-09-09
+
+- 统一指标 JSON 输入契约、标准模板和消费示例，指标定义可更稳定地在工具间传递。
+- 指标创建与编辑的类型、字段校验对齐服务端契约，非法组合会在提交前明确失败。
+
 ## @guandata/guanmetric 0.1.13 - 2026-09-03
 
 - 复合指标创建和编辑会校验公式上游类型，只允许原子指标或复合指标，阻止衍生指标、快捷引用指标和自身引用进入公式。

package/README.md

@@ -38,6 +38,17 @@ guanmetric metric-tree update-config <metric_tree_id> --file metric_tree_config.
 
 ## 版本更新
 
+### @guandata/guanmetric 0.1.15
+
+- 新增 `batch online|offline` 指标批量上下线，支持 `--id` 或 `--file` 输入并先 `--dry-run` 规划。
+- 批量上线逐项读取草稿、原子指标执行 save-precheck、全部类型执行影响校验；冲突或下游影响默认标记 `blocked`，需 `--confirm` 才提交。
+- 批量输出 `schemaVersion: 1.0` 机器契约，存在失败或阻断时非零退出；单项失败不回滚已成功项。
+
+### @guandata/guanmetric 0.1.14
+
+- 统一指标 JSON 输入契约、模板和消费示例，便于跨工具稳定传递指标定义。
+- 创建与编辑校验对齐服务端字段规则，非法组合会在提交前明确失败。
+
 ### @guandata/guanmetric 0.1.13
 
 - 复合指标公式会校验上游类型，阻止衍生指标、快捷引用指标和自身引用。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanmetric",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "观远 BI 指标写操作工具 - 指标创建编辑删除、指标目录、公共维度、Excel 标准化",
   "bin": {
     "guanmetric": "bin/run.js"
@@ -37,7 +37,6 @@
     "node": ">=14"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
+    "registry": "https://registry.npmjs.org/"
   }
 }

package/skills/guanmetric/SKILL.md

@@ -22,6 +22,8 @@ guanmetric dir-create 广告分析 --project-id <project_id> --dry-run
 guanmetric create --file atomic_metric.json --dry-run
 guanmetric edit <metric_id> --file patch.json --dry-run
 guanmetric delete <metric_id>
+guanmetric batch online --id <metric_id_1> --id <metric_id_2> --dry-run
+guanmetric batch offline --file metric_ids.json --dry-run
 guanmetric public-dim create --file public_dim.json --dry-run
 guanmetric business-dict list 销售 -f table
 guanmetric business-dict get <business_dict_id>
@@ -65,6 +67,8 @@ guanmetric fetch POST /api/metric-platform/metrics/composite-metrics --file comp
 查询加速写操作已封装为 `accelerate` 专用命令；查询加速列表查询使用 `guancli metric accelerate list <metric_id>`。查询加速筛选条件使用和指标定义一致的 `WebFilterData` 结构，可放在完整请求体的 `filter` 字段，也可通过 `--filter-json` 或 `--filter-file` 传入；合法节点仅为 `condition/operator/composition`，禁止使用 `group/combineType/conditions`。查询加速无法从指标适用维度自动补齐另一数据集的字段元数据，因此条件必须显式提供 `dsId/fdId/name/fdType/metaType`；清空筛选条件可传 `--filter-json null`。完整契约和嵌套示例见 `metric-common-fields.md`。
 指标树创建和修改已封装为 `metric-tree` 专用命令，优先使用专用命令，不要再用裸 `fetch` 直接调用指标树写接口。指标树父目录来自 `METRIC_TREE` 目录树，可用 `guancli metric_attribution tree -f json` 查询；不要把 `guancli metric tree` 返回的 `METRIC_PLATFORM` 指标目录 ID 当作指标树目录 ID。用户给出指标拆解公式时，按 `metric-tree-mutation.md` 解析成 `metricRelationTree`；遇到复合指标时读取指标详情中的 `formula`，按规则递归展开或在计划中标注不能无损展开的原因。
 
+指标批量上下线使用 `batch online|offline`，输入可重复传 `--id`，或用 `--file` 提供 `{"ids":[...]}`，两者互斥。必须先执行 `--dry-run`。批量上线支持原子、复合和衍生指标：逐项读取 `fromDraft=true` 草稿，原子指标执行 save-precheck，全部类型执行 validate-update-impact，再按类型原地更新；快捷引用指标不支持上线。预检冲突或下游影响默认将该项标记为 `blocked`，只有用户确认后才追加 `--confirm`。批量下线逐项调用权威单指标下线接口，以保留稳定的逐项成功/失败归因。两种操作都是 best-effort：单项失败后继续，已成功项不回滚，最终 JSON 使用 `schemaVersion=1.0` 并在存在 `failed`/`blocked` 时非零退出。服务端可能启用指标审批，因此“上线请求成功”不等同于最终已上线，最终状态必须回读确认。完整契约见 `metric-batch-status.md`。
+
 参考文档见本 skill 的 `references/` 目录：
 
 - `metric-excel-template.md`
@@ -76,3 +80,4 @@ guanmetric fetch POST /api/metric-platform/metrics/composite-metrics --file comp
 - `metric-public-dimension.md`
 - `metric-business-dictionary.md`
 - `metric-tree-mutation.md`
+- `metric-batch-status.md`

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

@@ -189,7 +189,7 @@ guancli metric get <metric_id> --brief
 1. 读取当前详情：
 
 ```bash
-guancli metric get <metric_id> -f json
+guancli metric get <metric_id> --raw
 ```
 
 2. 生成 patch 或完整 payload，先 dry-run：
@@ -223,3 +223,5 @@ guanmetric fetch POST /api/metric-platform/metrics/atomic-metrics/<metric_id>/va
 ```bash
 guanmetric edit <metric_id> --file /tmp/atomic_metric_update.json -f json
 ```
+
+编辑载荷和公式/格式复制使用 `--raw` 的后端详情，成功后从后端 `response` 读取字段；不能把后端响应当成 canonical envelope。普通机器发现使用 `-f json` 并从 `data` 取值，canonical 详情不承诺完整编辑字段。

package/skills/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/guanmetric/references/metric-common-fields.md

@@ -32,6 +32,8 @@
 | `filter` | 业务限定/筛选 | 可选或条件必填 | 业务限定衍生指标必填 |
 | `dynamicParameters` | 动态参数默认值 | 可选 | 表达式或最近 N 配置引用动态参数时使用 |
 
+`guanmetric create/edit` 和指标定义类 `fetch POST` 会在提交前统一校验 `name`、`engName`、`desc`；标准 Excel 的原子、复合、衍生指标行使用相同规则。长度按 Web 表单的 JavaScript UTF-16 计数语义计算，因此 emoji 等非 BMP 字符计为 2，避免 CLI 校验通过但 Web 编辑页报超长。
+
 ## 筛选条件 `filter`（WebFilterData）
 
 原子指标筛选、复合指标筛选、衍生指标业务限定和查询加速筛选共用同一套 `WebFilterData` 协议。合法节点只有：
@@ -215,6 +217,8 @@ guanmetric fetch GET /api/metric-attr-config
 - `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

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

@@ -145,7 +145,7 @@ guancli metric get <metric_id> --brief
 1. 读取当前详情：
 
 ```bash
-guancli metric get <metric_id> -f json
+guancli metric get <metric_id> --raw
 ```
 
 2. 基于当前详情生成完整编辑 payload，例如 `/tmp/composite_metric_update.json`。至少包含 `projectId`、`subType`、`name`、`formula`、`useExpressionMetricCommonDims`、`applicableDims`、`desc`、`publish`。
@@ -163,3 +163,5 @@ guanmetric fetch POST /api/metric-platform/metrics/composite-metrics/<metric_id>
 ```
 
 6. 保存后回读确认。
+
+编辑载荷和公式/格式复制使用 `--raw` 的后端详情，成功后从后端 `response` 读取字段；不能把后端响应当成 canonical envelope。普通机器发现使用 `-f json` 并从 `data` 取值，canonical 详情不承诺完整编辑字段。

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

@@ -342,7 +342,7 @@
 
 衍生指标常见做法：
 
-- 用户说“跟基础指标格式一样”时，先 `guancli metric get <baseMetricId> -f json` 读取基础指标 `format` 并复制。
+- 用户说“跟基础指标格式一样”时，先 `guancli metric get <baseMetricId> --raw` 读取基础指标 `format` 并复制。
 - 同比/环比增长率、转化率、占比类指标通常使用 `PERCENTAGE`。
 - 最近 N、累计、期末值通常复制基础指标 `format`；如果用户没有明确要求，也可以省略 `format` 使用默认。
 
@@ -433,7 +433,7 @@ guanmetric fetch POST /api/metric-platform/metrics/derived-metrics --stdin < /tm
 1. 读取当前详情：
 
 ```bash
-guancli metric get <metric_id> -f json
+guancli metric get <metric_id> --raw
 ```
 
 2. 基于当前详情生成完整编辑 payload，例如 `/tmp/derived_metric_update.json`。至少包含 `projectId`、`subType`、`name`、`baseMetricId`（普通衍生）、`deriveSetting`、`desc`、`publish`。
@@ -451,3 +451,5 @@ guanmetric fetch POST /api/metric-platform/metrics/derived-metrics/<metric_id> -
 ```
 
 6. 保存后回读确认。
+
+编辑载荷和公式/格式复制使用 `--raw` 的后端详情，成功后从后端 `response` 读取字段；不能把后端响应当成 canonical envelope。普通机器发现使用 `-f json` 并从 `data` 取值，canonical 详情不承诺完整编辑字段。

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

@@ -140,9 +140,12 @@ guanmetric template normalize <input.xlsx> --out <standard.xlsx> --report <repor
 | 衍生创建 | Web 创建无 save-precheck；提交前做人工摘要和本地 JSON/引用检查 |
 | 衍生编辑 | 修改 `baseMetricId`、`deriveSetting` 或 `filter` 时跑 `validate-update-impact` |
 | 删除指标 | 先 `GET /api/metric-platform/metrics/{id}/validate-delete-impact`；有下游资源时阻断删除 |
+| 批量上线 | 逐项读取草稿；原子执行 save-precheck；全部类型执行 validate-update-impact；冲突/影响需 `--confirm` |
+| 批量下线 | 逐项调用 `POST /api/metric-platform/metrics/{id}/offline`；部分失败不回滚 |
 
 ## 命令能力边界
 
 - `guanmetric create` 和 `guanmetric edit` 当前是原子指标专用命令。
 - 复合指标和衍生指标创建/编辑使用 `guanmetric fetch POST ... --stdin < payload.json`。
 - 指标删除使用 `guanmetric delete <metric_id>`；默认只做影响校验，追加 `--confirm` 才会在无下游依赖时提交删除。
+- 指标批量上下线使用 `guanmetric batch online|offline`；详细输入、输出和失败语义见 `metric-batch-status.md`。

package/skills/guanmetric/references/metric-tree-mutation.md

@@ -114,7 +114,7 @@ guancli auth status
 
 - 有 ID：用 `guancli metric get <metric_id> --brief` 或 `-f json` 回读确认。
 - 只有名称：用 `guancli metric search <keyword> -f json` 搜索；多候选必须让用户指定 ID。
-- 需要配置维度、时间对比或复合指标展开时，必须用 `guancli metric get <metric_id> -f json` 读取完整详情。
+- 需要配置维度、时间对比或复合指标展开时，必须用 `guancli metric get <metric_id> --raw` 读取完整详情。
 
 指标树父目录来自 `METRIC_TREE` 目录体系：
 
@@ -265,7 +265,7 @@ guancli metric_attribution tree -f json
 
 处理规则：
 
-1. 对每个参与指标执行 `guancli metric get <metric_id> -f json`。
+1. 对每个参与指标执行 `guancli metric get <metric_id> --raw`。
 2. 如果 `subType=COMPOSITE`，读取其 `formula` 字段。
 3. 从 `formula` 中提取 `[metricId]` 引用和 `+ - * /` 运算符。
 4. 把复合指标作为节点保留，再把公式引用指标作为它的子节点。
@@ -468,3 +468,5 @@ guancli metric_attribution query <metric_tree_id> --target index
 - `metric-tree init-config <root_metric_id>`：按前端初始化逻辑生成默认 config。
 - `metric-tree validate-config`：离线校验维度、交叉维度、指标关系树和时间对比开关。
 - `metric-tree plan`：从简化 DSL 或用户公式生成 create/config JSON。
+
+编辑载荷和公式/格式复制使用 `--raw` 的后端详情，成功后从后端 `response` 读取字段；不能把后端响应当成 canonical envelope。普通机器发现使用 `-f json` 并从 `data` 取值，canonical 详情不承诺完整编辑字段。