Files
ccdi/docs/reports/implementation/2026-05-06-import-dropdown-validation-implementation.md
2026-05-06 14:04:21 +08:00

2.9 KiB
Raw Blame History

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

修改背景

员工信息维护导入文件中存在字典列下拉框被删除的情况,例如“状态”列不是模板下拉框。此类文件不应进入业务导入流程,需要在导入解析阶段直接报错,且所有使用 @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 的测试文件。