报表

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

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

报表生成涉及哪些职责

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

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

接入数据服务

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

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

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

模板与资源生命周期

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

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

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

当前实现范围

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

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

建议的验收顺序

1. 使用一份固定的小模板验证资源查找和引擎加载。

2. 用少量已知数据验证字段、分组、排序和数据权限。

3. 检查跨页数据、中文字体、时区与数值格式。

4. 针对实际实现支持的输出格式验证下载结果，记录页数与数据总量。

5. 再测试并发、超时、临时文件清理及失败后的资源释放。

表格数据交换不一定需要报表引擎。只需导入导出工作簿时，参见表格与模板扩展。

源码入口：报表模块、默认数据加载。