wkc/ccdi

Fork 0

Files

wkc 4258d74809 新增员工亲属资产维护设计与实施计划

2026-03-12 16:29:07 +08:00

12 KiB

Raw Blame History

员工亲属资产维护设计

背景

现有员工亲属关系维护页面 http://localhost/maintain/staffFmyRelation 已支持员工亲属关系的新增、编辑、删除、详情、导入导出，但尚不支持维护亲属名下资产信息。

当前仓库中已有员工资产维护设计文档 2026-03-12-employee-asset-maintenance-design.md，其核心约束是通过 family_id 表示归属员工，通过 person_id 表示资产实际持有人。本次需求需要将该能力调整到“员工亲属关系维护页面”中，并明确仅维护亲属资产，不包含员工本人资产。

本次设计于 2026-03-12 确认以下业务口径：

维护入口为员工亲属关系页面 staffFmyRelation
仅维护当前亲属关系对应的亲属资产，不包含员工本人资产
不新增独立的亲属资产菜单页面
不新增 relation_id 等额外资产归属字段
family_id 存员工证件号，对应亲属关系中的 person_id
person_id 存亲属证件号，对应亲属关系中的 relation_cert_no
亲属资产中的 person_id 不强制要求为身份证号，存证件号即可
编辑亲属关系时，relationCertType 与 relationCertNo 禁止修改

目标

在员工亲属关系维护页中新增亲属资产维护能力
在亲属关系新增/编辑弹窗中支持维护当前亲属名下资产
在亲属关系详情弹窗中展示当前亲属全部资产
在亲属关系列表页新增亲属资产导入入口，并复用现有异步导入交互
删除亲属关系时同步删除该亲属名下资产

非目标

不维护员工本人资产
不新增独立“亲属资产维护”菜单
不新增 relation_id
不在列表页直接展开显示资产明细
不改造现有亲属关系查询条件和分页结构

现状

当前员工亲属关系维护能力主要集中在以下位置：

前端页面：ruoyi-ui/src/views/ccdiStaffFmyRelation/index.vue
前端接口：ruoyi-ui/src/api/ccdiStaffFmyRelation.js
后端控制器：ccdi-info-collection/src/main/java/com/ruoyi/info/collection/controller/CcdiStaffFmyRelationController.java
后端服务：ccdi-info-collection/src/main/java/com/ruoyi/info/collection/service/impl/CcdiStaffFmyRelationServiceImpl.java
后端映射：ccdi-info-collection/src/main/resources/mapper/info/collection/CcdiStaffFmyRelationMapper.xml

当前一条亲属关系记录的关键字段如下：

person_id：员工证件号
relation_cert_type：亲属证件类型
relation_cert_no：亲属证件号

数据库对 ccdi_staff_fmy_relation 设有唯一约束 uk_person_cert(person_id, relation_cert_no)，因此一条亲属关系在业务上可以稳定地通过“员工证件号 + 亲属证件号”定位，这也正好可以复用为亲属资产的归属键。

方案对比

方案一：在亲属关系弹窗内嵌资产子表聚合维护

亲属关系详情接口聚合返回 assetInfoList
亲属关系新增、编辑时同步保存资产列表
亲属资产导入采用独立接口，但交互复用现有导入模式

优点：

最符合“在亲属关系维护页面维护亲属资产”的使用预期
页面上下文最完整，用户不需要在多个弹窗间切换
删除亲属关系时级联删除资产最直接

缺点：

需要扩展 DTO、VO、Service 和前端弹窗结构

方案二：在亲属关系页增加“维护资产”二级弹窗

亲属关系页保留现状
通过“维护资产”按钮打开独立二级弹窗编辑资产

优点：

对现有亲属关系表单侵入较小

缺点：

交互割裂
用户维护一条亲属关系时无法同时看到关系信息与资产信息

方案三：只新增资产查看与导入，不支持页面内编辑

优点：

开发量最小

缺点：

不满足“添加维护功能”的核心诉求

最终方案

采用方案一：在员工亲属关系维护页的新增、编辑、详情弹窗中内嵌“亲属资产信息”分区，由亲属关系接口作为聚合接口返回和保存 assetInfoList；同时新增“亲属资产导入”独立接口，并沿用现有亲属关系导入的异步处理与失败记录交互。

数据模型设计

资产归属规则

亲属资产的归属键定义如下：

family_id = 当前亲属关系.person_id
person_id = 当前亲属关系.relation_cert_no

含义如下：

family_id 表示归属员工
person_id 表示亲属资产实际持有人
当前页面只查询和保存满足 family_id = 员工证件号 且 person_id = 亲属证件号 的资产

数据表

新增 ccdi_asset_info 表，字段来源参考资产设计文档和 assets/资产信息表.csv，本次继续沿用以下关键字段：

asset_id：BIGINT 自增主键
family_id：VARCHAR(100)，保存员工证件号
person_id：VARCHAR(100)，保存亲属证件号
asset_main_type
asset_sub_type
asset_name
ownership_ratio
purchase_eval_date
original_value
current_value
valuation_date
asset_status
remarks
create_by
create_time
update_by
update_time

建议索引：

idx_family_id(family_id)
idx_person_id(person_id)
idx_family_person(family_id, person_id)

后端设计

新增资产模块对象

在 ccdi-info-collection 中新增：

domain/CcdiAssetInfo.java
domain/dto/CcdiAssetInfoDTO.java
domain/vo/CcdiAssetInfoVO.java
domain/excel/CcdiAssetInfoExcel.java
domain/vo/AssetImportFailureVO.java
mapper/CcdiAssetInfoMapper.java
service/ICcdiAssetInfoService.java
service/ICcdiAssetInfoImportService.java
service/impl/CcdiAssetInfoServiceImpl.java
service/impl/CcdiAssetInfoImportServiceImpl.java
controller/CcdiAssetInfoController.java
resources/mapper/info/collection/CcdiAssetInfoMapper.xml

扩展亲属关系聚合接口

扩展现有亲属关系 DTO 和 VO：

CcdiStaffFmyRelationAddDTO.assetInfoList
CcdiStaffFmyRelationEditDTO.assetInfoList
CcdiStaffFmyRelationVO.assetInfoList

聚合规则：

查询详情时，按当前亲属关系的 personId + relationCertNo 查询资产列表并组装到 assetInfoList
新增亲属关系时，先保存关系，再为资产统一回填 family_id、person_id
编辑亲属关系时，更新关系主信息，再按当前固定归属键重建资产列表
删除亲属关系时，先删资产再删亲属关系，整体使用事务

编辑时的特殊约束

编辑亲属关系时：

前端禁止修改 relationCertType
前端禁止修改 relationCertNo
后端读取旧记录后做防御校验
若请求中的 relationCertType 或 relationCertNo 与旧值不一致，直接拒绝保存并提示“关系人证件类型/证件号码不允许修改”

资产保存策略

编辑当前亲属关系时不要求前端传资产行状态，直接按“当前完整列表覆盖”处理：

查询当前亲属关系旧记录
校验亲属证件类型、亲属证件号未被修改
更新亲属关系主信息
按 family_id = personId 且 person_id = relationCertNo 删除旧资产
将当前提交的 assetInfoList 统一回填归属键后批量插入

由于编辑时禁止修改亲属证件类型和证件号，因此不需要处理资产跨亲属迁移问题。

资产导入接口

新增独立资产导入接口：

POST /ccdi/assetInfo/importTemplate
POST /ccdi/assetInfo/importData
GET /ccdi/assetInfo/importStatus/{taskId}
GET /ccdi/assetInfo/importFailures/{taskId}

导入归属规则：

模板中 person_id 填亲属证件号
模板中不要求填写 family_id
系统通过 ccdi_staff_fmy_relation.relation_cert_no = person_id 反查亲属关系
若能唯一匹配，则自动回填对应记录的 person_id 到 family_id
若找不到匹配关系，导入失败
若匹配到多条不同员工关系，导入失败，原因记为“亲属资产归属员工不唯一”

前端设计

列表页

在 ruoyi-ui/src/views/ccdiStaffFmyRelation/index.vue 按钮区新增：

“导入亲属资产信息”按钮
“查看亲属资产导入失败记录”按钮

资产导入状态全部独立维护：

独立上传弹窗状态
独立轮询定时器
独立任务 ID
独立 localStorage key
独立失败记录弹窗和分页状态

新增和编辑弹窗

在现有亲属关系弹窗的“基本信息”下方新增“亲属资产信息”分区，采用可编辑子表。

子表字段：

资产大类
资产小类
资产名称
产权占比
购买/评估日期
资产原值
当前估值
估值截止日期
资产状态
备注
操作

交互规则：

分区右侧提供“新增资产”按钮
每行支持删除
编辑时回显 assetInfoList
前端不展示 asset_id、family_id、person_id
新增资产前若当前尚未录入亲属证件类型或证件号码，则禁用新增资产并提示“请先填写关系人证件信息”
编辑时 relationCertType、relationCertNo 置灰禁用

详情弹窗

在详情弹窗中新增“亲属资产信息”区域，使用只读表格展示当前亲属名下资产。

若无资产数据，显示“暂无亲属资产信息”。

数据流

新增亲属关系

前端提交亲属关系基础信息和 assetInfoList，后端保存亲属关系后，按当前记录的 personId 与 relationCertNo 为每条资产回填 family_id、person_id，再批量保存。

编辑亲属关系

前端拉取详情回显基础信息和资产列表，用户修改后提交完整列表。后端校验证件类型、证件号码未变更后，按当前亲属关系归属键重建资产明细。

查询详情

后端查询亲属关系主信息，再按 family_id = personId 且 person_id = relationCertNo 查询资产列表并一并返回。

删除亲属关系

后端先删除当前亲属名下资产，再删除亲属关系主记录。

导入亲属资产

前端上传亲属资产 Excel，后端根据 person_id = 亲属证件号 识别归属亲属关系并自动回填 family_id，异步校验并批量插入资产数据，失败记录通过独立入口查看。

校验规则

亲属关系保存时

沿用现有亲属关系校验规则
编辑时禁止修改 relationCertType
编辑时禁止修改 relationCertNo
assetInfoList 中整行为空的数据自动过滤

亲属资产保存时

资产必填项：assetMainType、assetSubType、assetName、currentValue、assetStatus
数值字段必须合法
日期字段必须合法
后端不信任前端传入的归属字段，统一强制回填：
- family_id = 当前亲属关系.personId
- person_id = 当前亲属关系.relationCertNo

异常处理

编辑亲属关系时，若请求试图修改 relationCertType 或 relationCertNo，后端直接报错
删除亲属关系与删除资产使用同一事务，避免数据不一致
查询详情时若资产查询异常，整体接口返回失败，避免前端收到半残数据
亲属资产导入时，若亲属证件号无法匹配亲属关系，记录失败原因
亲属资产导入时，若一个亲属证件号匹配多个员工关系，记录“亲属资产归属员工不唯一”
前端提示文案中明确区分“亲属关系导入”和“亲属资产导入”

验收标准

staffFmyRelation 新增/编辑弹窗中可新增、编辑、删除亲属资产
编辑亲属关系时，关系人证件类型和证件号码不可修改
详情弹窗中可查看该亲属全部资产信息
删除亲属关系后，对应亲属资产同步删除
亲属资产支持独立导入，并可查看亲属资产导入失败记录
亲属资产导入模板不要求填写 family_id
系统根据 person_id = 亲属证件号 自动回填归属员工证件号到 family_id

测试建议

新增亲属关系但不维护资产
新增亲属关系并维护单条、多条资产
编辑亲属关系时新增、修改、删除资产
验证编辑时不能修改亲属证件类型与证件号码
删除亲属关系时资产级联删除
亲属资产导入成功、无法匹配、匹配不唯一三类场景

12 KiB Raw Blame History Unescape Escape