wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

修改目录

Browse Source
This commit is contained in:
wkc
2026-03-03 16:14:16 +08:00
parent c8b041f4b9
commit 521bb80b2f
438 changed files with 15313 additions and 21773 deletions
Download Patch File Download Diff File Expand all files Collapse all files

634
assets/api-docs/api/中介黑名单管理API文档-v2.0.md Normal file
View File

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