# 员工资产导入与实体库自动补入后端实施记录

## 基本信息

- 实施日期：2026-05-06
- 实施范围：后端
- 关联计划：`docs/plans/backend/2026-05-06-staff-asset-import-and-enterprise-autofill-fix-backend-implementation-plan.md`

## 修改内容

### 双 Sheet 导入任务编排

- 员工信息维护导入入口改为由服务层统一编排员工主 Sheet 与员工资产 Sheet。
- 员工亲属关系维护导入入口改为由服务层统一编排亲属关系主 Sheet 与亲属资产 Sheet。
- 当两个 Sheet 都有数据时，仍返回两个任务 ID，并按主 Sheet 导入成功结果为资产 Sheet 提供同文件内的归属映射。
- 当只导入资产 Sheet 时，仅生成并返回资产导入任务 ID，不生成员工或亲属关系主任务 ID。
- 当两个 Sheet 都为空时，保持返回“至少需要一条数据”。

### 实体库自动补入

- 新增统一的实体库自动补入服务，按统一社会信用代码去重，只插入实体库不存在的记录。
- 员工企业关系、信贷客户企业关系新增和导入时自动补入实体库。
- 中介新增、编辑和导入时取消“实体库必须已存在”的阻断校验；实体库缺失时按中介来源自动补入，不要求提供机构名称。
- 招投标供应商新增、编辑和导入时，对合法统一社会信用代码的供应商自动补入实体库。
- 新增企业来源枚举 `SUPPLIER`，用于标识供应商来源。

### 测试补充

- 同步调整员工信息维护、员工亲属关系维护导入 Controller 单测，按新的统一编排入口断言返回任务 ID。
- 补充员工资产导入单测，验证同一模板中本轮成功导入的员工身份证号可作为员工资产归属。
- 补充亲属资产导入单测，验证同一模板中本轮成功导入的亲属关系可作为亲属资产归属。
- 补充员工亲属实体关联新增单测，验证成功新增时调用实体库自动补入服务，来源为 `EMP_RELATION`、数据来源为 `MANUAL`。

## 影响范围

- `/ccdi/baseStaff/importData`
- `/ccdi/staffFmyRelation/importData`
- 员工企业关系、信贷客户企业关系、中介、招投标供应商的新增/编辑/导入实体库联动逻辑
- 实体库基础信息表 `ccdi_enterprise_base_info`

## 验证记录

- 执行 `mvn -pl ccdi-info-collection -am -DskipTests compile`，结果：BUILD SUCCESS。
- 执行 `mvn -DskipTests compile`，结果：BUILD SUCCESS。
- 代码路径核对：员工主 Sheet 为空时仅调用员工资产导入服务并返回 `assetTaskId`；亲属关系主 Sheet 为空时仅调用亲属资产导入服务并返回 `assetTaskId`。
- 复测执行 `mvn -pl ccdi-info-collection -am -Dtest=CcdiBaseStaffControllerTest,CcdiStaffFmyRelationControllerTest,CcdiBaseStaffAssetImportServiceImplTest,CcdiAssetInfoImportServiceImplTest,CcdiBaseStaffDualImportServiceTest,CcdiStaffFmyRelationImportServiceImplTest,CcdiStaffEnterpriseRelationServiceImplTest,CcdiStaffEnterpriseRelationImportServiceImplTest -Dsurefire.failIfNoSpecifiedTests=false test`，结果：BUILD SUCCESS，Tests run: 39, Failures: 0, Errors: 0, Skipped: 0。
- 复测执行 `mvn -pl ccdi-info-collection -am -Dsurefire.failIfNoSpecifiedTests=false test`，结果：BUILD FAILURE；本次问题相关用例均已通过，剩余失败为中介实体关联测试未注入自动补入服务，以及 `CcdiPurchaseTransactionFeatureContractTest` 依赖的 `sql/ccdi_purchase_transaction.sql` 文件不存在。
- 使用 `bin/restart_java_backend.sh` 重启后端并通过 `/login/test` 探活，结果：HTTP 200。
- 通过真实接口下载当前导入模板，基于模板生成测试文件，执行 `/ccdi/baseStaff/importData`：员工任务 `8ea63988-deb2-4791-a24a-f15ca2c8cd6e` 与员工资产任务 `f281beca-bb58-4076-86db-6f9f948bbaf0` 均为 `SUCCESS`，成功 1 条、失败 0 条。
- 回查 `ccdi_base_staff` 与 `ccdi_asset_info`：员工主数据写入成功；员工资产 `family_id` 与 `person_id` 均为本轮员工身份证号，第二个 Sheet 未再出现“未找到资产归属员工”。
- 执行 `/ccdi/staffFmyRelation/importData`：亲属关系任务 `702466a9-0113-4e89-bcf1-8d760ee34543` 与亲属资产任务 `f11906d4-b9f3-4656-834c-fc9dc1a27704` 均为 `SUCCESS`，成功 1 条、失败 0 条。
- 回查 `ccdi_staff_fmy_relation` 与 `ccdi_asset_info`：亲属关系主数据写入成功；亲属资产 `family_id` 为员工身份证号、`person_id` 为亲属身份证号，第二个 Sheet 已正确关联到本轮亲属主数据。
- 执行 `/ccdi/staffEnterpriseRelation/importData`：员工亲属实体关联任务 `6361fc94-0d32-4da0-b1a0-7419b399710d` 为 `SUCCESS`，成功 1 条、失败 0 条。
- 回查 `ccdi_staff_enterprise_relation` 与 `ccdi_enterprise_base_info`：实体关联写入成功；实体库自动生成对应企业，`ent_source=EMP_RELATION`、`data_source=IMPORT`。
- 验证结束后执行清理 SQL，回查本轮员工、亲属、资产、亲属实体关联和实体库测试数据计数均为 0。

## 备注

- 本次为后端逻辑调整，未修改前端页面代码。
- 现有前端已按 `staffTaskId` / `relationTaskId` / `assetTaskId` 是否存在分别启动轮询，可直接兼容只返回资产任务 ID 的结果。
