# 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导出
- 支持订单/商品/库存/供应商导出
- 支持异步导出