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