report-editor

报表编辑器

使用 dxs CLI 修改 Datex Studio 分支上现有 RDLX-JSON 报表的工作流。

核心原则： 修改前先理解。进行任何更改前，下载并检查当前报表。

创作方式：

• 所有修改都使用增量 CLI（set/move/remove/batch/table add-column/dataset add-field）
• 仅对 CLI 无法处理的结构（PageHeader/PageFooter、复杂的 Tablix 分组）使用直接编辑 JSON
• 绝不从头重建——基于现有文件进行修改

参考资料（共享）

• ../datex-studio-shared/branch-setup.md -- 分支和连接选择
• ../datex-studio-shared/studio-management.md -- Studio 生命周期：检查、启动、清理
• ../datex-studio-shared/report-authoring/design-standards.md -- Datex 设计语言：调色板、字体排印、表格样式、字段标签-值模式、网格对齐、报表类别
• ../datex-studio-shared/report-authoring/design-patterns.md -- 坐标系、布局模式、元素尺寸
• ../datex-studio-shared/report-authoring/json-structure.md -- RDLX-JSON 格式：文档模板、元素 JSON 格式、表达式速查
• ../datex-studio-shared/report-authoring/cli-commands.md -- CLI 语法：批量操作、tablix、图像、数据集、set/move/remove、验证
• ../datex-studio-shared/report-authoring/sample-data.md -- 实时预览的示例数据格式
• ../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 错误及修复方法

依赖项

仅在需要时（类别 4-5）调用 datasource-creator 和 schema-explorer。仅修改布局（类别 1-3）时不需要它们。

编排模型

report-editor (this skill)
  |
  +-- Phase 1: Download & Inspect
  |     +-- Select branch + find report (branch-setup.md)
  |     +-- Download report folder (RDLX-JSON + datasources + manifest)
  |     +-- Inspect layout + DataSets + datasource fields
  |     +-- Output: report folder + structural understanding
  |
  +-- Phase 2: Triage -- Determine Change Depth
  |     +-- Classify user's request into category 1-5
  |     +-- Check DataSet fields vs datasource fields
  |     +-- Output: modification plan with category + steps
  |
  +-- Phase 3: Modify (conditional paths by category)
  |     +-- Cat 1-2: Layout-only --> set/move/remove/batch on folder/report.rdlx-json
  |     +-- Cat 3: Add from existing DataSet field --> table add-column
  |     +-- Cat 4: Datasource gap --> datasource-creator --> datasource add --> DataSet --> layout
  |     +-- Cat 5: New section --> schema-explorer --> datasource-creator --> datasource add --> DataSet --> layout
  |
  +-- Phase 4: Deploy & Verify (deploy-patterns.md)
  |     +-- assemble folder --> wrapper JSON
  |     +-- upload wrapper JSON

阶段 1：下载并检查

选择分支并查找报表

按照 branch-setup.md 选择分支和连接。

然后列出该分支上的报表：

dxs report list --branch <branch_id>

如果目标报表不明确，请向用户展示报表列表。如果用户指定了某个报表，请将其与列表进行匹配。

下载报表文件夹

# Auto-names folder from reference name
dxs report download --branch <branch_id> --reference-name <reference_name>

# Or specify folder path explicitly
dxs report download <folder_path> --branch <branch_id> --reference-name <reference_name>

这会创建一个报表文件夹，其中包含：

• report.rdlx-json -- RDLX-JSON 布局（编辑命令以此文件为目标）
• manifest.json -- 所有绑定元数据（数据源、参数、数据源参数、访问修饰符）
• ds_*.json -- 每个自有数据源配置对应一个文件（从包装对象中提取）

清单会保留所有数据源绑定、参数映射和元数据。重新上传时无需手动提取或重建标志。

检查报表文件夹

检查清单以了解数据源绑定：

dxs report datasource list <folder>/

检查布局：

dxs report inspect <folder>/report.rdlx-json

还要直接读取 RDLX-JSON，以了解 DataSet、元素层级和表达式。

视觉布局检查

使用 --bbox 生成带彩色边界框的预览，有助于在修改前了解元素位置：

dxs report preview <file.rdlx-json> --bbox ElementName:red --bbox AnotherElement:blue -o /tmp/inspect.svg

检查当前布局

dxs report inspect <file.rdlx-json>

这会显示每个元素的类型、名称、位置、大小、值/表达式以及 DataSet 绑定。还要直接读取文件，以了解：

• DataSet（名称、字段、CommandText 模式）
• 元素层级（包含子元素的矩形）
• 使用的表达式
• 页面设置（大小、边距、方向）

确定可用的数据源字段

对于报表使用的每个数据源（运行 dxs report datasource list <folder>/ 查看）：

# For standalone datasources
dxs report datasource-fields <datasource_ref> --branch <branch_id>

# For owned datasources
dxs report datasource-fields <datasource_ref> --branch <branch_id> --report <report_ref>

这会提供完整的字段列表、in_params、结果类型和集合。这是分类的关键门槛——在第 2 阶段，你将检查所请求的字段是否已在此处提供。

未找到报表

如果 dxs report list 未返回目标报表：

1. 告知用户：“在分支 X 上未找到该报表。”
2. 询问：“你想从头创建吗？”
3. 如果是，则调用 report-creator 技能。

第 2 阶段：分类——确定变更深度

将每项请求的变更归入以下五个类别之一。不同类别需要采用不同的工作流。

变更类别

类别	示例	所需操作	依赖技能
1. 标签/样式	“将 ‘SHIPPER’ 改为 ‘FROM’”、“将页眉设为蓝色”、“增大字号”	仅使用 set/batch	无
2. 重新排列	“交换第 2 列和第 3 列”、“将地址块下移”、“删除页脚”	move/remove/set	无
3. 添加列（DataSet 中的字段）	“添加 Status 列”，其中 Status 已在 DataSet 中	table add-column + 布局	无
4a. 添加字段（在数据源中，但不在 DataSet 中）	“添加 Material Description”，该字段在数据源输出中，但不在 DataSet 中	dataset add-field + 布局	无
4b. 添加字段（数据源缺少字段）	“添加 Material Description”，该字段不在数据源的 $select/$expand 中	重新生成数据源 + dataset add-field + 布局	datasource-creator
5. 新数据区域	“添加一个行项目表”，但不存在合适的数据源	完整流程：schema-explorer + datasource-creator + DataSet + 布局	schema-explorer + datasource-creator

决策树

User request
  |
  +-- Does the change involve data fields?
  |   +-- NO --> Is it positional/structural (move, swap, remove)?
  |   |   +-- YES --> Category 2 (rearrangement)
  |   |   +-- NO  --> Category 1 (label/style)
  |   |         --> Proceed to Phase 3
  |   |
  |   +-- YES --> Does the needed field exist in a report DataSet?
  |       +-- YES --> Category 3 (add column/element from existing DataSet field)
  |       |         --> Proceed to Phase 3
  |       |
  |       +-- NO --> Is the field in the datasource output? (from datasource-fields)
  |           +-- YES --> Category 4a (field in datasource, missing from DataSet)
  |           |         --> Add to DataSet, then layout
  |           |
  |           +-- NO --> Is the field reachable from the datasource's entity?
  |               |     (just missing from $select/$expand)
  |               |
  |               +-- YES --> Category 4b (datasource needs regeneration)
  |               |         --> Modify datasource --> re-upsert --> DataSet --> layout
  |               |
  |               +-- NO --> Category 5 (entirely new data requirement)
  |                         --> schema-explorer --> datasource-creator --> DataSet --> layout

呈现分类结果

继续进入第 3 阶段之前，先向用户呈现分类结果并征得批准。未经用户确认计划，不要开始修改报表。

### Modification Plan

**Requested change:** [user's request]
**Category:** [1-5] -- [description]

**Steps:**
1. [what will happen]
2. [what will happen]
...

**Impact:** [layout-only / DataSet change / datasource modification / new datasource]

Proceed?

第 3 阶段：修改

在 Studio 中打开以进行实时预览

对于任何涉及布局的变更（类别 1-3，或类别 4-5 中涉及布局的部分），请确保 Studio 正在运行，并且报表已打开以供实时预览，然后再进行修改。

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

类别 1-2：仅布局变更

按照 cli-commands.md 使用 CLI 命令：

# Change a label
dxs report set <file> ElementName --value "New Label Text"

# Change styling
dxs report set <file> ElementName --font-size 12pt --color Navy --font-weight Bold

# Move an element
dxs report move <file> ElementName --left 1in --top 2in

# Resize an element
dxs report set <file> ElementName --width 3in --height 1in

# Remove an element
dxs report remove <file> ElementName

# Batch operations (for multiple changes)
cat > /tmp/ops.json << 'OPEOF'
[
  {"action": "set", "name": "Title", "value": "New Title", "font-size": "18pt"},
  {"action": "set", "name": "SubTitle", "color": "DimGray"},
  {"action": "move", "name": "AddressBlock", "left": "0in", "top": "1.5in"},
  {"action": "remove", "name": "OldElement"}
]
OPEOF

dxs report batch <file> --ops-file /tmp/ops.json

批量操作上限：每次调用最多 25 项。 如果操作超过 25 项，请拆分为多次批量调用。按逻辑分组（例如，第一批调整位置，第二批设置样式并添加新元素）。

对任何新增或修改的元素，应用 design-standards.md 中的标准：Arial 字体、官方配色方案、按 0.25in 网格对齐。

线条需要特殊处理。 线条使用 StartPoint/EndPoint 和 start-x/start-y/end-x/end-y，而不是 left/top/width/height。move 命令不适用于线条。请直接在 JSON 中编辑线条位置，或使用带端点标志的批量 set。

类别 3：从现有 DataSet 字段添加列

该字段已存在于 DataSet 中，只需将列添加到表格：

dxs report table add-column <file> --table <TablixName> --shrink \
  --header-cell "New Header" \
  --detail-cell '=Fields!ExistingField.Value' \
  --header-style 'font-family:Arial;font-size:10pt;font-weight:Bold;border-bottom-width:1.5pt;border-bottom-style:Solid;border-bottom-color:#5B08B2;padding:2pt;vertical-align:Bottom' \
  --detail-style 'font-family:Arial;font-size:10pt;padding:2pt;vertical-align:Middle;border-bottom-width:0.25pt;border-bottom-style:Solid;border-bottom-color:LightGray'

--shrink 标志会按比例缩小现有列的宽度，为新列腾出空间，同时保持表格总宽度不变。

对于非表格元素（独立文本框），请使用 dxs report batch 和 add 操作，将新字段放入布局中。

为新列应用 Datex 设计标准，使其样式与表格中的现有列相匹配。

类别 4a：字段在数据源中，但缺失于 DataSet

该字段在数据源输出中可用，但未包含在报告的 DataSet 定义中。请将其添加：

dxs report dataset add-field <file> --dataset <DataSetName> --field "New.Field.Path"

请遵循 dataset-rules.md：

• 日期注解：在日期字段后追加 [Date|YYYY-MM-DDTHH:mm:ss.fffffff]
• 集合处理：对于单结果 DataSet，不能将集合字段作为扁平 DataSet 字段添加
• CommandText：验证 DataSet 的 CommandText 模式是否适用于结果类型

然后添加引用新字段的布局元素（列或文本框）。如果报告有配套的 .data.json，请在其中更新新字段的示例值。

类别 4b：需要重新生成数据源

该字段存在于 OData 实体中，但不在数据源的 $select 或 $expand 中。必须更新数据源配置。

对于独立 OData 数据源：

1. 获取当前数据源配置：dxs datasource get <ref> --branch <id>
2. 确定缺失的字段路径（例如，需要在 $expand 中添加 Material/Description）
3. 调用 datasource-creator，使用更新后的查询重新生成
4. 使用 dxs configuration upsert datasource -D <file.json> --branch <id> 更新分支
5. 使用 dxs report dataset add-field 将字段添加到 DataSet
6. 添加布局元素

对于自有 OData 数据源：

1. 当前配置已在报告文件夹中（下载时提取为 ds_*.json）
2. 调用 datasource-creator，使用更新后的查询重新生成
3. 在文件夹中替换：dxs report datasource remove <folder> <alias>，然后执行 dxs report datasource add <folder> --owned <new_ds.json>:<alias>
4. 使用 dxs report dataset add-field 将字段添加到 DataSet
5. 添加布局元素

对于流数据源：

1. 检查所需字段是否位于流的某个源 OData 数据源中
2. 如果是：更新流代码，将字段包含在返回类型中，并更新类型定义 YAML
3. 如果否：可能需要先更新源 OData 数据源，再更新流代码
4. 使用 dxs datasource generate-flow 重新生成
5. 重新执行 upsert（独立数据源），或在文件夹中替换：dxs report datasource remove/add（自有数据源）
6. 将字段添加到 DataSet 和布局中

类别 5：新增数据部分

新增部分需要使用现有任何数据源都未涵盖的实体或关系中的数据。

1. 收集需求，了解新增部分所需的数据和布局。通常进行简短沟通即可——只有当新增部分较复杂时，才调用 requirements-gathering。
2. 调用 schema-explorer，查找合适的 OData 实体和字段。
3. 调用 datasource-creator 创建数据源配置，然后运行 dxs report datasource add <folder> --owned <file>:<alias>（优先使用 owned；如果数据源由多个部分共用，则使用 standalone）。
4. 根据 dataset-rules.md 添加 DataSet——以 datasource-creator 提供的字段摘要作为字段名称的主要来源，并包含所有字段。
5. 使用 dxs report batch 构建布局（矩形容器、文本框或表格）。
6. 如需预览，根据 sample-data.md 创建或更新示例数据。

创建 DataSet：

dxs report dataset add <file> --name ds_new_section \
  --field Id --field LookupCode --field Status \
  --field "Account.Name" \
  --field "OrderDate[Date|YYYY-MM-DDTHH:mm:ss.fffffff]"

构建此部分的布局时，使用矩形容器进行分组：

cat > /tmp/new-section-ops.json << 'OPEOF'
[
  {"action": "add", "type": "rectangle", "name": "NewSectionBox",
   "left": "0in", "top": "4in", "width": "7.5in", "height": "2in"},
  {"action": "add", "type": "textbox", "name": "NewSectionTitle",
   "parent": "NewSectionBox", "left": "0in", "top": "0in",
   "width": "7.5in", "height": "0.3in",
   "value": "Section Title", "font-size": "14pt", "color": "DimGray"}
]
OPEOF

dxs report batch <file> --ops-file /tmp/new-section-ops.json

对于表格，请使用 dxs report add tablix——完整语法（包括分组、页脚行和排序表达式）请参阅 cli-commands.md。

反馈迭代

每次修改后，询问用户在 Studio 中看到的效果。使用 set/move/remove 进行调整。重复此过程，直到用户批准。

在用户确认布局在 Studio 中显示良好之前，不要进入阶段 4（组装/上传）。明确询问：“在 Studio 中看起来怎么样？可以上传了吗，还是需要调整？”

阶段 4：部署与验证

组装并上传

报告文件夹已包含所需的一切——清单会保留下载时的所有数据源绑定、参数和元数据。无需重建任何标志。

# Assemble folder into wrapper JSON
dxs report assemble <folder>/ -o <reference_name>.json

# Upload wrapper to branch
dxs report upload <reference_name>.json --branch <branch_id>

如果在阶段 3 添加或移除了数据源，这些更改已通过 dxs report datasource add/remove 反映在清单中。

如需了解其他上传模式和验证方法，请参阅 deploy-patterns.md。

验证

dxs report get <reference_name> --branch <branch_id>

确认报告位于分支上，并具有预期的结构、数据源绑定和参数。

测试参数发现

如果数据源包含 in_params，请按照 deploy-patterns.md 查找真实测试值，并将其输出为 JSON，供用户在 Studio 中测试。

故障排除

常见的 RDLX-JSON 表达式问题以及布局或 CLI 操作错误，请参阅 troubleshooting.md。

特定编辑器问题

错误	修复方法
未先下载报告就进行修改	始终运行 dxs report download 获取当前版本——编辑过时的本地文件会导致其他更改丢失
向 DataSet 添加字段，但未更新示例数据	Studio 预览中的新字段会显示为空白——请使用示例值更新 .data.json
未经检查就假设数据源包含该字段	始终运行 datasource-fields 进行验证——该字段可能不在 $select 中
更改字段表达式，但未更改 DataSet 字段	如果重命名 DataField 路径，也必须更新 DataSet 字段以保持一致
移除仍被引用的数据源字段	移除之前，检查报告中的所有表达式，确认没有 Fields!RemovedField.Value
将集合路径字段作为平铺的 DataSet 字段添加	在单结果 DataSet 中，集合导航属性会静默解析为空白——使用 flow 数据源展平，或创建子数据集并设置 CommandText: "$.ds.result.Collection.*"

---

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