wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
wkc
2026-04-23 16:47:26 +08:00
parent e9403662e2
commit d79a60ab8c
1 changed files with 544 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

544
docs/superpowers/specs/2026-04-23-staff-family-enterprise-relation-design.md Normal file
View File

@@ -0,0 +1,544 @@
# 员工亲属实体关联维护设计
## 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 查询回填链路
列表和详情展示使用以下关联链路：
1. 以 `ccdi_staff_enterprise_relation` 为主表
2. 通过 `ccdi_staff_fmy_relation.relation_cert_no = ccdi_staff_enterprise_relation.person_id`
3. 并限定 `ccdi_staff_fmy_relation.is_emp_family = 1`
4. 从 `ccdi_staff_fmy_relation` 获取：
- `relation_name` 作为亲属名称
- `person_id` 作为关联员工身份证
5. 再通过 `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 改为从亲属关系表回补字段，示意逻辑如下：
```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 新增与导入校验
新增和导入都统一改为校验有效亲属关系：
1. 根据亲属身份证号查询 `ccdi_staff_fmy_relation`
2. 要求命中 `is_emp_family = 1 and status = 1`
3. 未命中则报错
4. 命中后继续校验 `亲属身份证号 + 统一社会信用代码` 唯一
### 7.5 亲属下拉搜索接口
前端新增/编辑弹窗需要按身份证号模糊搜索有效亲属。
实现方式：
- 在员工实体关联模块后端新增一个用于下拉搜索的查询接口
- 返回有效亲属列表
返回项建议包含：
- `relationCertNo`
- `relationName`
- `personId`
- `personName`
查询条件：
- `relation_cert_no` 模糊匹配输入值
- `is_emp_family = 1`
- `status = 1`
### 7.6 亲属失效联动落点
联动逻辑放在员工亲属关系保存链路中处理，即：
- `CcdiStaffFmyRelationServiceImpl.updateRelation`
处理规则：
1. 查询更新前旧记录
2. 判断旧状态是否为有效、更新后状态是否为无效
3. 若是，则按当前亲属身份证号批量更新实体关联表状态为无效
该联动需和亲属关系更新处于同一事务内，保证状态一致。
## 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 导入校验规则
每行导入数据按以下顺序校验：
1. 基础字段非空与格式合法
2. 亲属身份证号必须存在于员工亲属关系中
3. 且该亲属必须为员工亲属、状态有效
4. `亲属身份证号 + 统一社会信用代码` 在库中不能重复
5. 导入文件内同组合不能重复
### 9.3 失败记录展示
失败记录弹窗字段调整为：
- 亲属身份证号
- 亲属名称
- 企业名称
- 统一社会信用代码
- 失败原因
失败原因示例：
- 亲属身份证号不存在于员工亲属关系中
- 亲属已失效，无法导入实体关联
- 亲属身份证号和统一社会信用代码组合已存在
### 9.4 导入结果提示
所有导入提示文案统一改为：
- 员工亲属实体关联导入
避免继续出现“员工实体关系”旧语义。
## 10. 错误处理
后端错误提示统一切换为亲属语义，示例：
- 所选身份证号不是有效的员工亲属，无法新增实体关联
- 亲属身份证号和统一社会信用代码组合已存在
- 亲属身份证号不存在于员工亲属关系中，或该亲属已无效
- 亲属身份证号不可修改
前端不新增特殊兜底逻辑，直接按现有错误提示机制回显后端返回信息。
## 11. 测试要点
### 11.1 列表与详情
- 列表正确展示亲属身份证、亲属名称、关联员工
- 详情页展示字段与列表语义一致
### 11.2 新增
- 输入亲属身份证可模糊搜索有效亲属
- 选中亲属后自动带出亲属名称和关联员工
- 无效亲属、非员工亲属、不存在的亲属身份证不能新增
- 重复的亲属身份证号 + 统一社会信用代码不能新增
### 11.3 编辑
- 亲属身份证号不可修改
- 统一社会信用代码不可修改
- 企业名称、职务、状态、备注可正常编辑
### 11.4 导入
- 有效亲属导入成功
- 亲属不存在导入失败
- 亲属无效导入失败
- 导入文件内重复失败
- 数据库内重复失败
- 失败记录文案与字段正确
### 11.5 失效联动
- 将员工亲属关系从有效改为无效后
- 该亲属名下已有实体关联自动更新为无效
- 列表仍能查到该记录，但状态为无效
## 12. 实施边界总结
本次改造严格限定为“在原员工实体关联模块上切换主对象为员工亲属”，核心边界如下：
- 不新建表
- 不新建页面
- 不迁移旧数据
- 不做兼容性兜底
- 不做反向恢复联动
- 所有合法性判断均以员工亲属关系表为准
在此边界内，前后端和导入链路均可形成完整闭环，并满足本次需求。