footprint-entity-expert

Footprint 实体专家

Footprint WMS 领域知识参考。这些知识无法仅从 OData 元数据推导出来，涵盖导航链、业务规则筛选条件、重量计算，以及其他通常需要通过逆向分析现有报表才能了解的背景信息。

此技能位于 schema-explorer 和 datasource-creator 之上：在这两个技能执行验证字段和生成配置等机械性工作之前，它会告诉你应该探索哪些实体，以及有哪些注意事项。

何时使用此技能

工作内容……	使用此技能？
查询 Tasks、Shipments、License Plates、Inventory、Materials、Lots 等内容的报表或流程	是 — 从此处开始，再探索架构
基于 Archived... 实体（发货或收货历史记录）创建数据源	是 — 归档实体有特定的导航链
重量或计量单位计算（箱重、托盘重量、合计）	是 — 固定重量与浮动重量之间的分支逻辑并不直观
与 WMS 数据无关的应用或报表（自定义组织设置、通用仪表板）	否 — 此技能不适用
基于客户自行添加的数据制作报表（自定义 Material 扩展字段等）	部分适用 — 使用实体参考了解标准字段，然后通过 schema-explorer 验证客户扩展字段

如果不确定数据是否属于 Footprint 数据，可以查看连接的 apiConnectionTypeName：FootPrintApi 表示是，其他值则很可能不是。

使用方法（渐进式展开）

此 SKILL.md 是一个索引，不是具体内容。不要试图一口气读完以下所有内容：先在表格中找到所需主题，再阅读对应的参考文件。每个参考文件都是自包含的：包括实体定义、导航链、注意事项，以及一个完整的 OData 查询示例。

此索引分别列出实体和跨实体的关注点，因为有些模式（重量逻辑、所有者导航）会在多个实体中反复出现。

实体参考

实体 / 领域	参考文件	何时查阅
ArchivedShippingLicensePlateContents (ASLPC) — 历史发货库存	references/archived-shipping-lpc.md	构建发货历史报表、按发货量计费的查询，以及任何过去会使用 SQL ShippingActivityRaw 视图的场景
筛选为收货任务的 Tasks	references/receiving-tasks.md	构建收货活动报表、从码头到入库的指标，以及任何统计已收货单位数 / 托盘数 / 重量的场景

跨领域参考

主题	参考文件	何时查阅
Owner / Project 导航链	references/owner-navigation.md	任何按 Owner 或 Project 分组、筛选或标记的报告——不同实体的路径各不相同
重量计算（固定重量与变动重量）	references/weight-and-units.md	任何总重量或每个 LP 的重量计算——公式取决于 Material.IsFixedWeight
状态与操作代码（Order / Shipment / Wave / Task / OperationCodeId）	references/footprint-status-codes.md	任何由状态驱动的筛选或生命周期逻辑——元数据给出 StatusId : Edm.Int32，但未说明各整数的含义；还涵盖补货门控拣货、创建时已完成的装载任务，以及 Task.Result/Notes 负载字段
实体 ID 预留（$api.ReserveEntityIdBatch）	references/entity-id-reservation.md	批量创建时预先预留 ID——NewIdCeiling 是预留范围的上限；ceiling - idx 映射仅适用于从 0 开始的稠密计数器
销售订单行创建（create_sales_order_line_action 与 create_sales_order_lines_action）	references/order-line-creation.md	任何创建订单行的流程——批量操作要求订单行信息完整（MaterialId、计算出的 Amount、包装；不能只有序列号）；向导/UI 创建必须循环调用单条操作，该操作会从批次推导物料

此处刻意不包含的内容

• 按客户定制的业务规则——需要排除的订单类别 ID、自定义状态、计费等级等。这些因客户而异，应放在客户专属文档中，而非此处。本技能提及排除项时（例如常见的收货订单类别），会标注为“常见情况，但请按客户核实”。
• OData 机制——$expand、$filter、分页的工作方式。这些内容见 schema-explorer、datasource-creator，以及 'datex-studio-shared' 技能中的 flow-code-patterns.md。
• 没有特殊情况的标准 CRUD 实体——Warehouse、Carrier、Pack 等。请直接使用 schema-explorer；这些实体无需单独的参考页面。
• UI / hub 配置——Footprint hub 和网格的配置方式。相关内容见 datex-studio/hub-editor。

在会话中发现新的实体注意事项时，请在此处添加参考文件，而不是让相关知识只留在提交历史中。

与其他技能的关系

[user asks for a Footprint report]
        |
[footprint-entity-expert]   ← THIS SKILL: which entities, what gotchas?
        |
[schema-explorer]           ← validate the entity exists on this connection,
        |                     confirm property names and types
[datasource-creator]        ← generate the OData/flow datasource using
        |                     the validated schema + the rules from this skill
[report-creator]            ← assemble the report

此技能每个实体查阅一次，而非每次查询都查阅。输出是一份心智模型：哪个 OData 实体对应业务概念、要展开什么、要筛选什么、如何处理重量，以及通过哪条导航链访问 Owner。将这些理解传递给 datasource-creator，让其架构验证工作有明确方向。