ccdi/openspec/changes/replace-poi-with-easyexcel/specs/excel-import-export/spec.md

Spec: Excel Import/Export with EasyExcel

ADDED Requirements

Requirement: 流式导出大量数据

The system MUST support streaming export using EasyExcel to handle datasets exceeding 100,000 rows while maintaining low memory footprint.

系统必须支持使用 EasyExcel 进行流式导出，以处理超过 10 万行的数据集，同时保持低内存占用。

Scenario: 导出 10 万行用户数据

Given 系统中有 10 万条用户记录

When 管理员调用用户导出接口

Then 系统应：

• 成功生成包含 10 万行数据的 Excel 文件
• 内存占用不超过 500MB
• 导出时间在合理范围内（< 30 秒）
• 生成的文件包含所有必要的表头和样式

Scenario: 导出超过 65536 行数据

Given 数据集包含 10 万行记录（超过传统 Excel 限制）

When 调用导出功能

Then 系统应：

• 自动使用 .xlsx 格式
• 不进行 Sheet 分割（EasyExcel 自动处理）
• 所有数据完整导出到单个文件

---

Requirement: 流式导入大文件

The system MUST support streaming import using EasyExcel to process Excel files larger than 100MB.

系统必须支持使用 EasyExcel 进行流式读取，以处理超过 100MB 的 Excel 文件。

Scenario: 导入包含 10 万行数据的 Excel 文件

Given 一个包含 10 万行数据的 Excel 文件（约 50MB）

When 管理员上传该文件进行导入

Then 系统应：

• 逐行解析文件，不一次性加载到内存
• 内存占用不超过 200MB
• 正确解析所有数据行
• 返回完整的解析结果列表

Scenario: 导入包含超长文本的单元格

Given Excel 文件中某些单元格包含超过 32,767 个字符（超过 POI 限制）

When 执行导入操作

Then 系统应：

• 完整读取单元格内容
• 不截断或丢失数据
• 正确映射到实体类字段

---

Requirement: 保持注解驱动配置兼容性

The system MUST maintain compatibility with existing @Excel and @Excels annotations, allowing existing entity classes to work without modification.

系统必须保持与现有 @Excel 和 @Excels 注解的兼容性，使现有实体类无需修改即可使用新实现。

Scenario: 使用现有注解导出数据

Given 实体类上已定义 @Excel 注解

@Excel(name = "用户名", sort = 1)
private String userName;

@Excel(name = "性别", dictType = "sys_user_sex", sort = 2)
private String sex;

@Excel(name = "创建时间", dateFormat = "yyyy-MM-dd HH:mm:ss", sort = 3)
private Date createTime;

When 调用导出功能

Then 系统应：

• 正确解析 @Excel 注解配置
• 按指定的 sort 顺序排列列
• 应用字典转换（dictType）
• 应用日期格式化（dateFormat）
• 生成包含正确表头的 Excel 文件

Scenario: 使用复合注解导出嵌套属性

Given 实体类使用 @Excels 注解配置多个导出规则

@Excels({
    @Excel(name = "部门名称", targetAttr = "deptName", sort = 10),
    @Excel(name = "部门编码", targetAttr = "deptCode", sort = 11)
})
private SysDept dept;

When 调用导出功能

Then 系统应：

• 正确解析嵌套对象属性
• 生成多个对应的列
• 正确填充数据

---

Requirement: 样式与格式支持

The system SHALL support basic cell styling configuration through annotations, including alignment, background color, etc.

系统应当支持通过注解配置基本的单元格样式，包括对齐方式、背景色等。

Scenario: 应用自定义样式

Given 实体类定义了样式配置

@Excel(
    name = "金额",
    align = HorizontalAlignmentEnum.RIGHT,
    backgroundColor = "yellow",
    color = "red",
    sort = 5
)
private BigDecimal amount;

When 导出数据

Then 系统应：

• 单元格内容右对齐
• 背景色为黄色
• 字体颜色为红色

Scenario: 数字格式化

Given 字段配置了精度和舍入模式

@Excel(name = "单价", scale = 2, roundingMode = BigDecimal.ROUND_HALF_UP)
private BigDecimal price;

When 导出包含该字段的数据

Then 系统应：

• 数值保留 2 位小数
• 使用四舍五入规则

---

Requirement: 导入模板生成

The system MUST support generating empty import templates for users to fill and upload.

系统必须支持生成空的导入模板，供用户填写后上传。

Scenario: 生成导入模板

Given 实体类配置了 @Excel 注解，其中部分字段标记为仅导入

@Excel(name = "用户名", type = Type.ALL)
private String userName;

@Excel(name = "密码", type = Type.IMPORT)  // 仅导入
private String password;

When 调用 importTemplateExcel() 方法

Then 系统应：

• 生成包含所有 type=IMPORT 或 type=ALL 字段的表头
• 仅导入字段（type=IMPORT）不出现在模板中
• 应用数据验证配置（如果有）
• 设置合适的列宽

---

Requirement: 字段筛选功能

The system MUST support runtime control of exported fields.

系统必须支持运行时动态控制导出包含的字段。

Scenario: 显示指定字段

Given 实体类有 20 个字段，但只想导出其中 5 个

When 调用 util.showColumn("id", "name", "email", "phone", "status")

Then 导出的 Excel 应：

• 仅包含指定的 5 个字段
• 其他字段不出现在导出结果中

Scenario: 排除指定字段

Given 实体类有 20 个字段，想导出其中 18 个

When 调用 util.hideColumn("password", "salt")

Then 导出的 Excel 应：

• 包含除 password 和 salt 外的所有字段
• 敏感字段不出现在导出结果中

---

Requirement: 自定义数据处理器

The system MUST support custom data handlers for special cell data processing.

系统必须支持通过自定义处理器对单元格数据进行特殊处理。

Scenario: 使用自定义处理器格式化数据

Given 定义了自定义处理器

public class CustomAmountHandler implements ExcelHandlerAdapter {
    @Override
    public Object format(Object value, String[] args, Cell cell, Workbook wb) {
        // 将金额转换为中文大写
        return convertToChinese((BigDecimal) value);
    }
}

And 实体字段配置使用该处理器

@Excel(name = "金额(大写)", handler = CustomAmountHandler.class)
private BigDecimal amount;

When 导出数据

Then 金额列应显示为中文大写形式（如：壹万贰仟叁佰肆拾伍元陆角柒分）

---

Requirement: 数据验证支持

The system SHALL support configuring dropdown options and prompt information for import templates.

系统应当支持为导入模板配置下拉选项和提示信息。

Scenario: 配置下拉选项

Given 字段配置了固定的下拉选项

@Excel(name = "状态", combo = {"启用", "禁用"})
private String status;

When 生成导入模板

Then 该单元格应：

• 显示下拉箭头
• 仅能选择"启用"或"禁用"
• 无法输入其他值

Scenario: 从字典读取下拉选项

Given 字段配置从字典读取选项

@Excel(name = "性别", dictType = "sys_user_sex", comboReadDict = true)
private String sex;

When 生成导入模板

Then 该单元格的下拉列表应：

• 包含字典中定义的所有选项
• 动态从系统缓存读取

---

MODIFIED Requirements

Requirement: ExcelUtil API 兼容性

The modified ExcelUtil MUST maintain API compatibility with existing code.

修改后的 ExcelUtil 必须保持与现有代码的 API 兼容性。

Scenario: 使用现有导出方法

Given 现有 Controller 代码

List<SysUser> list = userService.selectUserList(user);
ExcelUtil<SysUser> util = new ExcelUtil<SysUser>(SysUser.class);
util.exportExcel(response, list, "用户数据");

When 替换为 EasyExcel 实现

Then 代码应无需修改即可正常工作

Scenario: 使用现有导入方法

Given 现有导入代码

ExcelUtil<SysUser> util = new ExcelUtil<SysUser>(SysUser.class);
List<SysUser> userList = util.importExcel(file.getInputStream());

When 替换为 EasyExcel 实现

Then 代码应无需修改即可正常工作

---

REMOVED Requirements

无

此变更不删除任何现有功能需求，仅替换底层实现。