# rdms-spring-boot-starter-excel

## 模块定位
这是一个面向业务的 Excel 能力模块，核心目标是：

1. 降低导入导出开发成本（统一工具类）
2. 让业务字段和 Excel 展示语义解耦（注解 + Converter）
3. 把字典能力接入 Excel 场景（值与标签互转、校验、下拉选项）

## 设计思路

1. 统一入口：通过 `ExcelUtils` 封装读写，Controller 只关心 VO 和数据。
2. 注解驱动：通过 `@DictFormat`、`@ExcelColumnSelect` 把“字段语义”放在 VO 上，而不是散落在业务代码里。
3. 转换器分层：`DictConvert`、`AreaConvert`、`JsonConvert`、`MoneyConvert` 分别处理不同类型转换。
4. 字典缓存：`DictFrameworkUtils` 基于缓存读取字典，减少重复远程调用。
5. 导出体验：自动列宽、下拉选项、Long 防精度丢失等细节统一在模块内处理。

## 核心类

1. `com.njcn.rdms.framework.excel.core.util.ExcelUtils`
2. `com.njcn.rdms.framework.excel.core.convert.DictConvert`
3. `com.njcn.rdms.framework.excel.core.handler.SelectSheetWriteHandler`
4. `com.njcn.rdms.framework.dict.core.DictFrameworkUtils`
5. `com.njcn.rdms.framework.dict.validation.InDict`

## 示例：用户导入导出（含字典转换）

### 1. 定义 Excel VO

```java
import cn.idev.excel.annotation.ExcelProperty;
import com.njcn.rdms.framework.excel.core.annotations.DictFormat;
import com.njcn.rdms.framework.excel.core.convert.DictConvert;
import lombok.Data;

@Data
public class UserImportExcelVO {

    @ExcelProperty("登录名称")
    private String username;

    @ExcelProperty(value = "用户性别", converter = DictConvert.class)
    @DictFormat("USER_SEX")
    private Integer sex;

    @ExcelProperty(value = "账号状态", converter = DictConvert.class)
    @DictFormat("COMMON_STATUS")
    private Integer status;
}
```

### 2. 导出模板

```java
import com.njcn.rdms.framework.excel.core.util.ExcelUtils;
import jakarta.servlet.http.HttpServletResponse;

public void exportTemplate(HttpServletResponse response) throws Exception {
    ExcelUtils.write(response, "用户导入模板.xls", "用户列表", UserImportExcelVO.class, List.of());
}
```

### 3. 导入解析

```java
import com.njcn.rdms.framework.excel.core.util.ExcelUtils;
import org.springframework.web.multipart.MultipartFile;

public List<UserImportExcelVO> importExcel(MultipartFile file) throws Exception {
    return ExcelUtils.read(file, UserImportExcelVO.class);
}
```

说明：

1. 导入时 `DictConvert` 会把 Excel 标签值转回字典 value（如“男”->`1`）。
2. 导出时 `DictConvert` 会把字典 value 转成可读标签（如 `1`->“男”）。

## 适用场景

1. 后台管理常规 Excel 导入导出
2. 字典字段较多、希望自动做值/标签转换
3. 需要生成带下拉选项的导入模板

## 不适用场景

1. 超大规模离线数据处理（建议走专用批处理链路）
2. 复杂流式处理或多工作簿复杂编排（建议单独实现）