component-wiring-check

组件连线检查

审查 Datex Studio 分支上的跨组件引用契约——验证一个组件对另一个组件的引用（例如，挂载网格的枢纽标签页、指向选择器的枢纽筛选器、指向数据源的网格 datasourceConfig、由数据源支持的选择器，以及通过 $shell.<Package>.open<referenceName>Dialog 打开的表单）是否满足完整契约。这是一项只读审计技能：它读取配置、报告发现的问题，并将修复任务交给对应的创建技能。它绝不会修改分支上的配置。

**另请参阅：**创建技能（hub-creator、grid-creator、form-creator、editor-creator、selector-creator）——每个技能负责处理本审计发现的问题，并完成往返与推送步骤。

参考资料

• ../datex-studio-shared/branch-setup.md — 分支／连接选择（各技能共用）
• references/component-wiring.md — 权威连线规则参考：三个静默失败陷阱、moduleId 规则、configParameters ↔ inParams 镜像关系、vars / rowVars 声明规则
• ../datex-studio-conventions/defaults.md — 新建组件的默认包（不适用于引用现有组件——务必不要混淆两者）
• ../tailoring-overlay/ — 覆盖层专用的影子标记规则（“导入时契约已过时”这一现象属于单独的定制问题）

依赖项

• grid-creator / hub-creator / form-creator / editor-creator / selector-creator 技能——当本审计发现需要应用的修复时，由下游调用（本技能报告发现的问题；创建技能负责往返与推送）
• tailoring-overlay 技能——当问题表现为定制覆盖层上的“契约已过时”，而不是基础组件上的连线漂移时调用
• post-edit-verification / component-validator 技能——修复落地后，由应用修复的创建技能调用（本审计不会直接调用）

CLI 生命周期

组件连线审计为只读操作——它会获取配置并检查契约，但绝不会推送更改。没有 dxs componentwiringcheck 子命令；审计使用通用的 dxs configuration get / list 基本操作，拉取所需组件进行比对。

获取单个组件以供检查：

# 1. Fetch — note the envelope wrapper
dxs configuration get <type> <configId> -b <branchId> -O envelope.json
# 2. EXTRACT THE INNER BODY (same envelope-vs-body distinction as the creator skills)
jq .json envelope.json > body.json
# 3. Inspect — read inParams, configParameters, moduleId, vars, rowVars

在分支上查找候选组件：

# List configs of a given type — filter to the components you want to audit
dxs configuration list <type> -b <branchId>

本审计发现的问题由对应的创建技能（hub-creator、grid-creator 等）应用；该技能负责完成往返规则（get -O envelope.json → jq .json → 编辑 → upsert）。本技能不会调用 dxs configuration upsert——如果你发现自己准备调用它，请改为交给创建技能处理。

工作流

[Phase 1: Setup + target components]
Follow branch-setup.md for branch/connection selection
        |
Identify the reference under audit:
  - referencing component (the caller — hub, grid, form, ...)
  - target component (the callee — grid, selector, datasource, form, ...)
  - the reference site (hub filter, hub tab, grid datasourceConfig,
    selector datasource, dialog opener)
        |
[Phase 2: Audit reference contracts]
Walk the three silent-failure traps (see references/component-wiring.md):
  1. moduleId matches the target's package?
  2. configParameters mirrors target inParams one-to-one
     (no missing, no extras)?
  3. vars / rowVars declares every $<component>.vars.<id> /
     $row.vars.<id> used in flow code?
Cross-check tailored overlays separately (see tailoring-overlay)
        |
[Phase 3: Report findings]
For each trap that fires, surface:
  - what's broken (target id / inParam / var)
  - which component file owns the fix (caller vs callee)
  - which creator skill applies it
NO `dxs configuration upsert` from this skill — defer to the
creator skill that owns the component being edited
        |
[Phase 4: Re-audit (optional, after fixes land)]
Re-fetch the same configs and walk the three traps again.
Clean run = no findings.

阶段详情

阶段 1：设置与目标组件

1. 按照 ../datex-studio-shared/branch-setup.md 选择分支和连接。绝不要假定分支 ID——请用户确认。
2. **确定引用位置。**连线审计始终针对一对（或一串）特定组件。请确定：
   • 引用组件（调用方）：挂载网格的 hub、datasourceConfig 指向某个 datasource 的网格、其 datasource 为下拉列表提供数据的选择器、通过 $shell.<Package>.open<referenceName>Dialog(...) 打开表单的操作。
   • 目标组件（被调用方）：接收该引用的网格、选择器、datasource、表单或编辑器。
   • 引用位置：hub 筛选器（→ 选择器）、hub 标签页 contentConfig（→ 网格或其他组件）、网格 datasourceConfig（→ datasource）、选择器 datasourceConfig（→ datasource）、操作层对话框打开器（→ 表单/编辑器）。
3. 使用 dxs configuration get <type> <configId> -b <branchId> -O envelope.json 获取两个组件，并分别通过 jq .json 提取 body.json。审计读取的是组件主体；此技能不会进行任何编辑。

第 2 阶段：审计引用契约

按顺序检查以下三个陷阱。每项均在 references/component-wiring.md 中有完整说明；以下摘要是审计清单。

1. moduleId 与目标组件所在的包一致。 在每个引用位置，moduleId 字段都应填写目标组件所在的包，而不是调用方的包，也不是功能文件夹名称。直接打开目标组件文件，查看其包声明（如果不明显，也可以询问用户）。不要根据功能文件夹名称推断，也不要使用新组件的默认值 Utilities——该默认值适用于新建组件，不适用于对现有组件的引用。请参阅 references/component-wiring.md → Cross-Component References Use the Target's Module。

2. configParameters 与目标组件的 inParams 一一对应。 比较这两个数组：

   • 对目标组件 inParams 中的每一项，确认引用中的 configParameters 都有对应项（id / type / isCollection 相同）。未使用的参数也要保留在契约中，并显式设置 value: null / ""。缺少的项在运行时会悄然表现为未定义的输入——例如下拉列表为空、列表筛选错误。
   • 对 configParameters 中的每一项，确认目标组件的 inParams 声明了对应的 id。多余的项属于无效连线——其值会被悄然丢弃，调用方以为数据正在传递，目标组件却收不到。这一方向的风险更大。无论目标组件的 inParam 是否设置了 required: true/false，此规则都适用。

   当目标组件的结构不符合调用方需求时（例如，某个 hub 想通过 project_ids 限定 grid 的范围，但该 grid 尚未声明此 inParam），应当扩展目标组件，而不是向调用方添加虚构的条目。请参阅 references/component-wiring.md → Reference Contracts Include Every Target inParam。

3. 声明 Vars / rowVars。 对于流程代码中读取或写入的每个 $<component>.vars.<id>（$form.vars、$hub.vars、$editor.vars、$grid.vars），确认组件顶层的 vars[] 数组中存在对应条目。对于 grid，还要确认行流程（on_save_new_row、on_save_existing_row 等）中使用的每个 $row.vars.<id>，都在 grid 的 rowVars[] 中有对应条目。两个数组都使用与 inParam 相同结构的描述符。请参阅 references/component-wiring.md → Component Variables Must Be Declared。

4. 定制覆盖层是另一个独立问题。 如果问题表现为“导入时契约过时”，而不是运行时漂移，原因是定制覆盖层的影子标记漂移，而非基础组件的连线漂移。请转交给 tailoring-overlay 技能。

阶段 3：报告发现

对于每个触发的陷阱，编写一条发现，说明损坏的契约及负责修复的技能：

陷阱	报告内容	负责修复的技能
moduleId 不匹配	调用方组件 + 引用位置 + 观察到的 moduleId + 目标的实际包	调用方的创建技能（引用位于调用方一侧）
缺少 configParameters 条目	调用方组件 + 引用位置 + 镜像中缺失的目标 inParam id	调用方的创建技能
多余的 configParameters 条目	调用方组件 + 引用位置 + 多余的 id + 决策：删除调用方的条目，或扩展目标的 inParams	如果删除：调用方的创建技能。如果扩展：目标的创建技能。
未声明的 vars / rowVars	组件 + 在流程代码中观察到的 var id + 在 vars[] / rowVars[] 中缺少的声明	拥有该流程代码的组件的创建技能

此技能不会推送修复。 列出发现，指出负责每项修复的创建技能，然后停止。创建技能负责执行往返规则（dxs configuration get -O envelope.json → jq .json envelope.json > body.json → 编辑 → dxs configuration upsert）；在审计技能中直接应用修复会绕过该契约，并可能导致配置内容在不知情的情况下被破坏。

阶段 4：重新审计（可选）

修复完成后，重新获取相同组件（dxs configuration get <type> <configId> -b <branchId> -O envelope.json，通过 jq .json 提取），并再次检查这三个陷阱。干净的运行 = 没有发现。重新审计成本很低；每当修复涉及多个组件文件，或原始审计发现超过两项时，都应执行重新审计——如果调用方和目标没有原子化地更新，同一次编辑中就可能再次出现偏差。

静默失败症状——诊断索引

当用户报告的是症状而非已知的损坏契约时，此表会将症状映射到应优先审计的陷阱。底层机制请参阅 references/component-wiring.md。

症状	可能原因
下拉列表为空	选择器的后备数据源收到未定义的输入（挂载位置缺少 configParameters 条目）
下拉列表显示了错误的选项	选择器收到的真实 inParam 值错误（绑定表达式有误，或多余的 configParameters 条目遮蔽了真实值）
网格筛选器不起作用	Hub 筛选值没有传递到网格（存在多余的 configParameters 条目；网格未声明该 inParam）
Hub 筛选器没有传递到选项卡	选项卡的 configParameters 缺少该条目，或网格缺少该 inParam
对话框无法打开	$shell.<Package>.open<referenceName>Dialog 使用了错误的包（不是目标表单所属的包）
组件已解析，但行为异常	引用上的 moduleId 有误
流程代码中的 Var 未定义	顶层 vars[] 中缺少声明（网格行流程则缺少 rowVars[] 中的声明）
导入时提示“Outdated contract”	定制覆盖层的影子配置已偏离其基础配置——交由 tailoring-overlay 处理

预检清单

审查跨组件引用时，请逐项检查。完整清单见 references/component-wiring.md；快速版如下：

1. moduleId 与目标组件的 package 一致——通过阅读目标组件文件或询问用户确认。不要根据功能文件夹或 Utilities 新建组件默认值推断。
2. configParameters 与目标的 inParams 一一对应——每个 inParam 都有一项（未使用的项设为 value: null / ""）；没有多余项。
3. 如果目标与调用方的需求不同步，应在同一次编辑中扩展目标，而不是在调用方添加虚构条目。调用方的 configParameters 只能描述目标实际接受的参数。
4. 流程代码中写入的每个 $<component>.vars.<id> 都必须在组件顶层的 vars[] 数组中声明。
5. 网格的 rowVars[] 必须声明行流程读取或写入的每个 $row.vars.<id>。
6. 对话框打开器使用目标表单的 package——$shell.<TargetPackage>.open<referenceName>Dialog(...)，其中 <referenceName> 使用 snake_case（不要使用 camelCase）。

常见错误

错误	修正方法
moduleId 设置成调用方的 package，而不是目标的 package	直接读取目标组件文件中的 package 声明，或询问用户。不要查看功能文件夹，也不要使用 Utilities 默认值。
根据功能文件夹名称推断 moduleId	功能文件夹可能包含不同的 package——FootprintManager 中的 hub 旁边可能就是 Carriers 中的选择器。Package 是组件级属性，不是文件夹属性。
Tab 的 configParameters 绑定了网格未声明为 inParam 的 id	这是无效绑定——运行时会静默丢弃。要么删除绑定，要么通过 grid-creator 在同一次编辑中扩展网格的 inParams（以及底层数据源）。
调用方的 configParameters 缺少目标声明的某个 inParam	目标会静默地解析未定义的输入——导致下拉列表为空或列表筛选错误。添加该项；如果调用方不打算绑定它，请使用 value: null / ""。
写入 $form.vars.<id> = ...（或 $hub.vars.* / $editor.vars.* / $grid.vars.*），却未在顶层 vars[] 中声明 <id>	变量不在类型化接口中——导入时不会校验其结构，下游代码也无法依赖它。声明每个变量。
在网格行流程中写入 $row.vars.<id>，却未在 rowVars[] 中声明 <id>	同类问题，但作用于行作用域。在 rowVars[] 中声明（描述符结构与 vars[] 相同）。
对话框打开器使用调用方的 package，而不是目标表单的 package	$shell.<Package>.open<referenceName>Dialog(...)——<Package> 是表单的 package，<referenceName> 使用 snake_case。
在此审查技能中直接应用修复，而不是使用相应的创建器技能	此技能为只读——它负责审查，不负责修改。将修复交给 hub-creator / grid-creator / form-creator / editor-creator / selector-creator。这些技能负责安全推送的往返规则。
将“导入时契约过时”误认为连线漂移	这种现象是定制覆盖层的 shadow-marker 漂移，而不是运行时连线问题。请转交给 tailoring-overlay。

审查发现问题后，将每项发现转交给相应的创建器技能（grid-creator、hub-creator 等）进行修复。修复完成后重新调用此技能，验证运行结果正常。