@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,500 @@
+# 指标树创建 / 修改指引
+
+本文用于指导 Agent 创建、配置和原地修改指标树。查询、搜索、归因分析仍优先使用 `guancli metric_attribution`；写操作使用 `guanmetric metric-tree`。
+
+## 读取顺序
+
+处理指标树需求时按需读取：
+
+1. 先读本文，判断用户是创建壳、创建并配置维度拆解、创建并配置指标拆解、修改配置、改名、移动，还是目录管理。
+2. 如果需要根指标或下级指标，读取 `metric-common-fields.md` 的环境、资源查询和通用字段规则。
+3. 如果用户需要先创建根指标或子指标，再建指标树，按 `metric-mutation.md` 完成指标创建闭环，拿到指标 ID 后再回到本文。
+4. 如果指标拆解里出现复合指标公式，读取 `metric-composite-mutation.md` 和 `metric-expression-rules.md`，理解 `formula` 中 `[metricId]` 的含义。
+5. 构造请求或解析响应前读取 `metric-tree-api-contracts.md`，不要混用详情、列表和写入模型。
+6. 只在最终提交时使用 `guanmetric metric-tree`；不要用裸 `fetch` 调指标树写接口。
+
+## 能力边界
+
+`guanmetric metric-tree` 覆盖：
+
+- `create`：创建指标树。
+- `get`：回读指标树详情。
+- `rename`：原地更新指标树名称。
+- `move`：原地移动指标树目录。
+- `update-config`：原地更新指标树配置。
+- `delete`：默认展示待删除详情，追加 `--confirm` 后删除指标树。
+
+不要用删除重建模拟指标树编辑。指标树 ID 可能被归因入口、页面链接、目录和外部系统引用，删除重建会造成断链。
+
+## 前端同款流程
+
+`guandata-web` 前端创建指标树分两步：
+
+1. 创建壳：选择根指标，提交 `{ metricId, parentDirId, name }` 到 `POST /api/metric-platform/metric-tree/add`。
+2. 编辑配置：进入 `/metrics-store/hierarchy/{metricTreeId}/edit/dimension`，保存时提交 `{ name, config }` 到 `POST /api/metric-platform/metric-tree/{metricTreeId}/update-config`。
+
+因此 Agent 推荐也按两阶段执行：先创建指标树壳，再按用户确认的配置执行 `update-config`。只有用户明确要求“创建时带完整 config”时，才在 create payload 中携带 `config`。
+
+默认名称可模拟前端格式：
+
+```text
+未命名的指标树_YYYY_MM_DD_HH_mm_ss
+```
+
+默认配置应模拟前端初始化。根指标必须有时间维度；没有时间维度时不得创建指标树，应提示用户先为指标配置时间维度。未显式指定对比方式时，CLI 会默认生成同环比 + 日环比配置，并开启对比和贡献计算：
+
+```json
+{
+  "timeComparisonSetting": {
+    "advType": "COMPARATIVE",
+    "advValue": {
+      "advType": "COMPARATIVE",
+      "dateFdId": "<root_metric_time_dim_fd_id>",
+      "dateFdName": "<root_metric_time_dim_name>",
+      "valueType": "RAWDATA",
+      "offset": 1,
+      "offsetType": "DAY",
+      "granularity": "DAY",
+      "window": {
+        "period": ["<today:YYYY-MM-DD>"],
+        "withMacro": false
+      },
+      "mode": "NORMAL"
+    }
+  },
+  "comparisonEnabled": true,
+  "contributionCalcEnabled": true,
+  "dimensionDecompositionContent": {
+    "decomposableDimensionIds": [],
+    "multipleDimensionEnabled": false,
+    "multipleDimensionList": [],
+    "nodeNum": 5,
+    "orderBy": "valueDesc",
+    "drillDownLevels": []
+  },
+  "metricDecompositionContent": {
+    "metricRelationTree": [
+      {
+        "metricId": "<root_metric_id>",
+        "parentId": null,
+        "operation": "",
+        "decomposeMode": "calculation"
+      }
+    ]
+  },
+  "reportDisplaySetting": {
+    "conclusionSetting": null
+  }
+}
+```
+
+如果根指标有时间维度，前端会初始化同环比 `timeComparisonSetting`。当前 CLI 已内置同款默认生成器：当提交的 config 未包含 `timeComparisonSetting` 或为 `null` 时，会基于根指标时间维度补齐默认配置，并把 `comparisonEnabled`、`contributionCalcEnabled` 置为 `true`。
+
+## 意图判断
+
+| 用户意图 | 判断 | 推荐流程 |
+| --- | --- | --- |
+| 给某指标建一个指标树 | 只创建壳 | 查根指标、查 `METRIC_TREE` 目录、计划确认、create |
+| 按地区/渠道拆某指标 | 维度拆解 | 查根指标适用维度、生成 config、create 后 update-config |
+| A = B + C / A 拆成 B、C | 指标拆解计算模式 | 解析公式、查指标 ID、生成 `metricRelationTree` |
+| A 关系拆解为 B、C | 指标拆解关系模式 | 生成 relation 模式，子节点 operation 为空 |
+| 根指标或子指标是复合指标 | 自动读取复合公式 | 根据 `formula` 可控展开 |
+| 打开贡献分析/贡献排序 | 时间对比 + 贡献计算 | 必须根指标时间配置合法 |
+| 改名 | 原地重命名 | `metric-tree rename` |
+| 移动目录 | 原地移动 | 查 `METRIC_TREE` 目录，`metric-tree move` |
+| 删除指标树 | 高风险删除 | `metric-tree delete <id>` 预览，明确确认后追加 `--confirm` |
+| 重建同名指标树替换旧的 | 高风险 | 阻断并说明断链，除非用户明确二次确认 |
+
+## 删除流程
+
+删除前必须先读取并展示指标树详情：
+
+```bash
+guanmetric metric-tree delete <metric_tree_id>
+```
+
+默认不会提交删除。用户确认目标无误后执行：
+
+```bash
+guanmetric metric-tree delete <metric_tree_id> --confirm
+```
+
+需要查看完整调用计划但仍不写入时使用：
+
+```bash
+guanmetric metric-tree delete <metric_tree_id> --confirm --dry-run
+```
+
+服务端最终校验删除权限。删除会使指标树 ID、归因入口和外部链接失效，不能恢复，也不能用删除重建模拟改名、移动或配置编辑。
+
+## 资源解析规则
+
+使用当前已登录环境，不主动询问 profile；写操作前可执行：
+
+```bash
+guancli auth status
+```
+
+根指标和下级指标：
+
+- 有 ID：用 `guancli metric get <metric_id> --brief` 或 `-f json` 回读确认。
+- 只有名称：用 `guancli metric search <keyword> -f json` 搜索；多候选必须让用户指定 ID。
+- 需要配置维度、时间对比或复合指标展开时，必须用 `guancli metric get <metric_id> --raw` 读取完整详情。
+
+指标树父目录来自 `METRIC_TREE` 目录体系：
+
+```bash
+guancli metric_attribution tree -f json
+```
+
+不要使用 `guancli metric tree` 返回的 `METRIC_PLATFORM` 指标目录 ID 创建指标树。只有目录名时，按路径唯一匹配；重复时必须让用户指定目录 ID。
+
+## 维度拆解配置规则
+
+维度拆解需要先读取根指标详情，确认 `applicableDims`、`publicDimensionMap` 和 `timeDim`。
+
+规则：
+
+- 拆解维度必须在根指标 `applicableDims` 中。
+- 不要把根指标时间维度作为拆解维度。
+- 交叉维度每组至少 2 个维度，最多 5 个维度。
+- 交叉维度中的每个维度必须已经在 `decomposableDimensionIds` 中。
+- `multipleDimensionEnabled=true` 时，至少保留一组合法交叉维度；长度小于等于 1 的组合应提前过滤并提示。
+- `drillDownLevels` 统一写 `dimensionIds`，不要写历史 `dimensionId`。
+- `nodeNum` 默认 5，合法范围 5-20。
+- `orderBy` 默认 `valueDesc`。
+- `contributionCalcEnabled=false` 时只允许 `valueAsc` 和 `valueDesc`。
+- 关闭对比时必须同时关闭贡献计算。
+- 关闭贡献计算时，贡献排序要降级：`contributionAsc -> valueAsc`，`contributionDesc -> valueDesc`。
+
+## 时间对比和贡献计算
+
+根指标没有时间维度时，不允许创建指标树；必须提示用户先为指标配置时间维度。
+
+根指标已经是同环比衍生指标时，不要再配置时间对比。
+
+如果启用贡献计算：
+
+- 必须 `comparisonEnabled=true`。
+- `timeComparisonSetting` 必须合法。
+- 排序可使用 `contributionAsc` 或 `contributionDesc`。
+
+如果用户只说“按贡献排序”，Agent 应解释该能力依赖时间对比和贡献计算，先确认时间配置。
+
+## 指标拆解公式理解
+
+用户可能直接给出自然语言公式，Agent 需要转换为 `metricDecompositionContent.metricRelationTree`。
+
+示例输入：
+
+```text
+销售额 = 订单数 * 客单价
+利润 = 销售额 - 成本
+转化率 = 下单人数 / 访问人数
+```
+
+处理流程：
+
+1. 识别公式左侧父指标和右侧子指标。
+2. 如果用户只给右侧，例如“按 B + C 拆 A”，父指标来自当前根指标或上下文。
+3. 对公式中的每个指标名解析唯一指标 ID；不能按名称猜。
+4. 构造关系树节点：
+   - 父节点必须存在。
+   - 第一个子节点 `operation` 为空。
+   - 第二个及之后子节点的 `operation` 取它前面的运算符。
+5. 输出计划时展示用户公式、ID 公式和关系表。
+
+公式：
+
+```text
+销售额 = 订单数 * 客单价
+```
+
+生成：
+
+```json
+[
+  {
+    "metricId": "metric_sales",
+    "parentId": null,
+    "operation": "",
+    "decomposeMode": "calculation"
+  },
+  {
+    "metricId": "metric_orders",
+    "parentId": "metric_sales",
+    "operation": "",
+    "decomposeMode": "calculation"
+  },
+  {
+    "metricId": "metric_aov",
+    "parentId": "metric_sales",
+    "operation": "*",
+    "decomposeMode": "calculation"
+  }
+]
+```
+
+关系拆解：
+
+```text
+销售额 关系拆解为 线上销售额、线下销售额
+```
+
+生成：
+
+```json
+[
+  {
+    "metricId": "metric_sales",
+    "parentId": null,
+    "operation": "",
+    "decomposeMode": "relation"
+  },
+  {
+    "metricId": "metric_online_sales",
+    "parentId": "metric_sales",
+    "operation": "",
+    "decomposeMode": "calculation"
+  },
+  {
+    "metricId": "metric_offline_sales",
+    "parentId": "metric_sales",
+    "operation": "",
+    "decomposeMode": "calculation"
+  }
+]
+```
+
+## 公式能力边界
+
+前端指标树关系模型是“父节点 = 直接子指标按顺序四则运算”。因此：
+
+- 支持 `A = B + C - D`、`A = B * C`、`A = B / C`。
+- 支持多层级：对子指标继续配置子节点。
+- 不要无损承诺任意括号优先级，例如 `A = (B + C) / D`。
+
+遇到括号、常量、函数、条件表达式或窗口表达式时：
+
+1. 如果括号内已有线上复合指标，例如 `X = B + C`，用 `X` 作为中间节点。
+2. 如果没有中间指标，提示用户指标树不能完整表达该公式优先级，建议先创建中间复合指标。
+3. 不要把 `A = (B + C) / D` 强行转成 `A = B + C / D`。
+
+## 复合指标自动拆解
+
+触发场景：
+
+- 根指标本身是 `subType=COMPOSITE`。
+- 用户公式中的某个子指标是复合指标。
+- 用户明确说“按复合指标公式展开”。
+
+处理规则：
+
+1. 对每个参与指标执行 `guancli metric get <metric_id> --raw`。
+2. 如果 `subType=COMPOSITE`，读取其 `formula` 字段。
+3. 从 `formula` 中提取 `[metricId]` 引用和 `+ - * /` 运算符。
+4. 把复合指标作为节点保留，再把公式引用指标作为它的子节点。
+5. 递归处理公式里的复合指标。
+6. 设置 `decomposeMode=calculation`。
+7. 检测循环引用和重复路径；同一条路径中重复出现的指标必须停止展开并提示。
+8. 默认最大递归深度为 3；超过时停止并在计划中标记“未展开，需要确认”。
+
+根指标是复合指标：
+
+```text
+客单价(metric_aov) = 销售额(metric_sales) / 订单数(metric_orders)
+```
+
+生成：
+
+```json
+[
+  {
+    "metricId": "metric_aov",
+    "parentId": null,
+    "operation": "",
+    "decomposeMode": "calculation"
+  },
+  {
+    "metricId": "metric_sales",
+    "parentId": "metric_aov",
+    "operation": "",
+    "decomposeMode": "calculation"
+  },
+  {
+    "metricId": "metric_orders",
+    "parentId": "metric_aov",
+    "operation": "/",
+    "decomposeMode": "calculation"
+  }
+]
+```
+
+注意：前端关系图用 `metricId` 作为节点 ID，同一指标 ID 多父节点可能产生展示冲突。对子复合指标展开时，如果会让同一指标出现在多个父节点下，推荐默认不展开该子复合指标，并在计划中说明。用户可选择：
+
+- 不展开子复合指标，只保留复合指标节点。
+- 展开子复合指标，但调整顶层公式，避免重复节点。
+- 先创建新的中间指标或调整拆解公式。
+
+## 指标树创建计划
+
+创建计划确认前，不生成最终 config，不执行 dry-run，不真实写入。
+
+计划至少包含：
+
+- 当前环境。
+- 指标树名称。
+- 根指标：ID、名称、主题、时间维度、指标类型。
+- 目标指标树目录：路径、ID。
+- 维度拆解配置：拆解维度、交叉维度、下钻层级、展示个数、排序。
+- 指标拆解配置：每条父子关系、模式、运算符、来源。
+- 指标拆解来源：用户公式、复合指标公式、手工关系。
+- 自动展开结果：展开了哪些复合指标，跳过了哪些复合指标，以及原因。
+- 时间对比和贡献计算开关。
+- 后续步骤：create dry-run、真实 create、update-config dry-run、真实 update-config、回读和可选归因查询。
+
+关系表示例：
+
+| 父指标 | 子指标 | 模式 | 运算符 | 来源 |
+| --- | --- | --- | --- | --- |
+| 销售额 | 订单数 | calculation | 空 | 用户公式 |
+| 销售额 | 客单价 | calculation | * | 用户公式 |
+| 客单价 | 商品单价 | calculation | 空 | 复合指标公式 |
+| 客单价 | 购买件数 | calculation | * | 复合指标公式 |
+
+## JSON 生成
+
+建议生成两个 JSON。
+
+`metric_tree_create.json`：
+
+```json
+{
+  "metricId": "<root_metric_id>",
+  "name": "<tree_name>",
+  "parentDirId": "<metric_tree_dir_id>"
+}
+```
+
+`metric_tree_config.json`：
+
+```json
+{
+  "config": {
+  "timeComparisonSetting": null,
+  "comparisonEnabled": true,
+  "contributionCalcEnabled": true,
+    "dimensionDecompositionContent": {
+      "decomposableDimensionIds": ["fd-region", "fd-channel"],
+      "multipleDimensionEnabled": true,
+      "multipleDimensionList": [["fd-region", "fd-channel"]],
+      "nodeNum": 5,
+      "orderBy": "valueDesc",
+      "drillDownLevels": [
+        {
+          "dimensionIds": ["fd-region"]
+        }
+      ]
+    },
+    "metricDecompositionContent": {
+      "metricRelationTree": [
+        {
+          "metricId": "metric-root",
+          "parentId": null,
+          "operation": "",
+          "decomposeMode": "calculation"
+        },
+        {
+          "metricId": "metric-child-1",
+          "parentId": "metric-root",
+          "operation": "",
+          "decomposeMode": "calculation"
+        },
+        {
+          "metricId": "metric-child-2",
+          "parentId": "metric-root",
+          "operation": "+",
+          "decomposeMode": "calculation"
+        }
+      ]
+    },
+    "reportDisplaySetting": {
+      "conclusionSetting": null
+    }
+  }
+}
+```
+
+如果只创建壳，不生成 config；若用户要求“Web 同款可编辑初始配置”，可生成默认 config 并执行 `update-config`。
+
+## 执行顺序
+
+创建：
+
+```bash
+guanmetric metric-tree create --file metric_tree_create.json --dry-run
+guanmetric metric-tree create --file metric_tree_create.json
+```
+
+创建成功后拿到 `metricTreeId`。如果有配置：
+
+```bash
+guanmetric metric-tree update-config <metric_tree_id> --file metric_tree_config.json --dry-run
+guanmetric metric-tree update-config <metric_tree_id> --file metric_tree_config.json
+```
+
+原地修改：
+
+```bash
+guanmetric metric-tree rename <metric_tree_id> 新名称 --dry-run
+guanmetric metric-tree move <metric_tree_id> --parent-dir-id <metric_tree_dir_id> --dry-run
+guanmetric metric-tree update-config <metric_tree_id> --file metric_tree_config.json --dry-run
+```
+
+## 验证和回读
+
+回读详情：
+
+```bash
+guanmetric metric-tree get <metric_tree_id>
+guancli metric_attribution get <metric_tree_id> -f json
+```
+
+验证维度拆解：
+
+```bash
+guancli metric_attribution query <metric_tree_id> --target dim --dim <维度名>
+```
+
+验证指标拆解：
+
+```bash
+guancli metric_attribution query <metric_tree_id> --target index
+```
+
+不要把 dry-run 成功描述成指标树已经创建或修改成功。只有真实写入并回读确认后，才能报告线上更新成功。
+
+## 命令和接口速查
+
+| 操作 | 命令 | 后端接口 |
+| --- | --- | --- |
+| 创建指标树 | `guanmetric metric-tree create` | `POST /api/metric-platform/metric-tree/add` |
+| 回读指标树 | `guanmetric metric-tree get` | `GET /api/metric-platform/metric-tree/{id}` |
+| 重命名 | `guanmetric metric-tree rename` | `POST /api/metric-platform/metric-tree/{id}/rename` |
+| 移动 | `guanmetric metric-tree move` | `POST /api/metric-platform/metric-tree/{id}/move` |
+| 更新配置 | `guanmetric metric-tree update-config` | `POST /api/metric-platform/metric-tree/{id}/update-config` |
+| 查询目录树 | `guanmetric metric-tree directory tree` | `GET /api/directory/METRIC_TREE/authorized-tree` |
+| 目录详情 | `guanmetric metric-tree directory get` | `GET /api/directory/METRIC_TREE` |
+| 创建目录 | `guanmetric metric-tree directory create` | `POST /api/metric-platform/directory/create` |
+| 编辑目录 | `guanmetric metric-tree directory edit` | `POST /api/metric-platform/directory/{id}/update` |
+| 删除目录 | `guanmetric metric-tree directory delete` | `POST /api/metric-platform/directory/{id}/delete` |
+
+## 后续 CLI 增强建议
+
+当前 skill 可通过 `guancli` 查询、手写 JSON 和 `guanmetric metric-tree` 完成闭环。后续可考虑新增：
+
+- `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 详情不承诺完整编辑字段。

package/skills-bundle/guanmetric/references/metric-validation-ownership.md

@@ -0,0 +1,74 @@
+# 指标创建校验职责
+
+本文件记录 `guanmetric flow`、BI 后端和 Web 创建页之间的校验边界。指标业务校验采用差集原则：**Flow 只实现当前 Web 创建页已有、但当前后端创建链路没有覆盖的规则**。后端已有的规则不复制；前后端都没有的规则也不由 Flow 擅自新增。Flow 自身的跨指标编排契约单独列出，不属于单指标业务校验差集。
+
+## 基线
+
+- BI 后端：`guandata-core` `origin/master@baeb7d55ca`
+- Web 前端：`guandata-web` `origin/master@633f656934`
+- Flow：`guanmetric` `schemaVersion=1.0`
+
+前后端主线变化后，应重新核对本表。未合入主线的字段或功能不进入 Flow 稳定契约。
+
+维护时按规则粒度计算差集，不按字段名粗略判断：同一字段可能在草稿和发布态、不同指标类型下由不同层负责。只有 `Web=true && Backend=false` 才能进入 Flow 单指标业务校验；后端补齐后，必须同步删除 Flow 规则及其“应阻断”测试，改成验证请求交给后端。
+
+## 单指标业务校验差集
+
+| 规则 | Web 创建页 | BI 后端创建链路 | Flow 处理 |
+| --- | --- | --- | --- |
+| 草稿名称最长 50，且仅含中文、字母、数字、下划线 | 三类指标表单始终校验 | `MetricAbility.isNameValid` 仅在 `publish=true` 执行；草稿只校验非空 | `publish=false` 时校验；发布态不重复 |
+| 英文名最长 50，且仅含字母、数字、下划线 | 三类指标表单校验 | 只校验英文名重复，不校验格式和长度 | 校验格式和长度 |
+| 业务口径最长 1000 | `MetricBusinessSection.descRules` | 只校验非空 | 校验最大长度 |
+| 原子字段来源模式必须同时有 `fdId` 和 `aggrType` | 两个字段分别必填 | `onlyOneExisted` 只保证字段来源组至少有一个值，未保证两个都存在 | 仅在二者一有一无时阻断；二者都无由后端处理 |
+| 普通衍生必须选择 `baseMetricId` 和 `deriveSetting.advType` | 普通/快捷创建表单必填 | DTO 将两者作为可空值，普通衍生创建链路未统一拒绝缺失值 | `deriveType=ORDINARY` 时校验两个字段 |
+| 自定义业务属性文本长度 | `BizAttrs.tsx` 根据在线配置限制短文本 50、长文本 200 | 普通创建 DTO 不校验配置中的文本长度 | 复用在线属性配置校验文本长度；尚未声称覆盖全部表单交互约束 |
+| 原子指标“口径相同但适用维度不同”冲突 | 发布前调用 save-precheck 并要求二次确认 | 创建接口不等价于前端确认门禁；另有权威 save-precheck | 调用同一后端 save-precheck；有冲突时阻断自动创建 |
+| 草稿只能引用已发布指标 | 单指标公式和衍生选择器不提供草稿指标 | 草稿创建只做部分引用类型校验，未统一校验引用状态 | `acceptance.mode=draft` 禁止批内引用 |
+
+时间维度的前端规则依赖页面实时计算出的候选时间字段集合。Flow 当前请求体只有字段 ID，没有同等候选元数据，因此本阶段不复制一个不完整的本地判断；后续若要补齐，必须复用与 Web 相同的权威字段来源，而不能仅凭 `applicableDims` 猜测字段类型。
+
+## 创建计划 Excel 门禁
+
+Excel 是用户确认前的语义计划，不应包含已知不可创建的模型。生成 `*.ai_mapped.xlsx` 或标准创建计划 Excel 前，Agent 先建立本批“指标名称 → 指标类型”索引；复合指标公式引用本批衍生指标时直接停止生成，改为引用原子/复合指标，或在业务语义适用时改建组合衍生指标。`template normalize --check-only` 提供第二道确定性门禁，以 `TEMPLATE_INVALID_REFERENCE` 和具体 Sheet/row/column 返回错误。
+
+这条规则不放入 `flow plan`：后端创建接口已有复合引用类型校验，Flow 再做会重复维护；Excel 门禁的目的则是在形成用户评审产物之前阻止错误建模，职责阶段不同。
+
+## 明确不重复的后端规则
+
+| 校验面 | 后端权威实现 | Flow 行为 |
+| --- | --- | --- |
+| 名称/描述/责任人等必填、发布态名称格式和长度 | `Create*MetricRO.paramCheck`、`MetricAbility.*ValidationCheck` | 不重复；由创建接口返回结构化错误 |
+| 项目、目录、资源与创建权限 | `checkProjectAndMetricAuth`、Spring `METRIC_PLATFORM / CREATE` | 不根据本地快照判断权限 |
+| 原子来源类型互斥、数据集字段、表达式与适用维度 | `CreateAtomicMetricRO.paramCheck`、`checkAtomicSourceField`、`getByFdIdsInDs` | 不复制字段/聚合兼容矩阵 |
+| 名称、英文名和指标定义重复 | `MetricAbility.*MetricValidationCheck` | 不复制重复判定 |
+| 复合/组合衍生公式、引用类型、引用状态和嵌套深度 | `CompositeDerivedFormulaValidator`、`compositeMetricReferenceTypeValidationCheck`、`validateCompositeDerivedMetricReferences`、`checkNestTimes` | 既有指标由后端裁决；仅保留批内依赖拓扑检查 |
+| 期末值、业务限定和业务指标关联 | `DerivedMetricBusinessValidator`、`derivedMetricValidationCheck`、`validateBizMetricCanAssociateForCreate` | 不复制业务类型矩阵和关联状态规则 |
+
+## Flow 编排契约（非单指标业务校验）
+
+| 编排面 | 为什么只能由 Flow 负责 |
+| --- | --- |
+| 逻辑 key、批内占位符、未知引用、自引用、循环依赖、稳定拓扑顺序 | Web 单指标页面和后端单次创建接口没有批次概念 |
+| 计划哈希、目标环境、断点状态和重复创建保护 | 后端没有跨多次创建请求的计划状态 |
+| 发布审批、`canUse` 和数据查询可用性 | Flow 负责逐项回读和验收，未可用时不创建下游 |
+
+## 错误归属
+
+Flow 不匹配后端中英文错误文案。后端创建链路在校验后还会写指标、写草稿、同步血缘/权限并执行上线或审批；当前没有覆盖全链路的原子性或幂等契约。因此所有未返回可记录 `metricId` 的创建错误都按结果不确定处理：
+
+- 结构化 API 错误：保留 `businessStatus`、`httpStatus`、`method`、`path` 和原始 `message`，记录 `blocked/reconcile`、`FLOW_CREATE_RESULT_UNKNOWN`。
+- 非结构化子进程错误、断线或超时：记录 `blocked/reconcile`、`FLOW_CREATE_RESULT_UNKNOWN`。
+- 响应成功但取不到创建 ID：无法安全判断和续跑，记录 `blocked/reconcile`、`FLOW_CREATE_RESULT_UNKNOWN`。
+
+状态文件的可选 `error` 字段保存 `code`、`kind`、`httpStatus`、`businessStatus`、`method`、`path` 和服务端原始 `message`。这是 Flow 1.0 的向后兼容增量字段。
+
+## 主线证据
+
+- Web 表单：`atomic-rules.ts`、`composite-rules.ts`、`derived-rules.ts`、`MetricBusinessSection.tsx`、`BizAttrs.tsx`
+- Web 保存编排：`MetricEdit.tsx`、`common/metric-save-precheck.ts`
+- 后端路由与 PAT：`MetricManagementNgController.java`
+- 后端请求和基础参数：`application/metric_platform/request/MetricRO.scala`
+- 后端业务编排：`application/metric_platform/MetricUseCase.scala`
+- 后端定义重复和发布校验：`domain/metric_platform/ability/impl/MetricAbilityImpl.scala`、`domain/metric_platform/ability/util/ParamCheckUtil.scala`
+
+普通创建继续使用现有原子、复合、衍生创建接口。复合和衍生当前没有单独的 create-precheck，本阶段沿用创建请求中的后端权威校验，不新增接口。