ccdi/doc/reviews/2026-02-11-staff-relation-import-supplement.md

员工实体关系导入 - 补充说明文档

文档说明

创建日期： 2026-02-11 关联功能： 员工实体关系信息维护 关联审查： 2026-02-11-staff-relation-import-fix-review.md

---

一、身份证号存在性检查功能说明

1.1 功能现状

当前状态： ❌ 未实现

员工实体关系导入功能不会验证身份证号是否存在于 ccdi_base_staff 表中。

影响：

• 用户可以导入包含不存在身份证号的员工实体关系数据
• 导入过程中不会因为身份证号不存在而报错

1.2 设计符合性分析

✅ 符合参照标准

参照对象： CcdiPurchaseTransactionImportServiceImpl（采购交易管理）

验证结果：

# 在采购交易导入服务中搜索身份证号存在性检查
grep -n "CcdiBaseStaff\|existingPersonIds\|身份证.*存在" \
  ruoyi-info-collection/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查询验证引用完整性：

-- 查找员工实体关系表中引用了不存在员工的数据
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：数据库外键约束（可选）

⚠️ 注意： 添加外键约束会影响性能和灵活性，建议谨慎使用。

-- 添加外键约束（生产环境慎用）
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调用建议

前端导入提示：

// 在导入对话框中添加提示信息
this.$message.info({
  message: '请确保身份证号已在员工信息表中存在，导入工具不会验证身份证号的有效性',
  duration: 5000
});

API文档说明：

### 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. 定期数据质量检查

   -- 定期运行此查询，发现引用完整性问题
   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()

验证内容：

// 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

---

六、相关文档

• 员工实体关系信息维护功能设计文档
• 2026-02-11 员工实体关系导入代码审查报告（修复后复审）
• 采购交易管理功能实现