7.3 KiB
7.3 KiB
Report Export Module - 报表导出模块
概述
报表导出模块是ERP系统的核心组件，负责将系统中的各类业务数据（订单、商品、库存、供应商等）导出为多种格式（CSV、Excel、PDF），支持同步和异步导出，提供定时任务功能。
功能特性
1. 多格式导出
- CSV: 带BOM的UTF-8编码，完美兼容Microsoft Excel
- Excel (XLSX): Apache POI生成，支持大数据量
- PDF: OpenPDF生成，适合打印存档
2. 导出类型
| 类型 | 说明 | API端点 |
|---|---|---|
| 订单导出 | 导出订单主信息和明细 | POST /api/v1/exports/orders |
| 商品导出 | 导出商品SKU信息 | POST /api/v1/exports/goods |
| 库存导出 | 导出库存快照数据 | POST /api/v1/exports/inventory |
| 供应商导出 | 导出供应商信息 | POST /api/v1/exports/suppliers |
| 库存报表 | 导出库存统计报表 | POST /api/v1/exports/reports/stock |
| 销售报表 | 导出销售统计报表 | POST /api/v1/exports/reports/sales |
| 订单报表 | 导出订单统计报表 | POST /api/v1/exports/reports/orders |
| 采购报表 | 导出采购统计报表 | POST /api/v1/exports/reports/purchases |
| 资金报表 | 导出资金流水报表 | POST /api/v1/exports/reports/finances |
3. 异步导出
- 支持异步导出，提交后立即返回
- 异步任务使用独立线程池处理
- 可查询导出进度和历史记录
4. 定时导出
- 支持Cron表达式配置定时任务
- 可按每天/每周/每月等周期自动导出
- 定时任务可取消和管理
5. 导出历史管理
- 记录每次导出的元信息
- 支持分页查询导出历史
- 自动清理过期导出文件
API文档
导出订单
POST /api/v1/exports/orders
Content-Type: application/json
{
"tenantId": 1,
"userId": 100,
"format": "CSV",
"platform": "taobao",
"status": "completed",
"warehouseId": 1,
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"keyword": "测试"
}
响应示例：
{
"code": 200,
"message": "导出成功",
"data": {
"id": 1,
"filename": "orders_1_1704067200000.csv",
"filePath": "/data/exports/1/orders_1_1704067200000.csv",
"fileSize": 102400,
"fileSizeFormatted": "100.00 KB",
"rowCount": 1000,
"status": "COMPLETED",
"downloadUrl": "/api/v1/exports/1/download",
"createdAt": "2024-01-01T12:00:00",
"completedAt": "2024-01-01T12:00:05"
}
}
异步导出
POST /api/v1/exports/orders/async
Content-Type: application/json
{
"tenantId": 1,
"format": "XLSX",
"startDate": "2024-01-01",
"endDate": "2024-01-31"
}
查询导出历史
GET /api/v1/exports?tenantId=1&type=ORDERS&status=COMPLETED&page=1&pageSize=20
下载导出文件
GET /api/v1/exports/{id}/download?tenantId=1
创建定时导出任务
POST /api/v1/exports/scheduled?cronExpression=0%200%2012%20*%20*%20?
Content-Type: application/json
{
"tenantId": 1,
"type": "ORDERS",
"format": "CSV",
"startDate": "2024-01-01",
"endDate": "2024-01-31"
}
技术架构
核心技术栈
- Spring Boot 3.x: 基础框架
- Spring Scheduling: 定时任务
- Apache POI 5.x: Excel文件生成
- OpenPDF: PDF文件生成
- MyBatis Plus: 数据访问层
- Redis: 缓存和分布式锁
- Nacos: 服务发现和配置中心
核心组件
com.erp.report.export
├── controller/
│ └── ReportExportController.java # REST API控制器
├── service/
│ ├── ReportExportService.java # 服务接口
│ └── ReportExportServiceImpl.java # 服务实现
├── entity/
│ └── DataExportEntity.java # 导出记录实体
├── repository/
│ └── DataExportRepository.java # 数据访问层
├── dto/
│ ├── ExportFormat.java # 导出格式枚举
│ ├── ExportType.java # 导出类型枚举
│ ├── ExportStatus.java # 导出状态枚举
│ ├── ExportRequest.java # 导出请求DTO
│ └── ExportResponse.java # 导出响应DTO
├── scheduler/
│ └── ExportScheduler.java # 定时任务调度器
└── config/
├── AsyncConfig.java # 异步配置
└── ExportWebConfig.java # Web配置
线程池配置
| 参数 | 值 | 说明 |
|---|---|---|
| corePoolSize | 4 | 核心线程数 |
| maxPoolSize | 8 | 最大线程数 |
| queueCapacity | 100 | 任务队列容量 |
| threadNamePrefix | export- | 线程名前缀 |
文件存储
- 默认存储路径:
/data/exports/{tenantId}/ - 支持NFS等共享存储
- 自动清理7天前的导出文件
部署指南
Docker部署
# 构建并启动
docker-compose -f deploy/docker-compose.yml up -d
# 查看日志
docker logs -f report-service
# 扩缩容
docker-compose -f deploy/docker-compose.yml scale report-service=3
Kubernetes部署
# 部署
./deploy/deploy.sh deploy
# 查看状态
kubectl get pods -n erp -l app=report-service
# 扩缩容
kubectl scale deployment/report-service --replicas=4 -n erp
# 查看日志
kubectl logs -f deployment/report-service -n erp
配置参数
| 参数 | 默认值 | 说明 |
|---|---|---|
| export.base-path | /data/exports | 导出文件存储基础路径 |
| export.max-rows | 10000 | 单次最大导出行数 |
| export.async.core-pool-size | 4 | 异步导出核心线程数 |
| export.async.max-pool-size | 8 | 异步导出最大线程数 |
| export.cleanup.cron | 0 0 2 * * ? | 清理任务Cron表达式 |
| export.cleanup.retention-days | 7 | 导出文件保留天数 |
性能优化
1. 大数据量导出
- 使用流式处理，避免内存溢出
- 分批次查询数据库
- 异步处理，不阻塞主线程
2. 并发控制
- 限制最大并发导出数
- 使用线程池隔离任务
- 队列缓冲，防止过载
3. 存储优化
- 及时清理过期文件
- 使用压缩存储
- 考虑使用对象存储(OSS)
监控告警
健康检查
/actuator/health: 服务健康状态/actuator/metrics: 性能指标
关键指标
export.tasks.total: 导出任务总数export.tasks.active: 当前活跃任务数export.tasks.completed: 已完成任务数export.tasks.failed: 失败任务数export.file.size: 导出文件大小
常见问题
Q: 导出文件打不开？
A: 检查CSV文件编码是否为UTF-8-BOM，Excel需要使用带BOM的UTF-8编码才能正确显示中文。
Q: 导出超时怎么办？
A: 建议使用异步导出接口，导出会后台处理，完成后可查询历史记录下载。
Q: 导出文件在哪里？
A: 默认存储在/data/exports/{tenantId}/目录下，可通过API下载或直接访问。
Q: 如何设置定时导出？
A: 使用/api/v1/exports/scheduled接口创建定时任务，Cron表达式如0 0 12 * * ?表示每天中午12点执行。
更新日志
v1.1.0 (2024-01-15)
- 新增PDF导出格式支持
- 新增定时导出任务功能
- 优化大数据量导出性能
- 新增加强监控指标
v1.0.0 (2024-01-01)
- 初始版本
- 支持CSV/Excel导出
- 支持订单/商品/库存/供应商导出
- 支持异步导出