> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/framework/reporting.md).

# 报表

组织报表描述、模板资源与数据加载，并辨别报表契约和具体引擎的能力。

`Zongsoft.Reporting` 提供报表、描述信息、资源、数据模型与数据加载契约。业务可以借此分开管理模板来源和数据供应，但最终渲染、导出及设计功能仍依赖具体报表引擎。

## 报表生成涉及哪些职责

| 环节     | 解决的问题          | 对应抽象                                   |
| ------ | -------------- | -------------------------------------- |
| 识别模板   | 报表名称、来源和描述是什么  | `IReportDescriptor`                    |
| 打开资源   | 从文件或其他位置取得模板内容 | 描述对象、资源及资源解析器                          |
| 建立报表实例 | 用具体引擎加载模板      | 引擎实现的 `IReport`                        |
| 提供数据   | 将报表模型映射到业务查询   | `IReportDataLoader`、`IReportDataModel` |
| 渲染和导出  | 生成可展示或下载的输出    | 具体报表引擎                                 |

资源解析器返回的是报表资源，不能直接当作报表实例工厂。接口中有保存、渲染或导出方法，也不代表每个适配器都已经实现相应方法。

## 接入数据服务

默认 `ReportDataLoader` 按数据模型的 `Name` 从服务容器解析对象，并要求该对象是数据服务；随后使用模型的 `Schema` 发起选择查询。报表模型名因此必须与业务注册的服务别名对应，不能只填写数据库表名。

先完成[数据服务](/framework/data/services.md)的注册与单独查询验证，再连接报表模型。服务的授权、过滤器和查询约束仍然生效，不应通过报表入口绕过业务数据范围。

{% hint style="warning" %}
🚨 默认加载器使用 `Paging.Page(1)`，不会自动遍历全部分页。导出全量报表前，需要明确分页策略、行数上限和资源消耗，并实现适合该报表的数据加载器；否则可能只得到第一页数据。
{% endhint %}

## 模板与资源生命周期

文件描述对象可以打开模板流，但打开文件只证明资源可读，不证明模板格式受目标引擎支持。模板格式、字体、图片和外部数据源应随部署一起核对。

资源流应由明确的一层负责释放。尤其要检查引擎打开模板时是否会关闭调用者传入的流，避免后续处理继续读取已经释放的资源。缓存报表实例之前，还应确认引擎实例能否跨请求共享和并发使用。

文件描述对象的 `Key` 基于路径及运行时哈希，不应当作跨进程、跨版本稳定的报表编号。持久化目录应使用业务自己定义的稳定标识。

## 当前实现范围

`ReportDataLocator` 的当前默认实现没有完成数据定位。使用前需要逐一检查计划调用的方法，而不是仅根据包名安排一条完整的导出流水线。

部署 `Zongsoft.Reporting` 不会自动提供设计器或一个可工作的报表下载接口。应用还需要选择引擎、满足其运行与许可条件、加载模板、连接数据，并处理输出和错误。

## 建议的验收顺序

1. 使用一份固定的小模板验证资源查找和引擎加载。
2. 用少量已知数据验证字段、分组、排序和数据权限。
3. 检查跨页数据、中文字体、时区与数值格式。
4. 针对实际实现支持的输出格式验证下载结果，记录页数与数据总量。
5. 再测试并发、超时、临时文件清理及失败后的资源释放。

表格数据交换不一定需要报表引擎。只需导入导出工作簿时，参见[表格与模板扩展](/framework/externals/documents.md)。

源码入口：[报表模块](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Reporting)、[默认数据加载](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Reporting/src/ReportDataLoader.cs)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zongsoft.com/framework/reporting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.