report-creator

报表创建器

使用 dxs CLI 构建和部署 RDLX-JSON 报表的工作流。报表会在 Datex Studio 中通过 ActiveReportsJS 渲染。

**核心原则：**先规划，再编写代码。先构建布局原型，再编写最终 JSON。

**原型设计：**此技能有专属的可视化原型工作流——使用 dxs report create + dxs report batch + dxs studio open 在浏览器中实时预览。除非用户明确要求，否则不要使用外部头脑风暴可视化辅助工具、基于浏览器的模型工具或其他原型设计工具。Studio 实时预览就是设计工具。

编写方式：

• 实时原型设计，用于创建新报表——创建空白 .rdlx-json，使用 dxs report create + dxs report batch 逐步构建布局，并在 Studio 中实时预览
• 增量式 CLI（add/set/move/remove/batch），用于布局迭代期间的定向编辑
• 直接编辑 JSON，仅用于 CLI 尚不支持的高级结构（例如，复杂的 BandedList 分组，或超出简单表头/明细结构的自定义 Tablix 列/行层级）

参考资料（共享）：

• ../datex-studio-shared/branch-setup.md — 分支和连接选择
• ../datex-studio-shared/report-authoring/design-standards.md — **Datex 设计语言：**调色板、字体排印、表格样式、字段标签-值模式、网格对齐、报表类别
• ../datex-studio-shared/report-authoring/json-structure.md — 文档模板、元素 JSON 格式、表达式快速参考
• ../datex-studio-shared/report-authoring/design-patterns.md — 坐标系、布局模式、元素尺寸
• ../datex-studio-shared/report-authoring/cli-commands.md — CLI 详细语法：批量操作、tablix、图像、数据集、set/move/remove
• ../datex-studio-shared/report-authoring/sample-data.md — 用于实时预览的配套 .data.json 文件
• ../datex-studio-shared/report-authoring/dataset-rules.md — DataSet 管理：CommandText 规则、集合处理、日期注释
• ../datex-studio-shared/report-authoring/deploy-patterns.md — 上传、预览和验证模式
• ../datex-studio-shared/report-authoring/troubleshooting.md — 常见的 RDLX-JSON 和 CLI 错误及修复方法
• ../datex-studio-shared/studio-management.md — Studio 生命周期：检查、启动、清理

参考资料（创建专用）：

• references/ssrs-migration.md — 将旧版 SSRS（.rdl）报表转换为 NextGen RDLX-JSON
• references/examples/ — **典范示例：**基于真实场景语料分析提炼出的常见报表类型标准模式

编排模型

**此技能是创建新报表的顶层编排器。**它会按顺序调用依赖技能，并在各阶段之间设置验证关卡。请勿在使用此技能之前独立调用依赖技能——此技能会在适当的时机，结合恰当的上下文触发它们。

report-creator (this skill — orchestrates everything)
  │
  ├── Phase 1: Setup + Requirements
  │     ├── Select branch + connection
  │     └── Invoke `requirements-gathering` skill (routes to right source)
  │           ├── DevOps work item → invokes `devops-requirements` skill
  │           ├── Mockup/screenshot → visual analysis
  │           ├── User conversation → structured Q&A
  │           ├── Existing report (.rdl, .rdlx-json) → extract structure
  │           └── Document/spec → extract fields and layout
  │     Output: standardized requirements brief
  │
  ├── Phase 2: Schema Discovery + Datasource Creation
  │     ├── Invoke `schema-explorer` (via `datasource-creator`) for EVERY entity
  │     ├── Invoke `datasource-creator` for EVERY datasource
  │     ├── Invoke `odata-execution` to verify queries
  │     │
  │     ├── ▶ COVERAGE GATE: requirements brief vs datasource fields
  │     │   For EVERY field in the requirements brief:
  │     │   - Is it mapped to an OData path? If not, why?
  │     │   - Is it included in a datasource config? If not, why?
  │     │   - Does it need a calculated expression? Document it.
  │     │   Present gap report to user. Do NOT proceed until gaps are
  │     │   resolved or explicitly accepted.
  │     │
  │     └── Output: validated datasource configs + field coverage report
  │
  ├── Phase 3: Layout Prototype (live in Studio)
  │     ├── Create report + open in Studio
  │     ├── Build sections incrementally with user feedback
  │     ├── Add DataSets + sample data
  │     └── Output: working .rdlx-json with sample data preview
  │
  ├── Phase 4: Report Finalization
  │     └── Verify DataSets, refine expressions, validate
  │
  └── Phase 5: Deploy & Verify
        └── Upload, preview with real data, provide test parameters

意图路由：创建新报表还是修改现有报表

如果用户要求修改分支上的现有报表（例如“在收货报表中添加一列”“更改 BOL 上的标签”“更新 64 号分支上的报表”），请改为调用 report-editor 技能。report-creator 用于从头构建新报表。

如果用户说要“修改”，但该报表尚不存在于此分支上，请向用户确认：“此报表目前在此分支上不存在。要我从头创建吗？”如果用户确认，请继续使用 report-creator。

**规划边界：**第 1 至 3 阶段在规划期间（ExitPlanMode 之前）完成。原型就是报表文件；第 4 阶段从第 3 阶段结束处继续。计划获批后执行第 4 至 5 阶段。

第 1 阶段：设置与需求

选择分支

按照 branch-setup.md 确认当前组织、列出仓库、选择功能分支，并发现 API 连接。

工件收集（可选）

询问用户是否要将流程工件保存到磁盘（架构说明、查询、报表文件、样本数据、预览图像）。建议位置：./reports/<report-name>/。

如果用户同意，请创建工件目录并使用以下命名约定：

文件名	内容
01-schema-exploration.md	实体描述、字段列表、关系
02-field-mapping.md	字段映射表
<report-name>.rdlx-json	报表文件（在第 3 阶段创建，在第 4 阶段完善）
<report-name>.data.json	用于 Studio 实时预览的样本数据
04-query-building.md	逐步构建查询的记录及最终验证过的查询
<report-name>-preview.svg	通过 dxs report preview 生成的预览图像
requirements/	下载的附件和需求简介（DevOps）

收集需求

在探索架构或创建数据源之前，必须先收集并记录需求。即使用户说“直接构建”或只提供了模糊描述，也不得跳过此步骤。需求会决定后续所有工作——跳过此步骤会导致字段映射错误、数据缺失和布局返工。

**调用 requirements-gathering 技能。**该技能会处理路由到正确的信息来源（DevOps 工作项、模型图、对话、文档、现有报表），并生成标准化的需求简介，其中包括：

• 字段列表及其语义角色（每个字段代表什么，而不仅仅是字段名称）
• 布局预期
• 业务规则和计算字段
• 参数

该需求简介是第 2 阶段（架构探索与数据源创建）的输入，也是后续覆盖检查的依据。

**理想范例：**查看 references/examples/，寻找与报表类型相符的规范模式（例如车牌标签、BOL、装箱单）。这些模式源自对真实报表语料的分析，定义了必要元素、常见可选字段、布局属性和结构原型。使用理想范例验证需求是否完整，并指导布局决策——它会展示此类报表的典型样式以及存在的变体。

**对于 SSRS 迁移：**如果源文件包含 .rdl 文件，还请参阅 references/ssrs-migration.md，了解如何读取这些文件并将 SQL 转换为 OData。

阶段 2：架构发现 + 数据源创建

你 MUST 在此阶段为 EVERY 数据源调用 `datasource-creator` 技能。即使出现以下情况，也不得跳过此步骤： - 你找到了展示了完全相同数据模型的现有示例或模板 - 用户要求创建流数据源（流数据源会聚合来自 OData 查询的数据——底层实体仍需进行架构验证） - 你认为自己已通过此前的探索了解实体结构

示例和模板只是待验证的假设。针对 CURRENT 连接进行架构探索才是验证方式。实体是否可用、属性名称、类型和关系都会因连接而异。

Footprint 报告——先查看 footprint-entity-expert。 如果报告查询 Footprint WMS 实体（Tasks、Shipments、ArchivedShippingLicensePlateContents、LicensePlate、Lot、Material 等），footprint-entity-expert 技能包含导航链、重量计算规则和实体选择指导，这些信息无法仅从架构元数据中得知。请先查阅该技能，再调用 datasource-creator，以便将架构探索集中到正确的实体上。对于非 Footprint 应用，请跳过此步骤。

针对报告需要的每个数据源：

1. 调用 datasource-creator 技能，并将 mode 设为 owned——这是默认模式。仅在适用例外情况时使用 standalone：其他报告或组件确实需要相同查询，或者流数据源必须通过 $datasources.<Package>.<name> 访问该数据源（流依赖项始终为 standalone）。完整列表见 ../datasource-creator/references/datasources.md → 默认归属。对于报告，“owned”表示数据源保留为独立文件，并通过 --owned FILE:ALIAS 注册到文件夹清单中——而不是将代码块插入报告 JSON
2. Datasource-creator 会调用 schema-explorer 和 odata-execution，根据实时连接验证实体和属性
3. 对于流数据源：架构探索会识别流代码将查询的 OData 实体和字段，然后根据已验证的架构构建类型定义，而不是依据示例
4. 收集返回摘要：JSON 配置文件路径、引用名称、结果类型、in_params 和 字段摘要（第 3 阶段第 5 步创建 DataSet 时会用到）

对报告所需的每个数据源重复上述步骤。

记录量注意事项：OData 的 5,000 条记录上限

OData 端点每次请求最多返回 5,000 条记录。对于任何按日期范围、多个所有者／项目或其他会产生大量记录的维度进行聚合的数据源（Tasks、ArchivedShippingLicensePlateContents、Shipments 等），如果底层流未分页，报告会静默截断，只保留前 5,000 行。

设计数据源时：

• 单记录 OData 数据源（--param-keys，例如 Shipments(0)）——无需分页。
• 为 tablix 提供数据的集合型 OData 数据源（典型的明细项查询）——如果父级筛选条件已限制行数（例如 ShipmentLines?$filter=ShipmentId eq X），通常无需分页。
• 按日期范围、仓库、所有者等进行聚合的流数据源——必须分页。在调用 datasource-creator 时说明这一点，以便其创建的 standalone OData 数据源声明 skip inParam，并让流代码循环请求，直到返回的页面不足一页为止。

有关配置细节和标准循环，请参阅 ../datex-studio-shared/flow-code-patterns.md#odata-pagination--the-5000-record-cap。如果应该分页却没有分页，繁忙仓库的报告就会少计数据，而且不会报错——症状是数据静默丢失。

覆盖率门槛：需求与数据源字段

创建完所有数据源后，请根据需求说明验证覆盖情况。除非此门槛通过，或用户明确接受缺失项，否则不要进入阶段 3。

对于需求说明中的每个字段：

检查项	未通过时的操作
字段在架构映射中有 OData 路径	调查实体是否缺失、路径是否过深，并提出关联数据源或流程数据源方案。
字段已包含在数据源配置中	将其添加进去 — 数据源可能需要重新生成，并添加额外的 $select/$expand 路径。
字段需要计算（例如，tareWeight = GrossWeight - NetWeight）	记录表达式，供阶段 3 使用。注明所需的输入字段。
字段没有对应的 OData 字段（例如，SQL 函数、自定义视图）	提出流程数据源方案，或将其标记为已知缺失项，由用户决定。

向用户展示覆盖率报告：

### Coverage Report: Requirements → Datasources

✅ Covered (N fields): [list]
⚠️ Calculated (N fields): [field → expression]
❌ Not available (N fields): [field → reason + proposed solution]

Proceed to layout? [Y / resolve gaps first]

此门槛可捕获以下错误：

• Shipper 映射到了错误的实体（Account 而不是 Owner）
• 数据源遗漏了行项目字段（tareWeight、packUOM）
• 跳过了没有替代方案的深层导航路径（Owner 地址）

阶段 3：布局原型（在 Studio 中实时操作）

构建实际的 RDLX-JSON 报表，并在 Datex Studio 中实时预览。 原型就是报表文件 — 阶段 4 将从本阶段结束的位置继续。用户可以实时看到每项更改。

步骤 1：创建空白报表

dxs report create <artifact_dir>/<report_name>_report --page letter --margins 0.5in

标准尺寸使用 --page（letter、legal、a4、4x6、4x8），自定义尺寸使用 WxH。添加 --landscape 可设置横向。--margins 支持 CSS 风格的简写。

命名规则： 文件夹名称会成为报表的 referenceName，Datex Studio 平台会用它生成 TypeScript 服务类。它必须是有效的 JavaScript 标识符 — 只能包含字母、数字、下划线和 $。不能包含连字符、句点或空格。请使用 _report 后缀约定。

错误	正确	原因
srs-bol	srs_bol_report	连字符会破坏 TS 类名
srs-bol.rdlx-json	srs_bol_report	句点和扩展名会破坏 TS 导入
my report	my_report	标识符中不能包含空格

已拥有数据源的别名规则： 使用 dxs report datasource add --owned FILE:ALIAS 添加已拥有的数据源时，别名必须与 JSON 配置文件中数据源的 referenceName 一致。平台按 referenceName 注册服务，但报表通过别名引用这些服务 — 两者不匹配会导致“property does not exist” TS 错误。例如，如果配置中有 "referenceName": "ds_bol_header"，请使用 --owned ds_bol_header.json:ds_bol_header。

步骤 2：在 Studio 中打开

dxs studio open <artifact_dir>/<report_name>_report/report.rdlx-json

这会在 Studio 设计画布中打开报表，地址为 http://127.0.0.1:5051/design。每次文件更改都会实时反映出来。

自动管理 Studio，遵循 ../datex-studio-shared/studio-management.md：检查状态，如有需要则在后台启动（并验证就绪状态），打开报表，并在阶段 5 后清理。

步骤 3：使用 dxs report batch 逐步构建布局

使用 dxs report batch 分组添加元素。将操作写入文件，并使用 --ops-file 避免 shell 转义问题。每批最多 25 个操作。

遵循 Datex 设计语言，参见 ../datex-studio-shared/report-authoring/design-standards.md：为所有文本元素设置 FontFamily: Arial（数值和条码说明文字使用 Courier New），使用官方调色板（Black、DimGray、LightGray、Gray、Datex Purple #5B08B2），表格使用紫色表头边框和 LightGray 行分隔线（不使用背景色），遵循字段标签-值模式（标签为 8pt DimGray，位于 10pt Black 值的上方），并将位置对齐到 0.25in 网格。

使用矩形容器构建逻辑分区。 每个主要分区（页眉、信息字段、地址块、页脚）都应放在矩形中。先添加矩形，再使用 "parent": "RectangleName" 添加子元素。子元素的坐标相对于矩形的左上角（0,0），因此移动矩形即可重新定位其中的所有内容。这对迭代布局很重要——如果不使用矩形，重新定位一个分区就意味着要逐个移动其中的每个元素。批处理模式参见 ../datex-studio-shared/report-authoring/cli-commands.md。表格是独立的，无需矩形包装。

表格： 使用 dxs report add tablix 添加明细项，并通过 --header-cell、--detail-cell、--footer-cell（每个单元格重复使用一次选项）以及 --header-style/--detail-style/--footer-style 设置行级默认样式。总计优先使用页脚行，而非独立文本框。

线条在批处理时使用 start-x/start-y/end-x/end-y（而非 left/top/width/height）。move 不适用于线条——请直接编辑 JSON。

图像： 使用 dxs report add image --file logo.png 添加嵌入式图像；对于数据绑定图像，使用 --source Database --value '=Fields!X.Value'。数据库绑定图像需要在示例数据文件中使用 data URI，参见 ../datex-studio-shared/report-authoring/sample-data.md。

PageHeader/PageFooter： 这些是需要直接编辑 JSON 的文档根元素，参见 ../datex-studio-shared/report-authoring/json-structure.md。

所有批处理操作、tablix 创建、图像处理和元素编辑的详细语法及示例，参见 ../datex-studio-shared/report-authoring/cli-commands.md。

步骤 4：创建示例数据文件

在报表旁边创建配套的 <report-name>.data.json 文件。Studio 会自动发现此文件。

从 DataSets 搭建脚手架——添加 DataSets（步骤 5）后，生成模板：

dxs report data generate <report-name>.rdlx-json -o <report-name>.data.json

然后将占位符替换为真实的示例值——每个数据集 3-5 行。字段名称必须与 DataSet 字段的 Names 匹配（使用下划线表示法，例如 Lines_Material_LookupCode），而不是点表示法的 DataField 路径。

完整格式和示例参见 ../datex-studio-shared/report-authoring/sample-data.md。

第 5 步：向报表添加 DataSet

Studio 预览必需。 如果没有 DataSet 定义，Studio 会显示“报表中没有匹配的 DataSet”错误，字段表达式也会以原始文本形式呈现。

请遵循 dataset-rules.md，了解 DataSet 创建、CommandText 模式、集合处理、日期注释和敏感度属性。

将 datasource-creator 返回的字段摘要作为字段名称的主要来源——它直接从生成的配置类型定义中提取，具有权威性。请包含所有字段，而不仅仅是表达式中使用的字段。字段映射产物提供了额外的可读上下文，可用于布局决策，但不应作为 DataSet 字段名称的主要来源。

执行 dataset add 后，立即验证 CommandText 是否与 Phase 2 datasource-creator 返回的结果类型匹配：

• 如果是 Result type: collection → CommandText 必须以 .* 结尾（例如 $.ds_name.result.*）
• 如果是 Result type: single → CommandText 不得以 .* 结尾（例如 $.ds_name.result）

此处出错会导致报表静默地变为空白（无错误、无数据、无警告）。这是 DataSet 绑定中最常见的错误。

Phase 4 将根据实际数据源（独立模式）或配置 JSON（自有模式）进行验证。

处理 DataSet 中的集合字段：

检查 datasource-creator 的返回内容，找出标记为 [collection] 的字段。这些字段不能作为单结果 DataSet 中的扁平 DataSet 字段添加——否则会静默地显示为空白。

首选方案：flow 数据源。 如果 datasource-creator 的返回内容包含独立文本框所需的集合字段，请返回 Phase 2，将该数据源重建为 flow。flow 代码会获取 OData 数据，并将集合扁平化为标量字段。所有现有的复杂导航 Datex Studio 报表都采用这种生产模式。

替代方案：使用 CommandText 深层路径的子数据集。 如果无法重写为 flow，请创建一个单独的 DataSet，导航到集合中：

{
    "Name": "ds_shipment_OrderLookups",
    "Fields": [
        {"Name": "Order_OwnerReference", "DataField": "Order.OwnerReference"},
        {"Name": "Order_Account_Name", "DataField": "Order.Account.Name"}
    ],
    "Query": {
        "DataSourceName": "Datasource",
        "CommandText": "$.ds_shipment.result.OrderLookups.*"
    }
}

然后在独立文本框中使用 =First(Fields!Order_OwnerReference.Value, "ds_shipment_OrderLookups") 引用字段。对于嵌套集合（集合中的集合），请串联路径：$.ds_shipment.result.OrderLookups.*.Order.Addresses.*。

CommandText 的 .* 后缀规则：

• 单个结果，标量字段：$.ds_name.result（不带 .*）
• 集合结果（table/tablix）：$.ds_name.result.*
• 单个结果中的集合：$.ds_name.result.CollectionPath.*

第 6 步：通过预览进行验证

dxs report preview <file> -o /tmp/preview.svg
dxs report preview <file> --bbox Title:red --bbox LinesTable:blue -o /tmp/inspect.svg

使用 --bbox NAME[:COLOR] 进行视觉调试，并显示彩色边界框。

反馈迭代循环

完成每个部分后，询问用户在 Studio 中的显示效果。使用 dxs report batch 配合 set/move/remove 操作进行修改。重复此过程，直到用户满意为止。

布局参考

请参阅 ../datex-studio-shared/report-authoring/design-patterns.md，了解模式示例（Shipping Label、GS1、BOL、Tabular Report）和元素尺寸表。

Phase 4：完成报表

.rdlx-json 文件已在 Phase 3 中创建，其中包含布局、元素、示例数据和 DataSet 定义。本阶段将完成该文件，使其可用于部署。

最终检查清单

1. 验证数据集 — 对于独立数据源：将字段 Names/DataFields 与 dxs report datasource-fields <ref> --branch <id> 的输出进行比较。对于所属数据源：与第 2 阶段的字段摘要进行比较（datasource-fields 仅在上传后可用）。使用 dxs report dataset add-field 添加缺失字段。确保 CommandText = $.{ds_name}.result.*，并且所有敏感性属性都已填写。
2. 完善表达式 — 将任何占位值更新为最终的 =Fields!Name.Value 表达式。表达式速查请参见 ../datex-studio-shared/report-authoring/json-structure.md。
3. 验证：

   dxs report validate my-report.rdlx-json
   

如需在最终定稿期间进行增量编辑，请参见 ../datex-studio-shared/report-authoring/cli-commands.md 中 set/move/remove/dataset add-field 的语法。

第 5 阶段：部署与验证

按照 deploy-patterns.md 进行上传（所属数据源或独立数据源）、预览、验证和测试参数发现。

产物： 使用 dxs report preview <report>.rdlx-json -o <artifact_dir>/<report-name>-preview.svg 保存预览。

收尾（上传验证完成后）

确认分支上的配置无误后：

1. 文件： 按照 deploy-patterns.md 中的清理提示操作——删除会话文件前先询问用户；绝不可静默清理。如果用户在第 1 阶段选择收集产物，默认保留这些产物。
2. 进程： 按照 studio-management.md 的“清理”部分，停止你启动的进程——如果你在后台启动了 Studio，则运行 dxs studio stop（无需询问；绝不可停止由用户启动的服务），并检查是否有残留的预览进程（agent-browser 会话守护进程 / 来自 preview-arjs/validate-arjs 的无头 Chrome）。拒绝退出的进程，或任何阻塞终端的残留进程，都是需要报告的 CLI 生命周期缺陷——记录其症状链，而不要盲目终止。

故障排除

有关常见的 RDLX-JSON 表达式问题以及布局/CLI 错误，请参见 troubleshooting.md。

---

编辑完成后，调用 post-edit-verification，以发现描述/JSON/架构违规。最终审查时，调用 component-validator。