wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ac4e02e8c5e615538c2079728be679a2885b7922
ccdi/doc/api/中介黑名单管理API文档.md

583 lines
16 KiB
Markdown
Raw Normal View History

中介类型修改
2026-01-29 13:39:47 +08:00
# 中介黑名单管理 API 文档
## 概述
中介黑名单管理模块提供个人和机构两类中介信息的增删改查、类型化模板下载和批量导入导出功能。
**基础路径**: `/dpc/intermediary`
**权限标识前缀**: `dpc:intermediary`
---
## API 接口列表
### 1. 查询中介黑名单列表
**接口地址**: `GET /dpc/intermediary/list`
**权限要求**: `dpc:intermediary:list`
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | String | 否 | 姓名/机构名称（模糊查询） |
| certificateNo | String | 否 | 证件号/统一社会信用代码（精确查询） |
| intermediaryType | String | 否 | 中介类型（1=个人, 2=机构） |
| status | String | 否 | 状态（0=正常, 1=停用） |
| pageNum | Integer | 否 | 页码（默认1） |
| pageSize | Integer | 否 | 每页数量（默认10） |
**响应示例**:
```json
{
"code": 200,
"msg": "操作成功",
"rows": [
{
"intermediaryId": 1,
"name": "张三",
"certificateNo": "110101199001011234",
"intermediaryType": "1",
"intermediaryTypeName": "个人",
"status": "0",
"statusName": "正常",
"remark": "测试数据",
"createTime": "2026-01-29 10:00:00"
}
],
"total": 1
}
```
**响应字段说明**:
| 字段名 | 类型 | 说明 |
|--------|------|------|
| intermediaryId | Long | 中介ID |
| name | String | 姓名/机构名称 |
| certificateNo | String | 证件号/统一社会信用代码 |
| intermediaryType | String | 中介类型（1=个人, 2=机构） |
| intermediaryTypeName | String | 中介类型名称 |
| status | String | 状态（0=正常, 1=停用） |
| statusName | String | 状态名称 |
| remark | String | 备注 |
| createTime | Date | 创建时间 |
---
### 2. 获取中介黑名单详细信息
**接口地址**: `GET /dpc/intermediary/{intermediaryId}`
**权限要求**: `dpc:intermediary:query`
**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| intermediaryId | Long | 是 | 中介ID |
**功能说明**: 根据中介类型返回不同的详情结构
**个人类型响应示例**:
```json
{
"code": 200,
"msg": "操作成功",
"data": {
"intermediaryId": 1,
"name": "张三",
"certificateNo": "110101199001011234",
"intermediaryType": "1",
"intermediaryTypeName": "个人",
"status": "0",
"statusName": "正常",
"dataSource": "IMPORT",
"dataSourceName": "批量导入",
"indivType": "中介",
"indivGender": "M",
"indivGenderName": "男",
"indivCertType": "身份证",
"indivPhone": "13800138000",
"indivCompany": "XX公司",
"indivPosition": "经纪人"
}
}
```
**机构类型响应示例**:
```json
{
"code": 200,
"msg": "操作成功",
"data": {
"intermediaryId": 2,
"name": "XX中介公司",
"intermediaryType": "2",
"intermediaryTypeName": "机构",
"status": "0",
"statusName": "正常",
"dataSource": "MANUAL",
"dataSourceName": "手动录入",
"corpCreditCode": "91110000XXXXXXXXXX",
"corpType": "有限责任公司",
"corpNature": "民企",
"corpLegalRep": "张三",
"corpAddress": "北京市朝阳区"
}
}
```
---
### 3. 新增中介黑名单
中介新增 修改接口
2026-01-29 22:03:42 +08:00
#### 3.1 新增个人中介黑名单
**接口地址**: `POST /dpc/intermediary/person`
中介类型修改
2026-01-29 13:39:47 +08:00
**权限要求**: `dpc:intermediary:add`
**请求体**:
```json
{
"name": "张三",
"certificateNo": "110101199001011234",
中介新增 修改接口
2026-01-29 22:03:42 +08:00
"indivType": "中介",
"indivSubType": "本人",
"indivGender": "M",
"indivCertType": "身份证",
"indivPhone": "13800138000",
"indivWechat": "zhangsan",
"indivAddress": "北京市朝阳区",
"indivCompany": "XX公司",
"indivPosition": "经纪人",
中介类型修改
2026-01-29 13:39:47 +08:00
"status": "0",
"remark": "测试数据"
}
```
**字段说明**:
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
中介新增 修改接口
2026-01-29 22:03:42 +08:00
| name | String | 是 | 姓名 |
| certificateNo | String | 是 | 证件号 |
| indivType | String | 否 | 人员类型 |
| indivSubType | String | 否 | 人员子类型 |
| indivGender | String | 否 | 性别（M男 F女 O其他） |
| indivCertType | String | 否 | 证件类型 |
| indivPhone | String | 否 | 手机号码 |
| indivWechat | String | 否 | 微信号 |
| indivAddress | String | 否 | 联系地址 |
| indivCompany | String | 否 | 所在公司 |
| indivPosition | String | 否 | 职位/职务 |
| indivRelatedId | String | 否 | 关联人员ID |
| indivRelation | String | 否 | 关联关系 |
中介类型修改
2026-01-29 13:39:47 +08:00
| status | String | 是 | 状态（0=正常, 1=停用） |
| remark | String | 否 | 备注 |
**响应示例**:
```json
{
"code": 200,
"msg": "操作成功"
}
```
中介新增 修改接口
2026-01-29 22:03:42 +08:00
#### 3.2 新增机构中介黑名单
**接口地址**: `POST /dpc/intermediary/entity`
**权限要求**: `dpc:intermediary:add`
**请求体**:
```json
{
"name": "XX中介公司",
"corpCreditCode": "91110000XXXXXXXXXX",
"corpType": "有限责任公司",
"corpNature": "民企",
"corpIndustryCategory": "房地产",
"corpIndustry": "房地产业",
"corpEstablishDate": "2020-01-01",
"corpAddress": "北京市朝阳区",
"corpLegalRep": "张三",
"corpLegalCertType": "身份证",
"corpLegalCertNo": "110101199001011234",
"corpShareholder1": "李四",
"corpShareholder2": "王五",
"status": "0",
"remark": "测试数据"
}
```
**字段说明**:
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | String | 是 | 机构名称 |
| corpCreditCode | String | 是 | 统一社会信用代码 |
| corpType | String | 否 | 主体类型 |
| corpNature | String | 否 | 企业性质 |
| corpIndustryCategory | String | 否 | 行业分类 |
| corpIndustry | String | 否 | 所属行业 |
| corpEstablishDate | Date | 否 | 成立日期 |
| corpAddress | String | 否 | 注册地址 |
| corpLegalRep | String | 否 | 法定代表人 |
| corpLegalCertType | String | 否 | 法定代表人证件类型 |
| corpLegalCertNo | String | 否 | 法定代表人证件号码 |
| corpShareholder1-5 | String | 否 | 股东信息 |
| status | String | 是 | 状态（0=正常, 1=停用） |
| remark | String | 否 | 备注 |
**响应示例**:
```json
{
"code": 200,
"msg": "操作成功"
}
```
**注意**:
- 中介类型由系统自动设置，无需手动传递
- 新增个人中介时，机构专属字段会被自动忽略
- 新增机构中介时，证件号自动使用统一社会信用代码
中介类型修改
2026-01-29 13:39:47 +08:00
---
### 4. 修改中介黑名单
中介新增 修改接口
2026-01-29 22:03:42 +08:00
#### 4.1 修改个人中介黑名单
**接口地址**: `PUT /dpc/intermediary/person`
中介类型修改
2026-01-29 13:39:47 +08:00
**权限要求**: `dpc:intermediary:edit`
**请求体**:
```json
{
"intermediaryId": 1,
"name": "张三",
"certificateNo": "110101199001011234",
中介新增 修改接口
2026-01-29 22:03:42 +08:00
"indivType": "中介",
"indivSubType": "本人",
"indivGender": "M",
"indivCertType": "身份证",
"indivPhone": "13800138000",
"indivWechat": "zhangsan",
"indivAddress": "北京市朝阳区",
"indivCompany": "XX公司",
"indivPosition": "经纪人",
"indivRelatedId": null,
"indivRelation": null,
"status": "0",
"remark": "测试数据"
}
```
**字段说明**:
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| intermediaryId | Long | 是 | 中介ID |
| name | String | 是 | 姓名 |
| certificateNo | String | 否 | 证件号 |
| indivType | String | 否 | 人员类型 |
| indivSubType | String | 否 | 人员子类型 |
| indivGender | String | 否 | 性别（M男 F女 O其他） |
| indivCertType | String | 否 | 证件类型 |
| indivPhone | String | 否 | 手机号码 |
| indivWechat | String | 否 | 微信号 |
| indivAddress | String | 否 | 联系地址 |
| indivCompany | String | 否 | 所在公司 |
| indivPosition | String | 否 | 职位/职务 |
| indivRelatedId | String | 否 | 关联人员ID |
| indivRelation | String | 否 | 关联关系 |
| status | String | 是 | 状态（0=正常, 1=停用） |
| remark | String | 否 | 备注 |
**响应示例**:
```json
{
"code": 200,
"msg": "操作成功"
}
```
#### 4.2 修改机构中介黑名单
**接口地址**: `PUT /dpc/intermediary/entity`
**权限要求**: `dpc:intermediary:edit`
**请求体**:
```json
{
"intermediaryId": 2,
"name": "XX中介公司",
"certificateNo": "91110000XXXXXXXXXX",
"corpCreditCode": "91110000XXXXXXXXXX",
"corpType": "有限责任公司",
"corpNature": "民企",
"corpIndustryCategory": "房地产",
"corpIndustry": "房地产业",
"corpEstablishDate": "2020-01-01",
"corpAddress": "北京市朝阳区",
"corpLegalRep": "张三",
"corpLegalCertType": "身份证",
"corpLegalCertNo": "110101199001011234",
"corpShareholder1": "李四",
"corpShareholder2": "王五",
"corpShareholder3": null,
"corpShareholder4": null,
"corpShareholder5": null,
中介类型修改
2026-01-29 13:39:47 +08:00
"status": "0",
"remark": "测试数据"
}
```
中介新增 修改接口
2026-01-29 22:03:42 +08:00
**字段说明**:
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| intermediaryId | Long | 是 | 中介ID |
| name | String | 是 | 机构名称 |
| certificateNo | String | 否 | 证件号（统一社会信用代码） |
| corpCreditCode | String | 否 | 统一社会信用代码 |
| corpType | String | 否 | 主体类型 |
| corpNature | String | 否 | 企业性质 |
| corpIndustryCategory | String | 否 | 行业分类 |
| corpIndustry | String | 否 | 所属行业 |
| corpEstablishDate | Date | 否 | 成立日期 |
| corpAddress | String | 否 | 注册地址 |
| corpLegalRep | String | 否 | 法定代表人 |
| corpLegalCertType | String | 否 | 法定代表人证件类型 |
| corpLegalCertNo | String | 否 | 法定代表人证件号码 |
| corpShareholder1-5 | String | 否 | 股东信息 |
| status | String | 是 | 状态（0=正常, 1=停用） |
| remark | String | 否 | 备注 |
中介类型修改
2026-01-29 13:39:47 +08:00
**响应示例**:
```json
{
"code": 200,
"msg": "操作成功"
}
```
中介新增 修改接口
2026-01-29 22:03:42 +08:00
**注意**:
- 中介类型（intermediaryType）不允许修改，系统会自动根据接口设置正确的类型
- 使用个人中介接口时，机构专属字段会被自动清空
- 使用机构中介接口时，个人专属字段会被自动清空
中介类型修改
2026-01-29 13:39:47 +08:00
---
### 5. 删除中介黑名单
**接口地址**: `DELETE /dpc/intermediary/{intermediaryIds}`
**权限要求**: `dpc:intermediary:remove`
**路径参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| intermediaryIds | Long[] | 是 | 中介ID数组（逗号分隔） |
**响应示例**:
```json
{
"code": 200,
"msg": "操作成功"
}
```
---
### 6. 导出中介黑名单
**接口地址**: `POST /dpc/intermediary/export`
**权限要求**: `dpc:intermediary:export`
**请求参数**: 与查询列表接口相同（支持筛选条件）
**响应**: Excel 文件下载
---
### 7. 下载个人中介导入模板（带字典下拉框）
**接口地址**: `POST /dpc/intermediary/importPersonTemplate`
**权限要求**: 无
**功能说明**: 下载的 Excel 模板中，性别、证件类型列会自动添加字典下拉框。
**响应**: Excel 模板文件下载
**Excel 格式说明**:
**Sheet1: 个人中介黑名单**
| 姓名 | 人员类型 | 人员子类型 | 性别▼ | 证件类型▼ | 证件号码 | 手机号码 | 微信号 | 联系地址 | 所在公司 | 职位 | 关联人员ID | 关联关系 | 备注 |
|------|---------|-----------|-------|-----------|---------|---------|--------|---------|---------|-----|-----------|---------|------|
| 张三 | 中介 | 本人 | 男 | 身份证 | 110101199001011234 | 13800138000 | zhangsan | 北京市朝阳区 | XX公司 | 经纪人 | - | - | 测试 |
**注**：带 ▼ 标记的列包含下拉框，选项来自字典：
- 性别：`dpc_indiv_gender`
- 证件类型：`dpc_certificate_type`
---
### 8. 下载机构中介导入模板（带字典下拉框）
**接口地址**: `POST /dpc/intermediary/importEntityTemplate`
**权限要求**: 无
**功能说明**: 下载的 Excel 模板中，主体类型、企业性质列会自动添加字典下拉框。
**响应**: Excel 模板文件下载
**Excel 格式说明**:
**Sheet1: 机构中介黑名单**
| 机构名称 | 统一社会信用代码 | 主体类型▼ | 企业性质▼ | 行业分类 | 所属行业 | 成立日期 | 注册地址 | 法定代表人 | 法定代表人证件类型 | 法定代表人证件号码 | 股东1 | 股东2 | 股东3 | 股东4 | 股东5 | 备注 |
|---------|-----------------|-----------|-----------|---------|---------|---------|---------|-----------|-------------------|-------------------|-------|-------|-------|-------|-------|------|
| XX公司 | 91110000XXXXXXXXXX | 有限责任公司 | 民企 | 房地产 | 房地产业 | 2020-01-01 | 北京市朝阳区 | 张三 | 身份证 | 110101199001011234 | 李四 | 王五 | - | - | - | - |
**注**：带 ▼ 标记的列包含下拉框，选项来自字典：
- 主体类型：`dpc_entity_type`
- 企业性质：`dpc_enterprise_nature`
---
### 9. 导入个人中介黑名单
**接口地址**: `POST /dpc/intermediary/importPersonData`
**权限要求**: `dpc:intermediary:import`
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| file | File | 是 | Excel 文件 |
| updateSupport | Boolean | 否 | 是否更新已存在数据（默认false） |
**Excel 格式**: 参见"下载个人中介导入模板"
**数据验证规则**:
1. **姓名**：必填，长度 1-100 字符
2. **证件号码**：必填，长度不超过 50 字符
3. **证件类型**：选填，默认"身份证"
4. **其他字段**：选填，按长度限制验证
5. **状态**：系统默认设置为"正常"（0）
6. **数据来源**：系统默认设置为"批量导入"（IMPORT）
**响应示例**:
```json
{
"code": 200,
"msg": "恭喜您，数据已全部导入成功！共 10 条"
}
```
---
### 10. 导入机构中介黑名单
**接口地址**: `POST /dpc/intermediary/importEntityData`
**权限要求**: `dpc:intermediary:import`
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| file | File | 是 | Excel 文件 |
| updateSupport | Boolean | 否 | 是否更新已存在数据（默认false） |
**Excel 格式**: 参见"下载机构中介导入模板"
**数据验证规则**:
1. **机构名称**：必填，长度 1-200 字符
2. **统一社会信用代码**：选填，18 位
3. **其他字段**：选填，按长度限制验证
4. **状态**：系统默认设置为"正常"（0）
5. **数据来源**：系统默认设置为"批量导入"（IMPORT）
**响应示例**:
```json
{
"code": 200,
"msg": "恭喜您，数据已全部导入成功！共 10 条"
}
```
---
## 字典数据说明
导入模板中的下拉框选项来自系统字典管理，相关字典类型：
### 个人中介字典
| 字典类型 | 字典名称 | 用途 |
|---------|---------|------|
| dpc_indiv_gender | 个人中介性别 | 个人中介模板性别下拉框 |
| dpc_certificate_type | 证件类型 | 个人中介模板证件类型下拉框 |
### 机构中介字典
| 字典类型 | 字典名称 | 用途 |
|---------|---------|------|
| dpc_entity_type | 主体类型 | 机构中介模板主体类型下拉框 |
| dpc_enterprise_nature | 企业性质 | 机构中介模板企业性质下拉框 |
### 通用字典
| 字典类型 | 字典名称 | 用途 |
|---------|---------|------|
| dpc_data_source | 数据来源 | 数据来源字段映射 |
---
## 错误码说明
| 错误码 | 说明 |
|--------|------|
| 200 | 操作成功 |
| 401 | 未授权，请先登录 |
| 403 | 无权限访问 |
| 500 | 服务器内部错误 |
## 业务错误信息
| 错误信息 | 说明 |
|----------|------|
| 姓名不能为空 | 个人中介导入时姓名为空 |
| 机构名称不能为空 | 机构中介导入时机构名称为空 |
| 证件号码不能为空 | 个人中介导入时证件号码为空 |
| 该证件号已存在 | 新增/导入时证件号重复 |
| 该统一社会信用代码已存在 | 新增/导入时信用代码重复 |
## 测试账号
- 用户名: `admin`
- 密码: `admin123`
测试前请先调用 `/login/test` 接口获取 Token。
## 更新日志
| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2026-01-29 | 初始版本，支持个人和机构分类管理 |
| 1.1.0 | 2026-01-29 | 添加字典下拉框功能，分离个人/机构模板 |
中介新增 修改接口
2026-01-29 22:03:42 +08:00
| 1.2.0 | 2026-01-29 | 修改接口分离：新增个人/机构专用修改接口，修复中介类型修改问题 |
| 1.3.0 | 2026-01-29 | 新增接口分离：新增个人/机构专用新增接口，统一接口设计 |
Reference in New Issue Copy Permalink