report-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Report Creator

报表创建工具

Workflow for building and deploying RDLX-JSON reports using the

dxs

CLI. Reports render in ActiveReportsJS within Datex Studio.

Key principle: Plan before code. Build the layout prototype before writing final JSON.

Prototyping and design: This skill has its own visual prototyping workflow —

dxs report create

dxs report batch

dxs studio open

for live preview in a browser. Do NOT use external brainstorming visual companions, browser-based mockup tools, or other prototyping tools unless the user explicitly requests them. The Studio live preview IS the design tool.

Authoring approach:

Live prototyping for new reports — create a blank
```
.rdlx-json
```
, build layout incrementally with
```
dxs report create
```
+
```
dxs report batch
```
, preview live in Studio
Incremental CLI (
```
add
```
/
```
set
```
/
```
move
```
/
```
remove
```
/
```
batch
```
) for targeted edits during layout iteration
Direct JSON only for advanced structures not yet in the CLI (e.g., complex BandedList grouping, custom Tablix column/row hierarchies beyond simple header/detail)

References (shared):

../shared/branch-setup.md — Branch & connection selection
../shared/report-authoring/design-standards.md — Datex design language: color palette, typography, table styling, field label-value pattern, grid alignment, report categories
../shared/report-authoring/json-structure.md — Document template, element JSON formats, expression quick reference
../shared/report-authoring/design-patterns.md — Coordinate system, layout patterns, element sizing
../shared/report-authoring/cli-commands.md — Detailed CLI syntax: batch ops, tablix, images, datasets, set/move/remove
../shared/report-authoring/sample-data.md — Companion
```
.data.json
```
files for live preview
../shared/report-authoring/dataset-rules.md — DataSet management: CommandText rules, collection handling, date annotations
../shared/report-authoring/deploy-patterns.md — Upload, preview, and verification patterns
../shared/report-authoring/troubleshooting.md — Common RDLX-JSON and CLI mistakes & fixes
../shared/studio-management.md — Studio lifecycle: check, start, cleanup

References (creation-specific):

references/ssrs-migration.md — Converting legacy SSRS (.rdl) reports to NextGen RDLX-JSON
references/examples/ — Platonic ideals: canonical patterns for common report types, distilled from real-world corpus analysis

使用

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列/行层次结构）

通用参考文档：

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

创建专属参考文档：

references/ssrs-migration.md — 将旧版SSRS（.rdl）报表转换为下一代RDLX-JSON格式
references/examples/ — 典型模板： 常见报表类型的标准模式，由真实场景分析提炼而成

Orchestration Model

编排模型

This skill is the top-level orchestrator for new report creation. It invokes dependency skills in sequence with validation gates between phases. Do NOT invoke the dependency skills independently before this skill — this skill triggers them at the right time with the right context.

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

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

report-creator（本技能——编排所有流程）
  │
  ├── 阶段1：设置 + 需求收集
  │     ├── 选择分支 + 连接
  │     └── 调用`requirements-gathering`技能（路由至对应来源）
  │           ├── DevOps工作项 → 调用`devops-requirements`技能
  │           ├── 原型/截图 → 视觉分析
  │           ├── 用户对话 → 结构化问答
  │           ├── 现有报表（.rdl, .rdlx-json）→ 提取结构
  │           └── 文档/规范 → 提取字段与布局
  │     输出：标准化需求简报
  │
  ├── 阶段2：Schema发现 + 数据源创建
  │     ├── 为每个实体调用`schema-explorer`（通过`datasource-creator`）
  │     ├── 为每个数据源调用`datasource-creator`
  │     ├── 调用`odata-execution`验证查询
  │     │
  │     ├── ▶ 覆盖验证关卡：需求简报 vs 数据源字段
  │     │   针对需求简报中的每个字段：
  │     │   - 是否映射到OData路径？如果没有，原因是什么？
  │     │   - 是否包含在数据源配置中？如果没有，原因是什么？
  │     │   - 是否需要计算表达式？请记录。
  │     │   向用户展示差距报告。在差距解决或用户明确接受之前，请勿继续。
  │     │
  │     └── 输出：已验证的数据源配置 + 字段覆盖报告
  │
  ├── 阶段3：布局原型（在Studio中实时预览）
  │     ├── 创建报表并在Studio中打开
  │     ├── 根据用户反馈逐步构建各部分
  │     ├── 添加数据集 + 示例数据
  │     └── 输出：可预览示例数据的有效.rdlx-json文件
  │
  ├── 阶段4：报表最终定稿
  │     └── 验证数据集、优化表达式、完成校验
  │
  └── 阶段5：部署与验证
        └── 上传、使用真实数据预览、提供测试参数

Intent routing: create vs modify existing

意图路由：创建 vs 修改现有报表

If the user asks to modify an existing report on a branch (e.g., "add a column to the receiving report", "change the label on the BOL", "update the report on branch 64"), invoke the

report-editor

skill instead. Report-creator is for building new reports from scratch.

If the user says "modify" but the report does not exist yet on the branch, confirm with the user: "That report doesn't exist on this branch yet. Should I create it from scratch?" If yes, continue with report-creator.

Planning boundary: Phases 1-3 complete during planning (before

ExitPlanMode

). The prototype IS the report file — Phase 4 picks up where Phase 3 left off. Phases 4-5 execute after plan approval.

如果用户要求修改分支上的现有报表（例如："在收货报表中添加一列"、"修改BOL上的标签"、"更新分支64上的报表"），请调用

report-editor

技能。Report-creator仅用于从头构建新报表。

如果用户说"修改"但该分支上不存在目标报表，请与用户确认："该分支上尚未存在此报表。是否需要从头创建？"如果用户同意，则继续使用report-creator。

规划边界： 阶段1-3在规划阶段完成（

ExitPlanMode

之前）。原型即为报表文件——阶段4将在阶段3的基础上继续推进。阶段4-5在规划获批后执行。

Phase 1: Setup + Requirements

阶段1：设置 + 需求收集

Select branch

选择分支

Follow branch-setup.md to identify the active organization, list repositories, select a feature branch, and discover API connections.

遵循branch-setup.md确定活跃组织、列出仓库、选择特性分支并发现API连接。

Artifact collection (optional)

工件收集（可选）

Ask the user if they want to save process artifacts to disk (schema notes, queries, report file, sample data, preview images). Suggested location:

./reports/<report-name>/

If yes, create the artifact directory and use this naming convention:

Filename	Content
`01-schema-exploration.md`	Entity descriptions, field lists, relationships
`02-field-mapping.md`	Field mapping table
`<report-name>.rdlx-json`	The report file (created in Phase 3, refined in Phase 4)
`<report-name>.data.json`	Sample data for live Studio preview
`04-query-building.md`	Incremental query steps and final verified query
`<report-name>-preview.svg`	Preview image from `dxs report preview`
`requirements/`	Downloaded attachments and requirements brief (DevOps)

询问用户是否要将流程工件保存到磁盘（Schema笔记、查询语句、报表文件、示例数据、预览图片）。建议保存位置：

./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

需求收集

<HARD-GATE> You MUST gather and document requirements BEFORE schema exploration or datasource creation. Do NOT skip this step, even if the user says "just build it" or provides a vague description. Requirements drive everything downstream — skipping this step causes field mapping errors, missing data, and layout rework. </HARD-GATE>

Invoke the
requirements-gathering
skill. It handles routing to the right source (DevOps work item, mockup, conversation, document, existing report) and produces a standardized requirements brief with:

Field list with semantic roles (what each field means, not just its name)
Layout expectations
Business rules and calculated fields
Parameters

The requirements brief is the input to Phase 2 (schema exploration + datasource creation) and the coverage gate that follows it.

Platonic ideals: Check references/examples/ for a canonical pattern matching the report type (e.g., license plate label, BOL, packing slip). These are distilled from corpus analysis of real-world reports and define the essential elements, common optional fields, layout properties, and structural archetypes. Use the platonic ideal to validate requirements completeness and guide layout decisions — it tells you what a typical report of this type looks like and what variations exist.

For SSRS migrations: If the source includes

.rdl

files, also see references/ssrs-migration.md for how to read them and translate SQL→OData.

<HARD-GATE> **必须在Schema探索或数据源创建之前收集并记录需求。** 即使用户说"直接构建"或提供模糊描述，也请勿跳过此步骤。需求决定了后续所有流程——跳过此步骤会导致字段映射错误、数据缺失和布局返工。 </HARD-GATE>

调用
requirements-gathering
技能。它会处理路由至对应来源（DevOps工作项、原型、对话、文档、现有报表），并生成包含以下内容的标准化需求简报：

带有语义角色的字段列表（每个字段的含义，而非仅字段名）
布局预期
业务规则与计算字段
参数

需求简报是阶段2（Schema探索 + 数据源创建）的输入，也是后续覆盖验证关卡的依据。

典型模板： 查看references/examples/获取与报表类型匹配的标准模式（例如车牌标签、BOL、装箱单）。这些模板由真实报表场景分析提炼而成，定义了必需元素、常见可选字段、布局属性和结构原型。使用典型模板验证需求完整性并指导布局决策——它会告诉你该类型报表的典型样式和可能的变体。

SSRS迁移： 如果来源包含

.rdl

文件，请同时查看references/ssrs-migration.md了解如何读取文件并将SQL转换为OData。

Phase 2: Schema Discovery + Datasource Creation

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

<HARD-GATE> You MUST invoke the `datasource-creator` skill for EVERY datasource in this phase. Do NOT skip this step, even if: - You found existing examples or templates that show the exact data model - The user asked for a flow datasource (flow datasources aggregate data from OData queries — the underlying entities still need schema validation) - You think you already know the entity structure from prior exploration

Examples and templates are hypotheses. Schema exploration against the CURRENT connection is the validation. Entity availability, property names, types, and relationships vary between connections. </HARD-GATE>

For each datasource the report needs:

Invoke
```
datasource-creator
```
skill with mode =
```
owned
```
(preferred) or
```
standalone
```
Datasource-creator invokes
```
schema-explorer
```
and
```
odata-execution
```
to validate entities and properties against the live connection
For flow datasources: schema exploration identifies the OData entities and fields the flow code will query, then the type definition is built from validated schema — not from examples
Collect the return summary: JSON config file path, reference name, result type, in_params, and field summary (used in Phase 3 Step 5 for DataSet creation)

Repeat for each datasource needed by the report.

<HARD-GATE> **必须为每个数据源调用`datasource-creator`技能。** 即使出现以下情况，也请勿跳过此步骤： - 你找到了显示完全匹配数据模型的现有示例或模板 - 用户要求使用流式数据源（流式数据源从OData查询聚合数据——底层实体仍需Schema验证） - 你认为通过之前的探索已经了解实体结构

示例和模板只是假设。针对当前连接的Schema探索才是验证环节。实体可用性、属性名称、类型和关系会因连接而异。 </HARD-GATE>

针对报表所需的每个数据源：

调用
```
datasource-creator
```
技能，模式设置为
```
owned
```
（首选）或
```
standalone
```
Datasource-creator会调用
```
schema-explorer
```
和
```
odata-execution
```
，针对实时连接验证实体和属性
对于流式数据源：Schema探索会识别流式代码将查询的OData实体和字段，然后基于已验证的Schema构建类型定义——而非基于示例
收集返回摘要：JSON配置文件路径、引用名称、结果类型、输入参数和字段摘要（用于阶段3步骤5的数据集创建）

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

Coverage gate: requirements vs datasource fields

覆盖验证关卡：需求 vs 数据源字段

<HARD-GATE> After ALL datasources are created, verify coverage against the requirements brief. Do NOT proceed to Phase 3 until this gate passes or the user explicitly accepts gaps. </HARD-GATE>

For every field in the requirements brief:

Check	Action if failed
Field has an OData path in the schema mapping	Investigate: is the entity missing? Is the path too deep? Propose a linked or flow datasource.
Field is included in a datasource config	Add it — the datasource may need regeneration with additional `$select` / `$expand` paths.
Field requires a calculation (e.g., `tareWeight = GrossWeight - NetWeight` )	Document the expression for Phase 3. Note fields needed as inputs.
Field has no OData equivalent (e.g., SQL function, custom view)	Propose a flow datasource, or flag as a known gap for user decision.

Present the coverage report to the user:

undefined

<HARD-GATE> **在所有数据源创建完成后，验证其与需求简报的覆盖情况。** 在该关卡通过或用户明确接受差距之前，请勿进入阶段3。 </HARD-GATE>

针对需求简报中的每个字段：

检查项	未通过时的操作
字段在Schema映射中有对应的OData路径	调查：实体是否缺失？路径是否过深？建议使用关联或流式数据源。
字段包含在数据源配置中	添加该字段——可能需要重新生成数据源并添加额外的 `$select` / `$expand` 路径。
字段需要计算（例如： `tareWeight = GrossWeight - NetWeight` ）	记录该表达式，用于阶段3。标注所需的输入字段。
字段没有对应的OData等效项（例如SQL函数、自定义视图）	建议使用流式数据源，或标记为已知差距供用户决策。

向用户展示覆盖报告：

undefined

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]


This gate catches errors like:
- Shipper mapped to wrong entity (Account instead of Owner)
- Line-item fields omitted from datasource (tareWeight, packUOM)
- Deep navigation paths skipped without alternatives (Owner address)

✅ 已覆盖（N个字段）：[列表] ⚠️ 需计算（N个字段）：[字段 → 表达式] ❌ 不可用（N个字段）：[字段 → 原因 + 建议方案]

是否继续布局？[是 / 先解决差距]


该关卡可捕获以下错误：
- 发货方映射到错误实体（Account而非Owner）
- 数据源中遗漏了行项目字段（tareWeight、packUOM）
- 未提供替代方案就跳过了深层导航路径（Owner地址）

Phase 3: Layout Prototype (Live in Studio)

阶段3：布局原型（在Studio中实时预览）

Build an actual RDLX-JSON report and preview it live in Datex Studio. The prototype IS the report file — Phase 4 picks up where this phase leaves off. The user sees every change in real time.

构建真实的RDLX-JSON报表并在Datex Studio中实时预览。 原型即为报表文件——阶段4将在本阶段的基础上继续推进。用户可实时查看每一处变更。

Step 1: Create a blank report

步骤1：创建空白报表

bash

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

Use

--page

for standard sizes (

letter

legal

a4

4x6

4x8

) or custom (

WxH

). Add

--landscape

for landscape orientation.

--margins

supports CSS-style shorthand.

Naming rule: The folder name becomes the report's

referenceName

, which the Wavelength platform uses to generate TypeScript service classes. It must be a valid JavaScript identifier — letters, digits, underscores,

only. No hyphens, dots, or spaces. Use the

_report

suffix convention.

Bad	Good	Why
`srs-bol`	`srs_bol_report`	Hyphens break TS class names
`srs-bol.rdlx-json`	`srs_bol_report`	Dots and extensions break TS imports
`my report`	`my_report`	Spaces are not valid in identifiers

Alias rule for owned datasources: When adding owned datasources with

dxs report datasource add --owned FILE:ALIAS

, the alias must match the datasource's
referenceName
inside the JSON config file. The platform registers services by referenceName but the report references them by alias — a mismatch causes "property does not exist" TS errors. Example: if the config has

"referenceName": "ds_bol_header"

, use

--owned ds_bol_header.json:ds_bol_header

bash

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

使用

--page

指定标准尺寸（

letter

、

legal

、

a4

、

4x6

、

4x8

）或自定义尺寸（

WxH

）。添加

--landscape

设置横向 orientation。

--margins

支持CSS风格的简写格式。

命名规则： 文件夹名将成为报表的

referenceName

，Wavelength平台会用它生成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注册服务，但报表通过别名引用服务——不匹配会导致"属性不存在"TS错误。示例：如果配置中

"referenceName": "ds_bol_header"

，则使用

--owned ds_bol_header.json:ds_bol_header

。

Step 2: Open in Studio

步骤2：在Studio中打开

bash

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

This opens the report in the Studio design canvas at

http://127.0.0.1:5051/design

. Every file change is reflected live.

Auto-manage Studio per ../shared/studio-management.md: check status, start in background if needed (with readiness verification), open the report, and clean up after Phase 5.

bash

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

这会在Studio设计画布

http://127.0.0.1:5051/design

中打开报表。文件的每一处变更都会实时反映。

按照../shared/studio-management.md自动管理Studio： 检查状态、按需在后台启动（并验证就绪状态）、打开报表、在阶段5后清理。

Step 3: Build layout incrementally with

dxs report batch

步骤3：使用

dxs report batch

逐步构建布局

Use

dxs report batch

to add elements in groups. Write ops to a file and use

--ops-file

to avoid shell escaping issues. Maximum 25 operations per batch.

Apply the Datex design language from ../shared/report-authoring/design-standards.md: set

FontFamily: Arial

on all text elements (use

Courier New

for numeric values and barcode captions), use the official color palette (Black, DimGray, LightGray, Gray, Datex Purple #5B08B2), style tables with purple header borders and LightGray row separators (no background colors), follow the field label-value pattern (8pt DimGray labels above 10pt Black values), and snap positions to the 0.25in grid.

Build in logical sections using rectangle containers. Every major section (header, info fields, address blocks, footer) should be wrapped in a rectangle. Add the rectangle first, then add child elements with

"parent": "RectangleName"

. Child coordinates are relative to the rectangle's top-left corner (0,0), so moving the rectangle repositions everything inside it. This is important for layout iteration — without rectangles, repositioning a section means moving every element individually. See ../shared/report-authoring/cli-commands.md for the batch pattern. Tables are self-contained and don't need a rectangle wrapper.

Tables: Use

dxs report add tablix

for line items with

--header-cell

--detail-cell

--footer-cell

(repeated options, one per cell) and

--header-style

--detail-style

--footer-style

for row-level defaults. Prefer footer rows over standalone textboxes for totals.

Lines use

start-x

start-y

end-x

end-y

in batch (not

left

top

width

height

move

does not work on lines — edit JSON directly.

Images: Use

dxs report add image --file logo.png

for embedded images,

--source Database --value '=Fields!X.Value'

for data-bound images. Database-bound images need data URIs in the sample data file — see ../shared/report-authoring/sample-data.md.

PageHeader/PageFooter: These are document-root elements requiring direct JSON editing — see ../shared/report-authoring/json-structure.md.

See ../shared/report-authoring/cli-commands.md for detailed syntax and examples of all batch operations, tablix creation, image handling, and element editing.

使用

dxs report batch

批量添加元素。将操作写入文件并使用

--ops-file

避免shell转义问题。每批最多25个操作。

应用../shared/report-authoring/design-standards.md中的Datex设计规范： 为所有文本元素设置

FontFamily: Arial

（数值和条形码说明使用

Courier New

），使用官方调色板（Black、DimGray、LightGray、Gray、Datex紫色 #5B08B2），为表格设置紫色页眉边框和LightGray行分隔线（无背景色），遵循字段标签-值模式（8号DimGray标签位于10号Black值上方），并将位置对齐到0.25英寸网格。

使用矩形容器构建逻辑区块。 每个主要区块（页眉、信息字段、地址块、页脚）都应包裹在矩形中。先添加矩形，然后使用

"parent": "RectangleName"

添加子元素。子元素坐标相对于矩形的左上角（0,0），因此移动矩形会重新定位其内部的所有元素。这对布局迭代非常重要——如果没有矩形，重新定位一个区块意味着要单独移动每个元素。查看../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'

添加数据绑定图片。数据库绑定图片需要在示例数据文件中包含数据URI——查看../shared/report-authoring/sample-data.md。

PageHeader/PageFooter： 这些是文档根元素，需要直接编辑JSON——查看../shared/report-authoring/json-structure.md。

查看../shared/report-authoring/cli-commands.md了解所有批量操作、Tablix创建、图片处理和元素编辑的详细语法与示例。

Step 4: Create sample data file

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

Create a companion

<report-name>.data.json

alongside the report. Studio auto-discovers this file.

Scaffold from DataSets — after adding DataSets (Step 5), generate a template:

bash

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

Then replace placeholders with realistic sample values — 3-5 rows per dataset. Field names must match DataSet field Names (underscore notation, e.g.,

Lines_Material_LookupCode

), not dot-notation DataField paths.

See ../shared/report-authoring/sample-data.md for the full format and examples.

在报表旁边创建配套的

<report-name>.data.json

文件。Studio会自动发现该文件。

从数据集生成模板——添加数据集（步骤5）后，生成模板：

bash

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

然后将占位符替换为真实的示例值——每个数据集3-5行。字段名称必须与数据集字段Names（下划线格式，例如

Lines_Material_LookupCode

）匹配，而非点格式的DataField路径。

查看../shared/report-authoring/sample-data.md获取完整格式与示例。

Step 5: Add DataSets to the report

步骤5：向报表添加数据集

REQUIRED for Studio preview. Without DataSet definitions, Studio shows "no matching DataSet in report" errors and field expressions render as raw text.

Follow dataset-rules.md for DataSet creation, CommandText patterns, collection handling, date annotations, and sensitivity properties.

Use the field summary from the datasource-creator's return as the primary source for field names. Phase 4 will verify against the actual datasource.

Studio预览必需。 没有数据集定义，Studio会显示"报表中无匹配数据集"错误，字段表达式会显示为原始文本。

遵循dataset-rules.md进行数据集创建、CommandText模式设置、集合处理、日期注释和敏感属性配置。

使用数据源创建器返回的字段摘要作为字段名称的主要来源。阶段4会针对实际数据源进行验证。

Step 6: Verify with preview

步骤6：使用预览验证

bash

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

Use

--bbox NAME[:COLOR]

for visual debugging with colored bounding boxes.

bash

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]

添加彩色边框进行可视化调试。

Feedback iteration loop

反馈迭代循环

After building each section, ask the user how it looks in Studio. Use

dxs report batch

with

set

move

remove

ops for changes. Repeat until the user approves.

构建完每个区块后，询问用户在Studio中的显示效果。使用

dxs report batch

配合

set

move

remove

操作进行修改。重复此过程直到用户批准。

Layout reference

布局参考

See ../shared/report-authoring/design-patterns.md for pattern examples (Shipping Label, GS1, BOL, Tabular Report) and element sizing tables.

查看../shared/report-authoring/design-patterns.md获取模式示例（运输标签、GS1、BOL、表格报表）和元素尺寸表。

Phase 4: Report Finalization

阶段4：报表最终定稿

The

.rdlx-json

file already exists from Phase 3 with layout, elements, sample data, and DataSet definitions. This phase finalizes it for deployment.

.rdlx-json

文件已在阶段3创建，包含布局、元素、示例数据和数据集定义。本阶段将完成定稿以便部署。

Finalization checklist

定稿检查清单

Verify DataSets — For standalone datasources: compare field Names/DataFields against
```
dxs report datasource-fields <ref> --branch <id>
```
output. For owned datasources: compare against the field summary from Phase 2 (datasource-fields is only available post-upload). Add missing fields with
```
dxs report dataset add-field
```
. Ensure
```
CommandText = $.{ds_name}.result.*
```
and all sensitivity properties are present.
Refine expressions — Update any placeholder values with final
```
=Fields!Name.Value
```
expressions. See ../shared/report-authoring/json-structure.md for expression quick reference.
Validate:
bash
```
dxs report validate my-report.rdlx-json
```

For incremental edits during finalization, see ../shared/report-authoring/cli-commands.md for

set

move

remove

dataset add-field

syntax.

验证数据集——对于独立数据源：对比字段Names/DataFields与
```
dxs report datasource-fields <ref> --branch <id>
```
的输出。对于自有数据源：对比阶段2的字段摘要（datasource-fields仅在上传后可用）。使用
```
dxs report dataset add-field
```
添加缺失字段。确保
```
CommandText = $.{ds_name}.result.*
```
且所有敏感属性已配置。
优化表达式——将占位符值更新为最终的
```
=Fields!Name.Value
```
表达式。查看../shared/report-authoring/json-structure.md获取表达式速查。
验证：
bash
```
dxs report validate my-report.rdlx-json
```

如需在定稿阶段进行增量编辑，请查看../shared/report-authoring/cli-commands.md了解

set

move

remove

dataset add-field

语法。

Phase 5: Deploy & Verify

阶段5：部署与验证

Follow deploy-patterns.md for upload (owned vs standalone), preview, verification, and test parameter discovery.

Artifact: Save preview with

dxs report preview <report>.rdlx-json -o <artifact_dir>/<report-name>-preview.svg

遵循deploy-patterns.md进行上传（自有 vs 独立）、预览、验证和测试参数发现。

工件： 使用

dxs report preview <report>.rdlx-json -o <artifact_dir>/<report-name>-preview.svg

保存预览。

Troubleshooting

故障排除

See troubleshooting.md for common RDLX-JSON expression issues and layout/CLI mistakes.

查看troubleshooting.md获取常见RDLX-JSON表达式问题和布局/CLI错误的解决方案。

report-creator

Original

Translation

Report Creator

报表创建工具

Orchestration Model

编排模型

Intent routing: create vs modify existing

意图路由：创建 vs 修改现有报表

Phase 1: Setup + Requirements

阶段1：设置 + 需求收集

Select branch

选择分支

Artifact collection (optional)

工件收集（可选）

Requirements gathering

需求收集

Phase 2: Schema Discovery + Datasource Creation

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

Coverage gate: requirements vs datasource fields

覆盖验证关卡：需求 vs 数据源字段

Coverage Report: Requirements → Datasources

覆盖报告：需求 → 数据源

Phase 3: Layout Prototype (Live in Studio)

阶段3：布局原型（在Studio中实时预览）

Step 1: Create a blank report

步骤1：创建空白报表

Step 2: Open in Studio

步骤2：在Studio中打开

Step 3: Build layout incrementally with dxs report batch

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

Step 4: Create sample data file

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

Step 5: Add DataSets to the report

步骤5：向报表添加数据集

Step 6: Verify with preview

步骤6：使用预览验证

Feedback iteration loop

反馈迭代循环

Layout reference

布局参考

Phase 4: Report Finalization

阶段4：报表最终定稿

Finalization checklist

定稿检查清单

Phase 5: Deploy & Verify

阶段5：部署与验证

Troubleshooting

故障排除

Step 3: Build layout incrementally with
`dxs report batch`

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