635 lines
18 KiB
Markdown
635 lines
18 KiB
Markdown
# 中介黑名单管理 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`
|
|
|
|
### 查询功能增强
|
|
|
|
- 支持按中介类型查询
|
|
- 支持按姓名/机构名称模糊查询
|
|
- 支持按证件号/统一社会信用代码精确查询
|