@guandata/guanmetric 0.1.18 → 0.1.20

package/skills/guanmetric/references/metric-public-dimension-api-contract.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://guandata.example/schemas/metric-public-dimension-api-contract.schema.json",
+  "title": "GuanData metric public dimension API contracts",
+  "$defs": {
+    "nonEmptyString": {"type": "string", "minLength": 1},
+    "user": {
+      "type": "object",
+      "required": ["uId", "name", "isDel"],
+      "properties": {"uId": {"$ref": "#/$defs/nonEmptyString"}, "name": {"type": "string"}, "email": {"type": "string"}, "avatar": {"type": "string"}, "isDel": {"type": "boolean"}},
+      "additionalProperties": true
+    },
+    "relatedFieldWrite": {
+      "type": "object",
+      "required": ["dsId", "fdId"],
+      "properties": {"dsId": {"$ref": "#/$defs/nonEmptyString"}, "fdId": {"$ref": "#/$defs/nonEmptyString"}},
+      "additionalProperties": false
+    },
+    "writeRequest": {
+      "type": "object",
+      "required": ["name", "businessOwner", "relatedFields"],
+      "properties": {"name": {"$ref": "#/$defs/nonEmptyString"}, "businessOwner": {"$ref": "#/$defs/nonEmptyString"}, "relatedFields": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/relatedFieldWrite"}}},
+      "additionalProperties": false
+    },
+    "mutationResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {"result": {"const": "ok"}, "response": {"type": "object", "required": ["id"], "properties": {"id": {"$ref": "#/$defs/nonEmptyString"}}, "additionalProperties": true}},
+      "additionalProperties": true
+    },
+    "detailResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {"result": {"const": "ok"}, "response": {"type": "object", "required": ["id", "domId", "name", "businessOwner", "relatedFields", "creator", "ctime", "utime"], "properties": {"id": {"type": "string"}, "domId": {"type": "string"}, "name": {"type": "string"}, "businessOwner": {"$ref": "#/$defs/user"}, "relatedFields": {"type": "array"}, "creator": {"$ref": "#/$defs/user"}, "ctime": {"type": "string"}, "utime": {"type": "string"}}, "additionalProperties": true}},
+      "additionalProperties": true
+    },
+    "listResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {"result": {"const": "ok"}, "response": {"type": "object", "required": ["contents", "count", "limit", "offset"], "properties": {"contents": {"type": "array"}, "count": {"type": "number"}, "limit": {"type": "number"}, "offset": {"type": "number"}}, "additionalProperties": true}},
+      "additionalProperties": true
+    },
+    "fieldMapResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"type": "object"}}, "additionalProperties": true},
+    "dependCheckResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"type": "object", "required": ["isDepended"], "properties": {"isDepended": {"type": "boolean"}}, "additionalProperties": true}}, "additionalProperties": true},
+    "deleteResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"type": "string"}}, "additionalProperties": true}
+  }
+}

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

@@ -2,6 +2,8 @@
 
 公共维度用于把多个数据集中的同一业务维度字段关联起来，让跨指标、跨数据集的适用维度能够按同一逻辑维度对齐。
 
+构造或解析请求和响应前先读取 `metric-public-dimension-api-contract-examples.json` 与 `metric-public-dimension-api-contract.schema.json`。样例于 2026-09-21 在 test153 使用隔离临时公共维度和账号密码认证完成 create、detail/list、edit、depend-check、delete 后脱敏；PAT 尚未验证。仓库测试会按 Schema 校验这些真实快照的必需字段和类型，后端新增可选字段不会误报，但刷新快照时若 CLI 依赖字段缺失或变型会失败。
+
 ## 命令入口
 
 ```bash
@@ -47,6 +49,8 @@ guanmetric public-dim fd-map <ds_id>
 
 `fd-map` 返回 `fdId -> { id, name }`，用于新建/编辑公共维度时避免选择已被其它公共维度使用的字段。
 
+真实返回的外层统一为 `{ "result": "ok", "response": ... }`：列表 `response` 包含 `contents/count/limit/offset`；详情中的 `businessOwner/creator` 是用户对象，`relatedFields` 是 `{dsInfo,fdInfo}` 数组；创建和编辑成功的 `response` 包含 `id`；依赖检查使用 `response.isDepended`；删除成功的 `response` 是 `"delete success."`。详情是读模型，不能把 `dsInfo/fdInfo`、用户对象、`domId/creator/ctime/utime` 原样回写。
+
 ## 新建/编辑入参
 
 | 字段 | 中文 | 说明 |

package/skills/guanmetric/references/metric-tree-api-contract-examples.json

@@ -0,0 +1,277 @@
+{
+  "schemaVersion": "1.0",
+  "source": {
+    "environment": "test71",
+    "capturedAt": "2026-09-21",
+    "authentication": "account-password",
+    "note": "由隔离临时指标树真实请求采集后脱敏；示例 ID、名称和日期不可直接用于调用。PAT 未验证。"
+  },
+  "createRequest": {
+    "metricId": "metric_root_example",
+    "name": "销售额指标树",
+    "parentDirId": "metric_tree_dir_root",
+    "config": {
+      "timeComparisonSetting": {
+        "advType": "COMPARATIVE",
+        "advValue": {
+          "advType": "COMPARATIVE",
+          "dateFdId": "fd_order_date",
+          "valueType": "RAWDATA",
+          "offset": 1,
+          "offsetType": "DAY",
+          "granularity": "DAY",
+          "window": { "period": ["2026-09-21"], "withMacro": false },
+          "mode": "NORMAL"
+        }
+      },
+      "comparisonEnabled": true,
+      "contributionCalcEnabled": true,
+      "dimensionDecompositionContent": {
+        "decomposableDimensionIds": [],
+        "multipleDimensionEnabled": false,
+        "multipleDimensionList": [],
+        "nodeNum": 5,
+        "orderBy": "valueDesc",
+        "drillDownLevels": []
+      },
+      "metricDecompositionContent": {
+        "metricRelationTree": [
+          { "operation": "", "metricId": "metric_root_example", "decomposeMode": "calculation" }
+        ]
+      }
+    }
+  },
+  "createResponse": {
+    "result": "ok",
+    "response": {
+      "success": true,
+      "message": "指标树创建成功",
+      "metricTreeId": "metric_tree_example"
+    }
+  },
+  "renameRequest": { "name": "销售经营分析指标树" },
+  "renameResponse": {
+    "result": "ok",
+    "response": {
+      "success": true,
+      "message": "指标树名称更新成功",
+      "data": {
+        "domId": "example_domain",
+        "metricId": "metric_root_example",
+        "metricTreeId": "metric_tree_example",
+        "name": "销售经营分析指标树",
+        "config": {},
+        "parentDirId": "metric_tree_dir_root",
+        "uId": "user_example",
+        "ctime": "2026-09-21 11:18:16+0800",
+        "utime": "2026-09-21 11:19:01+0800",
+        "isDel": false
+      }
+    }
+  },
+  "moveRequest": { "newParentDirId": "metric_tree_dir_sales" },
+  "moveResponse": {
+    "result": "ok",
+    "response": { "success": true, "message": "指标树移动成功" }
+  },
+  "updateConfigRequest": {
+    "config": {
+      "comparisonEnabled": true,
+      "contributionCalcEnabled": true,
+      "dimensionDecompositionContent": {
+        "decomposableDimensionIds": [],
+        "multipleDimensionEnabled": false,
+        "multipleDimensionList": [],
+        "nodeNum": 5,
+        "orderBy": "valueDesc",
+        "drillDownLevels": []
+      },
+      "metricDecompositionContent": {
+        "metricRelationTree": [
+          { "operation": "", "metricId": "metric_root_example", "decomposeMode": "calculation" }
+        ]
+      }
+    }
+  },
+  "updateConfigResponse": {
+    "result": "ok",
+    "response": {
+      "success": true,
+      "message": "指标树配置更新成功",
+      "data": {
+        "domId": "example_domain",
+        "metricId": "metric_root_example",
+        "metricTreeId": "metric_tree_example",
+        "name": "销售经营分析指标树",
+        "config": {},
+        "parentDirId": "metric_tree_dir_root",
+        "uId": "user_example",
+        "ctime": "2026-09-21 11:18:16+0800",
+        "utime": "2026-09-21 11:19:43+0800",
+        "isDel": false
+      }
+    }
+  },
+  "detailResponse": {
+    "result": "ok",
+    "response": {
+      "domId": "example_domain",
+      "metricTreeId": "metric_tree_example",
+      "metricTreeName": "销售经营分析指标树",
+      "config": {},
+      "parentDirId": "metric_tree_dir_root",
+      "ctime": "2026-09-21 11:18:16",
+      "utime": "2026-09-21 11:19:43",
+      "isDel": false,
+      "metricId": "metric_root_example",
+      "metricName": "销售额",
+      "projectId": "project_example",
+      "projectName": "经营指标",
+      "creatorId": "user_example",
+      "creatorName": "示例用户",
+      "canUse": true,
+      "canManage": true,
+      "dirPath": [
+        { "dirId": "metric_tree_dir_root", "dirName": "根目录" }
+      ]
+    }
+  },
+  "listByParentResponse": {
+    "result": "ok",
+    "response": {
+      "success": true,
+      "data": [
+        {
+          "domId": "example_domain",
+          "metricId": "metric_root_example",
+          "metricTreeId": "metric_tree_example",
+          "name": "销售经营分析指标树",
+          "config": {},
+          "parentDirId": "metric_tree_dir_root",
+          "uId": "user_example",
+          "ctime": "2026-09-21 11:18:16+0800",
+          "utime": "2026-09-21 11:19:43+0800",
+          "isDel": false
+        }
+      ],
+      "total": 1
+    }
+  },
+  "searchResponse": {
+    "result": "ok",
+    "response": {
+      "success": true,
+      "data": [
+        {
+          "metricTreeId": "metric_tree_example",
+          "metricTreeName": "销售经营分析指标树",
+          "metricId": "metric_root_example",
+          "metricName": "销售额",
+          "projectId": "project_example",
+          "projectName": "经营指标",
+          "creatorId": "user_example",
+          "creatorName": "示例用户",
+          "parentDirId": "metric_tree_dir_root",
+          "canUse": true,
+          "canManage": true,
+          "dirPath": [
+            { "dirId": "metric_tree_dir_root", "dirName": "根目录" }
+          ]
+        }
+      ],
+      "total": 1
+    }
+  },
+  "deleteResponse": {
+    "result": "ok",
+    "response": { "success": true, "message": "指标树删除成功" }
+  },
+  "directory": {
+    "createRequest": {
+      "name": "经营分析",
+      "parentDirId": "metric_tree_dir_root",
+      "dirType": "METRIC_TREE"
+    },
+    "createResponse": {
+      "result": "ok",
+      "response": {
+        "dirId": "metric_tree_dir_sales",
+        "dirName": "经营分析",
+        "dirType": "METRIC_TREE",
+        "parentDirId": "metric_tree_dir_root",
+        "parentDirName": "根目录",
+        "dirPath": [
+          { "dirId": "metric_tree_dir_root", "dirName": "根目录" },
+          { "dirId": "metric_tree_dir_sales", "dirName": "经营分析" }
+        ]
+      }
+    },
+    "updateRequest": {
+      "name": "销售经营分析",
+      "parentDirId": "metric_tree_dir_root",
+      "dirType": "METRIC_TREE"
+    },
+    "updateResponse": {
+      "result": "ok",
+      "response": {
+        "dirId": "metric_tree_dir_sales",
+        "dirName": "销售经营分析",
+        "dirType": "METRIC_TREE",
+        "parentDirId": "metric_tree_dir_root",
+        "parentDirName": "根目录",
+        "dirPath": [
+          { "dirId": "metric_tree_dir_root", "dirName": "根目录" },
+          { "dirId": "metric_tree_dir_sales", "dirName": "销售经营分析" }
+        ]
+      }
+    },
+    "detailResponse": {
+      "result": "ok",
+      "response": {
+        "count": 0,
+        "parentDirId": "metric_tree_dir_root",
+        "parentDirName": "根目录",
+        "dirType": "METRIC_TREE",
+        "dirId": "metric_tree_dir_sales",
+        "dirName": "销售经营分析",
+        "canManage": true,
+        "canUse": true,
+        "contents": [],
+        "dirPath": [
+          { "dirId": "metric_tree_dir_root", "dirName": "根目录" },
+          { "dirId": "metric_tree_dir_sales", "dirName": "销售经营分析" }
+        ],
+        "hasChildDir": false
+      }
+    },
+    "treeResponse": {
+      "result": "ok",
+      "response": {
+        "id": "metric_tree_dir_root",
+        "parentDirId": "",
+        "name": "根目录",
+        "type": "DIRECTORY",
+        "contents": [
+          {
+            "id": "metric_tree_dir_sales",
+            "parentDirId": "metric_tree_dir_root",
+            "name": "销售经营分析",
+            "type": "DIRECTORY",
+            "canManage": true,
+            "canUse": true,
+            "ctime": "2026-09-21T11:31:51.00Z",
+            "utime": "2026-09-21T11:32:55.00Z"
+          }
+        ],
+        "canManage": true,
+        "canUse": true,
+        "ctime": "2025-12-25T17:02:08.00Z",
+        "utime": "2026-09-21T11:32:55.00Z"
+      }
+    },
+    "deleteResponse": {
+      "result": "ok",
+      "response": "Directory deleted"
+    }
+  }
+}

package/skills/guanmetric/references/metric-tree-api-contract.schema.json

@@ -0,0 +1,263 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://guandata.dev/schemas/guanmetric/metric-tree-api-contract-1.0.json",
+  "title": "GuanData metric tree API contract",
+  "description": "用于 Agent 构造指标树写请求并解析真实后端响应。响应允许后端新增字段。",
+  "oneOf": [
+    { "$ref": "#/$defs/createRequest" },
+    { "$ref": "#/$defs/renameRequest" },
+    { "$ref": "#/$defs/moveRequest" },
+    { "$ref": "#/$defs/updateConfigRequest" },
+    { "$ref": "#/$defs/createResponse" },
+    { "$ref": "#/$defs/mutationResponse" },
+    { "$ref": "#/$defs/detailResponse" },
+    { "$ref": "#/$defs/listResponse" },
+    { "$ref": "#/$defs/searchResponse" },
+    { "$ref": "#/$defs/deleteResponse" },
+    { "$ref": "#/$defs/directoryWriteRequest" },
+    { "$ref": "#/$defs/directoryMutationResponse" },
+    { "$ref": "#/$defs/directoryDetailResponse" },
+    { "$ref": "#/$defs/directoryTreeResponse" },
+    { "$ref": "#/$defs/directoryDeleteResponse" }
+  ],
+  "$defs": {
+    "nonEmptyString": { "type": "string", "minLength": 1 },
+    "config": { "type": "object", "additionalProperties": true },
+    "createRequest": {
+      "type": "object",
+      "required": ["metricId", "name", "parentDirId"],
+      "properties": {
+        "metricId": { "$ref": "#/$defs/nonEmptyString" },
+        "name": { "$ref": "#/$defs/nonEmptyString" },
+        "parentDirId": { "$ref": "#/$defs/nonEmptyString" },
+        "config": { "$ref": "#/$defs/config" }
+      },
+      "additionalProperties": false
+    },
+    "renameRequest": {
+      "type": "object",
+      "required": ["name"],
+      "properties": { "name": { "$ref": "#/$defs/nonEmptyString" } },
+      "additionalProperties": false
+    },
+    "moveRequest": {
+      "type": "object",
+      "required": ["newParentDirId"],
+      "properties": { "newParentDirId": { "$ref": "#/$defs/nonEmptyString" } },
+      "additionalProperties": false
+    },
+    "updateConfigRequest": {
+      "type": "object",
+      "required": ["config"],
+      "properties": { "config": { "$ref": "#/$defs/config" } },
+      "additionalProperties": false
+    },
+    "pathItem": {
+      "type": "object",
+      "required": ["dirId", "dirName"],
+      "properties": {
+        "dirId": { "$ref": "#/$defs/nonEmptyString" },
+        "dirName": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "listItem": {
+      "type": "object",
+      "required": ["domId", "metricId", "metricTreeId", "name", "parentDirId", "isDel"],
+      "properties": {
+        "domId": { "$ref": "#/$defs/nonEmptyString" },
+        "metricId": { "$ref": "#/$defs/nonEmptyString" },
+        "metricTreeId": { "$ref": "#/$defs/nonEmptyString" },
+        "name": { "$ref": "#/$defs/nonEmptyString" },
+        "config": { "$ref": "#/$defs/config" },
+        "parentDirId": { "$ref": "#/$defs/nonEmptyString" },
+        "uId": { "type": "string" },
+        "ctime": { "type": "string" },
+        "utime": { "type": "string" },
+        "isDel": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "detail": {
+      "type": "object",
+      "required": ["metricTreeId", "metricTreeName", "metricId", "parentDirId", "canUse", "canManage"],
+      "properties": {
+        "metricTreeId": { "$ref": "#/$defs/nonEmptyString" },
+        "metricTreeName": { "$ref": "#/$defs/nonEmptyString" },
+        "metricId": { "$ref": "#/$defs/nonEmptyString" },
+        "metricName": { "type": "string" },
+        "parentDirId": { "$ref": "#/$defs/nonEmptyString" },
+        "config": { "$ref": "#/$defs/config" },
+        "canUse": { "type": "boolean" },
+        "canManage": { "type": "boolean" },
+        "dirPath": { "type": "array", "items": { "$ref": "#/$defs/pathItem" } }
+      },
+      "additionalProperties": true
+    },
+    "successPayload": {
+      "type": "object",
+      "required": ["success", "message"],
+      "properties": {
+        "success": { "const": true },
+        "message": { "$ref": "#/$defs/nonEmptyString" },
+        "data": { "$ref": "#/$defs/listItem" }
+      },
+      "additionalProperties": true
+    },
+    "envelope": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": { "result": { "const": "ok" } },
+      "additionalProperties": true
+    },
+    "createResponse": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "properties": {
+            "response": {
+              "allOf": [
+                { "$ref": "#/$defs/successPayload" },
+                { "required": ["metricTreeId"], "properties": { "metricTreeId": { "$ref": "#/$defs/nonEmptyString" } } }
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "mutationResponse": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        { "properties": { "response": { "$ref": "#/$defs/successPayload" } } }
+      ]
+    },
+    "detailResponse": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        { "properties": { "response": { "$ref": "#/$defs/detail" } } }
+      ]
+    },
+    "pagedListPayload": {
+      "type": "object",
+      "required": ["success", "data", "total"],
+      "properties": {
+        "success": { "const": true },
+        "data": { "type": "array", "items": { "$ref": "#/$defs/listItem" } },
+        "total": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": true
+    },
+    "listResponse": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        { "properties": { "response": { "$ref": "#/$defs/pagedListPayload" } } }
+      ]
+    },
+    "searchResponse": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        {
+          "properties": {
+            "response": {
+              "type": "object",
+              "required": ["success", "data", "total"],
+              "properties": {
+                "success": { "const": true },
+                "data": { "type": "array", "items": { "$ref": "#/$defs/detail" } },
+                "total": { "type": "integer", "minimum": 0 }
+              },
+              "additionalProperties": true
+            }
+          }
+        }
+      ]
+    },
+    "deleteResponse": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        { "properties": { "response": { "$ref": "#/$defs/successPayload" } } }
+      ]
+    },
+    "directoryWriteRequest": {
+      "type": "object",
+      "required": ["name", "parentDirId", "dirType"],
+      "properties": {
+        "name": { "$ref": "#/$defs/nonEmptyString" },
+        "parentDirId": { "$ref": "#/$defs/nonEmptyString" },
+        "dirType": { "const": "METRIC_TREE" }
+      },
+      "additionalProperties": false
+    },
+    "directoryMutationPayload": {
+      "type": "object",
+      "required": ["dirId", "dirName", "dirType", "parentDirId", "parentDirName", "dirPath"],
+      "properties": {
+        "dirId": { "$ref": "#/$defs/nonEmptyString" },
+        "dirName": { "$ref": "#/$defs/nonEmptyString" },
+        "dirType": { "const": "METRIC_TREE" },
+        "parentDirId": { "$ref": "#/$defs/nonEmptyString" },
+        "parentDirName": { "type": "string" },
+        "dirPath": { "type": "array", "items": { "$ref": "#/$defs/pathItem" } }
+      },
+      "additionalProperties": true
+    },
+    "directoryMutationResponse": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        { "properties": { "response": { "$ref": "#/$defs/directoryMutationPayload" } } }
+      ]
+    },
+    "directoryDetail": {
+      "type": "object",
+      "required": ["count", "parentDirId", "dirType", "dirId", "dirName", "canManage", "canUse", "contents", "dirPath", "hasChildDir"],
+      "properties": {
+        "count": { "type": "integer", "minimum": 0 },
+        "parentDirId": { "type": "string" },
+        "parentDirName": { "type": ["string", "null"] },
+        "dirType": { "const": "METRIC_TREE" },
+        "dirId": { "$ref": "#/$defs/nonEmptyString" },
+        "dirName": { "type": "string" },
+        "canManage": { "type": "boolean" },
+        "canUse": { "type": "boolean" },
+        "contents": { "type": "array" },
+        "dirPath": { "type": "array", "items": { "$ref": "#/$defs/pathItem" } },
+        "hasChildDir": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "directoryDetailResponse": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        { "properties": { "response": { "$ref": "#/$defs/directoryDetail" } } }
+      ]
+    },
+    "directoryTreeNode": {
+      "type": "object",
+      "required": ["id", "parentDirId", "name", "type"],
+      "properties": {
+        "id": { "$ref": "#/$defs/nonEmptyString" },
+        "parentDirId": { "type": "string" },
+        "name": { "type": "string" },
+        "type": { "const": "DIRECTORY" },
+        "contents": { "type": "array", "items": { "$ref": "#/$defs/directoryTreeNode" } },
+        "canManage": { "type": "boolean" },
+        "canUse": { "type": "boolean" },
+        "ctime": { "type": "string" },
+        "utime": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "directoryTreeResponse": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        { "properties": { "response": { "$ref": "#/$defs/directoryTreeNode" } } }
+      ]
+    },
+    "directoryDeleteResponse": {
+      "allOf": [
+        { "$ref": "#/$defs/envelope" },
+        { "properties": { "response": { "type": "string" } } }
+      ]
+    }
+  }
+}

package/skills/guanmetric/references/metric-tree-api-contracts.md

@@ -0,0 +1,53 @@
+# 指标树 API 真实契约
+
+本文记录指标树及其 `METRIC_TREE` 目录的创建、原地编辑、详情、列表和删除接口真实形态，供 Agent 构造请求和解析返回。完整脱敏样例见 `metric-tree-api-contract-examples.json`，JSON Schema 见 `metric-tree-api-contract.schema.json`。
+
+样例于 2026-09-21 使用 test71 隔离临时指标树和账号密码认证实测。PAT 尚未验证，不能据此声明这些接口已完成 PAT 兼容验证。
+
+## 接口矩阵
+
+| 操作 | Method / Path | 请求体 | 关键响应 |
+| --- | --- | --- | --- |
+| 创建 | `POST /api/metric-platform/metric-tree/add` | `metricId/name/parentDirId`，可选 `config` | `success/message/metricTreeId` |
+| 详情 | `GET /api/metric-platform/metric-tree/{id}` | 无 | 详情读模型，名称字段为 `metricTreeName` |
+| 父目录列表 | `GET /api/metric-platform/metric-tree/by-parent/{parentDirId}` | 无 | `{success,data,total}`；列表项名称字段为 `name` |
+| 搜索 | `GET /api/metric-platform/metric-tree/search?nameLike=...` | 无 | `{success,data,total}`；搜索项更接近详情模型，名称字段为 `metricTreeName` |
+| 改名 | `POST /api/metric-platform/metric-tree/{id}/rename` | 仅 `{name}` | `success/message/data`，`data` 是列表态对象 |
+| 移动 | `POST /api/metric-platform/metric-tree/{id}/move` | 仅 `{newParentDirId}` | `success/message`；移到当前目录会返回业务码 `1012` |
+| 更新配置 | `POST /api/metric-platform/metric-tree/{id}/update-config` | 仅 `{config}` | `success/message/data`，`data` 是列表态对象 |
+| 删除 | `POST /api/metric-platform/metric-tree/{id}/delete` | 无 | `{success:true,message:"指标树删除成功"}` |
+
+### METRIC_TREE 目录接口
+
+| 操作 | Method / Path | 请求体 | 关键响应 |
+| --- | --- | --- | --- |
+| 目录树 | `GET /api/directory/METRIC_TREE/authorized-tree` | 无 | 递归目录节点，字段为 `id/name/type/contents` |
+| 目录详情 | `GET /api/directory/METRIC_TREE?dirId=...&dirType=METRIC_TREE&folderOnly=true&offset=0&limit=0` | 无 | 详情字段为 `dirId/dirName/dirPath/hasChildDir/count` |
+| 创建目录 | `POST /api/metric-platform/directory/create` | `{name,parentDirId,dirType:"METRIC_TREE"}` | 目录路径对象 |
+| 编辑目录 | `POST /api/metric-platform/directory/{id}/update` | 完整 `{name,parentDirId,dirType:"METRIC_TREE"}` | 目录路径对象 |
+| 删除目录 | `POST /api/metric-platform/directory/{id}/delete` | 无 | 字符串 `Directory deleted` |
+
+Spring Controller 已确认上述路由真实存在：目录树和详情要求 `BASE.READ`；创建、编辑、删除分别要求 `METRIC_PLATFORM.CREATE`、`METRIC_PLATFORM.UPDATE`、`METRIC_PLATFORM.DELETE`。这是服务端最终权限判断，CLI 不在本地复制权限规则。PAT 默认授权及有权/无权对照尚未实测。
+
+## 读写模型必须分离
+
+- 详情响应的 `metricTreeName`、`metricName`、`projectName`、`creatorName`、`canUse`、`canManage`、`dirPath`、`ctime`、`utime` 和 `isDel` 都是读模型字段，不能把详情整体提交给任一写接口。
+- 父目录列表、rename 和 update-config 返回的对象用 `name`，详情与搜索用 `metricTreeName`。解析器不能假设二者同名。
+- 改名只提交 `{name}`；移动只提交 `{newParentDirId}`；配置编辑只提交 `{config}`。不要用详情对象 merge 后整体回写。
+- 创建的最小写模型是 `{metricId,name,parentDirId}`。CLI 会读取根指标并补齐默认配置；根指标没有时间维度时会拒绝创建。
+- 指标树目录写模型必须固定 `dirType=METRIC_TREE`。目录树节点的 `id/name` 与详情/写响应的 `dirId/dirName` 是两套读模型字段，不能整体回写。
+- 目录 edit 即使只改名称，也要先读详情并提交完整 `{name,parentDirId,dirType}`；根目录不能编辑或删除，目录不能移动到自身或后代。
+
+## 删除安全语义
+
+`guanmetric metric-tree delete <id>` 默认先读取详情，展示根指标、项目、目录路径和配置，不真实删除。只有明确追加 `--confirm` 才调用删除接口；`--confirm --dry-run` 只展示 GET + POST 计划。删除由 BI 服务端最终校验权限，当前后端权限项为 `METRIC_PLATFORM.DELETE`。
+
+删除会使原指标树 ID、归因入口和外部链接失效，不可用“删除 + 同名创建”模拟编辑。改名、移动和配置变化必须使用对应原地编辑命令。
+
+`guanmetric metric-tree directory delete <dir_id>` 同样默认只展示目录详情；`--confirm` 才删除。前端明确要求先清空目录，目录非空时由后端拒绝。
+
+## 验证边界
+
+- 本轮账号密码实测覆盖：指标树创建、详情、父目录列表、搜索、改名、移动、更新配置、删除；以及指标树目录 tree、detail、create、rename、move、delete 和写后回读。
+- PAT 未实测；在完成同用户同 Domain 的有权、无权、资源不存在及写后回读对照前，PAT 状态必须标记为“未验证”。
+- JSON Schema 对请求体使用严格白名单；响应允许服务端新增字段，以降低只增加返回字段造成的漂移风险。