初始化

rdms-framework/rdms-spring-boot-starter-excel/README.md

@@ -0,0 +1,89 @@
+# 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. 复杂流式处理或多工作簿复杂编排（建议单独实现）
+