zcloud_gbs
/
zcloud_gbs_xinyi_gate
15
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
zcloud_gbs_xinyi_gate/docs/接口开发文档.md

395 lines
14 KiB
Markdown
Raw Normal View History

init
2026-06-10 14:39:21 +08:00
# 新益门禁后端接口开发文档
## 接口总览
| 编号 | 接口 | 方法 | 路径 | 模块 |
|------|------|------|------|------|
| 1 | 获取部门审核人/审批人/确认人列表 | POST | `/deptAuditor/list` | DeptAuditor |
| 2 | 设置审核人/审批人/确认人 | POST | `/deptAuditor/save` | DeptAuditor |
| 3 | 获取来访申请列表 | POST | `/visitorApply/page` | VisitorApply |
| 4 | 新增来访申请 | POST | `/visitorApply/add` | VisitorApply |
| 5 | 删除来访申请 | POST | `/visitorApply/remove` | VisitorApply |
| 6 | 进场/出场确认 | POST | `/visitorApply/confirm` | VisitorApply |
| 7 | 新增黑名单 | POST | `/blacklist/add` | Blacklist |
| 8 | 获取黑名单列表 | POST | `/blacklist/page` | Blacklist |
| 9 | 删除黑名单 | POST | `/blacklist/remove` | Blacklist |
---
## 接口1：获取部门审核人/审批人/确认人列表
### 请求
```
POST /deptAuditor/list
```
### 入参 `DeptAuditorListQry`
| 字段 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| deptId | String | 否 | 部门名称（模糊筛选） |
### 出参 `List<DeptAuditorCO>`
| 字段 | 类型 | 说明 |
|------|------|------|
| deptId | Long | 部门ID |
| deptName | String | 部门名称 |
| deptLevel | String | 部门级别 |
| leaderName | String | 主管领导 |
| headName | String | 部门负责人 |
| auditors | List<AuditorItemCO> | 审核人列表 |
| approvers | List<AuditorItemCO> | 审批人列表 |
| confirmers | List<AuditorItemCO> | 确认人列表 |
### `AuditorItemCO`
| 字段 | 类型 | 说明 |
|----------|--------|--------|
| id | Long | 主键id |
| configId | String | 配置UUID |
| userId | Long | 用户ID |
| userName | String | 用户姓名 |
### 逻辑说明
1. 查询部门列表（需调用外部部门服务获取部门名称、级别、主管领导、负责人信息）
2. 按部门ID分组查询 `gate_dept_auditor_config`，按 `config_type` 拆分为审核人/审批人/确认人
3. 组装返回，每个部门一行，三种人员作为子列表
---
## 接口2：设置审核人/审批人/确认人
### 请求
```
POST /deptAuditor/save
```
### 入参 `DeptAuditorSaveCmd`
| 字段 | 类型 | 必填 | 说明 |
|------|------------|------|------|
| deptId | Long | 是 | 部门ID |
| configType | Integer | 是 | 配置类型：1-审核人 2-审批人 3-确认人 |
| userList | List<Long> | 是 | 相关人员数组（可多个） |
### 逻辑说明
1. 每次只更新一种类型（configType）
2. 先删除该部门该类型的所有旧配置：`DELETE FROM gate_dept_auditor_config WHERE dept_id = ? AND config_type = ?`
3. 批量插入新配置，每条记录生成 `config_id` UUID
4. 事务保证原子性
---
## 接口3：获取外来人员/外来车辆管理列表
### 请求
```
POST /visitorApply/page
```
### 入参 `VisitorApplyPageQry`
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageIndex | Integer | 否 | 页码，默认1 |
| pageSize | Integer | 否 | 每页条数，默认10 |
| sourceUnit | String | 否 | 来源单位（模糊筛选） |
| statusList | List<Integer> | 否 | 状态列表（多选筛选） |
| applyStartTime | String | 否 | 申请时间起（yyyy-MM-dd） |
| applyEndTime | String | 否 | 申请时间止（yyyy-MM-dd） |
### 出参 `PageData<VisitorApplyCO>`
| 字段 | 类型 | 说明 |
|------|------|------|
| visitorApplyId | String | 业务主键UUID |
| applyType | Integer | 申请类型：1-外来人员 2-外来车辆 |
| sourceUnit | String | 来源单位 |
| visitorCount | Integer | 入场人数 |
| applyStartTime | String | 申请开始时间 |
| applyEndTime | String | 申请结束时间 |
| licensePlate | String | 车牌号 |
| vehicleType | String | 车型 |
| purpose | String | 入场事由 |
| applySourceDesc | String | 申请来源（来源类型 + 部门名称 + 人员名称） |
| status | Integer | 状态 |
### 逻辑说明
1. 分页查询 `gate_visitor_apply`，支持来源单位模糊、状态多选、申请时间范围筛选
2. `applySourceDesc` 拼接逻辑：申请来源类型(PC端/扫码) + 申请部门名称 + 申请人姓名，需关联部门服务和用户服务
3. 状态枚举：0未提交 1待审核 2待审批 3待确认 4已进场 5已出场 6已打回 7待归档 8已归档 9已过期
---
## 接口4：新增外来人员/外来车辆管理
### 请求
```
POST /visitorApply/add
```
### 入参 `VisitorApplyAddCmd`
| 字段 | 类型 | 必填 | 说明 |
|----------------|------------------------|------|---------------------|
| applyType | Integer | 是 | 申请类型：1-外来人员 2-外来车辆 |
| sourceUnit | String | 是 | 来源单位 |
| visitorCount | Integer | 否 | 入场人数 |
| licensePlate | String | 条件必填 | 车牌号（applyType=2时必填） |
| vehicleType | String | 否 | 车型（applyType=2时填写） |
| purpose | String | 是 | 入场事由 |
| applyStartTime | String | 是 | 申请开始时间 |
| applyEndTime | String | 是 | 申请结束时间 |
| auditDeptId | Long | 是 | 审批部门ID |
| personList | List<VisitorPersonCmd> | 是 | 人员列表（姓名+手机号，可多条） |
| status | Intger | 是 | 状态 |
### `VisitorPersonCmd`
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | 是 | 姓名 |
| phone | String | 是 | 手机号 |
### 逻辑说明
1. 生成 `visitor_apply_id` UUID，插入 `gate_visitor_apply`
2. `person_type` 自动设置：applyType=1时为1(来访人员)，applyType=2时为2(车内人员)
3. 批量插入 `gate_visitor_person`，每条生成 `visitor_person_id` UUID
4. 校验黑名单：遍历personList中的姓名+手机号查 `gate_blacklist`(blacklist_type=1)，以及车牌号查 `gate_blacklist`(blacklist_type=2)，命中则提示
5. 状态初始为 0(未提交)
---
## 接口5：删除外来人员/外来车辆管理
### 请求
```
POST /visitorApply/remove
```
### 入参 `VisitorApplyRemoveCmd`
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| visitorApplyId | String | 是 | 业务主键UUID |
### 逻辑说明
1. 逻辑删除 `gate_visitor_apply`：设置 `delete_enum = 'true'`
2. 同时逻辑删除关联的 `gate_visitor_person`：按 `visitor_apply_id` 设置 `delete_enum = 'true'`
---
## 接口6：进场/出场确认
### 请求
```
POST /visitorApply/confirm
```
### 入参 `VisitorApplyConfirmCmd`
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| visitorApplyId | String | 是 | 业务主键UUID |
| confirmType | Integer | 是 | 确认类型：1-进场 2-出场 |
### 逻辑说明
1. 根据 `visitorApplyId` 查询申请记录，校验存在且未删除
2. 进场确认(confirmType=1)：状态必须为3(待确认)，确认后改为4(已进场)
3. 出场确认(confirmType=2)：状态必须为4(已进场)，确认后改为5(已出场)
4. 同时插入一条 `gate_visitor_audit` 审核记录，`audit_type=3`(现场确认)，`audit_result=1`(通过)
---
## 接口7：新增黑名单
### 请求
```
POST /blacklist/add
```
### 入参 `BlacklistAddCmd`
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| blacklistType | Integer | 是 | 黑名单类型：1-人员 2-车辆 |
| name | String | 条件必填 | 姓名（blacklistType=1时必填） |
| phone | String | 条件必填 | 手机号（blacklistType=1时必填） |
| licensePlate | String | 条件必填 | 车牌号（blacklistType=2时必填） |
| affiliatedUnit | String | 否 | 所属单位 |
### 逻辑说明
1. 生成 `blacklist_id` UUID
2. `join_time` 自动设置为当前时间
3. `added_by_id` 自动取当前登录用户ID
4. 校验重复：人员黑名单按姓名+手机号查重，车辆黑名单按车牌号查重（同一租户下）
---
## 接口8：获取黑名单列表
### 请求
```
POST /blacklist/page
```
### 入参 `BlacklistPageQry`
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageIndex | Integer | 否 | 页码，默认1 |
| pageSize | Integer | 否 | 每页条数，默认10 |
| blacklistType | Integer | 是 | 黑名单类型：1-人员 2-车辆 |
| name | String | 否 | 姓名（模糊筛选） |
| phone | String | 否 | 手机号（模糊筛选） |
| status | Integer | 否 | 状态：1-启用 0-禁用 |
| affiliatedUnit | String | 否 | 所属单位（模糊筛选） |
| licensePlate | String | 否 | 车牌号（模糊筛选） |
### 出参 `PageData<BlacklistCO>`
| 字段 | 类型 | 说明 |
|------|------|------|
| blacklistId | String | 业务主键UUID |
| blacklistType | Integer | 类型：1-人员 2-车辆 |
| name | String | 姓名 |
| phone | String | 手机号 |
| licensePlate | String | 车牌号 |
| affiliatedUnit | String | 所属单位 |
| joinTime | String | 加入时间 |
| addedByName | String | 添加人 |
| status | Integer | 状态 |
### 逻辑说明
1. 按 `blacklist_type` 必选筛选
2. 支持姓名、手机号、车牌号、所属单位模糊筛选，状态精确筛选
3. `addedByName` 通过 `added_by_id` 关联用户服务获取
---
## 接口9：删除黑名单
### 请求
```
POST /blacklist/remove
```
### 入参 `BlacklistRemoveCmd`
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| blacklistId | String | 是 | 业务主键UUID |
### 逻辑说明
1. 逻辑删除：设置 `delete_enum = 'true'`
---
## 文件清单
按开发指南的分层架构，以下为需要创建的所有文件：
### 模块一：DeptAuditor（部门审核人配置）
| 层 | 文件路径 |
|----|---------|
| client | `dto/deptAuditor/DeptAuditorListQry.java` |
| client | `dto/deptAuditor/DeptAuditorSaveCmd.java` |
| client | `dto/deptAuditor/AuditorItemCmd.java` |
| client | `dto/clientobject/deptAuditor/DeptAuditorCO.java` |
| client | `dto/clientobject/deptAuditor/AuditorItemCO.java` |
| client | `api/deptAuditor/DeptAuditorServiceI.java` |
| domain | `domain/model/deptAuditor/DeptAuditorE.java` |
| domain | `domain/gateway/deptAuditor/DeptAuditorGateway.java` |
| infrastructure | `persistence/dataobject/deptAuditor/DeptAuditorConfigDO.java` |
| infrastructure | `persistence/mapper/deptAuditor/DeptAuditorConfigMapper.java` |
| infrastructure | `resources/mapper/deptAuditor/DeptAuditorConfigMapper.xml` |
| infrastructure | `gatewayimpl/deptAuditor/DeptAuditorGatewayImpl.java` |
| app | `command/deptAuditor/DeptAuditorSaveExe.java` |
| app | `command/query/deptAuditor/DeptAuditorQueryExe.java` |
| app | `service/deptAuditor/DeptAuditorServiceImpl.java` |
| adapter | `web/deptAuditor/DeptAuditorController.java` |
### 模块二：VisitorApply（来访申请）
| 层 | 文件路径 |
|----|---------|
| client | `dto/visitorApply/VisitorApplyAddCmd.java` |
| client | `dto/visitorApply/VisitorApplyRemoveCmd.java` |
| client | `dto/visitorApply/VisitorApplyConfirmCmd.java` |
| client | `dto/visitorApply/VisitorApplyPageQry.java` |
| client | `dto/visitorApply/VisitorPersonCmd.java` |
| client | `dto/clientobject/visitorApply/VisitorApplyCO.java` |
| client | `api/visitorApply/VisitorApplyServiceI.java` |
| domain | `domain/model/visitorApply/VisitorApplyE.java` |
| domain | `domain/model/visitorApply/VisitorPersonE.java` |
| domain | `domain/gateway/visitorApply/VisitorApplyGateway.java` |
| domain | `domain/gateway/visitorApply/VisitorPersonGateway.java` |
| infrastructure | `persistence/dataobject/visitorApply/VisitorApplyDO.java` |
| infrastructure | `persistence/dataobject/visitorApply/VisitorPersonDO.java` |
| infrastructure | `persistence/mapper/visitorApply/VisitorApplyMapper.java` |
| infrastructure | `persistence/mapper/visitorApply/VisitorPersonMapper.java` |
| infrastructure | `resources/mapper/visitorApply/VisitorApplyMapper.xml` |
| infrastructure | `resources/mapper/visitorApply/VisitorPersonMapper.xml` |
| infrastructure | `gatewayimpl/visitorApply/VisitorApplyGatewayImpl.java` |
| infrastructure | `gatewayimpl/visitorApply/VisitorPersonGatewayImpl.java` |
| app | `command/visitorApply/VisitorApplyAddExe.java` |
| app | `command/visitorApply/VisitorApplyRemoveExe.java` |
| app | `command/visitorApply/VisitorApplyConfirmExe.java` |
| app | `command/query/visitorApply/VisitorApplyQueryExe.java` |
| app | `service/visitorApply/VisitorApplyServiceImpl.java` |
| adapter | `web/visitorApply/VisitorApplyController.java` |
### 模块三：Blacklist（黑名单）
| 层 | 文件路径 |
|----|---------|
| client | `dto/blacklist/BlacklistAddCmd.java` |
| client | `dto/blacklist/BlacklistRemoveCmd.java` |
| client | `dto/blacklist/BlacklistPageQry.java` |
| client | `dto/clientobject/blacklist/BlacklistCO.java` |
| client | `api/blacklist/BlacklistServiceI.java` |
| domain | `domain/model/blacklist/BlacklistE.java` |
| domain | `domain/gateway/blacklist/BlacklistGateway.java` |
| infrastructure | `persistence/dataobject/blacklist/BlacklistDO.java` |
| infrastructure | `persistence/mapper/blacklist/BlacklistMapper.java` |
| infrastructure | `resources/mapper/blacklist/BlacklistMapper.xml` |
| infrastructure | `gatewayimpl/blacklist/BlacklistGatewayImpl.java` |
| app | `command/blacklist/BlacklistAddExe.java` |
| app | `command/blacklist/BlacklistRemoveExe.java` |
| app | `command/query/blacklist/BlacklistQueryExe.java` |
| app | `service/blacklist/BlacklistServiceImpl.java` |
| adapter | `web/blacklist/BlacklistController.java` |
---
## 状态流转图
```
0未提交 → 1待审核 → 2待审批 → 3待确认 → 4已进场 → 5已出场
↑ ↑ ↑
└──── 6已打回（任一环节拒绝） ────┘
7待归档 → 8已归档
9已过期（申请时间过期自动标记）
```