调整信息维护页面并修复项目概览统计

2026-05-06 18:22:26 +08:00
parent 0541ce0ac6
commit c64146ac40
33 changed files with 774 additions and 1831 deletions
--- a/docs/plans/backend/2026-05-06-staff-asset-import-and-enterprise-autofill-fix-backend-solution.md
+++ b/docs/plans/backend/2026-05-06-staff-asset-import-and-enterprise-autofill-fix-backend-solution.md
@@ -0,0 +1,236 @@
+# 员工资产导入与员工亲属实体自动补入后端解决方案
+
+## 背景
+
+本方案针对以下两个已验证问题：
+
+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 成功数据”，不能把失败主数据作为资产归属。
+- 实体库自动补入不能更新已存在企业，避免覆盖人工维护的企业名称、风险等级和来源信息。
+- 员工亲属实体关联自动补入必须只处理成功行，失败行不能产生实体库记录。
--- a/docs/plans/frontend/2026-04-29-base-staff-and-staff-recruitment-formal-shell-frontend-implementation.md
+++ b/docs/plans/frontend/2026-04-29-base-staff-and-staff-recruitment-formal-shell-frontend-implementation.md
@@ -1,34 +0,0 @@
-# 员工信息维护与招聘信息管理正式化外壳前端实施计划
-
-## 目标
-
- 基于当前本地最新代码，为 `ccdiBaseStaff` 与 `ccdiStaffRecruitment` 试套正式化外壳样式。
- 仅调整查询区、工具条、表格区、分页区与弹窗壳层视觉。
- 不改字段顺序、不改按钮位置、不改功能块结构。
-
-## 范围
-
- `ruoyi-ui/src/views/ccdiBaseStaff/index.vue`
- `ruoyi-ui/src/views/ccdiStaffRecruitment/index.vue`
- `ruoyi-ui/tests/unit/base-staff-formal-shell-layout.test.js`
- `ruoyi-ui/tests/unit/staff-recruitment-formal-shell-layout.test.js`
-
-## 方案
-
- 复用现有 `app-container`、`query-form`、`mb8`、弹窗 class，只补最少样式。
- 给列表区新增最小表格外壳，保证分页和表格归一。
- 通过边框、浅底、留白和表头背景统一正式化视觉。
-
-## 验证
-
- `node tests/unit/base-staff-formal-shell-layout.test.js`
- `node tests/unit/staff-recruitment-formal-shell-layout.test.js`
- `node tests/unit/employee-asset-maintenance-layout.test.js`
- `node tests/unit/staff-recruitment-import-toolbar.test.js`
-
-## 完成标准
-
- 两个页面外壳样式统一
- 按钮顺序和功能入口保持不变
- 单测通过
- 浏览器实测通过
--- a/docs/plans/frontend/2026-04-29-batch-formal-shell-rollout-frontend-implementation.md
+++ b/docs/plans/frontend/2026-04-29-batch-formal-shell-rollout-frontend-implementation.md
@@ -1,65 +0,0 @@
-# 2026-04-29 批量正式化外壳样式实施计划
-
-## 目标
-
- 基于当前本地最新前端代码，批量推进信息维护相关页面的正式化外壳样式。
- 严格保持“只改样式、不改内容和功能”的边界。
- 复用已经在详情弹窗、员工信息维护页、招聘信息管理页验证过的正式化样式骨架。
-
-## 范围
-
- `ruoyi-ui/src/views/ccdiAccountInfo/index.vue`
- `ruoyi-ui/src/views/ccdiCreditInfo/index.vue`
- `ruoyi-ui/src/views/ccdiCustEnterpriseRelation/index.vue`
- `ruoyi-ui/src/views/ccdiCustFmyRelation/index.vue`
- `ruoyi-ui/src/views/ccdiIntermediary/index.vue`
- `ruoyi-ui/src/views/ccdiIntermediary/components/SearchForm.vue`
- `ruoyi-ui/src/views/ccdiIntermediary/components/DataTable.vue`
- `ruoyi-ui/src/views/ccdiIntermediary/components/DetailDialog.vue`
- `ruoyi-ui/src/views/ccdiIntermediary/components/EditDialog.vue`
- `ruoyi-ui/src/views/ccdiIntermediary/components/ImportDialog.vue`
- `ruoyi-ui/src/views/ccdiPurchaseTransaction/index.vue`
- `ruoyi-ui/src/views/ccdiStaffEnterpriseRelation/index.vue`
- `ruoyi-ui/src/views/ccdiStaffFmyRelation/index.vue`
- `ruoyi-ui/src/views/ccdiStaffTransfer/index.vue`
-
-## 实施策略
-
-### 1. 查询区统一正式化
-
- 保留原有查询字段、排布逻辑和按钮位置。
- 为查询区补统一白色面板、边框、克制圆角和更稳重的标签文字。
- 收紧表单项底部留白，统一输入框、下拉框、日期控件的边框和圆角。
-
-### 2. 工具条统一正式化
-
- 保留搜索、重置、新增、导入、失败记录入口及其相对位置。
- 统一工具条外层白色承载区。
- 按钮仅调整圆角、边框与视觉重量，不改变语义和行为。
-
-### 3. 表格承载区统一正式化
-
- 新增或复用 `formal-table-shell` 包裹列表表格与分页区。
- 收紧表头和行高，提升单屏信息密度。
- 主体文本尽量左对齐，保留选择列和操作列居中。
-
-### 4. 弹窗与详情区统一正式化
-
- 统一弹窗圆角、头部下边线、正文浅底。
- 详情区、导入弹窗、编辑弹窗使用更克制的信息面板样式。
- 不重排现有字段，不新增删减交互块。
-
-## 验证计划
-
- 复用现有样式契约单测，确保已完成页面没有回退。
- 使用浏览器打开真实业务路由进行验证，禁止使用 prototype 页面替代。
- 核对关键页面是否保持：
-  - 查询区与工具条仍在原位置
-  - 新增、导入、失败记录按钮仍按原顺序出现
-  - 表格列和弹窗内容结构不变
-
-## 风险控制
-
- 不使用旧 patch 中的结构改法，只借用可复用的正式化视觉参数。
- 每个页面只处理最外层承载和控件外观，不触碰业务字段、接口、校验、按钮逻辑。
- 若真实页面路由可访问，则以真实页面结果为准；若不可访问，保留源码级验证说明。
--- a/docs/plans/frontend/2026-04-29-results-overview-project-analysis-dialog-formal-shell-frontend-implementation.md
+++ b/docs/plans/frontend/2026-04-29-results-overview-project-analysis-dialog-formal-shell-frontend-implementation.md
@@ -1,56 +0,0 @@
-# 结果总览项目分析详情正式化外壳前端实施计划
-
-## 目标
-
- 基于 `output/mockups/project-analysis-formal-soft-preview.html` 的静态预览稿，恢复“项目分析详情”弹窗的正式化、去卡片化外壳样式。
- 本次仅调整详情弹窗整体框架、标题区、左侧人物档案区、右侧主承载区与页签外层视觉。
- 不修改“异常明细”页签内部业务结构、分页、按钮、接口与数据逻辑。
-
-## 范围
-
- 修改 `ruoyi-ui/src/views/ccdiProject/components/detail/ProjectAnalysisDialog.vue`
- 修改 `ruoyi-ui/src/views/ccdiProject/components/detail/ProjectAnalysisSidebar.vue`
- 修改 `ruoyi-ui/tests/unit/project-analysis-dialog-layout.test.js`
- 修改 `ruoyi-ui/tests/unit/project-analysis-dialog-sidebar.test.js`
-
-## 实施方案
-
-### 1. 弹窗外壳正式化
-
- 将当前偏渐变、大圆角的详情弹窗外壳改为更平直的正式化工作台样式。
- 顶部保留“结果总览 / 项目分析详情”的信息层级，但改成浅边线、弱装饰、明确留白的标题区。
- 调整整体布局间距，让左侧档案区和右侧主区以纵向分隔线形成清晰结构。
-
-### 2. 左侧档案区映射静态稿
-
- 保留当前姓名、风险等级、工号、部门、所属项目、命中模型数、核心异常标签的数据字段。
- 通过信息头、字段列表、摘要区三段式样式，映射静态稿的人物档案视觉。
- 不新增额外字段、不新增辅助业务区块。
-
-### 3. 右侧主区外层收口
-
- 保持 `el-tabs`、错误提示、加载逻辑、默认页签逻辑不变。
- 只调整页签外层、内容承载区、主区边界与留白，不进入各 tab 内部重做内容样式。
-
-## 验证计划
-
-### 代码校验
-
- 在 `ruoyi-ui` 目录执行：
-  - `node tests/unit/project-analysis-dialog-layout.test.js`
-  - `node tests/unit/project-analysis-dialog-sidebar.test.js`
-  - `node tests/unit/project-analysis-dialog-empty-field.test.js`
-
-### 浏览器验证
-
- 先通过 `nvm use` 确认前端 Node 版本。
- 启动真实前端页面后，使用 `browser-use` 在系统真实页面打开“项目分析详情”弹窗。
- 重点核对：
-  - 标题区是否为正式化平直样式
-  - 左侧档案区是否按预览稿形成清晰三段层次
-  - 右侧主区是否只改外层、不影响“异常明细”内部内容与交互
-
-## 风险控制
-
- 不改接口、不改 mock 数据、不改异常明细内部组件，避免把外壳样式改动扩大成业务结构调整。
- 单测只更新与外层视觉契约直接相关的断言，避免引入无关回归。