275 lines
7.3 KiB
Markdown
275 lines
7.3 KiB
Markdown
# 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文档
|
||
|
||
### 导出订单
|
||
|
||
```http
|
||
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": "测试"
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 异步导出
|
||
|
||
```http
|
||
POST /api/v1/exports/orders/async
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"tenantId": 1,
|
||
"format": "XLSX",
|
||
"startDate": "2024-01-01",
|
||
"endDate": "2024-01-31"
|
||
}
|
||
```
|
||
|
||
### 查询导出历史
|
||
|
||
```http
|
||
GET /api/v1/exports?tenantId=1&type=ORDERS&status=COMPLETED&page=1&pageSize=20
|
||
```
|
||
|
||
### 下载导出文件
|
||
|
||
```http
|
||
GET /api/v1/exports/{id}/download?tenantId=1
|
||
```
|
||
|
||
### 创建定时导出任务
|
||
|
||
```http
|
||
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部署
|
||
|
||
```bash
|
||
# 构建并启动
|
||
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部署
|
||
|
||
```bash
|
||
# 部署
|
||
./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导出
|
||
- 支持订单/商品/库存/供应商导出
|
||
- 支持异步导出
|