wkc/ccdi

Files

wkc e0ce344d09 feat: 完成中介黑名单管理模块测试脚本、API文档、菜单配置和测试报告模板

## 新增文件

### 测试脚本 (Task 11)
- doc/scripts/test-intermediary-api.sh: 完整的API自动化测试脚本
  * 获取Token
  * 测试查询列表(含条件查询)
  * 测试新增个人/实体中介
  * 测试查询详情
  * 测试修改操作
  * 测试唯一性校验
  * 支持彩色输出和错误处理

- doc/scripts/cleanup-intermediary-test-data.sh: 测试数据清理脚本
  * 查询测试数据
  * 删除测试数据
  * 验证删除结果

- doc/scripts/run-test.bat: Windows测试脚本启动器
- doc/scripts/run-cleanup.bat: Windows清理脚本启动器

### API文档 (Task 12)
- doc/api/中介黑名单管理API文档-v2.0.md: 完整的v2.0 API接口文档
  * 14个API接口详细说明
  * 请求参数、响应格式、错误码
  * 字典数据说明
  * 业务错误信息
  * v2.0主要变更说明

### 菜单配置 (Task 13)
- sql/menu-intermediary.sql: 菜单和权限配置SQL
  * 主菜单: 中介黑名单(目录)
  * 子菜单: 中介管理(页面)
  * 按钮权限: 查询、列表、新增、修改、删除、导出、导入
  * 包含详细的注释和使用说明

### 测试报告模板 (Task 14)
- doc/test/intermediary-blacklist-test-report.md: 测试报告模板
  * 44个测试用例(列表查询、个人/实体中介、唯一性校验、删除、导入导出、权限)
  * 测试结果统计表格
  * 缺陷统计表格
  * 测试结论模板
  * 签名确认

### 文档 (Task 10)
- doc/README-中介黑名单测试部署.md: 测试与部署指南
  * 快速开始指南
  * API接口列表
  * 菜单权限说明
  * 数据字典说明
  * 常见问题解答
  * 版本历史

## 功能特性

1. **自动化测试**
   - 支持Linux/Windows环境
   - 完整的API覆盖
   - 彩色输出,易于阅读
   - 错误处理和提示

2. **完整的文档**
   - 详细的API文档
   - 清晰的测试报告模板
   - 便于复现的测试用例

3. **菜单配置**
   - 一键SQL执行
   - 完整的权限体系
   - 支持角色分配

4. **测试支持**
   - 测试数据清理
   - 测试结果验证
   - 批处理支持

## 技术亮点

- 使用jq进行JSON解析
- 支持Token自动获取
- 完整的错误处理
- 跨平台支持(Linux/Windows)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-02-04 19:37:17 +08:00

16 KiB

Raw Blame History

中介黑名单管理 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)

响应示例:

{
  "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

响应示例:

{
  "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	是	统一社会信用代码

响应示例:

{
  "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):

{
  "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字符)

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

5. 新增实体中介

接口地址: POST /ccdi/intermediary/entity

权限要求: ccdi:intermediary:add

请求体 (application/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字符)

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

6. 修改个人中介

接口地址: PUT /ccdi/intermediary/person

权限要求: ccdi:intermediary:edit

请求体 (application/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为必填项

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

7. 修改实体中介

接口地址: PUT /ccdi/intermediary/entity

权限要求: ccdi:intermediary:edit

请求体 (application/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为必填项

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

8. 删除中介

接口地址: DELETE /ccdi/intermediary/{ids}

权限要求: ccdi:intermediary:remove

路径参数:

参数名	类型	必填	说明
ids	String[]	是	业务ID数组(逗号分隔)

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

9. 校验人员ID唯一性

接口地址: GET /ccdi/intermediary/checkPersonIdUnique

权限要求: 无

请求参数:

参数名	类型	必填	说明
personId	String	是	证件号码
bizId	String	否	排除的业务ID(修改时使用)

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": true
}

data字段说明: true=唯一可用, false=已存在

10. 校验统一社会信用代码唯一性

接口地址: GET /ccdi/intermediary/checkSocialCreditCodeUnique

权限要求: 无

请求参数:

参数名	类型	必填	说明
socialCreditCode	String	是	统一社会信用代码
excludeId	String	否	排除的ID(修改时使用)

响应示例:

{
  "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)

响应示例:

{
  "code": 200,
  "msg": "恭喜您,数据已全部导入成功!共10条"
}

14. 导入实体中介数据

接口地址: POST /ccdi/intermediary/importEntityData

权限要求: ccdi:intermediary:import

请求参数 (multipart/form-data):

参数名	类型	必填	说明
file	File	是	Excel文件
updateSupport	Boolean	否	是否更新已存在数据(默认false)

响应示例:

{
  "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

查询功能增强

支持按中介类型查询
支持按姓名/机构名称模糊查询
支持按证件号/统一社会信用代码精确查询

16 KiB Raw Blame History

中介黑名单管理 API 文档 v2.0

概述

API 接口列表

1. 查询中介列表

2. 查询个人中介详情

3. 查询实体中介详情

4. 新增个人中介

5. 新增实体中介

6. 修改个人中介

7. 修改实体中介

8. 删除中介

9. 校验人员ID唯一性

10. 校验统一社会信用代码唯一性

11. 下载个人中介导入模板

12. 下载实体中介导入模板

13. 导入个人中介数据

14. 导入实体中介数据

字典数据说明

错误码说明

业务错误信息

测试账号

更新日志

主要变更说明 (v2.0)

架构变更

接口变更

数据模型变更

查询功能增强

16 KiB

Raw Blame History