wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ec67794f88fb709c24a3aa3b5ba8c2a2decbbd4d
ccdi/docs/plans/backend/2026-05-06-staff-asset-import-and-enterprise-autofill-fix-backend-solution.md

13 KiB
Raw Blame History

员工资产导入与员工亲属实体自动补入后端解决方案

背景

本方案针对以下两个已验证问题：

  1. 【员工信息维护】和【员工亲属关系维护】使用双 Sheet 模板导入时，第二个 Sheet 的资产信息只按数据库已有主数据反查归属，不能识别同一个导入文件中刚导入的员工或亲属关系，导致提示“未找到资产归属员工”等错误。
  2. 【员工亲属实体关联】新增或导入关系人与企业关联后，只写入员工亲属实体关联表，没有同步生成实体库数据，导致企业名称和统一社会信用代码不能自动落入【实体库管理】。

本次解决方案只涉及后端，不调整前端页面结构、上传入口和模板样式。现有前端已经能接收员工任务 ID 与资产任务 ID，并分别轮询失败记录，因此后端需要保持现有返回字段兼容。

目标

  • 双 Sheet 导入时，主 Sheet 和资产 Sheet 按同一个文件内的业务依赖顺序处理。
  • 资产 Sheet 可以关联到数据库已存在的员工或亲属主数据，也可以关联到同一文件中本轮成功导入的员工或亲属主数据。
  • 主 Sheet 校验失败的数据不能作为资产归属依据。
  • 员工亲属实体关联新增和导入成功后，缺失的企业自动补入实体库。
  • 实体库自动补入只插入缺失企业，不更新已存在实体。

方案一：员工信息维护双 Sheet 导入

当前问题链路

  • /ccdi/baseStaff/importData 当前分别读取 员工信息 与 员工资产信息 两个 Sheet。
  • 有员工数据时调用 baseStaffService.importBaseStaff(staffList)，有资产数据时调用 baseStaffAssetImportService.importAssetInfo(assetList)。
  • 两个任务独立异步执行，员工资产任务只通过 ccdi_base_staff.id_card 查询数据库已有员工。
  • 当模板中员工和资产同时首次导入时，资产任务无法稳定看到本轮员工导入结果。

改造策略

保留接口路径、模板名称、返回结构和前端轮询模型，新增后端双 Sheet 编排能力。

  1. 在员工导入服务中增加双 Sheet 提交方法：

    • 输入：List<CcdiBaseStaffExcel> staffList、List<CcdiBaseStaffAssetInfoExcel> assetList
    • 输出：BaseStaffImportSubmitResultVO
    • 有员工 Sheet 时生成 staffTaskId
    • 有资产 Sheet 时生成 assetTaskId

  2. 新增一个统一异步编排方法，按顺序执行：

    • 初始化员工导入任务状态
    • 执行员工主数据校验和批量插入
    • 收集本轮员工导入成功的 idCard
    • 更新员工任务状态和失败记录
    • 初始化员工资产导入任务状态
    • 执行员工资产导入
    • 员工资产归属候选来源为：
      • 数据库已有 ccdi_base_staff.id_card
      • 本轮员工 Sheet 成功导入的 idCard
    • 更新员工资产任务状态和失败记录

  3. 员工资产导入逻辑调整：

    • 保留“员工资产只允许员工本人身份证号”的业务规则。
    • 保留重复校验规则：personId + assetMainType + assetSubType + assetName。
    • personId 既可以命中数据库已有员工，也可以命中本轮成功导入员工。
    • 只命中员工 Sheet 失败行、且数据库中也不存在该身份证号时，资产行进入失败记录。

  4. /ccdi/baseStaff/importData 改为调用新的双 Sheet 提交方法，不再由 Controller 分别提交两个互相独立的异步任务。

结果状态

  • 只填员工 Sheet：只返回 staffTaskId，行为保持不变。
  • 只填员工资产 Sheet：只返回 assetTaskId，按数据库已有员工校验。
  • 两个 Sheet 都填写：返回 staffTaskId 与 assetTaskId，但后端在同一个编排任务中先处理员工再处理资产。

方案二：员工亲属关系维护双 Sheet 导入

当前问题链路

  • /ccdi/staffFmyRelation/importData 当前分别读取 员工亲属关系信息 与 亲属资产信息 两个 Sheet。
  • 有亲属关系数据时调用 relationService.importRelation(relationList)，有亲属资产数据时调用 assetInfoImportService.importAssetInfo(assetList)。
  • 亲属资产导入只通过 ccdi_staff_fmy_relation.relation_cert_no 查询数据库已有亲属关系。
  • 当模板中亲属关系和亲属资产同时首次导入时，资产任务无法稳定看到本轮亲属关系导入结果。

改造策略

保留接口路径、模板名称、返回结构和前端轮询模型，新增员工亲属关系双 Sheet 编排能力。

  1. 在员工亲属关系导入服务中增加双 Sheet 提交方法：

    • 输入：List<CcdiStaffFmyRelationExcel> relationList、List<CcdiAssetInfoExcel> assetList
    • 输出：StaffFmyRelationImportSubmitResultVO
    • 有亲属关系 Sheet 时生成 relationTaskId
    • 有亲属资产 Sheet 时生成 assetTaskId

  2. 新增一个统一异步编排方法，按顺序执行：

    • 初始化亲属关系导入任务状态
    • 执行亲属关系校验和批量插入
    • 收集本轮成功导入且有效的亲属关系映射：
      • relationCertNo 作为资产 Sheet 的 personId
      • personId 作为资产落库的 familyId
    • 更新亲属关系任务状态和失败记录
    • 初始化亲属资产导入任务状态
    • 执行亲属资产导入
    • 亲属资产归属候选来源为：
      • 数据库已有有效员工亲属关系
      • 本轮亲属关系 Sheet 成功导入的有效员工亲属关系
    • 更新亲属资产任务状态和失败记录

  3. 亲属资产导入逻辑调整：

    • 保留 family_id = 员工身份证号、person_id = 亲属身份证号 的落库规则。
    • personId 命中唯一亲属关系时导入成功。
    • personId 未命中数据库和本轮成功亲属关系时，失败原因为“未找到亲属资产归属员工”。
    • personId 命中多个员工归属时，失败原因为“亲属资产归属员工不唯一”。
    • 只命中亲属关系 Sheet 失败行、且数据库中也不存在有效亲属关系时，资产行进入失败记录。

  4. /ccdi/staffFmyRelation/importData 改为调用新的双 Sheet 提交方法，不再由 Controller 分别提交两个互相独立的异步任务。

结果状态

  • 只填亲属关系 Sheet：只返回 relationTaskId，行为保持不变。
  • 只填亲属资产 Sheet：只返回 assetTaskId，按数据库已有亲属关系校验。
  • 两个 Sheet 都填写：返回 relationTaskId 与 assetTaskId，但后端在同一个编排任务中先处理亲属关系再处理亲属资产。

方案三：员工亲属实体关联自动补入实体库

当前问题链路

  • 员工亲属实体关联新增只写入 ccdi_staff_enterprise_relation。
  • 员工亲属实体关联导入成功行也只写入 ccdi_staff_enterprise_relation。
  • 当前源码中没有可复用的实体库自动补入服务实现。

改造策略

新增后端内部服务 EnterpriseAutoFillService，统一处理缺失企业的最小插入。

  1. 新增服务文件：

    • ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/support/EnterpriseAutoFillService.java

  2. 服务方法：

    • ensureExists(EnterpriseFillItem item)
    • ensureExistsBatch(List<EnterpriseFillItem> items)

  3. EnterpriseFillItem 字段：

    • socialCreditCode
    • enterpriseName
    • entSource
    • dataSource
    • userName

  4. 插入规则：

    • 按 socialCreditCode 去重。
    • 先批量查询 ccdi_enterprise_base_info 已存在记录。
    • 已存在实体不更新。
    • 缺失实体最小插入：
      • social_credit_code = 统一社会信用代码
      • enterprise_name = 企业名称
      • ent_source = EMP_RELATION
      • data_source = MANUAL 或 IMPORT
      • risk_level = NULL
      • create_by/update_by = 当前用户
    • 不引入额外兜底字段，不改变实体库手工新增规则。

  5. 接入员工亲属实体关联新增：

    • 在 CcdiStaffEnterpriseRelationServiceImpl#insertRelation 中，亲属有效性校验和组合查重通过后，写关联表前调用：
      • entSource = EnterpriseSource.EMP_RELATION.getCode()
      • dataSource = DataSource.MANUAL.getCode()

  6. 接入员工亲属实体关联导入：

    • 在 CcdiStaffEnterpriseRelationImportServiceImpl#importRelationAsync 中，只对校验成功并即将插入的 newRecords 组装补入列表。
    • 批量写关联表前调用 ensureExistsBatch。
    • 失败行不进入实体库补入集合。
    • dataSource = DataSource.IMPORT.getCode()。

测试方案

单元测试

  1. 员工信息维护双 Sheet：

    • 同一模板中员工 Sheet 新增员工，员工资产 Sheet 使用该员工身份证号，资产应导入成功。
    • 员工 Sheet 行校验失败，资产 Sheet 使用该失败员工身份证号且数据库不存在，资产应失败。
    • 只导资产 Sheet，数据库已有员工时资产成功。
    • 只导资产 Sheet，数据库无员工时资产失败。
    • 资产重复命中数据库或当前文件重复时失败。

  2. 员工亲属关系维护双 Sheet：

    • 同一模板中亲属关系 Sheet 新增亲属，亲属资产 Sheet 使用该亲属证件号，资产应导入成功，并落库 family_id = 员工身份证号。
    • 亲属关系 Sheet 行校验失败，亲属资产 Sheet 使用该失败亲属证件号且数据库不存在，资产应失败。
    • 只导亲属资产 Sheet，数据库已有唯一有效亲属关系时资产成功。
    • 只导亲属资产 Sheet，数据库不存在亲属关系时资产失败。
    • 同一亲属证件号命中多个员工归属时资产失败。

  3. 员工亲属实体关联自动补入：

    • 手工新增员工亲属实体关联成功时，缺失企业自动插入实体库，来源为 EMP_RELATION，数据来源为 MANUAL。
    • 手工新增时实体库已存在该统一社会信用代码，不更新实体库旧记录。
    • 导入成功行自动插入实体库，来源为 EMP_RELATION，数据来源为 IMPORT。
    • 导入失败行不插入实体库。
    • 同一批多个成功行引用同一统一社会信用代码，只补入一次。

接口验证

  1. 调用 /ccdi/baseStaff/importTemplate 下载真实模板，构造：

    • 员工信息 新员工
    • 员工资产信息 引用该员工身份证号
    • 上传 /ccdi/baseStaff/importData
    • 轮询员工任务与资产任务，确认都成功
    • 查询 ccdi_base_staff 与 ccdi_asset_info，确认员工和资产落库

  2. 调用 /ccdi/staffFmyRelation/importTemplate 下载真实模板，构造：

    • 员工亲属关系信息 新亲属
    • 亲属资产信息 引用该亲属证件号
    • 上传 /ccdi/staffFmyRelation/importData
    • 轮询亲属关系任务与亲属资产任务，确认都成功
    • 查询 ccdi_staff_fmy_relation 与 ccdi_asset_info，确认亲属关系和资产落库

  3. 调用员工亲属实体关联新增接口：

    • 新增前确认 ccdi_enterprise_base_info 不存在该统一社会信用代码
    • 新增关联成功后查询实体库，确认自动生成企业记录
    • 校验 ent_source = EMP_RELATION

页面验证

完成后需要使用真实业务页面验证：

  1. 【员工信息维护】页面下载模板，按模板填写员工和员工资产，上传后检查任务状态、失败记录和列表详情。
  2. 【员工亲属关系维护】页面下载模板，按模板填写亲属关系和亲属资产，上传后检查任务状态、失败记录和详情资产列表。
  3. 【员工亲属实体关联】页面新增关系人与企业关联后，进入【实体库管理】查询该统一社会信用代码，确认企业已自动生成且来源显示为员工关系人。

测试结束后清理本轮新增员工、亲属关系、资产、员工亲属实体关联和自动补入实体库数据，并关闭测试过程中启动的前后端进程。

实施顺序

  1. 抽取员工导入和亲属关系导入的可复用执行方法，返回成功主数据上下文和失败记录。
  2. 新增员工信息维护双 Sheet 后端编排方法，接入 Controller。
  3. 新增员工亲属关系维护双 Sheet 后端编排方法，接入 Controller。
  4. 新增 EnterpriseAutoFillService。
  5. 员工亲属实体关联新增链路接入实体库自动补入。
  6. 员工亲属实体关联导入链路接入实体库自动补入。
  7. 补充单元测试。
  8. 执行接口验证和真实页面验证。
  9. 新增实施记录到 docs/reports/implementation/。

风险点

  • 双 Sheet 导入不能继续使用两个互相独立的异步任务，否则仍然存在主数据与资产任务执行顺序不确定的问题。
  • 资产归属上下文必须只使用“数据库已有数据”和“本轮主 Sheet 成功数据”，不能把失败主数据作为资产归属。
  • 实体库自动补入不能更新已存在企业，避免覆盖人工维护的企业名称、风险等级和来源信息。
  • 员工亲属实体关联自动补入必须只处理成功行，失败行不能产生实体库记录。
Reference in New Issue View Git Blame Copy Permalink