ccdi/docs/plans/backend/2026-04-30-import-dropdown-validation-backend-design.md

导入模板下拉框结构校验后端设计

背景

本次问题来自员工信息维护批量导入文件：

• 文件路径：/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<T>) 和 EasyExcelUtil.importExcel(InputStream, Class<T>, String) 内部先读取上传文件字节。
2. 使用 POI 打开工作簿，根据导入类上的 @DictDropdown 和 @ExcelProperty(index) 解析应校验的列。
3. 校验对应 Sheet 中是否存在覆盖该列数据区的数据验证规则。
4. 校验通过后，再使用 EasyExcel 按现有方式读取数据。

该方案集中在公共导入工具，能随现有导入调用链自然覆盖员工信息、员工资产、亲属关系、招聘、调动、招投标、实体库、中介等使用字典下拉模板的导入。

校验规则

字段解析

• 扫描导入类及父类字段。
• 仅处理同时具备 @DictDropdown 和带明确 index 的 @ExcelProperty 字段。
• 列标题优先取 @ExcelProperty.value() 的第一个值。

Sheet 定位

• 指定 Sheet 名读取时，校验该 Sheet。
• 未指定 Sheet 名读取时，校验第一个 Sheet。
• 若 Sheet 不存在，保持现有读取失败语义，不额外设计兜底。

下拉框判断

• 读取 Sheet 的 DataValidation 列表。
• 只认可 DataValidationConstraint.ValidationType.LIST 类型的数据验证；数字、日期、自定义公式等其他校验类型不能视为模板下拉框。
• 数据区定义为：从第 2 行开始，到本次上传文件中该 Sheet 的最后一行有效数据。
• 对每个实际数据行，目标列单元格都必须被 LIST 数据验证区域覆盖；只覆盖表头、只覆盖单个样例行、或只覆盖部分数据行，都视为该列下拉框缺失。
• 校验目标为模板结构是否保留，不判断用户是否逐单元格从下拉框选择。

失败行为

任一应有下拉框的列缺失数据验证时，导入立即失败，不进入异步任务，不写 Redis 状态，不产生部分成功。

建议错误文案：

员工信息 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. 非 LIST 类型数据验证不能替代下拉框。
4. 只覆盖部分实际数据行的下拉框应报错。
5. 双 Sheet 中任一 Sheet 的字典下拉列缺失时报错。
6. 无 @DictDropdown 字段的导入对象不触发结构校验。

样例文件验证

使用用户提供文件验证：

/Users/wkc/Desktop/ccdi/ccdi_bulk_20260430/员工信息维护导入模板_批量测试数据.xlsx

预期：导入员工信息 Sheet 时提示 状态 列缺少下拉框。

真实页面验证

实现完成后按仓库规则使用 browser-use 打开真实员工信息维护页面验证：

1. 下载页面当前真实导入模板。
2. 上传缺少下拉框的批量测试文件，确认页面提示导入失败。
3. 上传保留下拉框的测试文件，确认能进入现有正常导入链路。
4. 测试结束关闭本轮启动的前后端进程。

文档与实施记录

实现完成后新增实施记录：

docs/reports/implementation/2026-04-30-import-dropdown-validation-implementation.md

实施记录需包含：

• 修改内容。
• 影响范围。
• 测试命令与真实页面验证结果。
• 用户提供缺下拉框文件的验证结果。