中介新增 修改接口
This commit is contained in:
582
doc/api/中介黑名单管理API文档.md
Normal file
582
doc/api/中介黑名单管理API文档.md
Normal file
@@ -0,0 +1,582 @@
|
||||
# 中介黑名单管理 API 文档
|
||||
|
||||
## 概述
|
||||
|
||||
中介黑名单管理模块提供个人和机构两类中介信息的增删改查、类型化模板下载和批量导入导出功能。
|
||||
|
||||
**基础路径**: `/dpc/intermediary`
|
||||
|
||||
**权限标识前缀**: `dpc:intermediary`
|
||||
|
||||
---
|
||||
|
||||
## API 接口列表
|
||||
|
||||
### 1. 查询中介黑名单列表
|
||||
|
||||
**接口地址**: `GET /dpc/intermediary/list`
|
||||
|
||||
**权限要求**: `dpc:intermediary:list`
|
||||
|
||||
**请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| name | String | 否 | 姓名/机构名称（模糊查询） |
|
||||
| certificateNo | String | 否 | 证件号/统一社会信用代码（精确查询） |
|
||||
| intermediaryType | String | 否 | 中介类型（1=个人, 2=机构） |
|
||||
| status | String | 否 | 状态（0=正常, 1=停用） |
|
||||
| pageNum | Integer | 否 | 页码（默认1） |
|
||||
| pageSize | Integer | 否 | 每页数量（默认10） |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"rows": [
|
||||
{
|
||||
"intermediaryId": 1,
|
||||
"name": "张三",
|
||||
"certificateNo": "110101199001011234",
|
||||
"intermediaryType": "1",
|
||||
"intermediaryTypeName": "个人",
|
||||
"status": "0",
|
||||
"statusName": "正常",
|
||||
"remark": "测试数据",
|
||||
"createTime": "2026-01-29 10:00:00"
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
**响应字段说明**:
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| intermediaryId | Long | 中介ID |
|
||||
| name | String | 姓名/机构名称 |
|
||||
| certificateNo | String | 证件号/统一社会信用代码 |
|
||||
| intermediaryType | String | 中介类型（1=个人, 2=机构） |
|
||||
| intermediaryTypeName | String | 中介类型名称 |
|
||||
| status | String | 状态（0=正常, 1=停用） |
|
||||
| statusName | String | 状态名称 |
|
||||
| remark | String | 备注 |
|
||||
| createTime | Date | 创建时间 |
|
||||
|
||||
---
|
||||
|
||||
### 2. 获取中介黑名单详细信息
|
||||
|
||||
**接口地址**: `GET /dpc/intermediary/{intermediaryId}`
|
||||
|
||||
**权限要求**: `dpc:intermediary:query`
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| intermediaryId | Long | 是 | 中介ID |
|
||||
|
||||
**功能说明**: 根据中介类型返回不同的详情结构
|
||||
|
||||
**个人类型响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"intermediaryId": 1,
|
||||
"name": "张三",
|
||||
"certificateNo": "110101199001011234",
|
||||
"intermediaryType": "1",
|
||||
"intermediaryTypeName": "个人",
|
||||
"status": "0",
|
||||
"statusName": "正常",
|
||||
"dataSource": "IMPORT",
|
||||
"dataSourceName": "批量导入",
|
||||
"indivType": "中介",
|
||||
"indivGender": "M",
|
||||
"indivGenderName": "男",
|
||||
"indivCertType": "身份证",
|
||||
"indivPhone": "13800138000",
|
||||
"indivCompany": "XX公司",
|
||||
"indivPosition": "经纪人"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**机构类型响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"intermediaryId": 2,
|
||||
"name": "XX中介公司",
|
||||
"intermediaryType": "2",
|
||||
"intermediaryTypeName": "机构",
|
||||
"status": "0",
|
||||
"statusName": "正常",
|
||||
"dataSource": "MANUAL",
|
||||
"dataSourceName": "手动录入",
|
||||
"corpCreditCode": "91110000XXXXXXXXXX",
|
||||
"corpType": "有限责任公司",
|
||||
"corpNature": "民企",
|
||||
"corpLegalRep": "张三",
|
||||
"corpAddress": "北京市朝阳区"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 新增中介黑名单
|
||||
|
||||
#### 3.1 新增个人中介黑名单
|
||||
|
||||
**接口地址**: `POST /dpc/intermediary/person`
|
||||
|
||||
**权限要求**: `dpc:intermediary:add`
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"name": "张三",
|
||||
"certificateNo": "110101199001011234",
|
||||
"indivType": "中介",
|
||||
"indivSubType": "本人",
|
||||
"indivGender": "M",
|
||||
"indivCertType": "身份证",
|
||||
"indivPhone": "13800138000",
|
||||
"indivWechat": "zhangsan",
|
||||
"indivAddress": "北京市朝阳区",
|
||||
"indivCompany": "XX公司",
|
||||
"indivPosition": "经纪人",
|
||||
"status": "0",
|
||||
"remark": "测试数据"
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| name | String | 是 | 姓名 |
|
||||
| certificateNo | String | 是 | 证件号 |
|
||||
| indivType | String | 否 | 人员类型 |
|
||||
| indivSubType | String | 否 | 人员子类型 |
|
||||
| indivGender | String | 否 | 性别（M男 F女 O其他） |
|
||||
| indivCertType | String | 否 | 证件类型 |
|
||||
| indivPhone | String | 否 | 手机号码 |
|
||||
| indivWechat | String | 否 | 微信号 |
|
||||
| indivAddress | String | 否 | 联系地址 |
|
||||
| indivCompany | String | 否 | 所在公司 |
|
||||
| indivPosition | String | 否 | 职位/职务 |
|
||||
| indivRelatedId | String | 否 | 关联人员ID |
|
||||
| indivRelation | String | 否 | 关联关系 |
|
||||
| status | String | 是 | 状态（0=正常, 1=停用） |
|
||||
| remark | String | 否 | 备注 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2 新增机构中介黑名单
|
||||
|
||||
**接口地址**: `POST /dpc/intermediary/entity`
|
||||
|
||||
**权限要求**: `dpc:intermediary:add`
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"name": "XX中介公司",
|
||||
"corpCreditCode": "91110000XXXXXXXXXX",
|
||||
"corpType": "有限责任公司",
|
||||
"corpNature": "民企",
|
||||
"corpIndustryCategory": "房地产",
|
||||
"corpIndustry": "房地产业",
|
||||
"corpEstablishDate": "2020-01-01",
|
||||
"corpAddress": "北京市朝阳区",
|
||||
"corpLegalRep": "张三",
|
||||
"corpLegalCertType": "身份证",
|
||||
"corpLegalCertNo": "110101199001011234",
|
||||
"corpShareholder1": "李四",
|
||||
"corpShareholder2": "王五",
|
||||
"status": "0",
|
||||
"remark": "测试数据"
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| name | String | 是 | 机构名称 |
|
||||
| corpCreditCode | String | 是 | 统一社会信用代码 |
|
||||
| corpType | String | 否 | 主体类型 |
|
||||
| corpNature | String | 否 | 企业性质 |
|
||||
| corpIndustryCategory | String | 否 | 行业分类 |
|
||||
| corpIndustry | String | 否 | 所属行业 |
|
||||
| corpEstablishDate | Date | 否 | 成立日期 |
|
||||
| corpAddress | String | 否 | 注册地址 |
|
||||
| corpLegalRep | String | 否 | 法定代表人 |
|
||||
| corpLegalCertType | String | 否 | 法定代表人证件类型 |
|
||||
| corpLegalCertNo | String | 否 | 法定代表人证件号码 |
|
||||
| corpShareholder1-5 | String | 否 | 股东信息 |
|
||||
| status | String | 是 | 状态（0=正常, 1=停用） |
|
||||
| remark | String | 否 | 备注 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 中介类型由系统自动设置，无需手动传递
|
||||
- 新增个人中介时，机构专属字段会被自动忽略
|
||||
- 新增机构中介时，证件号自动使用统一社会信用代码
|
||||
|
||||
---
|
||||
|
||||
### 4. 修改中介黑名单
|
||||
|
||||
#### 4.1 修改个人中介黑名单
|
||||
|
||||
**接口地址**: `PUT /dpc/intermediary/person`
|
||||
|
||||
**权限要求**: `dpc:intermediary:edit`
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"intermediaryId": 1,
|
||||
"name": "张三",
|
||||
"certificateNo": "110101199001011234",
|
||||
"indivType": "中介",
|
||||
"indivSubType": "本人",
|
||||
"indivGender": "M",
|
||||
"indivCertType": "身份证",
|
||||
"indivPhone": "13800138000",
|
||||
"indivWechat": "zhangsan",
|
||||
"indivAddress": "北京市朝阳区",
|
||||
"indivCompany": "XX公司",
|
||||
"indivPosition": "经纪人",
|
||||
"indivRelatedId": null,
|
||||
"indivRelation": null,
|
||||
"status": "0",
|
||||
"remark": "测试数据"
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| intermediaryId | Long | 是 | 中介ID |
|
||||
| name | String | 是 | 姓名 |
|
||||
| certificateNo | String | 否 | 证件号 |
|
||||
| indivType | String | 否 | 人员类型 |
|
||||
| indivSubType | String | 否 | 人员子类型 |
|
||||
| indivGender | String | 否 | 性别（M男 F女 O其他） |
|
||||
| indivCertType | String | 否 | 证件类型 |
|
||||
| indivPhone | String | 否 | 手机号码 |
|
||||
| indivWechat | String | 否 | 微信号 |
|
||||
| indivAddress | String | 否 | 联系地址 |
|
||||
| indivCompany | String | 否 | 所在公司 |
|
||||
| indivPosition | String | 否 | 职位/职务 |
|
||||
| indivRelatedId | String | 否 | 关联人员ID |
|
||||
| indivRelation | String | 否 | 关联关系 |
|
||||
| status | String | 是 | 状态（0=正常, 1=停用） |
|
||||
| remark | String | 否 | 备注 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
#### 4.2 修改机构中介黑名单
|
||||
|
||||
**接口地址**: `PUT /dpc/intermediary/entity`
|
||||
|
||||
**权限要求**: `dpc:intermediary:edit`
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"intermediaryId": 2,
|
||||
"name": "XX中介公司",
|
||||
"certificateNo": "91110000XXXXXXXXXX",
|
||||
"corpCreditCode": "91110000XXXXXXXXXX",
|
||||
"corpType": "有限责任公司",
|
||||
"corpNature": "民企",
|
||||
"corpIndustryCategory": "房地产",
|
||||
"corpIndustry": "房地产业",
|
||||
"corpEstablishDate": "2020-01-01",
|
||||
"corpAddress": "北京市朝阳区",
|
||||
"corpLegalRep": "张三",
|
||||
"corpLegalCertType": "身份证",
|
||||
"corpLegalCertNo": "110101199001011234",
|
||||
"corpShareholder1": "李四",
|
||||
"corpShareholder2": "王五",
|
||||
"corpShareholder3": null,
|
||||
"corpShareholder4": null,
|
||||
"corpShareholder5": null,
|
||||
"status": "0",
|
||||
"remark": "测试数据"
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| intermediaryId | Long | 是 | 中介ID |
|
||||
| name | String | 是 | 机构名称 |
|
||||
| certificateNo | String | 否 | 证件号（统一社会信用代码） |
|
||||
| corpCreditCode | String | 否 | 统一社会信用代码 |
|
||||
| corpType | String | 否 | 主体类型 |
|
||||
| corpNature | String | 否 | 企业性质 |
|
||||
| corpIndustryCategory | String | 否 | 行业分类 |
|
||||
| corpIndustry | String | 否 | 所属行业 |
|
||||
| corpEstablishDate | Date | 否 | 成立日期 |
|
||||
| corpAddress | String | 否 | 注册地址 |
|
||||
| corpLegalRep | String | 否 | 法定代表人 |
|
||||
| corpLegalCertType | String | 否 | 法定代表人证件类型 |
|
||||
| corpLegalCertNo | String | 否 | 法定代表人证件号码 |
|
||||
| corpShareholder1-5 | String | 否 | 股东信息 |
|
||||
| status | String | 是 | 状态（0=正常, 1=停用） |
|
||||
| remark | String | 否 | 备注 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 中介类型（intermediaryType）不允许修改，系统会自动根据接口设置正确的类型
|
||||
- 使用个人中介接口时，机构专属字段会被自动清空
|
||||
- 使用机构中介接口时，个人专属字段会被自动清空
|
||||
|
||||
---
|
||||
|
||||
### 5. 删除中介黑名单
|
||||
|
||||
**接口地址**: `DELETE /dpc/intermediary/{intermediaryIds}`
|
||||
|
||||
**权限要求**: `dpc:intermediary:remove`
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| intermediaryIds | Long[] | 是 | 中介ID数组（逗号分隔） |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. 导出中介黑名单
|
||||
|
||||
**接口地址**: `POST /dpc/intermediary/export`
|
||||
|
||||
**权限要求**: `dpc:intermediary:export`
|
||||
|
||||
**请求参数**: 与查询列表接口相同（支持筛选条件）
|
||||
|
||||
**响应**: Excel 文件下载
|
||||
|
||||
---
|
||||
|
||||
### 7. 下载个人中介导入模板（带字典下拉框）
|
||||
|
||||
**接口地址**: `POST /dpc/intermediary/importPersonTemplate`
|
||||
|
||||
**权限要求**: 无
|
||||
|
||||
**功能说明**: 下载的 Excel 模板中，性别、证件类型列会自动添加字典下拉框。
|
||||
|
||||
**响应**: Excel 模板文件下载
|
||||
|
||||
**Excel 格式说明**:
|
||||
|
||||
**Sheet1: 个人中介黑名单**
|
||||
| 姓名 | 人员类型 | 人员子类型 | 性别▼ | 证件类型▼ | 证件号码 | 手机号码 | 微信号 | 联系地址 | 所在公司 | 职位 | 关联人员ID | 关联关系 | 备注 |
|
||||
|------|---------|-----------|-------|-----------|---------|---------|--------|---------|---------|-----|-----------|---------|------|
|
||||
| 张三 | 中介 | 本人 | 男 | 身份证 | 110101199001011234 | 13800138000 | zhangsan | 北京市朝阳区 | XX公司 | 经纪人 | - | - | 测试 |
|
||||
|
||||
**注**：带 ▼ 标记的列包含下拉框，选项来自字典：
|
||||
- 性别：`dpc_indiv_gender`
|
||||
- 证件类型：`dpc_certificate_type`
|
||||
|
||||
---
|
||||
|
||||
### 8. 下载机构中介导入模板（带字典下拉框）
|
||||
|
||||
**接口地址**: `POST /dpc/intermediary/importEntityTemplate`
|
||||
|
||||
**权限要求**: 无
|
||||
|
||||
**功能说明**: 下载的 Excel 模板中，主体类型、企业性质列会自动添加字典下拉框。
|
||||
|
||||
**响应**: Excel 模板文件下载
|
||||
|
||||
**Excel 格式说明**:
|
||||
|
||||
**Sheet1: 机构中介黑名单**
|
||||
| 机构名称 | 统一社会信用代码 | 主体类型▼ | 企业性质▼ | 行业分类 | 所属行业 | 成立日期 | 注册地址 | 法定代表人 | 法定代表人证件类型 | 法定代表人证件号码 | 股东1 | 股东2 | 股东3 | 股东4 | 股东5 | 备注 |
|
||||
|---------|-----------------|-----------|-----------|---------|---------|---------|---------|-----------|-------------------|-------------------|-------|-------|-------|-------|-------|------|
|
||||
| XX公司 | 91110000XXXXXXXXXX | 有限责任公司 | 民企 | 房地产 | 房地产业 | 2020-01-01 | 北京市朝阳区 | 张三 | 身份证 | 110101199001011234 | 李四 | 王五 | - | - | - | - |
|
||||
|
||||
**注**：带 ▼ 标记的列包含下拉框，选项来自字典：
|
||||
- 主体类型：`dpc_entity_type`
|
||||
- 企业性质：`dpc_enterprise_nature`
|
||||
|
||||
---
|
||||
|
||||
### 9. 导入个人中介黑名单
|
||||
|
||||
**接口地址**: `POST /dpc/intermediary/importPersonData`
|
||||
|
||||
**权限要求**: `dpc:intermediary:import`
|
||||
|
||||
**请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| file | File | 是 | Excel 文件 |
|
||||
| updateSupport | Boolean | 否 | 是否更新已存在数据（默认false） |
|
||||
|
||||
**Excel 格式**: 参见"下载个人中介导入模板"
|
||||
|
||||
**数据验证规则**:
|
||||
1. **姓名**：必填，长度 1-100 字符
|
||||
2. **证件号码**：必填，长度不超过 50 字符
|
||||
3. **证件类型**：选填，默认"身份证"
|
||||
4. **其他字段**：选填，按长度限制验证
|
||||
5. **状态**：系统默认设置为"正常"（0）
|
||||
6. **数据来源**：系统默认设置为"批量导入"（IMPORT）
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "恭喜您，数据已全部导入成功！共 10 条"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10. 导入机构中介黑名单
|
||||
|
||||
**接口地址**: `POST /dpc/intermediary/importEntityData`
|
||||
|
||||
**权限要求**: `dpc:intermediary:import`
|
||||
|
||||
**请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| file | File | 是 | Excel 文件 |
|
||||
| updateSupport | Boolean | 否 | 是否更新已存在数据（默认false） |
|
||||
|
||||
**Excel 格式**: 参见"下载机构中介导入模板"
|
||||
|
||||
**数据验证规则**:
|
||||
1. **机构名称**：必填，长度 1-200 字符
|
||||
2. **统一社会信用代码**：选填，18 位
|
||||
3. **其他字段**：选填，按长度限制验证
|
||||
4. **状态**：系统默认设置为"正常"（0）
|
||||
5. **数据来源**：系统默认设置为"批量导入"（IMPORT）
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "恭喜您，数据已全部导入成功！共 10 条"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 字典数据说明
|
||||
|
||||
导入模板中的下拉框选项来自系统字典管理，相关字典类型：
|
||||
|
||||
### 个人中介字典
|
||||
|
||||
| 字典类型 | 字典名称 | 用途 |
|
||||
|---------|---------|------|
|
||||
| dpc_indiv_gender | 个人中介性别 | 个人中介模板性别下拉框 |
|
||||
| dpc_certificate_type | 证件类型 | 个人中介模板证件类型下拉框 |
|
||||
|
||||
### 机构中介字典
|
||||
|
||||
| 字典类型 | 字典名称 | 用途 |
|
||||
|---------|---------|------|
|
||||
| dpc_entity_type | 主体类型 | 机构中介模板主体类型下拉框 |
|
||||
| dpc_enterprise_nature | 企业性质 | 机构中介模板企业性质下拉框 |
|
||||
|
||||
### 通用字典
|
||||
|
||||
| 字典类型 | 字典名称 | 用途 |
|
||||
|---------|---------|------|
|
||||
| dpc_data_source | 数据来源 | 数据来源字段映射 |
|
||||
|
||||
---
|
||||
|
||||
## 错误码说明
|
||||
|
||||
| 错误码 | 说明 |
|
||||
|--------|------|
|
||||
| 200 | 操作成功 |
|
||||
| 401 | 未授权，请先登录 |
|
||||
| 403 | 无权限访问 |
|
||||
| 500 | 服务器内部错误 |
|
||||
|
||||
## 业务错误信息
|
||||
|
||||
| 错误信息 | 说明 |
|
||||
|----------|------|
|
||||
| 姓名不能为空 | 个人中介导入时姓名为空 |
|
||||
| 机构名称不能为空 | 机构中介导入时机构名称为空 |
|
||||
| 证件号码不能为空 | 个人中介导入时证件号码为空 |
|
||||
| 该证件号已存在 | 新增/导入时证件号重复 |
|
||||
| 该统一社会信用代码已存在 | 新增/导入时信用代码重复 |
|
||||
|
||||
## 测试账号
|
||||
|
||||
- 用户名: `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 | 新增接口分离：新增个人/机构专用新增接口，统一接口设计 |
|
||||
271
doc/api/中介黑名单管理API测试报告.md
Normal file
271
doc/api/中介黑名单管理API测试报告.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# 中介黑名单管理API测试报告
|
||||
|
||||
## 测试概述
|
||||
|
||||
**测试时间:** 2026-01-29 16:43:11
|
||||
**测试环境:** http://localhost:8080
|
||||
**测试账号:** admin
|
||||
**测试脚本:** [test_intermediary_blacklist.sh](../scripts/test_intermediary_blacklist.sh)
|
||||
**测试通过率:** 100.00%
|
||||
|
||||
## 测试结果汇总
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 测试场景总数 | 11 |
|
||||
| 通过数量 | 11 |
|
||||
| 失败数量 | 0 |
|
||||
| 通过率 | 100.00% |
|
||||
|
||||
## 测试用例详情
|
||||
|
||||
### 1. 登录测试
|
||||
|
||||
**接口:** `POST /login/test`
|
||||
**描述:** 使用测试账号登录获取认证token
|
||||
|
||||
**请求参数:**
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "admin123"
|
||||
}
|
||||
```
|
||||
|
||||
**测试结果:** ✅ 通过
|
||||
- 成功获取token
|
||||
- token格式正确
|
||||
|
||||
---
|
||||
|
||||
### 2. 查询中介黑名单列表
|
||||
|
||||
**接口:** `GET /dpc/intermediary/list`
|
||||
**描述:** 分页查询中介黑名单列表
|
||||
|
||||
**请求参数:**
|
||||
- pageNum: 1
|
||||
- pageSize: 10
|
||||
|
||||
**测试结果:** ✅ 通过
|
||||
- 返回分页数据结构正确
|
||||
- 包含 total 和 rows 字段
|
||||
- 数据格式符合预期
|
||||
|
||||
---
|
||||
|
||||
### 3. 新增个人中介黑名单
|
||||
|
||||
**接口:** `POST /dpc/intermediary`
|
||||
**描述:** 新增个人类型的中介黑名单记录
|
||||
|
||||
**请求参数:**
|
||||
```json
|
||||
{
|
||||
"name": "测试个人中介_20260129_164311",
|
||||
"certificateNo": "TESTCERT20260129_164311",
|
||||
"intermediaryType": "1",
|
||||
"remark": "自动化测试数据"
|
||||
}
|
||||
```
|
||||
|
||||
**测试结果:** ✅ 通过
|
||||
- 成功创建记录
|
||||
- 返回状态码 200
|
||||
- 成功获取到新创建的ID: 2005
|
||||
|
||||
---
|
||||
|
||||
### 4. 新增机构中介黑名单
|
||||
|
||||
**接口:** `POST /dpc/intermediary`
|
||||
**描述:** 新增机构类型的中介黑名单记录
|
||||
|
||||
**请求参数:**
|
||||
```json
|
||||
{
|
||||
"name": "测试机构中介_20260129_164311",
|
||||
"certificateNo": "TESTORG20260129_164311",
|
||||
"intermediaryType": "2",
|
||||
"remark": "自动化测试机构数据"
|
||||
}
|
||||
```
|
||||
|
||||
**测试结果:** ✅ 通过
|
||||
- 成功创建记录
|
||||
- 返回状态码 200
|
||||
- 成功获取到新创建的ID: 2006
|
||||
|
||||
---
|
||||
|
||||
### 5. 获取中介详情
|
||||
|
||||
**接口:** `GET /dpc/intermediary/{intermediaryId}`
|
||||
**描述:** 根据ID获取中介详细信息
|
||||
|
||||
**请求参数:**
|
||||
- intermediaryId: 2005
|
||||
|
||||
**测试结果:** ✅ 通过
|
||||
- 成功获取详情信息
|
||||
- 返回完整的数据结构
|
||||
- 包含所有必要字段
|
||||
|
||||
---
|
||||
|
||||
### 6. 修改中介黑名单
|
||||
|
||||
**接口:** `PUT /dpc/intermediary`
|
||||
**描述:** 修改已存在的中介信息
|
||||
|
||||
**请求参数:**
|
||||
```json
|
||||
{
|
||||
"intermediaryId": 2005,
|
||||
"name": "测试个人中介_修改",
|
||||
"certificateNo": "TESTCERT20260129_164311",
|
||||
"intermediaryType": "1",
|
||||
"status": "1",
|
||||
"remark": "修改后的自动化测试数据"
|
||||
}
|
||||
```
|
||||
|
||||
**测试结果:** ✅ 通过
|
||||
- 成功更新记录
|
||||
- 返回状态码 200
|
||||
- 数据修改生效
|
||||
|
||||
---
|
||||
|
||||
### 7. 导出中介黑名单列表
|
||||
|
||||
**接口:** `POST /dpc/intermediary/export`
|
||||
**描述:** 导出中介黑名单数据为Excel文件
|
||||
|
||||
**请求参数:**
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
**测试结果:** ✅ 通过
|
||||
- 成功导出Excel文件
|
||||
- 文件格式正确
|
||||
- 文件保存至: test_output/test6_export.xlsx
|
||||
|
||||
---
|
||||
|
||||
### 8. 下载个人中介导入模板
|
||||
|
||||
**接口:** `POST /dpc/intermediary/importPersonTemplate`
|
||||
**描述:** 下载个人中介导入Excel模板
|
||||
|
||||
**测试结果:** ✅ 通过
|
||||
- 成功下载模板文件
|
||||
- 文件格式正确
|
||||
- 文件保存至: test_output/test7_person_template.xlsx
|
||||
|
||||
---
|
||||
|
||||
### 9. 下载机构中介导入模板
|
||||
|
||||
**接口:** `POST /dpc/intermediary/importEntityTemplate`
|
||||
**描述:** 下载机构中介导入Excel模板
|
||||
|
||||
**测试结果:** ✅ 通过
|
||||
- 成功下载模板文件
|
||||
- 文件格式正确
|
||||
- 文件保存至: test_output/test8_entity_template.xlsx
|
||||
|
||||
---
|
||||
|
||||
### 10. 条件查询（按中介类型）
|
||||
|
||||
**接口:** `GET /dpc/intermediary/list`
|
||||
**描述:** 按中介类型筛选查询
|
||||
|
||||
**请求参数:**
|
||||
- pageNum: 1
|
||||
- pageSize: 10
|
||||
- intermediaryType: 1 (个人)
|
||||
|
||||
**测试结果:** ✅ 通过
|
||||
- 查询结果正确
|
||||
- 数据筛选生效
|
||||
- 返回指定类型的数据
|
||||
|
||||
---
|
||||
|
||||
### 11. 条件查询（按状态）
|
||||
|
||||
**接口:** `GET /dpc/intermediary/list`
|
||||
**描述:** 按状态筛选查询
|
||||
|
||||
**请求参数:**
|
||||
- pageNum: 1
|
||||
- pageSize: 10
|
||||
- status: 1
|
||||
|
||||
**测试结果:** ✅ 通过
|
||||
- 查询结果正确
|
||||
- 数据筛选生效
|
||||
- 返回指定状态的数据
|
||||
|
||||
---
|
||||
|
||||
### 12. 删除中介黑名单
|
||||
|
||||
**接口:** `DELETE /dpc/intermediary/{intermediaryIds}`
|
||||
**描述:** 批量删除中介黑名单记录
|
||||
|
||||
**请求参数:**
|
||||
- intermediaryIds: 2005,2006
|
||||
|
||||
**测试结果:** ✅ 通过
|
||||
- 成功删除记录
|
||||
- 返回状态码 200
|
||||
- 数据删除生效
|
||||
|
||||
---
|
||||
|
||||
## 测试文件清单
|
||||
|
||||
### 响应JSON文件
|
||||
- `test1_list_response.json` - 查询列表响应
|
||||
- `test2_add_person_response.json` - 新增个人中介响应
|
||||
- `test3_add_entity_response.json` - 新增机构中介响应
|
||||
- `test4_get_info_response.json` - 获取详情响应
|
||||
- `test5_edit_response.json` - 修改中介响应
|
||||
- `test9_remove_response.json` - 删除中介响应
|
||||
- `test10_query_by_type_response.json` - 按类型查询响应
|
||||
- `test11_query_by_status_response.json` - 按状态查询响应
|
||||
|
||||
### Excel文件
|
||||
- `test6_export.xlsx` - 导出的数据文件
|
||||
- `test7_person_template.xlsx` - 个人中介导入模板
|
||||
- `test8_entity_template.xlsx` - 机构中介导入模板
|
||||
|
||||
### 报告文件
|
||||
- `test_report_20260129_164311.txt` - 详细测试日志
|
||||
|
||||
## 结论
|
||||
|
||||
**所有测试用例均已通过，中介黑名单管理API功能完整且运行正常。**
|
||||
|
||||
### 主要验证点
|
||||
1. ✅ 认证授权机制正常
|
||||
2. ✅ CRUD操作功能完整
|
||||
3. ✅ 分页查询功能正常
|
||||
4. ✅ 条件筛选功能正常
|
||||
5. ✅ 文件导入导出功能正常
|
||||
6. ✅ 批量操作功能正常
|
||||
|
||||
### 建议
|
||||
1. 建议在实际部署前进行压力测试
|
||||
2. 建议添加更多的边界条件测试用例
|
||||
3. 建议完善错误码和错误信息的文档
|
||||
|
||||
---
|
||||
|
||||
**报告生成时间:** 2026-01-29 16:43:11
|
||||
**测试工具:** curl + bash
|
||||
**报告生成者:** Claude Code
|
||||
348
doc/api/员工信息管理API文档.md
Normal file
348
doc/api/员工信息管理API文档.md
Normal file
@@ -0,0 +1,348 @@
|
||||
# 员工信息管理 API 文档
|
||||
|
||||
## 概述
|
||||
|
||||
员工信息管理模块提供员工及其亲属信息的增删改查、批量导入导出功能。
|
||||
|
||||
**基础路径**: `/dpc/employee`
|
||||
|
||||
**权限标识前缀**: `dpc:employee`
|
||||
|
||||
---
|
||||
|
||||
## API 接口列表
|
||||
|
||||
### 1. 查询员工列表
|
||||
|
||||
**接口地址**: `GET /dpc/employee/list`
|
||||
|
||||
**权限要求**: `dpc:employee:list`
|
||||
|
||||
**请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| name | String | 否 | 姓名（模糊查询） |
|
||||
| tellerNo | String | 否 | 柜员号（精确查询） |
|
||||
| deptId | Long | 否 | 所属部门ID |
|
||||
| idCard | String | 否 | 身份证号（精确查询） |
|
||||
| status | String | 否 | 状态（0=在职, 1=离职） |
|
||||
| pageNum | Integer | 否 | 页码（默认1） |
|
||||
| pageSize | Integer | 否 | 每页数量（默认10） |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"rows": [
|
||||
{
|
||||
"employeeId": 1,
|
||||
"name": "张三",
|
||||
"tellerNo": "001",
|
||||
"deptId": 100,
|
||||
"deptName": "总部",
|
||||
"idCard": "110101199001011234",
|
||||
"phone": "13800138000",
|
||||
"hireDate": "2020-01-01",
|
||||
"status": "0",
|
||||
"statusDesc": "在职",
|
||||
"createTime": "2026-01-28 10:00:00"
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
**响应字段说明**:
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| employeeId | Long | 员工ID |
|
||||
| name | String | 姓名 |
|
||||
| tellerNo | String | 柜员号 |
|
||||
| deptId | Long | 所属部门ID |
|
||||
| deptName | String | 所属部门名称（关联 sys_dept 表） |
|
||||
| idCard | String | 身份证号 |
|
||||
| phone | String | 电话 |
|
||||
| hireDate | Date | 入职时间 |
|
||||
| status | String | 状态（0=在职, 1=离职） |
|
||||
| statusDesc | String | 状态描述 |
|
||||
| createTime | Date | 创建时间 |
|
||||
|
||||
---
|
||||
|
||||
### 2. 查询员工详情
|
||||
|
||||
**接口地址**: `GET /dpc/employee/{employeeId}`
|
||||
|
||||
**权限要求**: `dpc:employee:query`
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| employeeId | Long | 是 | 员工ID |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"employeeId": 1,
|
||||
"name": "张三",
|
||||
"tellerNo": "001",
|
||||
"deptId": 100,
|
||||
"idCard": "110101199001011234",
|
||||
"phone": "13800138000",
|
||||
"hireDate": "2020-01-01",
|
||||
"status": "0",
|
||||
"statusDesc": "在职",
|
||||
"createTime": "2026-01-28 10:00:00",
|
||||
"relatives": [
|
||||
{
|
||||
"relativeId": 1,
|
||||
"employeeId": 1,
|
||||
"relativeName": "李四",
|
||||
"relativeIdCard": "110101199001011235",
|
||||
"relativePhone": "13800138001",
|
||||
"relationship": "配偶"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 新增员工
|
||||
|
||||
**接口地址**: `POST /dpc/employee`
|
||||
|
||||
**权限要求**: `dpc:employee:add`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"name": "张三",
|
||||
"tellerNo": "001",
|
||||
"deptId": 100,
|
||||
"idCard": "110101199001011234",
|
||||
"phone": "13800138000",
|
||||
"hireDate": "2020-01-01",
|
||||
"status": "0",
|
||||
"relatives": [
|
||||
{
|
||||
"relativeName": "李四",
|
||||
"relativeIdCard": "110101199001011235",
|
||||
"relativePhone": "13800138001",
|
||||
"relationship": "配偶"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 | 校验规则 |
|
||||
|--------|------|------|------|----------|
|
||||
| name | String | 是 | 姓名 | 最大100字符 |
|
||||
| tellerNo | String | 是 | 柜员号 | 最大50字符，唯一 |
|
||||
| deptId | Long | 否 | 所属部门ID | |
|
||||
| idCard | String | 是 | 身份证号 | 18位，符合国标，唯一 |
|
||||
| phone | String | 否 | 电话 | 11位手机号 |
|
||||
| hireDate | Date | 否 | 入职时间 | yyyy-MM-dd |
|
||||
| status | String | 是 | 状态 | 0=在职, 1=离职 |
|
||||
| relatives | Array | 否 | 亲属列表 | |
|
||||
|
||||
**亲属对象字段**:
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| relativeName | String | 是 | 亲属姓名 |
|
||||
| relativeIdCard | String | 否 | 亲属身份证号 |
|
||||
| relativePhone | String | 否 | 亲属手机号 |
|
||||
| relationship | String | 是 | 与员工关系 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 编辑员工
|
||||
|
||||
**接口地址**: `PUT /dpc/employee`
|
||||
|
||||
**权限要求**: `dpc:employee:edit`
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"employeeId": 1,
|
||||
"name": "张三",
|
||||
"tellerNo": "001",
|
||||
"deptId": 100,
|
||||
"idCard": "110101199001011234",
|
||||
"phone": "13800138000",
|
||||
"hireDate": "2020-01-01",
|
||||
"status": "0",
|
||||
"relatives": [
|
||||
{
|
||||
"relativeName": "李四",
|
||||
"relativeIdCard": "110101199001011235",
|
||||
"relativePhone": "13800138001",
|
||||
"relationship": "配偶"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**: 与新增接口相同，employeeId 为必填项。
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 删除员工
|
||||
|
||||
**接口地址**: `DELETE /dpc/employee/{employeeIds}`
|
||||
|
||||
**权限要求**: `dpc:employee:remove`
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| employeeIds | Long[] | 是 | 员工ID数组（逗号分隔） |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
**注意**: 删除员工时会级联删除该员工的所有亲属信息。
|
||||
|
||||
---
|
||||
|
||||
### 6. 导出员工信息
|
||||
|
||||
**接口地址**: `POST /dpc/employee/export`
|
||||
|
||||
**权限要求**: `dpc:employee:export`
|
||||
|
||||
**请求参数**: 与查询列表接口相同（支持筛选条件）
|
||||
|
||||
**响应**: Excel 文件下载
|
||||
|
||||
---
|
||||
|
||||
### 7. 下载导入模板（带字典下拉框）
|
||||
|
||||
**接口地址**: `POST /dpc/employee/importTemplate`
|
||||
|
||||
**权限要求**: 无
|
||||
|
||||
**功能说明**: 下载的 Excel 模板中，"状态"列会自动添加字典下拉框，方便用户选择。
|
||||
|
||||
**响应**: Excel 模板文件下载
|
||||
|
||||
**Excel 格式说明**:
|
||||
|
||||
**Sheet1: 员工信息**
|
||||
| 姓名 | 柜员号 | 所属部门ID | 身份证号 | 电话 | 入职时间 | 状态▼ |
|
||||
|------|--------|------------|----------|------|----------|------|
|
||||
| 张三 | 001 | 100 | 110101199001011234 | 13800138000 | 2020-01-01 | 在职 |
|
||||
|
||||
**注**：带 ▼ 标记的列包含下拉框，选项来自字典 `dpc_employee_status`。
|
||||
|
||||
**使用 @DictDropdown 注解实现**:
|
||||
- 状态字段使用 `@DictDropdown(dictType = "dpc_employee_status")` 注解
|
||||
- 系统自动从 Redis 缓存读取字典数据并生成下拉框
|
||||
- 下拉选项可动态更新，刷新字典缓存后生效
|
||||
|
||||
---
|
||||
|
||||
### 8. 导入员工信息
|
||||
|
||||
**接口地址**: `POST /dpc/employee/importData`
|
||||
|
||||
**权限要求**: `dpc:employee:import`
|
||||
|
||||
**请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| file | File | 是 | Excel 文件 |
|
||||
| updateSupport | Boolean | 否 | 是否更新已存在数据（默认false） |
|
||||
|
||||
**Excel 格式**:
|
||||
|
||||
**Sheet1: 员工信息**
|
||||
| 姓名 | 柜员号 | 所属部门ID | 身份证号 | 电话 | 入职时间 | 状态 |
|
||||
|------|--------|------------|----------|------|----------|------|
|
||||
| 张三 | 001 | 100 | 110101199001011234 | 13800138000 | 2020-01-01 | 在职 |
|
||||
|
||||
**Sheet2: 亲属信息（可选）**
|
||||
| 员工身份证号 | 亲属姓名 | 亲属身份证号 | 亲属手机号 | 与员工关系 |
|
||||
|--------------|----------|--------------|------------|------------|
|
||||
| 110101199001011234 | 李四 | 110101199001011235 | 13800138001 | 配偶 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "恭喜您，数据已全部导入成功！共 10 条"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 错误码说明
|
||||
|
||||
| 错误码 | 说明 |
|
||||
|--------|------|
|
||||
| 200 | 操作成功 |
|
||||
| 401 | 未授权，请先登录 |
|
||||
| 403 | 无权限访问 |
|
||||
| 500 | 服务器内部错误 |
|
||||
|
||||
## 业务错误信息
|
||||
|
||||
| 错误信息 | 说明 |
|
||||
|----------|------|
|
||||
| 该柜员号已存在 | 新增/编辑时柜员号重复 |
|
||||
| 该身份证号已存在 | 新增/编辑时身份证号重复 |
|
||||
| 姓名不能为空 | 新增时姓名为空 |
|
||||
| 身份证号格式不正确 | 身份证号不符合18位国标 |
|
||||
| 电话格式不正确 | 手机号不符合11位格式 |
|
||||
| 状态只能填写'在职'或'离职' | 状态值不正确 |
|
||||
|
||||
---
|
||||
|
||||
## 测试账号
|
||||
|
||||
- 用户名: `admin`
|
||||
- 密码: `admin123`
|
||||
|
||||
测试前请先调用 `/login/test` 接口获取 Token。
|
||||
Reference in New Issue
Block a user