diff --git a/docs/plans/backend/2026-04-30-import-dropdown-validation-backend-design.md b/docs/plans/backend/2026-04-30-import-dropdown-validation-backend-design.md new file mode 100644 index 00000000..470a9763 --- /dev/null +++ b/docs/plans/backend/2026-04-30-import-dropdown-validation-backend-design.md @@ -0,0 +1,124 @@ +# 导入模板下拉框结构校验后端设计 + +## 背景 + +本次问题来自员工信息维护批量导入文件: + +- 文件路径:`/Users/wkc/Desktop/ccdi/ccdi_bulk_20260430/员工信息维护导入模板_批量测试数据.xlsx` +- 问题表现:`员工信息` Sheet 的 `状态` 列没有 Excel 下拉框,但当前导入链路会继续读取数据并进入业务导入。 + +用户已确认本次范围为:所有 Excel 导入中,凡是导入对象字段标注了 `@DictDropdown`,上传文件对应 Sheet 的对应列都必须保留模板下拉框;缺失下拉框时导入应立即报错。 + +## 目标 + +1. 统一拦截缺少下拉框的数据文件,避免模板结构被破坏后仍被导入。 +2. 覆盖所有使用 `EasyExcelUtil.importExcel(...)` 读取、且导入对象含 `@DictDropdown` 字段的导入接口。 +3. 双 Sheet 导入按 Sheet 分别校验,任一应有下拉框的列缺失时立即失败。 +4. 错误提示明确到 Sheet 和列,便于用户重新下载模板处理。 + +## 非目标 + +1. 不改造无 `@DictDropdown` 字段的导入,例如当前未使用字典下拉模板的导入不强行纳入。 +2. 不改变现有业务字段校验、重复校验、异步导入、失败记录展示逻辑。 +3. 不新增兼容旧模板或降级导入逻辑;缺少下拉框即按模板不合规处理。 + +## 推荐方案 + +采用工具层统一校验: + +1. 在 `EasyExcelUtil.importExcel(InputStream, Class)` 和 `EasyExcelUtil.importExcel(InputStream, Class, String)` 内部先读取上传文件字节。 +2. 使用 POI 打开工作簿,根据导入类上的 `@DictDropdown` 和 `@ExcelProperty(index)` 解析应校验的列。 +3. 校验对应 Sheet 中是否存在覆盖该列数据区的数据验证规则。 +4. 校验通过后,再使用 EasyExcel 按现有方式读取数据。 + +该方案集中在公共导入工具,能随现有导入调用链自然覆盖员工信息、员工资产、亲属关系、招聘、调动、招投标、实体库、中介等使用字典下拉模板的导入。 + +## 校验规则 + +### 字段解析 + +- 扫描导入类及父类字段。 +- 仅处理同时具备 `@DictDropdown` 和带明确 `index` 的 `@ExcelProperty` 字段。 +- 列标题优先取 `@ExcelProperty.value()` 的第一个值。 + +### Sheet 定位 + +- 指定 Sheet 名读取时,校验该 Sheet。 +- 未指定 Sheet 名读取时,校验第一个 Sheet。 +- 若 Sheet 不存在,保持现有读取失败语义,不额外设计兜底。 + +### 下拉框判断 + +- 读取 Sheet 的 `DataValidation` 列表。 +- 只要任一数据验证区域覆盖目标列的数据区,即认为该列保留了模板下拉框。 +- 校验目标为模板结构是否保留,不判断用户是否逐单元格从下拉框选择。 + +### 失败行为 + +任一应有下拉框的列缺失数据验证时,导入立即失败,不进入异步任务,不写 Redis 状态,不产生部分成功。 + +建议错误文案: + +```text +员工信息 Sheet 的 状态 列缺少下拉框,请下载最新导入模板填写后重新导入 +``` + +双 Sheet 场景示例: + +- `员工信息` Sheet 的 `是否党员` 或 `状态` 缺失下拉框:失败。 +- `员工资产信息` Sheet 的 `资产状态` 缺失下拉框:失败。 +- 两个 Sheet 都保留下拉框:继续现有导入读取和业务校验。 + +## 影响范围 + +后端主要影响: + +- `ccdi-info-collection/src/main/java/com/ruoyi/info/collection/utils/EasyExcelUtil.java` +- 使用 `EasyExcelUtil.importExcel(...)` 的导入 Controller。 + +前端不需要改动。后端抛出的错误沿现有上传失败链路返回,页面展示现有错误提示即可。 + +## 测试设计 + +### 单元测试 + +新增工具层测试覆盖: + +1. 带 `@DictDropdown` 且保留下拉数据验证的模板读取通过。 +2. 员工信息 `状态` 列缺少下拉数据验证时报错。 +3. 双 Sheet 中任一 Sheet 的字典下拉列缺失时报错。 +4. 无 `@DictDropdown` 字段的导入对象不触发结构校验。 + +### 样例文件验证 + +使用用户提供文件验证: + +```text +/Users/wkc/Desktop/ccdi/ccdi_bulk_20260430/员工信息维护导入模板_批量测试数据.xlsx +``` + +预期:导入员工信息 Sheet 时提示 `状态` 列缺少下拉框。 + +### 真实页面验证 + +实现完成后按仓库规则使用 `browser-use` 打开真实员工信息维护页面验证: + +1. 下载页面当前真实导入模板。 +2. 上传缺少下拉框的批量测试文件,确认页面提示导入失败。 +3. 上传保留下拉框的测试文件,确认能进入现有正常导入链路。 +4. 测试结束关闭本轮启动的前后端进程。 + +## 文档与实施记录 + +实现完成后新增实施记录: + +```text +docs/reports/implementation/2026-04-30-import-dropdown-validation-implementation.md +``` + +实施记录需包含: + +- 修改内容。 +- 影响范围。 +- 测试命令与真实页面验证结果。 +- 用户提供缺下拉框文件的验证结果。