# Proposal: Replace Apache POI with Alibaba EasyExcel

## Summary

将若依框架中的 Apache POI 替换为 Alibaba EasyExcel，以解决大文本量 Excel 导入导出时的内存占用和性能问题。当前使用 POI 的 SXSSFWorkbook 虽然支持流式写入，但在处理大量数据时仍然存在性能瓶颈，且不支持真正的流式读取。

## Motivation

### 问题分析

1. **当前 POI 实现的限制**：
   - `ExcelUtil.java:112` - `sheetSize` 硬编码为 65536，这是 Excel 2003 的限制
   - `ExcelUtil.java:1682` - 使用 SXSSFWorkbook 进行流式写入，但内存优化有限
   - `ExcelUtil.java:325-525` - `importExcel` 方法一次性加载整个 Sheet 到内存，无法处理大文件
   - POI 的 DOM 解析模式导致大文件内存占用过高

2. **业务需求**：
   - 需要支持导入导出超过 10 万行数据
   - 需要支持单元格内容超过 32767 字符（POI STRING 类型限制）
   - 需要降低内存占用，避免 OOM

3. **EasyExcel 优势**：
   - 基于 SAX 解析，真正的流式读写
   - 内存占用仅与行数据大小相关，与文件大小无关
   - API 设计简洁，注解驱动
   - 官方维护活跃，社区成熟

## Proposed Solution

### 技术方案

1. **保持 API 兼容性**：
   - 保留 `@Excel` 和 `@Excels` 注解接口
   - 保留 `ExcelUtil<T>` 的公共方法签名
   - 保留 `ExcelHandlerAdapter` 接口（适配 EasyExcel 的写处理器）

2. **核心实现变更**：
   - 使用 `EasyExcel.write()` 替代 POI 的 Workbook/Sheet 操作
   - 使用 `EasyExcel.read()` 替代 POI 的 Workbook 解析
   - 实现自定义的 `HeadGenerator` 和 `ContentStyleStrategy` 以支持样式

3. **依赖变更**：
   - 移除 `poi-ooxml` 依赖
   - 添加 `easyexcel` 依赖（版本 3.3.4，支持 Spring Boot 3）

### 影响范围

**修改的文件**：
- `ruoyi-common/pom.xml` - 更新依赖
- `ruoyi-common/src/main/java/com/ruoyi/common/utils/poi/ExcelUtil.java` - 重写实现
- `ruoyi-common/src/main/java/com/ruoyi/common/annotation/Excel.java` - 调整注解属性
- `ruoyi-common/src/main/java/com/ruoyi/common/utils/poi/ExcelHandlerAdapter.java` - 适配新接口

**无需修改的文件**（向后兼容）：
- 所有 Controller 层代码（13 个文件使用 ExcelUtil）
- 实体类上的 `@Excel` 注解

## Alternatives Considered

### 方案 1：升级 POI 版本
- **优点**：代码改动最小
- **缺点**：无法从根本上解决内存问题，POI 的架构限制依然存在

### 方案 2：使用 Hutool 的 Excel 工具
- **优点**：API 简洁
- **缺点**：底层仍使用 POI，内存问题未解决

### 方案 3：使用 EasyExcel（选定方案）
- **优点**：真正的流式处理，内存占用低，社区成熟
- **缺点**：需要适配现有注解和 API

## Compatibility Notes

### 破坏性变更

1. **样式支持**：EasyExcel 的样式支持有限，以下功能可能需要简化：
   - 合并单元格（`needMerge`）
   - 图片插入（`ColumnType.IMAGE`）
   - 数据验证（`combo`, `comboReadDict`）
   - 自定义颜色（`headerBackgroundColor`, `color` 等）

2. **Sheet 分割**：EasyExcel 自动处理大文件，无需手动分割 Sheet

3. **统计行**：`isStatistics` 需要通过监听器实现

### 保留的功能

- ✅ 注解驱动配置
- ✅ 字典类型转换（`dictType`）
- ✅ 表达式转换（`readConverterExp`）
- ✅ 日期格式化（`dateFormat`）
- ✅ 导入/导出模板生成
- ✅ 字段筛选（`includeFields`, `excludeFields`）

## Success Criteria

1. **性能指标**：
   - 导出 10 万行数据，内存占用 < 500MB
   - 导入 100MB Excel 文件，内存占用 < 200MB

2. **功能完整性**：
   - 所有现有 Controller 的导入导出功能正常工作
   - 支持超过 65536 行数据

3. **兼容性**：
   - 现有实体类注解无需修改
   - 现有业务代码无需修改

## Timeline

阶段划分（具体任务见 tasks.md）：
1. 依赖更新与环境准备
2. 核心 ExcelUtil 重写
3. 注解与接口适配
4. 集成测试与验证
5. 文档更新

## Related Changes

- 无前置依赖
- 可能影响：所有使用 Excel 导入导出的模块