# 导入模板下拉框结构校验实施记录

## 修改背景

员工信息维护导入文件中存在字典列下拉框被删除的情况，例如“状态”列不是模板下拉框。此类文件不应进入业务导入流程，需要在导入解析阶段直接报错，且所有使用 `@DictDropdown` 的导入类都应统一校验。

## 修改内容

- 在 `EasyExcelUtil.importExcel(...)` 入口增加导入模板结构校验。
- 校验范围为导入实体类中带 `@DictDropdown` 且配置了 `@ExcelProperty(index = ...)` 的列。
- 对有实际数据的行逐行检查对应列是否被 `LIST` 类型数据验证覆盖。
- 同一个 Sheet 内存在多个缺失下拉框列时，合并列名一次性提示，例如：
  - `员工信息 Sheet 的 是否党员、状态 列缺少下拉框，请下载最新导入模板填写后重新导入`
- 无 `@DictDropdown` 的普通导入类不执行该结构校验。

## 影响范围

- 统一影响 `EasyExcelUtil.importExcel(InputStream, Class<T>)`、`EasyExcelUtil.importExcel(InputStream, Class<T>, String)` 和文件路径导入入口。
- 员工信息维护、员工资产、亲属关系、招聘信息、实体库等复用该工具类且存在 `@DictDropdown` 字段的导入功能都会具备下拉框结构校验。
- 不改变模板下载逻辑，不改变业务字段枚举值校验和异步导入逻辑。

## 验证结果

- 已执行 Maven 回归：
  - `mvn -pl ccdi-info-collection -am -Dtest=EasyExcelUtilImportDropdownValidationTest,EasyExcelUtilTemplateTest,CcdiBaseStaffControllerTest,CcdiStaffFmyRelationControllerTest,CcdiAssetInfoControllerTest,CcdiBaseStaffAssetImportControllerTest -Dsurefire.failIfNoSpecifiedTests=false -DargLine="-javaagent:/Users/wkc/.m2/repository/net/bytebuddy/byte-buddy-agent/1.17.8/byte-buddy-agent-1.17.8.jar" test`
  - 结果：32 个测试全部通过。
- 已检查用户提供的文件：
  - `/Users/wkc/Desktop/ccdi/ccdi_bulk_20260430/员工信息维护导入模板_批量测试数据.xlsx`
  - `员工信息` Sheet 数据验证数量为 0。
  - `员工资产信息` Sheet 数据验证数量为 0。
- 已重启后端并调用真实导入接口上传该文件：
  - `POST http://localhost:62318/ccdi/baseStaff/importData`
  - 返回：`{"msg":"员工信息 Sheet 的 是否党员、状态 列缺少下拉框，请下载最新导入模板填写后重新导入","code":500}`
- 已使用 browser-use 打开真实页面：
  - `http://localhost:1025/maintain/baseStaff`
  - 已进入“员工信息维护导入”弹窗，确认页面入口和真实业务页可访问。
  - 当前 browser-use 可用 API 不支持直接给隐藏文件选择框设置本地文件，上传动作改用真实后端接口验证。

## 清理说明

- 本轮异常导入在模板结构校验阶段被拦截，未提交异步导入任务，未写入员工或资产业务数据。
- 测试过程中未生成需要提交到 Git 的测试文件。