impact-analysis

影响分析

评估修改或移除 Datex Studio 分支上的配置所造成的影响。此技能仅分析依赖关系，不会进行任何更改。

适用场景

• 修改任何配置的输入／输出参数之前
• 重命名或移除分支上的配置之前
• 为存储添加 required: true 字段或更改存储列的结构之前
• 进行其他任何会破坏契约的编辑之前
• 调用技能需要确认契约变更是否安全时，例如：
  • function-creator — 更改函数的输入／输出参数之前
  • datasource-creator — 更改数据源结构之前
  • storage-creator — 重命名／移除列或添加必填字段之前
  • type-definition-creator — 移除或调整 _dd / i_* / e_* 类型之前
  • db-query / action-creator — 更改存储架构之前，或诊断契约问题时

工作流

分支选择。 按照 ../datex-studio-shared/branch-setup.md 选择分支／连接 — 切勿假设分支 ID；请先与用户确认，或先列出功能分支。

步骤 1：查找调用方

dxs source explore reverse-trace <reference_name> --branch <branch_id>

这会返回所有引用目标的配置。如果已知配置类型（例如 --type flow、--type datasource），可使用 --type <type> 加快查找。

步骤 2：解读结果

按类型对引用配置进行分类：

• 流程／函数 — 通过 $flows.* 调用目标
• 数据源 — 通过 $datasources.* 引用目标
• 表单／网格／编辑器 — 绑定到目标的 UI 组件
• 报告 — 通过 $reports.* 引用目标

如果要重命名、移除存储列，或添加必填字段，请进一步将调用方分为：

• 写入端调用方 — 对存储执行 insert / update / patch 的配置（对必填字段或重命名变更风险最高；如果不随存储编辑一并更新，运行时将失败）
• 读取端调用方 — 仅查询／读取存储的配置（风险较低；过滤条件或投影中可能会出现过期的字段名称）

如果某个调用方的引用存在歧义（例如，字符串字面量看起来像引用，但也可能是内嵌内容），请将其标记为“待审核”，不要将其计作真实调用方。由调用技能或用户进行判定。

列级粒度（存储结构变更）。 reverse-trace 报告的是配置级关系 — 它会指出哪些配置写入存储，但不会指出每个配置设置了哪些列。如果变更涉及特定列（重命名、移除或添加 required: true），请从分支获取每个写入端调用方的正文（dxs source explore config <caller_ref> --branch <id>），并检查其内嵌代码中的 $db.<Pkg>.<storage>.insert/update/patch 载荷，确认是否涉及该列。这样便可恢复配置级追踪本身无法提供的列级写入端分析 — 无需搜索本地目录树。

步骤 3：决策关口

• 未找到调用方 — 可以安全继续。告知调用技能／用户。
• 存在调用方 — 向用户提供完整列表，包括：
  • 每个调用方的引用名称和类型
  • 可能造成的问题（例如：“这 3 个流程使用 2 个参数调用 fn_sum — 将参数改为 3 个会导致它们出错”）
  • 在继续操作前请求用户明确确认

步骤 4：返回调用方

向调用技能报告决策：

• 安全 — 没有调用方，可继续更改
• 已批准 — 存在调用方，但用户已批准；调用技能必须在本次更改中更新所有受影响的调用方
• 已拒绝 — 用户决定不继续

其他命令

命令	使用场景
dxs source explore trace <name> --branch <id>	了解目标依赖的内容（正向依赖）
dxs source explore graph <name> --branch <id>	可视化完整依赖链（两个方向）

范围边界

• 此技能仅进行分析，绝不会修改配置
• 调用此技能的技能负责更新受影响的调用方
• 不涵盖引用名称变更——这需要先删除再重新创建，并应提醒用户手动操作
• 仅分析一跳。 报告目标的直接调用方。不要追踪传递影响（“此函数由 X 调用，而 X 又由 Y 调用”）——是否进行传递分析由调用此技能的技能或用户决定。如果用户需要完整调用链，请改用 dxs source explore graph <name> --branch <id>。
• 对有歧义的匹配不作推测。 如果某个引用存在歧义（字符串字面量与实际绑定、注释与配置字段），请标记为需要审核，而不要将其归类为实际调用方。
• 没有调用方就停止。 如果 reverse-trace 没有返回调用方，请如实报告并停止。不要建议相似的引用名称，也不要扩大搜索范围。