# 中介黑名单管理 API 文档 v2.0

## 概述

中介黑名单管理模块提供个人和实体两类中介信息的增删改查、类型化模板下载和批量导入导出功能。

**基础路径**: `/ccdi/intermediary`

**权限标识前缀**: `ccdi:intermediary`

**文档版本**: v2.0

**更新日期**: 2026-02-04

---

## API 接口列表

### 1. 查询中介列表

**接口地址**: `GET /ccdi/intermediary/list`

**权限要求**: `ccdi:intermediary:list`

**请求参数** (Query Params):

| 参数名              | 类型      | 必填 | 说明                 |
|------------------|---------|----|--------------------|
| name             | String  | 否  | 姓名/机构名称(模糊查询)      |
| certificateNo    | String  | 否  | 证件号/统一社会信用代码(精确查询) |
| intermediaryType | String  | 否  | 中介类型(1=个人, 2=实体)   |
| pageNum          | Integer | 否  | 页码(默认1)            |
| pageSize         | Integer | 否  | 每页数量(默认10)         |

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "rows": [
    {
      "bizId": "I202602040001",
      "name": "张三",
      "certificateNo": "110101199001011234",
      "intermediaryType": "1",
      "intermediaryTypeName": "个人",
      "status": "0",
      "statusName": "正常",
      "remark": "测试数据",
      "createBy": "admin",
      "createTime": "2026-02-04 10:00:00"
    }
  ],
  "total": 1
}
```

**响应字段说明**:

| 字段名                  | 类型     | 说明               |
|----------------------|--------|------------------|
| bizId                | String | 业务ID             |
| name                 | String | 姓名/机构名称          |
| certificateNo        | String | 证件号/统一社会信用代码     |
| intermediaryType     | String | 中介类型(1=个人, 2=实体) |
| intermediaryTypeName | String | 中介类型名称           |
| status               | String | 状态(0=正常, 1=停用)   |
| statusName           | String | 状态名称             |
| remark               | String | 备注               |
| createBy             | String | 创建人              |
| createTime           | String | 创建时间             |

---

### 2. 查询个人中介详情

**接口地址**: `GET /ccdi/intermediary/person/{bizId}`

**权限要求**: `ccdi:intermediary:query`

**路径参数**:

| 参数名   | 类型     | 必填 | 说明   |
|-------|--------|----|------|
| bizId | String | 是  | 业务ID |

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "bizId": "I202602040001",
    "name": "张三",
    "certificateNo": "110101199001011234",
    "intermediaryType": "1",
    "intermediaryTypeName": "个人",
    "status": "0",
    "statusName": "正常",
    "personType": "中介",
    "personSubType": "本人",
    "relationType": "正常",
    "gender": "M",
    "genderName": "男",
    "idType": "身份证",
    "personId": "110101199001011234",
    "mobile": "13800138000",
    "wechatNo": "zhangsan",
    "contactAddress": "北京市朝阳区",
    "company": "XX公司",
    "socialCreditCode": "91110000123456789X",
    "position": "经纪人",
    "relatedNumId": "",
    "relation": "",
    "remark": "测试数据",
    "createBy": "admin",
    "createTime": "2026-02-04 10:00:00"
  }
}
```

---

### 3. 查询实体中介详情

**接口地址**: `GET /ccdi/intermediary/entity/{socialCreditCode}`

**权限要求**: `ccdi:intermediary:query`

**路径参数**:

| 参数名              | 类型     | 必填 | 说明       |
|------------------|--------|----|----------|
| socialCreditCode | String | 是  | 统一社会信用代码 |

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "bizId": "I202602040002",
    "name": "XX中介公司",
    "certificateNo": "91110000123456789X",
    "intermediaryType": "2",
    "intermediaryTypeName": "实体",
    "status": "0",
    "statusName": "正常",
    "enterpriseName": "XX中介公司",
    "socialCreditCode": "91110000123456789X",
    "enterpriseType": "有限责任公司",
    "enterpriseNature": "民企",
    "industryClass": "房地产",
    "industryName": "房地产业",
    "establishDate": "2020-01-01",
    "registerAddress": "北京市朝阳区",
    "legalRepresentative": "张三",
    "legalCertType": "身份证",
    "legalCertNo": "110101199001011234",
    "shareholder1": "李四",
    "shareholder2": "王五",
    "shareholder3": "",
    "shareholder4": "",
    "shareholder5": "",
    "remark": "测试数据",
    "createBy": "admin",
    "createTime": "2026-02-04 10:00:00"
  }
}
```

---

### 4. 新增个人中介

**接口地址**: `POST /ccdi/intermediary/person`

**权限要求**: `ccdi:intermediary:add`

**请求体** (application/json):

```json
{
  "name": "张三",
  "personType": "中介",
  "personSubType": "本人",
  "relationType": "正常",
  "gender": "M",
  "idType": "身份证",
  "personId": "110101199001011234",
  "mobile": "13800138000",
  "wechatNo": "zhangsan",
  "contactAddress": "北京市朝阳区",
  "company": "XX公司",
  "socialCreditCode": "91110000123456789X",
  "position": "经纪人",
  "relatedNumId": "",
  "relation": "",
  "remark": "测试数据"
}
```

**字段说明**:

| 字段名              | 类型     | 必填 | 说明                 |
|------------------|--------|----|--------------------|
| name             | String | 是  | 姓名(最大100字符)        |
| personId         | String | 是  | 证件号码(最大50字符)       |
| personType       | String | 否  | 人员类型               |
| personSubType    | String | 否  | 人员子类型              |
| relationType     | String | 否  | 关系类型               |
| gender           | String | 否  | 性别(M=男, F=女, O=其他) |
| idType           | String | 否  | 证件类型               |
| mobile           | String | 否  | 手机号码(最大20字符)       |
| wechatNo         | String | 否  | 微信号(最大50字符)        |
| contactAddress   | String | 否  | 联系地址(最大200字符)      |
| company          | String | 否  | 所在公司(最大200字符)      |
| socialCreditCode | String | 否  | 企业统一信用码(最大50字符)    |
| position         | String | 否  | 职位(最大100字符)        |
| relatedNumId     | String | 否  | 关联人员ID(最大50字符)     |
| relation         | String | 否  | 关联关系(最大50字符)       |
| remark           | String | 否  | 备注(最大500字符)        |

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功"
}
```

---

### 5. 新增实体中介

**接口地址**: `POST /ccdi/intermediary/entity`

**权限要求**: `ccdi:intermediary:add`

**请求体** (application/json):

```json
{
  "enterpriseName": "XX中介公司",
  "socialCreditCode": "91110000123456789X",
  "enterpriseType": "有限责任公司",
  "enterpriseNature": "民企",
  "industryClass": "房地产",
  "industryName": "房地产业",
  "establishDate": "2020-01-01",
  "registerAddress": "北京市朝阳区",
  "legalRepresentative": "张三",
  "legalCertType": "身份证",
  "legalCertNo": "110101199001011234",
  "shareholder1": "李四",
  "shareholder2": "王五",
  "shareholder3": "",
  "shareholder4": "",
  "shareholder5": "",
  "remark": "测试数据"
}
```

**字段说明**:

| 字段名                 | 类型     | 必填 | 说明                |
|---------------------|--------|----|-------------------|
| enterpriseName      | String | 是  | 机构名称(最大200字符)     |
| socialCreditCode    | String | 否  | 统一社会信用代码(最大50字符)  |
| enterpriseType      | String | 否  | 主体类型(最大50字符)      |
| enterpriseNature    | String | 否  | 企业性质(最大50字符)      |
| industryClass       | String | 否  | 行业分类(最大100字符)     |
| industryName        | String | 否  | 所属行业(最大100字符)     |
| establishDate       | Date   | 否  | 成立日期              |
| registerAddress     | String | 否  | 注册地址(最大500字符)     |
| legalRepresentative | String | 否  | 法定代表人(最大100字符)    |
| legalCertType       | String | 否  | 法定代表人证件类型(最大50字符) |
| legalCertNo         | String | 否  | 法定代表人证件号码(最大50字符) |
| shareholder1-5      | String | 否  | 股东信息(每个最大100字符)   |
| remark              | String | 否  | 备注(最大500字符)       |

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功"
}
```

---

### 6. 修改个人中介

**接口地址**: `PUT /ccdi/intermediary/person`

**权限要求**: `ccdi:intermediary:edit`

**请求体** (application/json):

```json
{
  "bizId": "I202602040001",
  "name": "张三",
  "personType": "中介",
  "personSubType": "本人",
  "relationType": "正常",
  "gender": "M",
  "idType": "身份证",
  "personId": "110101199001011234",
  "mobile": "13800138000",
  "wechatNo": "zhangsan",
  "contactAddress": "北京市朝阳区",
  "company": "XX公司",
  "socialCreditCode": "91110000123456789X",
  "position": "经纪人",
  "relatedNumId": "",
  "relation": "",
  "remark": "测试数据"
}
```

**字段说明**: 与新增个人中介相同,bizId为必填项

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功"
}
```

---

### 7. 修改实体中介

**接口地址**: `PUT /ccdi/intermediary/entity`

**权限要求**: `ccdi:intermediary:edit`

**请求体** (application/json):

```json
{
  "socialCreditCode": "91110000123456789X",
  "enterpriseName": "XX中介公司",
  "enterpriseType": "有限责任公司",
  "enterpriseNature": "民企",
  "industryClass": "房地产",
  "industryName": "房地产业",
  "establishDate": "2020-01-01",
  "registerAddress": "北京市朝阳区",
  "legalRepresentative": "张三",
  "legalCertType": "身份证",
  "legalCertNo": "110101199001011234",
  "shareholder1": "李四",
  "shareholder2": "王五",
  "shareholder3": "",
  "shareholder4": "",
  "shareholder5": "",
  "remark": "测试数据"
}
```

**字段说明**: 与新增实体中介相同,socialCreditCode为必填项

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功"
}
```

---

### 8. 删除中介

**接口地址**: `DELETE /ccdi/intermediary/{ids}`

**权限要求**: `ccdi:intermediary:remove`

**路径参数**:

| 参数名 | 类型       | 必填 | 说明           |
|-----|----------|----|--------------|
| ids | String[] | 是  | 业务ID数组(逗号分隔) |

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功"
}
```

---

### 9. 校验人员ID唯一性

**接口地址**: `GET /ccdi/intermediary/checkPersonIdUnique`

**权限要求**: 无

**请求参数**:

| 参数名      | 类型     | 必填 | 说明             |
|----------|--------|----|----------------|
| personId | String | 是  | 证件号码           |
| bizId    | String | 否  | 排除的业务ID(修改时使用) |

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": true
}
```

**data字段说明**: true=唯一可用, false=已存在

---

### 10. 校验统一社会信用代码唯一性

**接口地址**: `GET /ccdi/intermediary/checkSocialCreditCodeUnique`

**权限要求**: 无

**请求参数**:

| 参数名              | 类型     | 必填 | 说明           |
|------------------|--------|----|--------------|
| socialCreditCode | String | 是  | 统一社会信用代码     |
| excludeId        | String | 否  | 排除的ID(修改时使用) |

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": true
}
```

**data字段说明**: true=唯一可用, false=已存在

---

### 11. 下载个人中介导入模板

**接口地址**: `POST /ccdi/intermediary/importPersonTemplate`

**权限要求**: 无

**响应**: Excel模板文件下载

**Excel格式说明**:

**Sheet1: 个人中介信息**
| 姓名 | 人员类型 | 人员子类型 | 关系类型 | 性别▼ | 证件类型▼ | 证件号码 | 手机号码 | 微信号 | 联系地址 | 所在公司 |
企业统一信用码 | 职位 | 关联人员ID | 关联关系 | 备注 |
|------|---------|-----------|---------|-------|-----------|---------|---------|--------|---------|---------|--------------|-----|-----------|---------|------|
| 张三 | 中介 | 本人 | 正常 | 男 | 身份证 | 110101199001011234 | 13800138000 | zhangsan | 北京市朝阳区 | XX公司 |
91110000XXXXXXXXXX | 经纪人 | - | - | 测试 |

**注**: 带▼标记的列包含下拉框,选项来自字典

---

### 12. 下载实体中介导入模板

**接口地址**: `POST /ccdi/intermediary/importEntityTemplate`

**权限要求**: 无

**响应**: Excel模板文件下载

**Excel格式说明**:

**Sheet1: 实体中介信息**
| 机构名称 | 统一社会信用代码 | 主体类型▼ | 企业性质▼ | 行业分类 | 所属行业 | 成立日期 | 注册地址 | 法定代表人 |
法定代表人证件类型 | 法定代表人证件号码 | 股东1 | 股东2 | 股东3 | 股东4 | 股东5 | 备注 |
|---------|-----------------|-----------|-----------|---------|---------|---------|---------|-----------|-------------------|-------------------|-------|-------|-------|-------|-------|------|
| XX公司 | 91110000XXXXXXXXXX | 有限责任公司 | 民企 | 房地产 | 房地产业 | 2020-01-01 | 北京市朝阳区 | 张三 | 身份证 |
110101199001011234 | 李四 | 王五 | - | - | - | - |

---

### 13. 导入个人中介数据

**接口地址**: `POST /ccdi/intermediary/importPersonData`

**权限要求**: `ccdi:intermediary:import`

**请求参数** (multipart/form-data):

| 参数名           | 类型      | 必填 | 说明                 |
|---------------|---------|----|--------------------|
| file          | File    | 是  | Excel文件            |
| updateSupport | Boolean | 否  | 是否更新已存在数据(默认false) |

**响应示例**:

```json
{
  "code": 200,
  "msg": "恭喜您,数据已全部导入成功!共10条"
}
```

---

### 14. 导入实体中介数据

**接口地址**: `POST /ccdi/intermediary/importEntityData`

**权限要求**: `ccdi:intermediary:import`

**请求参数** (multipart/form-data):

| 参数名           | 类型      | 必填 | 说明                 |
|---------------|---------|----|--------------------|
| file          | File    | 是  | Excel文件            |
| updateSupport | Boolean | 否  | 是否更新已存在数据(默认false) |

**响应示例**:

```json
{
  "code": 200,
  "msg": "恭喜您,数据已全部导入成功!共10条"
}
```

---

## 字典数据说明

导入模板中的下拉框选项来自系统字典管理,相关字典类型:

| 字典类型                   | 字典名称   | 用途            |
|------------------------|--------|---------------|
| ccdi_indiv_gender      | 个人中介性别 | 个人中介模板性别下拉框   |
| ccdi_certificate_type  | 证件类型   | 个人中介模板证件类型下拉框 |
| ccdi_entity_type       | 主体类型   | 机构中介模板主体类型下拉框 |
| ccdi_enterprise_nature | 企业性质   | 机构中介模板企业性质下拉框 |
| ccdi_data_source       | 数据来源   | 数据来源字段映射      |

---

## 错误码说明

| HTTP状态码 | 错误码 | 说明       |
|---------|-----|----------|
| 200     | 200 | 操作成功     |
| 401     | 401 | 未授权,请先登录 |
| 403     | 403 | 无权限访问    |
| 500     | 500 | 服务器内部错误  |

---

## 业务错误信息

| 错误信息             | 说明               |
|------------------|------------------|
| 姓名不能为空           | 个人中介新增/修改时姓名为空   |
| 机构名称不能为空         | 实体中介新增/修改时机构名称为空 |
| 证件号码不能为空         | 个人中介新增/修改时证件号码为空 |
| 该证件号已存在          | 新增/导入时证件号重复      |
| 该统一社会信用代码已存在     | 新增/导入时信用代码重复     |
| 姓名长度不能超过100个字符   | 姓名超长             |
| 证件号码长度不能超过50个字符  | 证件号码超长           |
| 机构名称长度不能超过200个字符 | 机构名称超长           |

---

## 测试账号

- 用户名: `admin`
- 密码: `admin123`

测试前请先调用 `/login/test` 接口获取Token。

---

## 更新日志

| 版本    | 日期         | 说明                                                |
|-------|------------|---------------------------------------------------|
| 1.0.0 | 2026-01-29 | 初始版本,支持个人和机构分类管理                                  |
| 1.1.0 | 2026-01-29 | 添加字典下拉框功能,分离个人/机构模板                               |
| 1.2.0 | 2026-01-29 | 修改接口分离:新增个人/机构专用修改接口,修复中介类型修改问题                   |
| 1.3.0 | 2026-01-29 | 新增接口分离:新增个人/机构专用新增接口,统一接口设计                       |
| 2.0.0 | 2026-02-04 | 重构版本:使用MyBatis Plus,分离DTO/VO,统一业务ID(bizId),优化查询接口 |

---

## 主要变更说明 (v2.0)

### 架构变更

- 使用MyBatis Plus替代原生MyBatis
- 分离DTO(请求)和VO(响应)对象
- 统一使用业务ID(bizId)作为主键

### 接口变更

- 查询详情接口分离为个人和实体两个接口
- 新增接口分离为个人和实体两个接口
- 修改接口分离为个人和实体两个接口
- 新增唯一性校验接口

### 数据模型变更

- 个人中介使用`personId`作为证件号字段
- 实体中介使用`socialCreditCode`作为统一社会信用代码字段
- 删除了`intermediaryId`,统一使用`bizId`

### 查询功能增强

- 支持按中介类型查询
- 支持按姓名/机构名称模糊查询
- 支持按证件号/统一社会信用代码精确查询
