schema-explorer

架构浏览器

使用 dxs schema 命令发现 OData 架构。

参考资料

• references/batch-syntax.md — 批量命令语法、参数样式、describe-entity 标志和反模式
• references/subagent-template.md — 子 Agent 委派提示词

Footprint 连接 — 请先检查 entity-expert 技能

如果连接是 FootPrintApi 连接（Footprint WMS 数据 — Tasks、Shipments、ArchivedShippingLicensePlateContents、LicensePlate、Lot、Material 等），请先检查 footprint-entity-expert 技能，再浏览架构。它记录了 OData 元数据中不可见的导航链、业务规则筛选条件和重量计算方式，并会告诉你哪个实体实际对应某个业务概念（例如，“已发货库存” → ASLPC，而不是 Shipments）。非 Footprint 连接无需检查此技能。

解析连接

架构命令需要连接 ID（-c <id>）。用户可能会明确提供，也可能不会。

如果用户提供了连接 ID 或名称 — 直接使用。例如：“使用连接 9”、“使用 Prod 连接”。

如果用户提到类似“在 Prod 中”或“在 Demo 环境上” — 查找匹配的 FootprintApi 连接：

1. dxs auth status — 获取已验证组织的 ID
2. dxs organization connection list --org <org_id> — 列出所有连接
3. 筛选 apiConnectionTypeName: FootPrintApi 并匹配名称

如果用户完全没有指定连接 — 列出可用的 FootprintApi 连接，并询问要使用哪一个：

1. dxs auth status — 获取组织 ID
2. dxs organization connection list --org <org_id> — 列出连接
3. 只向用户展示 FootprintApi 连接（筛除 MongoDB、AMQP、SFTP 等），并请用户选择一个

输入/输出约定

输入： 连接 ID + 搜索关键词

输出： 结构如下的 field-mapping.md 文件：

# Schema: <EntityName>

## Connection
- Connection ID: <id>
- Namespace: <namespace>

## Primary Entity
- Entity Set: <name>
- Entity Type: <namespace.type>
- Keys: <key fields and types>

## Fields

### Root Fields
| Field | Type | Notes |
|-------|------|-------|

### Navigation Properties
| Nav Property | Target Type | Cardinality | Key Fields |
|-------------|-------------|-------------|------------|

### Expanded Fields (via $expand)
| Path | Type | Source Entity | Binding |
|------|------|---------------|---------|

Mark the **Binding** column:
- `flat` — field is reachable through single navigation properties; safe for flat DataSet fields
- `⚠ collection` — path crosses a collection navigation property (1:N cardinality); requires flow datasource flattening or child dataset with `CommandText` deep path. Will silently render blank if added as a flat DataSet field.

## Composite Keys / Special Notes

命令选择规则

单个请求 → 使用直接命令。多个独立请求 → 合并为一个批量命令。

• 如果只需要一个操作（例如一次搜索、一次 describe），请使用直接命令 — 不要将其包装在只有一个 --request 的 dxs schema batch 中。
• 如果需要 2 个或更多独立操作，请将它们全部合并到一次 dxs schema batch 调用中。不要将独立请求拆分到多次批量调用中 — 每次调用都需要单独进行一次 HTTP 往返。
• 只有在第一次调用的结果决定接下来要查询什么时，才拆分为第二次调用。
• 为每个列表命令限定范围。 entities、actions、properties 和 indexes 在没有筛选条件时会返回整个模型 — 在实际连接中，每次调用的数据量可能达到几十到数百 KB，其中 indexes 的数据量最大。每个命令都有自己的缩小范围标志：properties / navigation-properties 使用 --entity-type，indexes 使用 --entity-set 和 --covering，以上所有命令都支持 --search 和 --filter。使用 -n 和 --skip 分页；如果只需要数量，请使用 --count。

工作流

1. 搜索实体 — 将所有关键词搜索合并为一批：

   dxs schema batch -c <id> \
     --request 'search shipment' \
     --request 'search order' \
     --request 'search warehouse' \
     --request 'search carrier'
   

   如果能猜出实体集名称，请将搜索与描述操作合并到同一批次中。搜索结果包含完整限定的 entity_type（例如 Datex.FootPrint.Api.Warehouse）——请保存这些值，以便在后续步骤的 --entity-type 标志中使用。

   对于单个关键词，使用直接命令：dxs schema search "keyword" -c <id>。

2. 描述实体和关系 — 将所有实体描述和关系探索合并为一批。在 describe-entity 上使用 --compact --no-udf，在 relationships 上使用 --depth 2：

   dxs schema batch -c <id> \
     --request 'describe-entity Shipments --compact --no-udf' \
     --request 'describe-relationships Shipments --depth 2' \
     --request 'describe-entity Orders --compact --no-udf' \
     --request 'describe-relationships Orders --depth 2' \
     --request 'describe-entity ShipmentLines --compact --no-udf' \
     --request 'describe-relationships ShipmentLines --depth 2'
   

   初步探索时使用 --compact。如果之后需要了解特定字段的完整详情，请使用 --select Field1,Field2，仅描述这些属性。

3. 扫描相关实体字段 — 将所有相关实体扫描合并为一批。对于计划使用 $expand 的每个导航属性目标，使用 describe-entity --compact --no-udf：

   dxs schema batch -c <id> \
     --request 'describe-entity Materials --compact --no-udf' \
     --request 'describe-entity Lots --compact --no-udf' \
     --request 'describe-entity Addresses --compact --no-udf' \
     --request 'describe-entity Contacts --compact --no-udf' \
     --request 'describe-entity Warehouses --compact --no-udf' \
     --request 'describe-relationships Warehouses --depth 2'
   

   跳过步骤 2 中已通过 describe-relationships --depth 2 覆盖的实体——深度为 2 的输出包含嵌套导航属性名称和目标类型。仅当需要 $select 子句的标量字段列表时，才扫描实体。

   只有类型 ID 时（例如关系输出中的 Datex.FootPrint.Api.Warehouse），如果不知道实体集名称，请改用 properties --entity-type Namespace.Type——它可以直接接受完整限定类型。若还需要 $expand 路径，请同时使用 navigation-properties --entity-type。

   注意： 如果需要某个相关实体的 $expand 路径（即从该实体开始可以展开什么），这些路径位于其 navigation_properties 输出中——describe-entity --compact 同时包含标量属性和导航属性。

4. 解析枚举值 — 如果某个属性的类型不以 Edm. 开头，则它是枚举或复杂类型。将所有枚举查询合并为一批（如果只有一个，则使用单条直接命令）：

   dxs schema batch -c <id> \
     --request 'describe-enum Datex.FootPrint.Api.Statuses' \
     --request 'describe-enum Datex.FootPrint.Api.OrderTypes'
   

   这会说明筛选值的含义（例如，StatusId eq 1 →“Active”）。

5. 验证展开路径 — 调用 odata-execution 技能，确认导航属性会返回数据（$top=1 + $expand）。某些实体的导航属性具有 NULL 外键，因此展开结果为空。

   需要验证的内容：

   • 深层路径（深度 >= 2，例如 OrderLine.Material.Description）——失败风险较高
   • 经过可空外键的路径（例如 ShipToContactId 可为空时的 ShipToContact）
   • 集合经过集合的展开（例如 ShipmentLines($expand=OrderLine(...))）
   • 任何你不确定的路径

   可以放心跳过： 展开到查找实体的单层路径（Status、Type、Category 模式），且外键不可为空。这些路径由架构保证有效。

   记录未覆盖的情况，并建议替代查询路径（例如直接通过筛选条件查询相关实体）。如果需要在展开的集合中进行筛选，也请测试 lambda 运算符（any()/all()）。

6. 构建字段映射表 — 将发现的所有字段整理到字段映射模板中，并区分根字段、导航属性和展开字段。

   明确说明缺失项。 如果用户询问的概念（例如“成功/失败”“逾期订单”“优先级”）在架构中没有对应的直接字段，请在字段映射中说明。解释不存在的内容与记录存在的内容同样有价值——这能避免用户继续查找不存在的字段，并让他们决定采用哪种变通方案（派生计算、外部查询等）。

索引注意事项

需要高于 0.5.5 的 dxs 版本——这些命令是在 0.5.5 标签之后合并的。在较旧的构建版本中， dxs schema indexes 不存在，且 describe-entity 不会返回 indexes 键。缺少该信息是 CLI 导致的，而非元数据本身所致，也不能据此判断存储情况。 元数据会报告每个实体集背后的物理数据库索引。每当你映射的架构会在大型实体集上进行筛选或排序时，都要检查这些索引——未建立索引的谓词通常会导致数据源在生产环境中超时，却在小型开发数据集上表现正常。

describe-entity 已经会返回实体集的索引，不会增加 HTTP 调用，因此如果你执行了第 2 步，就已经拿到了这些索引——--compact、--no-udf 和 --properties-only 都会保留它们。只有在需要跨实体查询时，才使用 indexes 命令：

dxs schema batch -c <id> \
  --request 'indexes --entity-set Shipments' \
  --request 'indexes --covering ModifiedSysDateTime'

--covering COLUMN 是 Columns/any(c: c/Name eq 'COLUMN') 的简写——无需手写 lambda，即可查询“这个列是否在任何地方都已建立索引？”

并非所有 Footprint 服务都会报告索引。 架构服务必须公开 Indexes 实体集，而旧版本并不支持。CLI 会在每个连接上探测一次（缓存 24 小时），并据此调整，而不是让请求失败：indexes 和 describe-index 会以 DXS-SCHEMA-015 拒绝请求，而 describe-entity 会移除可选的 expand，不返回 indexes 键。直接调用 describe-entity 时会在警告中说明原因；在批处理中则不会说明任何内容——该键只是缺失，因此在批处理路径中，若缺少 indexes 键，应先直接查询此连接，再得出任何结论。在批处理中，仅查询索引的请求会在本地返回该错误，不会发送出去，因此一项不受支持的请求不会连带导致整个批处理失败。能力缺失是关于服务版本的事实，不是第四种索引发现结果：它完全不能说明存储情况。应表述为“此服务不报告索引元数据”，绝不能说“没有索引”。

解读输出时要注意三点：

• 若要仅按该列筛选并使用索引查找，key_ordinal 必须为 1。 (StatusId, AccountId) 上的索引无法帮助仅按 AccountId 筛选。
• is_included: true 不代表可用于筛选。 该列会随索引一起返回，以便在无需查找的情况下满足 $select；但仅按该列筛选仍会扫描。
• 未报告索引表示未知，而非没有索引。 空结果——describe-entity 中的 indexes: []，或空的 indexes 列表——表示元数据没有提供有关该实体集的信息，并不表示其存储中没有索引。处于此状态的实体集在 API 中始终为只读，但其中有几个看起来像普通的带键表，因此很可能存在索引，只是没有报告。不要断定对该实体集进行筛选会扫描——也不要断定会使用索引查找。在映射中应写“没有索引信息”。

--covering 返回空结果可能有三种含义，而指定范围只能排除其中一种。 --entity-set 可以排除拼写错误：如果该实体类型上不存在某个列，请求会以 DXS-SCHEMA-014 失败，而不是返回空结果。但它不能排除未报告的情况——如果实体集完全没有报告索引，即使限定了范围，未命中仍然表示“未知”，正如第三点所述。要得出确定结论——“此列未建立索引，按它筛选会扫描”——必须同时满足两个条件：指定范围，并且实体集至少报告一个索引。若未指定范围，就没有实体类型可用于验证列名，因此无法区分“任何地方都未建立索引”和“拼写错误”。在整个模型范围内使用 --covering 来查询“此列在哪些地方建立了索引”完全没问题，但如果答案会影响 $filter，就应重新指定范围：

dxs schema indexes -c <id> --entity-set Shipments --covering ModifiedSysDateTime

让 CLI 告诉你遇到了上述哪种情况，不要自行推断——但要留意答案的位置，因为不同路径会有所不同：

路径	文案出现的位置
dxs schema indexes，结果为空且使用 --entity-set / --covering 限定范围	metadata.index_hint
dxs schema batch 中的 indexes，同样的情况	该请求的 warnings[]
直接调用 describe-entity，且 indexes: []	metadata.index_hint
在批处理中调用 describe-entity，且 indexes: []	该请求的 warnings[]
返回空结果的未限定范围的 indexes 列表	无文案——在据此得出任何结论前，先限定范围
完全没有 indexes 键	直接调用 describe-entity：会有一条指出服务名称的警告。在批处理中，或使用不支持此功能的旧版 CLI 时：无文案——无论如何都不能据此判断该实体集

每个可以据以推理的空结果都会附带相应文案；唯一没有文案的是未限定范围的查询结果，而这也正是最不能证明任何事情的结果。

如果预期的过滤列没有以该列为首列的索引，请在根字段表中该字段旁边的 备注 列说明。这是数据源设计中的实际限制，不是脚注。

受保护的过滤器可能消失，索引也就失去了作用。 dxs datasource generate 为过滤器添加参数的所有方式，都会用 $utils.isDefined() 守卫包裹谓词，因此运行时如果缺少参数，谓词就会被移除，而你刚刚检查过索引的查询就会扫描整张表。没有任何生成选项能输出必需且不受守卫保护的过滤器——尤其是 --detect-params，尽管它的名称听起来像是可以做到这一点。

因此，参数化过滤器上的索引检查，效果取决于其背后的绑定。请在索引发现旁报告限定范围的参数，并交由 datasource-creator 处理：其 references/odata-datasources.md → “受守卫保护的限定范围过滤器会使索引检查失效”一节说明了相关机制以及弥补这一缺口的两种方法。

子 Agent 用法

架构探索可能会产生大量输出。请委派给子 Agent，以保持主上下文简洁。提示词模板见 references/subagent-template.md。

将输出写入工件目录：

• 01-schema-exploration.md — 原始架构发现输出
• 02-field-mapping.md — 已完成的字段映射表

describe-entity 标志

describe-entity 不支持 --concise。完整的显示标志表（--compact、--no-udf、-P、-N、--prop-top、--select）请参阅 references/batch-syntax.md。所有标志均可在批处理中使用：--request 'describe-entity Orders --compact --no-udf'

其他规则

上方工作流步骤中已包含的规则不再重复。完整的反模式表请参阅 references/batch-syntax.md。

• 务必检查 keys: 部分——某些实体使用复合键（没有 Id 字段）
• describe-properties 一次只接受一个属性名称——不能用逗号分隔；批量发现请使用 describe-entity --compact --no-udf，或在批处理中调用多次
• 任何 schema 命令返回 DXS-API-CONN / DXS-API-TLS / DXS-API-TIMEOUT / DXS-API-NET 错误，表示网络故障，而非实体名称错误——请按照负载中的 suggestions[] 操作；另请参阅 configuration-roundtrip.md → 退出码 141 与传输错误
• 批处理消除了“按顺序运行”的限制——与并行工具调用（某个调用失败会导致其他调用中止）不同，批处理能妥善处理各个请求的失败情况