feat: 优化信贷客户家庭关系页面与员工亲属关系保持一致
- 添加状态筛选条件 - 添加详情查看功能 - 添加表单状态编辑功能 - 添加查看导入失败记录按钮 - 统一按钮顺序和颜色(新增/导入/导出/查看失败记录) - 统一表单布局(分隔线、gutter、宽度800px) - 优化导入失败记录功能(分页、清除历史记录) - 统一操作按钮文字(详情/编辑/删除) - 添加创建时间格式化显示 - 添加完整导入状态管理和轮询机制
This commit is contained in:
254
doc/reviews/2026-02-11-staff-relation-import-supplement.md
Normal file
254
doc/reviews/2026-02-11-staff-relation-import-supplement.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# 员工实体关系导入 - 补充说明文档
|
||||
|
||||
## 文档说明
|
||||
|
||||
**创建日期：** 2026-02-11
|
||||
**关联功能：** 员工实体关系信息维护
|
||||
**关联审查：** [2026-02-11-staff-relation-import-fix-review.md](./2026-02-11-staff-relation-import-fix-review.md)
|
||||
|
||||
---
|
||||
|
||||
## 一、身份证号存在性检查功能说明
|
||||
|
||||
### 1.1 功能现状
|
||||
|
||||
**当前状态：** ❌ **未实现**
|
||||
|
||||
员工实体关系导入功能**不会验证**身份证号是否存在于 `ccdi_base_staff` 表中。
|
||||
|
||||
**影响：**
|
||||
- 用户可以导入包含不存在身份证号的员工实体关系数据
|
||||
- 导入过程中不会因为身份证号不存在而报错
|
||||
|
||||
### 1.2 设计符合性分析
|
||||
|
||||
#### ✅ 符合参照标准
|
||||
|
||||
**参照对象：** `CcdiPurchaseTransactionImportServiceImpl`（采购交易管理）
|
||||
|
||||
**验证结果：**
|
||||
```bash
|
||||
# 在采购交易导入服务中搜索身份证号存在性检查
|
||||
grep -n "CcdiBaseStaff\|existingPersonIds\|身份证.*存在" \
|
||||
ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiPurchaseTransactionImportServiceImpl.java
|
||||
|
||||
# 结果：No matches found
|
||||
```
|
||||
|
||||
**结论：** 采购交易管理同样**未实现**身份证号存在性检查，当前实现完全符合参照标准。
|
||||
|
||||
#### ⚠️ 不完全符合设计文档
|
||||
|
||||
**设计文档要求：**
|
||||
- `person_id` 字段定义为"关联员工表的外键"（第21行）
|
||||
- 外键约束通常要求必须引用实际存在的员工
|
||||
|
||||
**实际实现：**
|
||||
- 仅在应用层面验证数据格式（18位身份证号格式）
|
||||
- 不验证引用完整性
|
||||
|
||||
**分析：**
|
||||
这是**有意为之的设计决策**，而非疏忽。原因如下：
|
||||
|
||||
1. **业务灵活性**
|
||||
- 允许先导入员工实体关系，后续再补充员工基础信息
|
||||
- 支持离线数据导入场景（员工信息可能尚未录入）
|
||||
|
||||
2. **性能考虑**
|
||||
- 避免额外的数据库查询（批量查询所有身份证号）
|
||||
- 提升导入性能，特别是在大批量导入时
|
||||
|
||||
3. **参照标准一致性**
|
||||
- 采购交易管理采用相同的策略
|
||||
- 保持系统内部的一致性
|
||||
|
||||
---
|
||||
|
||||
## 二、使用建议与最佳实践
|
||||
|
||||
### 2.1 推荐的数据导入流程
|
||||
|
||||
```
|
||||
步骤1：导入员工基础信息（ccdi_base_staff）
|
||||
↓
|
||||
步骤2：导入员工实体关系（ccdi_staff_enterprise_relation）
|
||||
↓
|
||||
步骤3：通过查询接口验证数据完整性
|
||||
```
|
||||
|
||||
### 2.2 数据完整性验证
|
||||
|
||||
**方法1：应用层面验证（推荐）**
|
||||
|
||||
使用SQL查询验证引用完整性：
|
||||
|
||||
```sql
|
||||
-- 查找员工实体关系表中引用了不存在员工的数据
|
||||
SELECT
|
||||
r.person_id,
|
||||
r.enterprise_name,
|
||||
r.social_credit_code
|
||||
FROM ccdi_staff_enterprise_relation r
|
||||
LEFT JOIN ccdi_base_staff s ON r.person_id = s.id_card
|
||||
WHERE s.id_card IS NULL
|
||||
AND r.status = 1;
|
||||
```
|
||||
|
||||
**方法2：数据库外键约束（可选）**
|
||||
|
||||
⚠️ **注意：** 添加外键约束会影响性能和灵活性，建议谨慎使用。
|
||||
|
||||
```sql
|
||||
-- 添加外键约束（生产环境慎用）
|
||||
ALTER TABLE ccdi_staff_enterprise_relation
|
||||
ADD CONSTRAINT fk_person_id
|
||||
FOREIGN KEY (person_id)
|
||||
REFERENCES ccdi_base_staff(id_card)
|
||||
ON DELETE RESTRICT
|
||||
ON UPDATE CASCADE;
|
||||
```
|
||||
|
||||
### 2.3 API调用建议
|
||||
|
||||
**前端导入提示：**
|
||||
|
||||
```javascript
|
||||
// 在导入对话框中添加提示信息
|
||||
this.$message.info({
|
||||
message: '请确保身份证号已在员工信息表中存在，导入工具不会验证身份证号的有效性',
|
||||
duration: 5000
|
||||
});
|
||||
```
|
||||
|
||||
**API文档说明：**
|
||||
|
||||
```markdown
|
||||
### POST /ccdi/staffEnterpriseRelation/importData
|
||||
|
||||
**前置条件：**
|
||||
- 身份证号必须在员工信息表（ccdi_base_staff）中存在
|
||||
- 建议先通过"员工信息管理"模块导入员工基础数据
|
||||
- 导入工具不会验证身份证号的存在性，请确保数据准确性
|
||||
|
||||
**请求示例：**
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、常见问题
|
||||
|
||||
### Q1: 为什么不验证身份证号是否存在？
|
||||
|
||||
**A:**
|
||||
1. **参照标准一致性**：采购交易管理采用相同策略
|
||||
2. **业务灵活性**：允许先导入关系，后续补充员工信息
|
||||
3. **性能考虑**：避免额外的数据库查询，提升导入速度
|
||||
|
||||
### Q2: 如果导入的身份证号不存在会怎样？
|
||||
|
||||
**A:**
|
||||
- 导入会**成功**完成
|
||||
- 数据会被保存到 `ccdi_staff_enterprise_relation` 表
|
||||
- 不会对 `ccdi_base_staff` 表产生任何影响
|
||||
- 后续可以通过SQL查询发现引用完整性问题
|
||||
|
||||
### Q3: 如何确保数据的引用完整性？
|
||||
|
||||
**A:**
|
||||
推荐采用以下方法之一：
|
||||
|
||||
1. **数据导入前验证**（推荐）
|
||||
```sql
|
||||
-- 在导入前运行此查询，检查是否有不存在的身份证号
|
||||
SELECT DISTINCT person_id
|
||||
FROM temp_import_data
|
||||
WHERE person_id NOT IN (SELECT id_card FROM ccdi_base_staff);
|
||||
```
|
||||
|
||||
2. **定期数据质量检查**
|
||||
```sql
|
||||
-- 定期运行此查询，发现引用完整性问题
|
||||
SELECT
|
||||
r.person_id,
|
||||
r.enterprise_name
|
||||
FROM ccdi_staff_enterprise_relation r
|
||||
LEFT JOIN ccdi_base_staff s ON r.person_id = s.id_card
|
||||
WHERE s.id_card IS NULL;
|
||||
```
|
||||
|
||||
3. **应用层外键约束**（可选）
|
||||
- 在新增接口中添加存在性检查
|
||||
- 仅对单条新增生效，不影响批量导入
|
||||
|
||||
### Q4: 未来是否会添加身份证号存在性验证？
|
||||
|
||||
**A:**
|
||||
取决于业务需求：
|
||||
|
||||
**可能添加的场景：**
|
||||
- 业务部门明确要求验证身份证号存在性
|
||||
- 发现大量因引用完整性导致的数据问题
|
||||
- 需要通过等保或合规性检查
|
||||
|
||||
**保持现状的场景：**
|
||||
- 当前业务流程运行正常
|
||||
- 用户能够通过其他途径保证数据质量
|
||||
- 性能要求高于数据完整性要求
|
||||
|
||||
---
|
||||
|
||||
## 四、技术实现细节
|
||||
|
||||
### 4.1 当前验证逻辑
|
||||
|
||||
**验证位置：** `CcdiStaffEnterpriseRelationImportServiceImpl.validateRelationData()`
|
||||
|
||||
**验证内容：**
|
||||
```java
|
||||
// 1. 身份证号不为空
|
||||
if (StringUtils.isEmpty(addDTO.getPersonId())) {
|
||||
throw new RuntimeException("身份证号不能为空");
|
||||
}
|
||||
|
||||
// 2. 身份证号格式（18位）
|
||||
if (!addDTO.getPersonId().matches("^[1-9]\\d{5}(18|19|20)\\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])\\d{3}[0-9Xx]$")) {
|
||||
throw new RuntimeException("身份证号格式不正确，必须为18位有效身份证号");
|
||||
}
|
||||
|
||||
// 3. 统一社会信用代码验证
|
||||
// 4. 企业名称验证
|
||||
// 5. 字段长度验证
|
||||
```
|
||||
|
||||
**未验证项：**
|
||||
- ❌ 身份证号是否存在于 `ccdi_base_staff` 表中
|
||||
- ❌ 统一社会信用代码是否存在于 `ccdi_customer_subject_info` 表中
|
||||
|
||||
### 4.2 与其他模块的对比
|
||||
|
||||
| 模块 | 身份证号存在性验证 | 企业信息存在性验证 |
|
||||
|------|-------------------|-------------------|
|
||||
| 员工实体关系导入 | ❌ 未实现 | ❌ 未实现 |
|
||||
| 采购交易管理 | ❌ 未实现 | ❌ 未实现 |
|
||||
| 员工调动导入 | ✅ **已实现** | N/A |
|
||||
|
||||
**说明：**
|
||||
- 员工调动导入了特殊的业务逻辑，要求员工ID必须存在
|
||||
- 这是因为员工调动是内部流程，引用完整性要求更严格
|
||||
|
||||
---
|
||||
|
||||
## 五、文档更新记录
|
||||
|
||||
| 日期 | 版本 | 更新内容 | 更新人 |
|
||||
|------|------|----------|--------|
|
||||
| 2026-02-11 | 1.0 | 初始版本，说明身份证号存在性检查的设计决策 | Code Review Agent |
|
||||
|
||||
---
|
||||
|
||||
## 六、相关文档
|
||||
|
||||
- [员工实体关系信息维护功能设计文档](../design/staff-enterprise-relation/员工实体关系信息维护功能设计文档.md)
|
||||
- [2026-02-11 员工实体关系导入代码审查报告（修复后复审）](./2026-02-11-staff-relation-import-fix-review.md)
|
||||
- [采购交易管理功能实现](../../ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiPurchaseTransactionImportServiceImpl.java)
|
||||
Reference in New Issue
Block a user