548 lines
13 KiB
Markdown
548 lines
13 KiB
Markdown
# 新益公司门禁系统 接口文档
|
||
|
||
> 基础路径：`/xinyiGate`，服务端口：`80`
|
||
> 所有接口均为 `POST` 请求，`Content-Type: application/json`
|
||
|
||
---
|
||
|
||
## 通用响应结构
|
||
|
||
### Response（无数据返回）
|
||
|
||
```json
|
||
{
|
||
"code": "0",
|
||
"message": "成功",
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
### PageResponse（分页返回）
|
||
|
||
```json
|
||
{
|
||
"code": "0",
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": [],
|
||
"totalCount": 0,
|
||
"pageSize": 10,
|
||
"pageIndex": 1
|
||
}
|
||
```
|
||
|
||
### MultiResponse（列表返回）
|
||
|
||
```json
|
||
{
|
||
"code": "0",
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": []
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 一、黑名单管理
|
||
|
||
### 1.1 新增黑名单
|
||
|
||
- **接口地址**：`POST /xinyiGate/blacklist/add`
|
||
- **接口描述**：新增黑名单人员或车辆
|
||
|
||
**请求参数**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| blacklistType | Integer | 是 | 黑名单类型：1-人员 2-车辆 |
|
||
| name | String | 条件必填 | 姓名（blacklistType=1时必填） |
|
||
| phone | String | 条件必填 | 手机号（blacklistType=1时必填） |
|
||
| licensePlate | String | 条件必填 | 车牌号（blacklistType=2时必填） |
|
||
| affiliatedUnit | String | 否 | 所属单位 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"blacklistType": 1,
|
||
"name": "张三",
|
||
"phone": "13800138000",
|
||
"affiliatedUnit": "某某公司"
|
||
}
|
||
```
|
||
|
||
**响应参数**：通用 Response
|
||
|
||
---
|
||
|
||
### 1.2 删除黑名单
|
||
|
||
- **接口地址**：`POST /xinyiGate/blacklist/remove`
|
||
- **接口描述**：删除黑名单记录
|
||
|
||
**请求参数**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| blacklistId | String | 是 | 业务主键UUID |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"blacklistId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
|
||
}
|
||
```
|
||
|
||
**响应参数**：通用 Response
|
||
|
||
---
|
||
|
||
### 1.3 获取黑名单列表（分页）
|
||
|
||
- **接口地址**：`POST /xinyiGate/blacklist/page`
|
||
- **接口描述**：分页查询黑名单列表
|
||
|
||
**请求参数**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| blacklistType | Integer | 是 | 黑名单类型：1-人员 2-车辆 |
|
||
| name | String | 否 | 姓名（模糊筛选） |
|
||
| phone | String | 否 | 手机号（模糊筛选） |
|
||
| status | Integer | 否 | 状态：1-启用 0-禁用 |
|
||
| affiliatedUnit | String | 否 | 所属单位（模糊筛选） |
|
||
| licensePlate | String | 否 | 车牌号（模糊筛选） |
|
||
| pageIndex | Integer | 否 | 页码，默认1 |
|
||
| pageSize | Integer | 否 | 每页条数，默认10 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"blacklistType": 1,
|
||
"name": "张",
|
||
"status": 1,
|
||
"pageIndex": 1,
|
||
"pageSize": 10
|
||
}
|
||
```
|
||
|
||
**响应参数**（PageResponse\<BlacklistCO\>）：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| data[].blacklistId | String | 业务主键UUID |
|
||
| data[].blacklistType | Integer | 黑名单类型：1-人员 2-车辆 |
|
||
| data[].name | String | 姓名 |
|
||
| data[].phone | String | 手机号 |
|
||
| data[].licensePlate | String | 车牌号 |
|
||
| data[].affiliatedUnit | String | 所属单位 |
|
||
| data[].joinTime | String | 加入时间 |
|
||
| data[].addedByName | String | 添加人 |
|
||
| data[].status | Integer | 状态：1-启用 0-禁用 |
|
||
| totalCount | Integer | 总条数 |
|
||
| pageSize | Integer | 每页条数 |
|
||
| pageIndex | Integer | 当前页码 |
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": "0",
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"blacklistId": "xxx-xxx",
|
||
"blacklistType": 1,
|
||
"name": "张三",
|
||
"phone": "13800138000",
|
||
"licensePlate": null,
|
||
"affiliatedUnit": "某某公司",
|
||
"joinTime": "2025-01-01 10:00:00",
|
||
"addedByName": "管理员",
|
||
"status": 1
|
||
}
|
||
],
|
||
"totalCount": 1,
|
||
"pageSize": 10,
|
||
"pageIndex": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 二、部门审核人配置
|
||
|
||
### 2.1 获取部门审核人/审批人/确认人列表
|
||
|
||
- **接口地址**：`POST /xinyiGate/deptAuditor/list`
|
||
- **接口描述**：查询部门下的审核人、审批人、确认人列表
|
||
|
||
**请求参数**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| deptId | Long | 否 | 部门ID |
|
||
| deptName | String | 否 | 部门名称（模糊筛选） |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"deptId": 100,
|
||
"deptName": "安全"
|
||
}
|
||
```
|
||
|
||
**响应参数**（MultiResponse\<DeptAuditorCO\>）：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| data[].deptId | Long | 部门ID |
|
||
| data[].deptName | String | 部门名称 |
|
||
| data[].deptLevel | String | 部门级别 |
|
||
| data[].leaderName | String | 主管领导 |
|
||
| data[].headName | String | 部门负责人 |
|
||
| data[].auditors | Array | 审核人列表 |
|
||
| data[].auditors[].id | Long | 主键ID |
|
||
| data[].auditors[].configId | String | 配置UUID |
|
||
| data[].auditors[].userId | Long | 用户ID |
|
||
| data[].auditors[].userName | String | 用户姓名 |
|
||
| data[].approvers | Array | 审批人列表（结构同auditors） |
|
||
| data[].confirmers | Array | 确认人列表（结构同auditors） |
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": "0",
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"deptId": 100,
|
||
"deptName": "安全部",
|
||
"deptLevel": "2",
|
||
"leaderName": "李领导",
|
||
"headName": "王负责人",
|
||
"auditors": [
|
||
{
|
||
"id": 1,
|
||
"configId": "cfg-001",
|
||
"userId": 1001,
|
||
"userName": "张审核"
|
||
}
|
||
],
|
||
"approvers": [
|
||
{
|
||
"id": 2,
|
||
"configId": "cfg-002",
|
||
"userId": 1002,
|
||
"userName": "李审批"
|
||
}
|
||
],
|
||
"confirmers": [
|
||
{
|
||
"id": 3,
|
||
"configId": "cfg-003",
|
||
"userId": 1003,
|
||
"userName": "王确认"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.2 设置审核人/审批人/确认人
|
||
|
||
- **接口地址**：`POST /xinyiGate/deptAuditor/save`
|
||
- **接口描述**：为指定部门设置审核人、审批人或确认人
|
||
|
||
**请求参数**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| deptId | Long | 是 | 部门ID |
|
||
| configType | Integer | 是 | 配置类型：1-审核人 2-审批人 3-确认人 |
|
||
| userList | List\<Long\> | 否 | 相关人员用户ID数组 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"deptId": 100,
|
||
"configType": 1,
|
||
"userList": [1001, 1002, 1003]
|
||
}
|
||
```
|
||
|
||
**响应参数**：通用 Response
|
||
|
||
---
|
||
|
||
## 三、来访申请管理
|
||
|
||
### 3.1 新增外来人员/外来车辆管理
|
||
|
||
- **接口地址**：`POST /xinyiGate/visitorApply/save`
|
||
- **接口描述**：PC端新增来访申请（人员或车辆）
|
||
|
||
**请求参数**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| visitorApplyId | String | 否 | 业务主键id（编辑时传入） |
|
||
| applyType | Integer | 是 | 申请类型：1-外来人员 2-外来车辆 |
|
||
| sourceUnit | String | 是 | 来源单位 |
|
||
| visitorCount | Integer | 否 | 入场人数 |
|
||
| licensePlate | String | 条件必填 | 车牌号（applyType=2时必填） |
|
||
| vehicleType | String | 否 | 车型（applyType=2时填写） |
|
||
| purpose | String | 是 | 入场事由 |
|
||
| applyStartTime | String | 是 | 申请开始时间（yyyy-MM-dd HH:mm:ss） |
|
||
| applyEndTime | String | 是 | 申请结束时间（yyyy-MM-dd HH:mm:ss） |
|
||
| auditDeptId | Long | 是 | 审批部门ID |
|
||
| status | Integer | 是 | 状态 |
|
||
| applyAddSource | Object | 否 | 申请来源相关信息 |
|
||
| applyAddSource.applySource | Integer | 否 | 申请来源：1-PC端 2-扫码申请 |
|
||
| applyAddSource.applyDeptId | Long | 否 | 申请部门ID |
|
||
| applyAddSource.applyUserId | Long | 否 | 申请人ID |
|
||
| personList | Array | 否 | 人员列表（applyType=1时填写） |
|
||
| personList[].name | String | 是 | 姓名 |
|
||
| personList[].phone | String | 是 | 手机号 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"applyType": 1,
|
||
"sourceUnit": "某某施工单位",
|
||
"visitorCount": 3,
|
||
"purpose": "设备检修",
|
||
"applyStartTime": "2025-06-01 08:00:00",
|
||
"applyEndTime": "2025-06-01 18:00:00",
|
||
"auditDeptId": 100,
|
||
"status": 1,
|
||
"applyAddSource": {
|
||
"applySource": 1,
|
||
"applyDeptId": 200,
|
||
"applyUserId": 1001
|
||
},
|
||
"personList": [
|
||
{ "name": "张三", "phone": "13800138001" },
|
||
{ "name": "李四", "phone": "13800138002" }
|
||
]
|
||
}
|
||
```
|
||
|
||
**响应参数**：通用 Response
|
||
|
||
---
|
||
|
||
### 3.2 扫码新增外来人员/外来车辆管理
|
||
|
||
- **接口地址**：`POST /xinyiGate/visitorApply/scanSave`
|
||
- **接口描述**：外部接口 - 扫码新增来访申请（人员或车辆）
|
||
|
||
**请求参数**：同 3.1
|
||
|
||
**请求示例**：同 3.1
|
||
|
||
**响应参数**：通用 Response
|
||
|
||
---
|
||
|
||
### 3.3 删除外来人员/外来车辆管理
|
||
|
||
- **接口地址**：`POST /xinyiGate/visitorApply/remove`
|
||
- **接口描述**：删除来访申请记录
|
||
|
||
**请求参数**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| visitorApplyId | String | 是 | 业务主键UUID |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"visitorApplyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
|
||
}
|
||
```
|
||
|
||
**响应参数**：通用 Response
|
||
|
||
---
|
||
|
||
### 3.4 审核/审批通过驳回
|
||
|
||
- **接口地址**：`POST /xinyiGate/visitorApply/audit`
|
||
- **接口描述**：对来访申请进行审核或审批操作
|
||
|
||
**请求参数**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| visitorApplyId | String | 是 | 业务主键UUID |
|
||
| auditType | Integer | 是 | 审核类型：1-职能部室审核 2-安监部门审批 |
|
||
| auditResult | Integer | 是 | 审核结果：1-通过 2-驳回 |
|
||
| auditOpinion | String | 条件必填 | 审核意见（驳回时必填） |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"visitorApplyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
|
||
"auditType": 1,
|
||
"auditResult": 1,
|
||
"auditOpinion": "同意"
|
||
}
|
||
```
|
||
|
||
**响应参数**：通用 Response
|
||
|
||
---
|
||
|
||
### 3.5 进场/出场
|
||
|
||
- **接口地址**：`POST /xinyiGate/visitorApply/confirm`
|
||
- **接口描述**：确认来访人员的进场或出场
|
||
|
||
**请求参数**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| visitorApplyId | String | 是 | 业务主键UUID |
|
||
| confirmType | Integer | 是 | 确认类型：1-进场 2-出场 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"visitorApplyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
|
||
"confirmType": 1
|
||
}
|
||
```
|
||
|
||
**响应参数**：通用 Response
|
||
|
||
---
|
||
|
||
### 3.6 获取外来人员/外来车辆管理列表（分页）
|
||
|
||
- **接口地址**：`POST /xinyiGate/visitorApply/page`
|
||
- **接口描述**：分页查询来访申请列表
|
||
|
||
**请求参数**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| sourceUnit | String | 否 | 来源单位（模糊筛选） |
|
||
| statusList | List\<Integer\> | 否 | 状态列表（多选筛选） |
|
||
| applyStartTime | String | 否 | 申请时间起（yyyy-MM-dd） |
|
||
| applyEndTime | String | 否 | 申请时间止（yyyy-MM-dd） |
|
||
| applyType | Integer | 否 | 申请类型：1-外来人员 2-外来车辆 |
|
||
| pageIndex | Integer | 否 | 页码，默认1 |
|
||
| pageSize | Integer | 否 | 每页条数，默认10 |
|
||
|
||
**请求示例**：
|
||
|
||
```json
|
||
{
|
||
"sourceUnit": "施工",
|
||
"statusList": [1, 2],
|
||
"applyStartTime": "2025-06-01",
|
||
"applyEndTime": "2025-06-30",
|
||
"applyType": 1,
|
||
"pageIndex": 1,
|
||
"pageSize": 10
|
||
}
|
||
```
|
||
|
||
**响应参数**（PageResponse\<VisitorApplyCO\>）：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| data[].visitorApplyId | String | 业务主键UUID |
|
||
| data[].applyType | Integer | 申请类型：1-外来人员 2-外来车辆 |
|
||
| data[].sourceUnit | String | 来源单位 |
|
||
| data[].visitorCount | Integer | 入场人数 |
|
||
| data[].applyStartTime | String | 申请开始时间（yyyy-MM-dd HH:mm:ss） |
|
||
| data[].applyEndTime | String | 申请结束时间（yyyy-MM-dd HH:mm:ss） |
|
||
| data[].licensePlate | String | 车牌号 |
|
||
| data[].vehicleType | String | 车型 |
|
||
| data[].purpose | String | 入场事由 |
|
||
| data[].applySourceDesc | String | 申请来源描述（来源类型+部门名称+人员名称） |
|
||
| data[].status | Integer | 状态 |
|
||
| data[].auditDeptId | Long | 审批部门ID |
|
||
| data[].auditDeptName | String | 审批部门名称 |
|
||
| data[].applySource | Integer | 申请来源：1-PC端 2-扫码申请 |
|
||
| data[].applyDeptName | String | 申请部门名称 |
|
||
| data[].applyUserName | String | 申请人姓名 |
|
||
| totalCount | Integer | 总条数 |
|
||
| pageSize | Integer | 每页条数 |
|
||
| pageIndex | Integer | 当前页码 |
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": "0",
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"visitorApplyId": "xxx-xxx",
|
||
"applyType": 1,
|
||
"sourceUnit": "某某施工单位",
|
||
"visitorCount": 3,
|
||
"applyStartTime": "2025-06-01 08:00:00",
|
||
"applyEndTime": "2025-06-01 18:00:00",
|
||
"licensePlate": null,
|
||
"vehicleType": null,
|
||
"purpose": "设备检修",
|
||
"applySourceDesc": "PC端-安全部-张三",
|
||
"status": 1,
|
||
"auditDeptId": 100,
|
||
"auditDeptName": "安全部",
|
||
"applySource": 1,
|
||
"applyDeptName": "安全部",
|
||
"applyUserName": "张三"
|
||
}
|
||
],
|
||
"totalCount": 1,
|
||
"pageSize": 10,
|
||
"pageIndex": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 附录：枚举值汇总
|
||
|
||
| 枚举项 | 值 | 说明 |
|
||
|--------|----|------|
|
||
| blacklistType | 1 | 人员 |
|
||
| blacklistType | 2 | 车辆 |
|
||
| status（黑名单） | 1 | 启用 |
|
||
| status（黑名单） | 0 | 禁用 |
|
||
| configType | 1 | 审核人 |
|
||
| configType | 2 | 审批人 |
|
||
| configType | 3 | 确认人 |
|
||
| applyType | 1 | 外来人员 |
|
||
| applyType | 2 | 外来车辆 |
|
||
| applySource | 1 | PC端 |
|
||
| applySource | 2 | 扫码申请 |
|
||
| auditType | 1 | 职能部室审核 |
|
||
| auditType | 2 | 安监部门审批 |
|
||
| auditResult | 1 | 通过 |
|
||
| auditResult | 2 | 驳回 |
|
||
| confirmType | 1 | 进场 |
|
||
| confirmType | 2 | 出场 |
|