ccdi/doc/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较长）