# Tasks: Replace Apache POI with Alibaba EasyExcel

## 依赖更新与环境准备

- [x] 1.1 更新 `pom.xml`，添加 `easyexcel.version` 属性（版本 3.3.4）
- [x] 1.2 更新 `ruoyi-common/pom.xml`，保留 `poi-ooxml` 依赖，添加 `easyexcel` 依赖
- [ ] 1.3 验证依赖解析成功：`mvn dependency:tree`
- [x] 1.4 备份现有的 `ExcelUtil.java` 文件到 `excel/` 目录（保留参考）

## 注解与接口适配

- [x] 2.1 更新 `Excel.java` 注解：
  - [x] 2.1.1 移除 POI 类型的 import（`HorizontalAlignment`, `IndexedColors`）
  - [x] 2.1.2 使用字符串替代（`align`, `headerBackgroundColor` 等）
  - [x] 2.1.3 调整颜色属性为字符串表示
  - [x] 2.1.4 更新 `Javadoc` 注释

- [x] 2.2 更新 `ExcelHandlerAdapter.java` 接口：
  - [x] 2.2.1 保留原有方法签名
  - [x] 2.2.2 添加 EasyExcel `Cell` 和 `Workbook` 类型适配说明

- [x] 2.3 验证注解编译无误

## 核心 ExcelUtil 重写

- [x] 3.1 创建新的 `ExcelUtil.java` 基础结构：
  - [x] 3.1.1 保留泛型类定义 `ExcelUtil<T>`
  - [x] 3.1.2 保留现有公共方法签名
  - [x] 3.1.3 移除 POI 相关的私有字段和方法

- [x] 3.2 实现导出功能：
  - [x] 3.2.1 `exportExcel(HttpServletResponse, List<T>, String, String)` - 主入口
  - [x] 3.2.2 `exportExcel(HttpServletResponse, List<T>, String)` - 简化版
  - [x] 3.2.3 `exportExcel()` - 返回文件名版本
  - [x] 3.2.4 `importTemplateExcel()` - 生成导入模板

- [x] 3.3 实现导入功能：
  - [x] 3.3.1 `importExcel(InputStream)` - 默认标题行
  - [x] 3.3.2 `importExcel(InputStream, int titleNum)` - 自定义标题行
  - [x] 3.3.3 `importExcel(String sheetName, InputStream, int titleNum)` - 指定 Sheet

- [x] 3.4 实现 EasyExcel 集成组件：
  - [x] 3.4.1 `ExcelStyleHandler` - 样式处理器（基于 `@Excel` 注解）
  - [x] 3.4.2 `ReadListener` - 读取监听器（内置在 `importExcel` 中）

- [x] 3.5 实现辅助功能：
  - [x] 3.5.1 字典类型转换（`dictType`）
  - [x] 3.5.2 表达式转换（`readConverterExp`）
  - [x] 3.5.3 字段筛选（`showColumn`, `hideColumn`）
  - [ ] 3.5.4 日期格式化（`dateFormat`）- EasyExcel 自动处理
  - [ ] 3.5.5 自定义处理器（`handler`）- 需要进一步适配

## 集成测试与验证

- [ ] 4.1 单元测试：
  - [ ] 4.1.1 测试基本导出功能（少量数据）
  - [ ] 4.1.2 测试大数据量导出（10 万行）
  - [ ] 4.1.3 测试基本导入功能
  - [ ] 4.1.4 测试大文件导入（100MB）
  - [ ] 4.1.5 测试超长文本单元格
  - [ ] 4.1.6 测试样式应用
  - [ ] 4.1.7 测试字典转换
  - [ ] 4.1.8 测试字段筛选

- [ ] 4.2 现有功能集成测试：
  - [ ] 4.2.1 测试 `SysUserController` 导入导出
  - [ ] 4.2.2 测试 `SysRoleController` 导入导出
  - [ ] 4.2.3 测试 `SysDictDataController` 导入导出
  - [ ] 4.2.4 测试 `SysPostController` 导入导出
  - [ ] 4.2.5 测试 `SysConfigController` 导入导出
  - [ ] 4.2.6 测试 `SysOperlogController` 导入导出
  - [ ] 4.2.7 测试 `SysLogininforController` 导入导出
  - [ ] 4.2.8 测试 `SysJobController` 导入导出
  - [ ] 4.2.9 测试 `SysJobLogController` 导入导出

- [ ] 4.3 性能验证：
  - [ ] 4.3.1 使用 VisualVM 监控导出 10 万行数据的内存占用
  - [ ] 4.3.2 使用 VisualVM 监控导入 100MB 文件的内存占用
  - [ ] 4.3.3 记录并对比迁移前后的性能指标

## 文档更新

- [ ] 5.1 更新 `openspec/project.md`：
  - [ ] 5.1.1 添加 EasyExcel 到技术栈
  - [ ] 5.1.2 更新项目约定中的 Excel 处理说明

- [ ] 5.2 创建 API 文档：
  - [ ] 5.2.1 记录 `ExcelUtil` 公共方法的使用方式
  - [ ] 5.2.2 记录 `@Excel` 注解的所有属性说明
  - [ ] 5.2.3 提供迁移指南（如果 API 有变化）

- [ ] 5.3 更新 `CLAUDE.md`（如需要）：
  - [ ] 5.3.1 添加 Excel 相关的开发约定

## 依赖关系

```
1. 依赖更新
    ↓
2. 注解适配
    ↓
3. ExcelUtil 重写
    ↓
4. 集成测试
    ↓
5. 文档更新
```

## 并行任务

以下任务可以并行执行：
- 2.1-2.3（注解适配）可与 3.1-3.2（ExcelUtil 基础结构）并行
- 4.1（单元测试）可与 4.2（集成测试）部分并行

## 验收标准

所有任务完成后，必须满足：
1. 编译通过，无依赖错误
2. 所有现有 Controller 的导入导出功能正常
3. 导出 10 万行数据内存占用 < 500MB
4. 导入 100MB 文件内存占用 < 200MB
5. 现有实体类注解无需修改