platform-report-generate

概述

Lightning 报表定义了 Salesforce 数据的查询、分组、筛选和显示方式。每个报表都是一个单独的 .report-meta.xml 文件，位于项目源目录下的 reports/<FolderName>/ 中（在 sfdx-project.json → packageDirectories[].path 中查看源目录根路径）。

关键规则（请先阅读）

最容易导致部署失败的因素——生成任何报表前，请先检查以下内容：

1. 分组字段出现在列中——<groupingsDown> 或 <groupingsAcross> 中的字段绝不能同时出现在 <columns> 中
2. 列名称错误——列名称因报表类型而异。务必调用 MCP 工具进行验证（参见 references/column-names.md）
3. 范围错误——LeadList 使用 org，而不是 organization
4. 筛选列的点号表示法——筛选器 <column> 值使用扁平名称（INDUSTRY、TYPE），而不是点号表示法（ACCOUNT.INDUSTRY 无效）
5. 多值选项列表筛选器——使用一个 <criteriaItems>，并以逗号分隔 <value>（例如 Technology,Financial Services）。不要使用 booleanFilter 将内容拆分为多个 criteriaItems

规则 1：格式决定必需元素

格式	<groupingsDown>	<groupingsAcross>	<block>
Tabular	不允许	不允许	否
Summary	至少 1 个（最多 3 个）	不允许	否
Matrix	至少 1 个（最多 3 个）	至少 1 个（最多 3 个）	否
Joined	顶层不允许	顶层不允许	至少 2 个（最多 5 个）

规则 2：使用平台列名称

报表元数据使用平台报表列名称，而不是原始 API 字段名称。**务必调用 get_metadata_type_sections 或 get_metadata_type_context，以确认有效列名称。**各报表类型的常见映射请参见 references/column-names.md。

规则 3：必须使用有效的报表类型

<reportType> 必须是标准 API 名称（例如 Opportunity、AccountList、CaseList、LeadList、AccountContactRole），或已部署的自定义报表类型开发者名称。

规则 4–5：图表和汇总字段需要 Summary/Matrix

图表和 <aggregateTypes>（Sum、Average 等）仅适用于 Summary 和 Matrix 报表。

规则 6–8：限制

• 每个报表最多 3 个交叉筛选器，每个筛选器最多包含 5 个条件项
• <filterLogic> 必须按顺序引用所有筛选器（例如 1 AND (2 OR 3)）
• Joined 报表：包含 2–5 个区块，每个区块的格式必须为 Summary 或 Matrix（不能是 Tabular）

规则 9：文件夹结构

报表必须位于包含对应文件夹元数据文件的文件夹中：

<sourceDir>/reports/<FolderName>/<ReportName>.report-meta.xml
<sourceDir>/reports/<FolderName>-meta.xml

根据 sfdx-project.json 确定 <sourceDir>（通常为 force-app/main/default，但可进行配置）。

规则 10–11：日期列和范围

• 日期列使用平台名称（CLOSE_DATE，而不是 CloseDate）
• LeadList 的范围为 org；Opportunity/AccountList/CaseList 使用 organization

规则 12–13：描述和分组

• <description> 最多 255 个字符
• 分组字段不得出现在 <columns> 中——否则部署会自动失败

规则 14：文件夹元数据必须包含 <sharedTo>

<?xml version="1.0" encoding="UTF-8"?>
<ReportFolder xmlns="http://soap.sforce.com/2006/04/metadata">
    <folderShares>
        <accessLevel>Manage</accessLevel>
        <sharedTo>AllInternalUsers</sharedTo>
        <sharedToType>Group</sharedToType>
    </folderShares>
    <name>My Report Folder</name>
</ReportFolder>

规则 15：仅使用有效的日期间隔

“本季度”使用 INTERVAL_CURRENT，“今年”使用 INTERVAL_CURY，“最近 30 天”使用 INTERVAL_LAST30。不要使用 INTERVAL_CURQ——它无效。完整列表请参见 references/date-intervals.md。

顶层元素

元素	必需	说明
<name>	是	报告名称（最多 40 个字符）
<reportType>	是	报告类型 API 名称
<format>	是	Tabular、Summary、Matrix 或 Joined
<scope>	建议	organization（LeadList 可使用 org）
<columns>	是	字段列 — 每列包含 <field> 和可选的 <aggregateTypes>
<filter>	否	包含 <criteriaItems>，其中含有 <column>、<operator>、<value>
<groupingsDown>	有条件	行分组：<field>、<dateGranularity>、<sortOrder>
<groupingsAcross>	有条件	列分组（仅限 Matrix）
<timeFrameFilter>	建议	<dateColumn>、<interval>，以及可选的 <startDate>/<endDate>
<chart>	否	请参阅 references/chart-types.md
<buckets>	否	分桶字段定义
<crossFilters>	否	跨对象筛选（with/without）
<showDetails>	建议	true/false
<showGrandTotal>	建议	true/false
<showSubTotals>	建议	true/false
<description>	建议	业务用途（最多 255 个字符）
<block>	有条件	Joined 格式区块

筛选语法

<filter>
    <criteriaItems>
        <column>STAGE_NAME</column>
        <operator>equals</operator>
        <value>Closed Won</value>
    </criteriaItems>
</filter>

多值选项列表： 使用一个 criteriaItem，并以逗号分隔多个值：

<criteriaItems>
    <column>INDUSTRY</column>
    <operator>equals</operator>
    <value>Technology,Financial Services</value>
</criteriaItems>

常见运算符：equals、notEqual、lessThan、greaterThan、contains、startsWith、includes、excludes、isBlank、notBlank。完整列表请参阅 references/filter-operations.md。

生成工作流

1. 收集需求 — 对象、字段、分组、筛选条件和图表需求
2. 确定格式 — 无分组 → Tabular；有行分组 → Summary；有行和列分组 → Matrix；多个对象 → Joined
3. 确定列名称 — 调用 get_metadata_type_sections MCP 工具，获取此报告类型的有效平台列名称
4. 编写元数据 — 从 examples/ 中最接近的示例开始并进行调整
5. 创建文件夹 — 生成文件夹目录和包含 <folderShares> 的 <FolderName>-meta.xml
6. 验证 — 按照 references/verification-checklist.md 进行检查

参考文件索引

文件	阅读时机
references/column-names.md	步骤 3 — 各报告类型的列名称映射
references/date-intervals.md	设置 timeFrameFilter 间隔时
references/chart-types.md	添加图表时 — 全部 17 种类型和 legendPosition 规则
references/filter-operations.md	构建筛选条件时 — 完整的运算符参考
references/verification-checklist.md	步骤 6 — 部署前验证
references/errors-and-troubleshooting.md	字段缺失或部署失败时
examples/TabularOpportunitiesReport.report-meta.xml	Tabular 报告模板
examples/OpportunitiesByStageReport.report-meta.xml	带图表的 Summary 报告
examples/OpportunitiesByStageAndQuarter.report-meta.xml	Matrix 报告模板
examples/AccountsCreatedThisYear.report-meta.xml	带时间范围的筛选报告