@guandata/guanmetric 0.1.18 → 0.1.20

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

@@ -10,7 +10,8 @@
 2. 如果需要根指标或下级指标，读取 `metric-common-fields.md` 的环境、资源查询和通用字段规则。
 3. 如果用户需要先创建根指标或子指标，再建指标树，按 `metric-mutation.md` 完成指标创建闭环，拿到指标 ID 后再回到本文。
 4. 如果指标拆解里出现复合指标公式，读取 `metric-composite-mutation.md` 和 `metric-expression-rules.md`，理解 `formula` 中 `[metricId]` 的含义。
-5. 只在最终提交时使用 `guanmetric metric-tree`；不要用裸 `fetch` 调指标树写接口。
+5. 构造请求或解析响应前读取 `metric-tree-api-contracts.md`，不要混用详情、列表和写入模型。
+6. 只在最终提交时使用 `guanmetric metric-tree`；不要用裸 `fetch` 调指标树写接口。
 
 ## 能力边界
 
@@ -21,6 +22,7 @@
 - `rename`：原地更新指标树名称。
 - `move`：原地移动指标树目录。
 - `update-config`：原地更新指标树配置。
+- `delete`：默认展示待删除详情，追加 `--confirm` 后删除指标树。
 
 不要用删除重建模拟指标树编辑。指标树 ID 可能被归因入口、页面链接、目录和外部系统引用，删除重建会造成断链。
 
@@ -100,8 +102,31 @@
 | 打开贡献分析/贡献排序 | 时间对比 + 贡献计算 | 必须根指标时间配置合法 |
 | 改名 | 原地重命名 | `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；写操作前可执行：
@@ -458,13 +483,16 @@ guancli metric_attribution query <metric_tree_id> --target index
 | 重命名 | `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` |
-| 查询目录树 | `guancli metric_attribution tree` | `GET /api/directory/METRIC_TREE/authorized-tree` |
+| 查询目录树 | `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 dir-create`：封装 `METRIC_TREE` 目录创建。
 - `metric-tree init-config <root_metric_id>`：按前端初始化逻辑生成默认 config。
 - `metric-tree validate-config`：离线校验维度、交叉维度、指标关系树和时间对比开关。
 - `metric-tree plan`：从简化 DSL 或用户公式生成 create/config JSON。

package/skills/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，本阶段沿用创建请求中的后端权威校验，不新增接口。