ccdi/assets/api-docs/api/中介黑名单管理API文档.md

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

## 概述

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

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

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

**技术栈**: Spring Boot 3 + MyBatis Plus + MySQL

---

## API 接口列表

### 1. 查询中介黑名单列表

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

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

**请求参数**:

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

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "rows": [
    {
      "id": "abc123",
      "name": "张三",
      "certificateNo": "110101199001011234",
      "intermediaryType": "1",
      "personType": "中介",
      "company": "XX公司",
      "dataSource": "MANUAL",
      "createTime": "2026-02-04 10:00:00",
      "updateTime": "2026-02-05 14:30:00"
    }
  ],
  "total": 1
}
```

**响应字段说明**:

| 字段名              | 类型     | 说明                                 |
|------------------|--------|------------------------------------|
| id               | String | ID（个人为bizId，实体为socialCreditCode）   |
| name             | String | 姓名/机构名称                            |
| certificateNo    | String | 证件号/统一社会信用代码                       |
| intermediaryType | String | 中介类型（1=个人, 2=实体）                   |
| personType       | String | 人员类型/实体                            |
| company          | String | 公司/机构名称                            |
| dataSource       | String | 数据来源（MANUAL=手动, IMPORT=导入, API=接口） |
| createTime       | Date   | 创建时间                               |
| updateTime       | Date   | 修改时间                               |

---

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

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

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

**路径参数**:

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

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "bizId": "abc123xyz456",
    "intermediaryType": "1",
    "name": "张三",
    "personType": "房产中介",
    "personSubType": "本人",
    "gender": "M",
    "idType": "身份证",
    "personId": "110101199001011234",
    "mobile": "13800138000",
    "wechatNo": "zhangsan_wx",
    "contactAddress": "北京市朝阳区XX路XX号",
    "company": "XX房产中介公司",
    "position": "经纪人",
    "socialCreditCode": "91110000XXXXXXXXXX",
    "relatedNumId": "rel123",
    "relationType": "配偶",
    "dataSource": "MANUAL",
    "remark": "测试数据",
    "createTime": "2026-02-04 10:00:00"
  }
}
```

**响应字段说明**:

| 字段名              | 类型     | 说明                 |
|------------------|--------|--------------------|
| bizId            | String | 人员业务ID             |
| intermediaryType | String | 中介类型（固定为"1"）       |
| name             | String | 姓名                 |
| personType       | String | 人员类型（房产中介、贷款中介等）   |
| personSubType    | String | 人员子类型（本人、配偶、父亲等）   |
| gender           | String | 性别（M=男, F=女, O=其他） |
| idType           | String | 证件类型（身份证、护照等）      |
| personId         | String | 证件号码               |
| mobile           | String | 手机号码               |
| wechatNo         | String | 微信号                |
| contactAddress   | String | 联系地址               |
| company          | String | 所在公司               |
| position         | String | 职位                 |
| socialCreditCode | String | 企业统一信用码            |
| relatedNumId     | String | 关联人员ID             |
| relationType     | String | 关联关系（配偶、父子、母女等）    |
| dataSource       | String | 数据来源               |
| remark           | String | 备注                 |
| createTime       | Date   | 创建时间               |

---

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

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

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

**路径参数**:

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

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "socialCreditCode": "91110000XXXXXXXXXX",
    "intermediaryType": "2",
    "enterpriseName": "XX中介公司",
    "enterpriseType": "有限责任公司",
    "enterpriseNature": "民企",
    "industryClass": "房地产",
    "industryName": "房地产业",
    "establishDate": "2020-01-01",
    "registerAddress": "北京市朝阳区XX路XX号",
    "legalRepresentative": "张三",
    "legalCertType": "身份证",
    "legalCertNo": "110101199001011234",
    "shareholder1": "李四",
    "shareholder2": "王五",
    "shareholder3": "赵六",
    "shareholder4": null,
    "shareholder5": null,
    "dataSource": "MANUAL",
    "remark": "测试数据",
    "createTime": "2026-02-04 10:00:00"
  }
}
```

**响应字段说明**:

| 字段名                 | 类型     | 说明           |
|---------------------|--------|--------------|
| socialCreditCode    | String | 统一社会信用代码     |
| intermediaryType    | String | 中介类型（固定为"2"） |
| enterpriseName      | String | 机构名称         |
| enterpriseType      | String | 主体类型         |
| enterpriseNature    | String | 企业性质         |
| industryClass       | String | 行业分类         |
| industryName        | String | 所属行业         |
| establishDate       | Date   | 成立日期         |
| registerAddress     | String | 注册地址         |
| legalRepresentative | String | 法定代表人        |
| legalCertType       | String | 法定代表人证件类型    |
| legalCertNo         | String | 法定代表人证件号码    |
| shareholder1-5      | String | 股东信息         |
| dataSource          | String | 数据来源         |
| remark              | String | 备注           |
| createTime          | Date   | 创建时间         |

---

### 4. 新增个人中介

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

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

**请求体**:

```json
{
  "name": "张三",
  "personType": "房产中介",
  "personSubType": "本人",
  "gender": "M",
  "idType": "身份证",
  "personId": "110101199001011234",
  "mobile": "13800138000",
  "wechatNo": "zhangsan_wx",
  "contactAddress": "北京市朝阳区XX路XX号",
  "company": "XX房产中介公司",
  "position": "经纪人",
  "socialCreditCode": "91110000XXXXXXXXXX",
  "relatedNumId": "rel123",
  "relationType": "配偶",
  "remark": "测试数据"
}
```

**字段说明**:

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

**响应示例**:

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

---

### 5. 新增实体中介

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

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

**请求体**:

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

**字段说明**:

| 字段名                 | 类型     | 必填 | 说明                 |
|---------------------|--------|----|--------------------|
| enterpriseName      | String | 是  | 机构名称（1-200字符）      |
| socialCreditCode    | String | 是  | 统一社会信用代码（不超过50字符）  |
| enterpriseType      | String | 否  | 主体类型（枚举值，见下文）      |
| enterpriseNature    | String | 否  | 企业性质（枚举值，见下文）      |
| industryClass       | String | 否  | 行业分类（不超过100字符）     |
| industryName        | String | 否  | 所属行业（不超过100字符）     |
| establishDate       | Date   | 否  | 成立日期（yyyy-MM-dd）   |
| registerAddress     | String | 否  | 注册地址（不超过500字符）     |
| legalRepresentative | String | 否  | 法定代表人（不超过100字符）    |
| legalCertType       | String | 否  | 法定代表人证件类型（枚举值）     |
| legalCertNo         | String | 否  | 法定代表人证件号码（不超过50字符） |
| shareholder1-5      | String | 否  | 股东信息（每个不超过100字符）   |
| remark              | String | 否  | 备注（不超过500字符）       |

**响应示例**:

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

---

### 6. 修改个人中介

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

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

**请求体**:

```json
{
  "bizId": "abc123xyz456",
  "name": "张三",
  "personType": "房产中介",
  "personSubType": "本人",
  "gender": "M",
  "idType": "身份证",
  "personId": "110101199001011234",
  "mobile": "13800138000",
  "wechatNo": "zhangsan_wx",
  "contactAddress": "北京市朝阳区XX路XX号",
  "company": "XX房产中介公司",
  "position": "经纪人",
  "socialCreditCode": "91110000XXXXXXXXXX",
  "relatedNumId": "rel123",
  "relationType": "配偶",
  "remark": "测试数据"
}
```

**字段说明**: 与新增接口相同，但 `bizId` 为必填项。

**响应示例**:

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

---

### 7. 修改实体中介

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

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

**请求体**:

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

**字段说明**: 与新增接口相同。

**响应示例**:

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

---

### 8. 删除中介

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

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

**路径参数**:

| 参数名 | 类型       | 必填 | 说明                                 |
|-----|----------|----|------------------------------------|
| ids | String[] | 是  | ID数组（个人为bizId，实体为socialCreditCode） |

**示例**: `/ccdi/intermediary/abc123,91110000XXXXXXXXXX`

**响应示例**:

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

---

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

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

**权限要求**: 无

**请求参数**:

| 参数名      | 类型     | 必填 | 说明             |
|----------|--------|----|----------------|
| personId | String | 是  | 证件号码           |
| bizId    | String | 否  | 排除的人员ID（修改时使用） |

**响应示例**:

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

**响应说明**: `true` 表示唯一，`false` 表示已存在。

---

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

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

**权限要求**: 无

**请求参数**:

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

**响应示例**:

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

**响应说明**: `true` 表示唯一，`false` 表示已存在。

---

## 枚举接口

### 获取人员类型选项

**接口地址**: `GET /ccdi/enum/indivType`

**权限要求**: 无

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "房产中介", "label": "房产中介" },
    { "value": "贷款中介", "label": "贷款中介" },
    { "value": "职业背债人", "label": "职业背债人" },
    { "value": "担保中介", "label": "担保中介" },
    { "value": "评估中介", "label": "评估中介" }
  ]
}
```

---

### 获取人员子类型选项

**接口地址**: `GET /ccdi/enum/indivSubType`

**权限要求**: 无

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "本人", "label": "本人" },
    { "value": "配偶", "label": "配偶" },
    { "value": "父亲", "label": "父亲" },
    { "value": "母亲", "label": "母亲" },
    { "value": "兄弟", "label": "兄弟" },
    { "value": "姐妹", "label": "姐妹" },
    { "value": "子女", "label": "子女" }
  ]
}
```

---

### 获取性别选项

**接口地址**: `GET /ccdi/enum/gender`

**权限要求**: 无

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "M", "label": "男" },
    { "value": "F", "label": "女" },
    { "value": "O", "label": "其他" }
  ]
}
```

---

### 获取证件类型选项

**接口地址**: `GET /ccdi/enum/certType`

**权限要求**: 无

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "身份证", "label": "身份证" },
    { "value": "护照", "label": "护照" },
    { "value": "港澳通行证", "label": "港澳通行证" },
    { "value": "台湾通行证", "label": "台湾通行证" }
  ]
}
```

---

### 获取关联关系选项

**接口地址**: `GET /ccdi/enum/relationType`

**权限要求**: 无

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "配偶", "label": "配偶" },
    { "value": "父子", "label": "父子" },
    { "value": "母女", "label": "母女" },
    { "value": "兄弟", "label": "兄弟" },
    { "value": "姐妹", "label": "姐妹" },
    { "value": "亲属", "label": "亲属" },
    { "value": "朋友", "label": "朋友" },
    { "value": "同事", "label": "同事" }
  ]
}
```

---

### 获取主体类型选项

**接口地址**: `GET /ccdi/enum/corpType`

**权限要求**: 无

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "有限责任公司", "label": "有限责任公司" },
    { "value": "股份有限公司", "label": "股份有限公司" },
    { "value": "个体工商户", "label": "个体工商户" },
    { "value": "合伙企业", "label": "合伙企业" },
    { "value": "个人独资企业", "label": "个人独资企业" }
  ]
}
```

---

### 获取企业性质选项

**接口地址**: `GET /ccdi/enum/corpNature`

**权限要求**: 无

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "国企", "label": "国企" },
    { "value": "民企", "label": "民企" },
    { "value": "外企", "label": "外企" },
    { "value": "合资", "label": "合资" }
  ]
}
```

---

### 获取数据来源选项

**接口地址**: `GET /ccdi/enum/dataSource`

**权限要求**: 无

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "MANUAL", "label": "手动录入" },
    { "value": "SYSTEM", "label": "系统同步" },
    { "value": "IMPORT", "label": "批量导入" },
    { "value": "API", "label": "接口获取" }
  ]
}
```

---

## 错误码说明

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

## 业务错误信息

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

## 测试账号

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

**获取Token**: 调用 `POST /login/test` 接口获取Token，后续请求在 Header 中添加：

```
Authorization: Bearer {token}
```

## 更新日志

| 版本    | 日期         | 说明                        |
|-------|------------|---------------------------|
| 2.0.0 | 2026-02-05 | 统一字段命名，使用接口枚举，更新文档与实际代码一致 |
| 1.3.0 | 2026-01-29 | 新增接口分离：个人/机构专用新增接口        |
| 1.2.0 | 2026-01-29 | 修改接口分离：个人/机构专用修改接口        |
| 1.1.0 | 2026-01-29 | 添加字典下拉框功能                 |
| 1.0.0 | 2026-01-29 | 初始版本                      |

## 注意事项

1. **中介类型字段**:
    - 个人中介：`intermediaryType = "1"`
    - 实体中介：`intermediaryType = "2"`

2. **枚举值使用**:
    - 所有下拉选项字段应使用枚举接口返回的 `value` 值
    - 不要硬编码或使用字典表的 `dictValue`

3. **数据来源字段**:
    - 手动录入：`MANUAL`
    - 系统同步：`SYSTEM`
    - 批量导入：`IMPORT`
    - 接口获取：`API`

4. **分页排序**:
    - 列表查询默认按 `updateTime` 降序排列
    - 使用 MyBatis Plus 分页插件

5. **ID字段**:
    - 个人中介使用 `bizId` 作为唯一标识
    - 实体中介使用 `socialCreditCode` 作为唯一标识

6. **批量操作**:
    - 删除接口支持同时删除个人和实体中介
    - 根据ID长度自动判断类型（个人ID较长）