@guandata/guanmetric 0.1.13 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## @guandata/guanmetric 0.1.14 - 2026-09-09
+
+- 统一指标 JSON 输入契约、标准模板和消费示例，指标定义可更稳定地在工具间传递。
+- 指标创建与编辑的类型、字段校验对齐服务端契约，非法组合会在提交前明确失败。
+
 ## @guandata/guanmetric 0.1.13 - 2026-09-03
 
 - 复合指标创建和编辑会校验公式上游类型，只允许原子指标或复合指标，阻止衍生指标、快捷引用指标和自身引用进入公式。

package/README.md

@@ -38,6 +38,11 @@ guanmetric metric-tree update-config <metric_tree_id> --file metric_tree_config.
 
 ## 版本更新
 
+### @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.14",
   "description": "观远 BI 指标写操作工具 - 指标创建编辑删除、指标目录、公共维度、Excel 标准化",
   "bin": {
     "guanmetric": "bin/run.js"

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-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-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 详情不承诺完整编辑字段。