wkc/ccdi

Fork 0

Files

wkc d79a60ab8c 新增员工亲属实体关联维护设计文档

2026-04-23 16:47:26 +08:00

14 KiB

Raw Blame History

员工亲属实体关联维护设计

1. 背景

当前信息维护中的员工实体关联维护模块，底层使用 ccdi_staff_enterprise_relation 表，页面、接口、导入能力均已完整存在，但现有语义以“员工本人”为主对象。

本次需求要求将该模块整体切换为“员工亲属与实体的关联关系维护”：

主对象从员工本人切换为员工亲属
员工亲属必须来源于员工亲属关系维护中已维护的亲属
新增和导入时仅允许使用员工亲属关系中状态为有效的亲属
列表需要展示亲属身份证、亲属名称、亲属关联的员工
现有导入能力同步切换为员工亲属实体关联导入
若亲属关系后续被改为无效，则该亲属名下已有实体关联自动更新为无效

本次设计按最短路径实施，不新增平行模块，不做兼容性方案，不额外扩展用户未提出的兜底逻辑。

2. 目标与范围

2.1 目标

在保留现有员工实体关联模块入口、表结构和基本交互骨架的前提下，将其业务语义改造为员工亲属实体关联维护，并保证新增、编辑、查询、详情、导入、失效联动链路闭环。

2.2 本次范围

改造员工实体关联模块的查询、详情、新增、编辑、导入语义
接入员工亲属关系表作为唯一合法亲属来源
页面支持按亲属身份证模糊搜索有效亲属并自动带出信息
列表和详情展示亲属名称及关联员工
员工亲属关系失效时，自动将对应实体关联更新为无效

2.3 非本次范围

不新增独立“员工亲属实体关联”新表
不迁移旧的员工本人实体关联历史数据
不设计旧数据兼容展示逻辑
不增加亲属关系失效后自动恢复实体关联为有效的反向联动
不扩展用户未提出的新查询条件、新统计能力或新菜单入口

3. 现状分析

3.1 现有实体关联模块

当前模块主要位置如下：

后端控制器：ccdi-info-collection/.../controller/CcdiStaffEnterpriseRelationController.java
后端服务：ccdi-info-collection/.../service/impl/CcdiStaffEnterpriseRelationServiceImpl.java
查询 Mapper：ccdi-info-collection/.../mapper/info/collection/CcdiStaffEnterpriseRelationMapper.xml
前端页面：ruoyi-ui/src/views/ccdiStaffEnterpriseRelation/index.vue
前端 API：ruoyi-ui/src/api/ccdiStaffEnterpriseRelation.js

当前主表为 ccdi_staff_enterprise_relation，核心字段包括：

person_id：当前语义为员工身份证号
social_credit_code
enterprise_name
relation_person_post
status
remark
data_source

当前列表通过 ccdi_base_staff.id_card = person_id 查询员工姓名。

3.2 现有员工亲属关系模块

员工亲属关系维护模块已完整存在，主要使用：

表：ccdi_staff_fmy_relation
员工身份证：person_id
亲属名称：relation_name
亲属身份证：relation_cert_no
员工亲属标记：is_emp_family
状态：status

该表已经能够稳定表达“某亲属属于哪个员工”，可以直接作为本次改造的唯一合法来源。

4. 方案对比

4.1 方案 A：沿用现有表并切换业务语义

做法：

继续使用 ccdi_staff_enterprise_relation
将 person_id 改为表示“亲属身份证号”
查询时通过亲属关系表回补亲属名称和关联员工

优点：

改动最小
现有增删改查和导入框架可复用
不需要新增表、菜单、权限和页面

缺点：

person_id 字段命名不再直观表达“亲属”

4.2 方案 B：沿用现有表并增加冗余字段

做法：

在原表上补充亲属名称、关联员工身份证、关联员工姓名等冗余字段

优点：

查询 SQL 简单

缺点：

引入冗余数据
与员工亲属关系、员工基础信息容易产生不一致
超出最短路径原则

4.3 方案 C：新建员工亲属实体关联表

做法：

新建全新表结构与全新模块

优点：

语义最干净

缺点：

改造范围明显扩大
需要增加整套表、接口、页面和权限
不符合本次“最短路径实现”要求

4.4 选型结论

采用方案 A。

原因：

可以在现有模块上直接改造，成本最低
满足业务闭环，不需要额外兜底
与当前仓库已有的员工亲属关系维护能力天然衔接

5. 数据模型设计

5.1 主表沿用

继续使用 ccdi_staff_enterprise_relation，但字段语义调整如下：

字段	新语义
`person_id`	亲属身份证号
`social_credit_code`	统一社会信用代码
`enterprise_name`	企业名称
`relation_person_post`	亲属在企业中的职务
`status`	关联关系状态
`remark`	补充说明
`data_source`	数据来源

本次不修改表结构，不新增字段。

5.2 查询回填链路

列表和详情展示使用以下关联链路：

以 ccdi_staff_enterprise_relation 为主表
通过 ccdi_staff_fmy_relation.relation_cert_no = ccdi_staff_enterprise_relation.person_id
并限定 ccdi_staff_fmy_relation.is_emp_family = 1
从 ccdi_staff_fmy_relation 获取：
- relation_name 作为亲属名称
- person_id 作为关联员工身份证
再通过 ccdi_base_staff.id_card = ccdi_staff_fmy_relation.person_id 获取员工姓名

最终返回给前端的核心展示字段为：

personId：亲属身份证
relationName：亲属名称
staffPersonId：关联员工身份证
staffPersonName：关联员工姓名

现有 personName 字段不再承载员工姓名语义，避免前后端继续误用，改造后统一使用新的返回字段。

6. 业务规则

6.1 合法亲属来源

新增和导入时，亲属身份证号必须匹配到一条满足以下条件的员工亲属关系：

is_emp_family = 1
status = 1
relation_cert_no = person_id

只要任一条件不满足，即判定该亲属不允许用于实体关联维护。

6.2 唯一性规则

业务唯一性继续沿用现有模式，但语义变更为：

亲属身份证号 + 统一社会信用代码 唯一

新增与导入都必须校验该组合唯一，禁止重复录入。

6.3 编辑规则

编辑时延续现有“业务主键不可修改”的方式：

亲属身份证号不可修改
统一社会信用代码不可修改

只允许修改：

企业名称
关联人在企业的职务
状态
补充说明

6.4 亲属失效联动规则

当员工亲属关系模块中某条亲属关系状态从有效改为无效时：

自动将该亲属名下所有实体关联记录的 status 更新为 0

联动范围限定为：

ccdi_staff_enterprise_relation.person_id = ccdi_staff_fmy_relation.relation_cert_no

本次仅实现“改为无效时自动同步为无效”的单向联动，不设计反向自动恢复为有效。

7. 后端设计

7.1 接口延用

继续沿用现有接口路径：

GET /ccdi/staffEnterpriseRelation/list
GET /ccdi/staffEnterpriseRelation/{id}
POST /ccdi/staffEnterpriseRelation
PUT /ccdi/staffEnterpriseRelation
DELETE /ccdi/staffEnterpriseRelation/{ids}
POST /ccdi/staffEnterpriseRelation/importTemplate
POST /ccdi/staffEnterpriseRelation/importData
GET /ccdi/staffEnterpriseRelation/importStatus/{taskId}
GET /ccdi/staffEnterpriseRelation/importFailures/{taskId}

不新增平行接口组。

7.2 查询 DTO 与 VO

查询条件建议调整为围绕亲属语义：

亲属身份证号
亲属名称
关联员工
统一社会信用代码
企业名称
状态

VO 增加或切换为以下字段：

personId
relationName
staffPersonId
staffPersonName
relationPersonPost
socialCreditCode
enterpriseName
status
remark
dataSource
createTime
updateTime
createdBy
updatedBy

7.3 查询 SQL

列表和详情 SQL 改为从亲属关系表回补字段，示意逻辑如下：

SELECT
    ser.id,
    ser.person_id,
    sfr.relation_name,
    sfr.person_id AS staff_person_id,
    bs.name AS staff_person_name,
    ser.relation_person_post,
    ser.social_credit_code,
    ser.enterprise_name,
    ser.status,
    ser.remark,
    ser.data_source,
    ser.created_by,
    ser.create_time,
    ser.updated_by,
    ser.update_time
FROM ccdi_staff_enterprise_relation ser
LEFT JOIN ccdi_staff_fmy_relation sfr
    ON sfr.relation_cert_no = ser.person_id
   AND sfr.is_emp_family = 1
LEFT JOIN ccdi_base_staff bs
    ON bs.id_card = sfr.person_id

其中：

列表查询不额外过滤 sfr.status = 1
原因是历史记录需要正常展示，即使亲属后续失效，记录仍可查到，但实体关联状态会被联动改为无效

7.4 新增与导入校验

新增和导入都统一改为校验有效亲属关系：

根据亲属身份证号查询 ccdi_staff_fmy_relation
要求命中 is_emp_family = 1 and status = 1
未命中则报错
命中后继续校验 亲属身份证号 + 统一社会信用代码 唯一

7.5 亲属下拉搜索接口

前端新增/编辑弹窗需要按身份证号模糊搜索有效亲属。

实现方式：

在员工实体关联模块后端新增一个用于下拉搜索的查询接口
返回有效亲属列表

返回项建议包含：

relationCertNo
relationName
personId
personName

查询条件：

relation_cert_no 模糊匹配输入值
is_emp_family = 1
status = 1

7.6 亲属失效联动落点

联动逻辑放在员工亲属关系保存链路中处理，即：

CcdiStaffFmyRelationServiceImpl.updateRelation

处理规则：

查询更新前旧记录
判断旧状态是否为有效、更新后状态是否为无效
若是，则按当前亲属身份证号批量更新实体关联表状态为无效

该联动需和亲属关系更新处于同一事务内，保证状态一致。

8. 前端设计

8.1 页面延用

继续使用：

ruoyi-ui/src/views/ccdiStaffEnterpriseRelation/index.vue

不新建新页面。

8.2 查询区

查询区改为亲属语义，保留或新增：

亲属身份证号
亲属名称
关联员工
统一社会信用代码
企业名称
状态

8.3 列表区

列表核心列调整为：

亲属身份证
亲属名称
关联员工
企业名称
关联人在企业的职务
状态
数据来源
创建时间
操作

其中“关联员工”展示建议为：

员工姓名（员工身份证号）

这样可以避免用户只看到姓名无法定位员工。

8.4 新增弹窗

新增弹窗保留现有骨架，调整主录入方式：

身份证号输入改为“按亲属身份证模糊搜索”
下拉数据来源改为有效员工亲属

下拉项显示建议：

左侧：亲属身份证号
右侧：亲属名称 / 关联员工姓名

用户选中后，自动回填并只读展示：

亲属名称
关联员工

其余字段继续录入：

统一社会信用代码
企业名称
关联人在企业的职务
补充说明

新增时状态仍默认有效。

8.5 编辑弹窗

编辑弹窗延续现有模式：

亲属身份证号不可编辑
统一社会信用代码不可编辑
亲属名称和关联员工仅展示，不可改

8.6 详情弹窗

详情弹窗基础信息展示：

亲属身份证
亲属名称
关联员工
统一社会信用代码
企业名称
关联人在企业的职务
状态
数据来源
补充说明
审计信息

9. 导入设计

9.1 导入模板

继续沿用现有异步导入机制，但模板标题、文案和字段语义改为亲属口径。

模板标题改为：

员工亲属实体关联信息

模板中的“身份证号”字段实际表示：

亲属身份证号

9.2 导入校验规则

每行导入数据按以下顺序校验：

基础字段非空与格式合法
亲属身份证号必须存在于员工亲属关系中
且该亲属必须为员工亲属、状态有效
亲属身份证号 + 统一社会信用代码 在库中不能重复
导入文件内同组合不能重复

9.3 失败记录展示

失败记录弹窗字段调整为：

亲属身份证号
亲属名称
企业名称
统一社会信用代码
失败原因

失败原因示例：

亲属身份证号不存在于员工亲属关系中
亲属已失效，无法导入实体关联
亲属身份证号和统一社会信用代码组合已存在

9.4 导入结果提示

所有导入提示文案统一改为：

员工亲属实体关联导入

避免继续出现“员工实体关系”旧语义。

10. 错误处理

后端错误提示统一切换为亲属语义，示例：

所选身份证号不是有效的员工亲属，无法新增实体关联
亲属身份证号和统一社会信用代码组合已存在
亲属身份证号不存在于员工亲属关系中，或该亲属已无效
亲属身份证号不可修改

前端不新增特殊兜底逻辑，直接按现有错误提示机制回显后端返回信息。

11. 测试要点

11.1 列表与详情

列表正确展示亲属身份证、亲属名称、关联员工
详情页展示字段与列表语义一致

11.2 新增

输入亲属身份证可模糊搜索有效亲属
选中亲属后自动带出亲属名称和关联员工
无效亲属、非员工亲属、不存在的亲属身份证不能新增
重复的亲属身份证号 + 统一社会信用代码不能新增

11.3 编辑

亲属身份证号不可修改
统一社会信用代码不可修改
企业名称、职务、状态、备注可正常编辑

11.4 导入

有效亲属导入成功
亲属不存在导入失败
亲属无效导入失败
导入文件内重复失败
数据库内重复失败
失败记录文案与字段正确

11.5 失效联动

将员工亲属关系从有效改为无效后
该亲属名下已有实体关联自动更新为无效
列表仍能查到该记录，但状态为无效

12. 实施边界总结

本次改造严格限定为“在原员工实体关联模块上切换主对象为员工亲属”，核心边界如下：

不新建表
不新建页面
不迁移旧数据
不做兼容性兜底
不做反向恢复联动
所有合法性判断均以员工亲属关系表为准

在此边界内，前后端和导入链路均可形成完整闭环，并满足本次需求。

14 KiB Raw Blame History Unescape Escape