395 lines
14 KiB
Markdown
395 lines
14 KiB
Markdown
# 新益门禁后端接口开发文档
|
||
|
||
## 接口总览
|
||
|
||
| 编号 | 接口 | 方法 | 路径 | 模块 |
|
||
|------|------|------|------|------|
|
||
| 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已过期（申请时间过期自动标记）
|
||
```
|