ccdi/doc/implementation/README-中介黑名单测试部署.md

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

## 文件说明

本目录包含中介黑名单管理模块(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