ccdi/doc/other/中介黑名单导入功能修复说明.md

# 中介黑名单导入功能修复说明

## 问题描述

在导入机构中介黑名单数据时，出现以下错误：

```
Error updating database. Cause: java.sql.SQLIntegrityConstraintViolationException: Column 'certificate_no' cannot be null
```

## 问题原因

1. **数据库约束**：`ccdi_intermediary_blacklist` 表的 `certificate_no` 字段设置为 `NOT NULL`，不允许存储 null 值。

2. **代码缺陷**：在 `CcdiIntermediaryBlacklistServiceImpl.java` 的 `importEntityIntermediary` 方法中，导入机构中介时只设置了 `corpCreditCode`（统一社会信用代码），但没有设置 `certificateNo` 字段，导致该字段为 null。

3. **批量插入失败**：`batchInsert` 方法明确插入 `certificate_no` 字段，当值为 null 时违反数据库约束。

## 解决方案

### 1. 代码修改

**文件**：[CcdiIntermediaryBlacklistServiceImpl.java](d:\discipline-prelim-check\discipline-prelim-check\ruoyi-ccdi\src\main\java\com\ruoyi\dpc\service\impl\CcdiIntermediaryBlacklistServiceImpl.java)

**修改位置**：第 390-394 行

**修改前**：
```java
// 转换为实体
CcdiIntermediaryBlacklist intermediary = new CcdiIntermediaryBlacklist();
intermediary.setName(excel.getName());
intermediary.setIntermediaryType("2");
```

**修改后**：
```java
// 转换为实体
CcdiIntermediaryBlacklist intermediary = new CcdiIntermediaryBlacklist();
intermediary.setName(excel.getName());
// 对于机构中介，使用统一社会信用代码作为证件号
intermediary.setCertificateNo(excel.getCorpCreditCode());
intermediary.setIntermediaryType("2");
```

### 2. 验证逻辑增强

**文件**：[CcdiIntermediaryBlacklistServiceImpl.java](d:\discipline-prelim-check\discipline-prelim-check\ruoyi-ccdi\src\main\java\com\ruoyi\dpc\service\impl\CcdiIntermediaryBlacklistServiceImpl.java)

**修改位置**：第 484-488 行

**修改前**：
```java
private void validateEntityIntermediaryData(CcdiIntermediaryEntityExcel excel) {
    if (StringUtils.isEmpty(excel.getName())) {
        throw new RuntimeException("机构名称不能为空");
    }
}
```

**修改后**：
```java
private void validateEntityIntermediaryData(CcdiIntermediaryEntityExcel excel) {
    if (StringUtils.isEmpty(excel.getName())) {
        throw new RuntimeException("机构名称不能为空");
    }
    // 验证统一社会信用代码不能为空（因为会用作 certificate_no 字段）
    if (StringUtils.isEmpty(excel.getCorpCreditCode())) {
        throw new RuntimeException("统一社会信用代码不能为空");
    }
}
```

### 3. 批量更新 XML 配置优化

**文件**：[CcdiIntermediaryBlacklistMapper.xml](d:\discipline-prelim-check\discipline-prelim-check\ruoyi-ccdi\src\main\resources\mapper\dpc\CcdiIntermediaryBlacklistMapper.xml)

**修改位置**：第 125-127 行

**修改前**：
```xml
<if test="item.dataSource != null">data_source = #{item.dataSource},</if>
update_by = #{item.updateBy},
update_time = #{item.updateTime}
```

**修改后**：
```xml
<if test="item.dataSource != null">data_source = #{item.dataSource},</if>
<if test="item.certificateNo != null">certificate_no = #{item.certificateNo},</if>
update_by = #{item.updateBy},
update_time = #{item.updateTime}
```

## 设计说明

### 为什么使用统一社会信用代码作为证件号？

1. **数据一致性**：统一社会信用代码本身就是机构的法定证件号，将其同时存储在 `certificate_no` 字段中可以保持数据的一致性。

2. **查询便利**：`certificate_no` 字段有索引，设置后可以快速查询机构中介。

3. **兼容性好**：个人中介和机构中介都使用 `certificate_no` 字段，查询逻辑更统一。

4. **不破坏现有结构**：不需要修改数据库表结构，只修改代码逻辑。

## 测试验证

### 测试用例

1. **个人中介导入**：正常导入个人中介数据，验证 `certificate_no` 字段正确存储身份证号。

2. **机构中介导入**：导入机构中介数据，验证 `certificate_no` 字段正确存储统一社会信用代码。

3. **统一社会信用代码为空**：验证当统一社会信用代码为空时，导入被正确拒绝并给出错误提示。

4. **批量更新**：验证批量更新时 `certificate_no` 字段能够正确更新。

### 测试脚本

测试脚本位于：[doc/test-data/test_import_fix.py](d:\discipline-prelim-check\discipline-prelim-check\doc\test-data\test_import_fix.py)

运行测试：
```bash
python doc/test-data/test_import_fix.py
```

## 影响范围

### 已影响的功能
- 机构中介批量导入功能

### 不影响的功能
- 个人中介导入功能
- 手动新增中介功能
- 中介查询功能
- 中介导出功能

## 注意事项

1. **数据迁移**：如果数据库中已存在机构中介数据且 `certificate_no` 为 null，需要执行以下 SQL 进行数据修复：

```sql
UPDATE ccdi_intermediary_blacklist
SET certificate_no = corp_credit_code
WHERE intermediary_type = '2' AND certificate_no IS NULL AND corp_credit_code IS NOT NULL;
```

2. **Excel 模板**：确保导入模板中统一社会信用代码字段设置为必填项。

3. **前端验证**：建议在前端表单中也添加统一社会信用代码的必填验证。

## 修改文件列表

1. [CcdiIntermediaryBlacklistServiceImpl.java](d:\discipline-prelim-check\discipline-prelim-check\ruoyi-ccdi\src\main\java\com\ruoyi\dpc\service\impl\CcdiIntermediaryBlacklistServiceImpl.java) - 服务层实现
2. [CcdiIntermediaryBlacklistMapper.xml](d:\discipline-prelim-check\discipline-prelim-check\ruoyi-ccdi\src\main\resources\mapper\dpc\CcdiIntermediaryBlacklistMapper.xml) - MyBatis 映射文件
3. [test_import_fix.py](d:\discipline-prelim-check\discipline-prelim-check\doc\test-data\test_import_fix.py) - 测试脚本

## 版本历史

| 版本 | 日期 | 作者 | 说明 |
|------|------|------|------|
| 1.0 | 2026-01-29 | ruoyi | 初始版本，修复机构中介导入时 certificate_no 为 null 的问题 |