# 通用 Excel 模块

`pjcloud-common-excel` 提供 Excel 导入、普通导出以及大数据量 XLSX 分批流式导出能力。

## 分批流式导出

`BatchExcelExportTemplate` 适用于单次导出不能把全部查询结果和全部工作表行同时保留在 JVM 堆中的场景。它统一负责：

- 根据预统计数量循环分页查询；
- 使用 `SXSSFWorkbook` 把超出内存窗口的工作表行刷新到磁盘；
- 校验分页实际数量与预统计数量一致；
- 校验 Excel 2007 单工作表行数上限；
- 释放模板流、工作簿、SXSSF 临时 XML 和最终 XLSX 临时文件；
- 通过回调接入业务进度、汇总行和文件上传逻辑。

业务模块先增加公共 Excel 依赖：

```xml
<dependency>
	<groupId>com.bsd</groupId>
	<artifactId>pjcloud-common-excel</artifactId>
</dependency>
```

典型调用方式：

```java
String fileUrl = BatchExcelExportTemplate.<ExportRow, ExportContext, String>builder(total)
		.batchSize(1000)
		.dataStartRowIndex(2)
		.reservedTailRowCount(1)
		.temporaryFilePrefix("user-export-")
		.templateSupplier(() -> ResourceUtil.getStream("file/user.xlsx"))
		.templateInitializer(workbook -> prepareTemplate(workbook))
		.pageFetcher((pageNumber, batchSize) -> {
			Page<ExportRow> page = new Page<>(pageNumber, batchSize, false);
			return userService.pageForExport(page, query).getRecords();
		})
		.rowWriter((sheet, rowIndex, dataIndex, item, context) ->
				writeRow(sheet, rowIndex, dataIndex, item, context))
		.footerWriter((sheet, rowIndex, processedTotal, context) ->
				writeSummary(sheet, rowIndex, context))
		.progressListener((processedTotal, expectedTotal) ->
				reporter.advance("已整理 " + processedTotal + " / " + expectedTotal + " 条"))
		.fileConsumer(path -> upload(Files.readAllBytes(path), fileName))
		.execute();
```

## 与异步任务组合

公共 Excel 模块不依赖 `pjcloud-common-async-task`。业务层通过 `progressListener` 把每批完成事件转给
`AsyncTaskProgressReporter`，通过 `fileConsumer` 上传完整文件并返回 `AsyncTaskResult` 所需的地址。

异步任务总步数可统一计算：

```java
int progressTotal = BatchExcelExportTemplate.calculateProgressTotal(total, batchSize, 2);
reporter.updateTotal(progressTotal, "已查询 " + total + " 条数据，将分批生成文件");
```

额外的 `2` 由业务流程定义，例如文件上传一步和异步任务成功收尾一步。公共模板每完成一个查询批次只通知一次，
不会按明细行高频写 Redis。

## 调用约束

- 预统计和分页查询必须使用完全相同的筛选条件、租户上下文和数据权限。
- 分页 SQL 必须有稳定排序；排序字段存在重复值时，需要追加唯一字段，避免翻页时漏行或重复。
- 导出期间数据发生增删会触发数量不一致异常，业务方应提示用户重新导出。
- `dataStartRowIndex` 和 `reservedTailRowCount` 都按 Excel 零基行号语义配置。
- `fileConsumer` 收到的路径只在回调期间有效，不得交给其他线程延迟读取。
- 默认关闭共享字符串表以控制内存；只有确认重复文本占比高且内存可控时才启用。
- 单个工作表仍受 XLSX 的 1,048,576 行上限约束；超过上限时应按业务条件拆分文件或扩展为多工作表导出。