237 lines
13 KiB
Markdown
237 lines
13 KiB
Markdown
# 员工资产导入与员工亲属实体自动补入后端解决方案
|
||
|
||
## 背景
|
||
|
||
本方案针对以下两个已验证问题：
|
||
|
||
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 成功数据”，不能把失败主数据作为资产归属。
|
||
- 实体库自动补入不能更新已存在企业，避免覆盖人工维护的企业名称、风险等级和来源信息。
|
||
- 员工亲属实体关联自动补入必须只处理成功行，失败行不能产生实体库记录。
|