# 中介黑名单管理模块 - 测试与部署文档

## 文件说明

本目录包含中介黑名单管理模块(v2.0)的测试脚本、API文档、菜单配置和测试报告模板。

```
doc/
├── scripts/
│   ├── test-intermediary-api.sh          # API自动化测试脚本
│   └── cleanup-intermediary-test-data.sh # 测试数据清理脚本
├── api/
│   └── 中介黑名单管理API文档-v2.0.md      # 完整的API接口文档
├── test/
│   └── intermediary-blacklist-test-report.md # 测试报告模板
└── sql/
    └── menu-intermediary.sql             # 菜单配置SQL
```

---

## 快速开始

### 1. 执行菜单SQL

首先在数据库中执行菜单配置SQL,为系统添加中介黑名单管理菜单:

```bash
mysql -u root -p ruoyi < sql/menu-intermediary.sql
```

或者直接在MySQL客户端中执行:

```sql
source D:/ccdi/ccdi/sql/menu-intermediary.sql;
```

执行后,在角色管理中为相应角色分配权限。

### 2. 运行API测试脚本

确保后端服务已启动(http://localhost:8080),然后执行测试脚本:

```bash
cd D:/ccdi/ccdi/doc/scripts
bash test-intermediary-api.sh
```

测试脚本会自动:

- 获取Token
- 测试查询列表
- 测试新增个人中介
- 测试新增实体中介
- 测试查询详情
- 测试修改操作
- 测试唯一性校验
- 测试条件查询

### 3. 清理测试数据

测试完成后,运行清理脚本删除测试数据:

```bash
cd D:/ccdi/ccdi/doc/scripts
bash cleanup-intermediary-test-data.sh
```

### 4. 查看API文档

参考API文档进行接口对接:

- 文件位置: `doc/api/中介黑名单管理API文档-v2.0.md`
- Swagger UI: http://localhost:8080/swagger-ui/index.html

### 5. 填写测试报告

根据测试结果填写测试报告模板:

- 文件位置: `doc/test/intermediary-blacklist-test-report.md`

---

## API接口列表

### 基础路径

`/ccdi/intermediary`

### 主要接口

| 方法     | 路径                           | 说明            | 权限                       |
|--------|------------------------------|---------------|--------------------------|
| GET    | /list                        | 查询中介列表        | ccdi:intermediary:list   |
| GET    | /person/{bizId}              | 查询个人中介详情      | ccdi:intermediary:query  |
| GET    | /entity/{socialCreditCode}   | 查询实体中介详情      | ccdi:intermediary:query  |
| POST   | /person                      | 新增个人中介        | ccdi:intermediary:add    |
| POST   | /entity                      | 新增实体中介        | ccdi:intermediary:add    |
| PUT    | /person                      | 修改个人中介        | ccdi:intermediary:edit   |
| PUT    | /entity                      | 修改实体中介        | ccdi:intermediary:edit   |
| DELETE | /{ids}                       | 删除中介          | ccdi:intermediary:remove |
| GET    | /checkPersonIdUnique         | 校验人员ID唯一性     | 无                        |
| GET    | /checkSocialCreditCodeUnique | 校验统一社会信用代码唯一性 | 无                        |
| POST   | /importPersonTemplate        | 下载个人中介导入模板    | 无                        |
| POST   | /importEntityTemplate        | 下载实体中介导入模板    | 无                        |
| POST   | /importPersonData            | 导入个人中介数据      | ccdi:intermediary:import |
| POST   | /importEntityData            | 导入实体中介数据      | ccdi:intermediary:import |

详细接口说明请参考API文档。

---

## 测试账号

- **用户名**: admin
- **密码**: admin123
- **角色**: 管理员

---

## 菜单权限说明

执行menu-intermediary.sql后,系统会创建以下权限:

| 权限标识                     | 说明     |
|--------------------------|--------|
| ccdi:intermediary:query  | 查询中介详情 |
| ccdi:intermediary:list   | 查询中介列表 |
| ccdi:intermediary:add    | 新增中介   |
| ccdi:intermediary:edit   | 修改中介   |
| ccdi:intermediary:remove | 删除中介   |
| ccdi:intermediary:export | 导出中介数据 |
| ccdi:intermediary:import | 导入中介数据 |

在角色管理中为相应角色分配这些权限。

---

## 数据字典说明

模块使用的数据字典类型:

| 字典类型                   | 字典名称   | 用途            |
|------------------------|--------|---------------|
| ccdi_indiv_gender      | 个人中介性别 | 个人中介模板性别下拉框   |
| ccdi_certificate_type  | 证件类型   | 个人中介模板证件类型下拉框 |
| ccdi_entity_type       | 主体类型   | 机构中介模板主体类型下拉框 |
| ccdi_enterprise_nature | 企业性质   | 机构中介模板企业性质下拉框 |
| ccdi_data_source       | 数据来源   | 数据来源字段映射      |

确保这些字典类型在系统中已配置。

---

## 测试用例统计

本模块共包含44个测试用例,涵盖:

1. **列表查询** (7个用例)
    - 基础列表查询
    - 分页查询
    - 按姓名查询
    - 按证件号查询
    - 按中介类型查询
    - 组合条件查询

2. **个人中介管理** (8个用例)
    - 新增个人中介
    - 字段验证
    - 唯一性校验
    - 修改个人中介
    - 查询详情

3. **实体中介管理** (7个用例)
    - 新增实体中介
    - 字段验证
    - 唯一性校验
    - 修改实体中介
    - 查询详情

4. **唯一性校验** (2个用例)
    - 人员ID唯一性
    - 统一社会信用代码唯一性

5. **删除功能** (3个用例)
    - 删除单条记录
    - 批量删除
    - 删除不存在的记录

6. **导入导出** (11个用例)
    - 模板下载
    - 数据导入
    - 数据导出
    - 异常处理

7. **权限控制** (6个用例)
    - 各功能点的权限验证

---

## 常见问题

### 1. 测试脚本无法执行

**问题**: bash: test-intermediary-api.sh: command not found

**解决**: 使用bash命令执行

```bash
bash test-intermediary-api.sh
```

### 2. jq命令未安装

**问题**: jq: command not found

**解决**: 安装jq命令

```bash
# Ubuntu/Debian
apt-get install jq

# CentOS/RHEL
yum install jq

# Windows (使用Git Bash)
# 下载jq for Windows并添加到PATH
```

### 3. Token获取失败

**问题**: Token获取失败或返回null

**解决**:

- 确保后端服务已启动
- 确认用户名密码正确(admin/admin123)
- 检查/login/test接口是否正常

### 4. 菜单不显示

**问题**: 执行SQL后菜单不显示

**解决**:

- 在角色管理中为当前角色分配权限
- 刷新页面或重新登录
- 检查父级菜单ID(2000)是否存在

### 5. 导入失败

**问题**: 导入数据时报错

**解决**:

- 确认Excel模板格式正确
- 检查必填字段是否为空
- 检查证件号或统一社会信用代码是否重复

---

## 版本历史

| 版本    | 日期         | 说明                                  |
|-------|------------|-------------------------------------|
| 2.0.0 | 2026-02-04 | 重构版本:使用MyBatis Plus,分离DTO/VO,统一业务ID |
| 1.3.0 | 2026-01-29 | 新增接口分离:新增个人/机构专用新增接口                |
| 1.2.0 | 2026-01-29 | 修改接口分离:新增个人/机构专用修改接口                |
| 1.1.0 | 2026-01-29 | 添加字典下拉框功能,分离个人/机构模板                 |
| 1.0.0 | 2026-01-29 | 初始版本,支持个人和机构分类管理                    |

---

## 联系方式

如有问题,请联系开发团队。

---

**最后更新**: 2026-02-04
