14 KiB

Raw Blame History

新益门禁后端接口开发文档

接口总览

编号	接口	方法	路径	模块
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	审核人列表
approvers	List	审批人列表
confirmers	List	确认人列表

`AuditorItemCO`

字段	类型	说明
id	Long	主键id
configId	String	配置UUID
userId	Long	用户ID
userName	String	用户姓名

逻辑说明

查询部门列表（需调用外部部门服务获取部门名称、级别、主管领导、负责人信息）
按部门ID分组查询 gate_dept_auditor_config，按 config_type 拆分为审核人/审批人/确认人
组装返回，每个部门一行，三种人员作为子列表

接口2：设置审核人/审批人/确认人

请求

POST /deptAuditor/save

入参 `DeptAuditorSaveCmd`

字段	类型	必填	说明
deptId	Long	是	部门ID
configType	Integer	是	配置类型：1-审核人 2-审批人 3-确认人
userList	List	是	相关人员数组（可多个）

逻辑说明

每次只更新一种类型（configType）
先删除该部门该类型的所有旧配置：DELETE FROM gate_dept_auditor_config WHERE dept_id = ? AND config_type = ?
批量插入新配置，每条记录生成 config_id UUID
事务保证原子性

接口3：获取外来人员/外来车辆管理列表

请求

POST /visitorApply/page

入参 `VisitorApplyPageQry`

字段	类型	必填	说明
pageIndex	Integer	否	页码，默认1
pageSize	Integer	否	每页条数，默认10
sourceUnit	String	否	来源单位（模糊筛选）
statusList	List	否	状态列表（多选筛选）
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	状态

逻辑说明

分页查询 gate_visitor_apply，支持来源单位模糊、状态多选、申请时间范围筛选
applySourceDesc 拼接逻辑：申请来源类型(PC端/扫码) + 申请部门名称 + 申请人姓名，需关联部门服务和用户服务
状态枚举：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	是	人员列表（姓名+手机号，可多条）
status	Intger	是	状态

`VisitorPersonCmd`

字段	类型	必填	说明
name	String	是	姓名
phone	String	是	手机号

逻辑说明

生成 visitor_apply_id UUID，插入 gate_visitor_apply
person_type 自动设置：applyType=1时为1(来访人员)，applyType=2时为2(车内人员)
批量插入 gate_visitor_person，每条生成 visitor_person_id UUID
校验黑名单：遍历personList中的姓名+手机号查 gate_blacklist(blacklist_type=1)，以及车牌号查 gate_blacklist(blacklist_type=2)，命中则提示
状态初始为 0(未提交)

接口5：删除外来人员/外来车辆管理

请求

POST /visitorApply/remove

入参 `VisitorApplyRemoveCmd`

字段	类型	必填	说明
visitorApplyId	String	是	业务主键UUID

逻辑说明

逻辑删除 gate_visitor_apply：设置 delete_enum = 'true'
同时逻辑删除关联的 gate_visitor_person：按 visitor_apply_id 设置 delete_enum = 'true'

接口6：进场/出场确认

请求

POST /visitorApply/confirm

入参 `VisitorApplyConfirmCmd`

字段	类型	必填	说明
visitorApplyId	String	是	业务主键UUID
confirmType	Integer	是	确认类型：1-进场 2-出场

逻辑说明

根据 visitorApplyId 查询申请记录，校验存在且未删除
进场确认(confirmType=1)：状态必须为3(待确认)，确认后改为4(已进场)
出场确认(confirmType=2)：状态必须为4(已进场)，确认后改为5(已出场)
同时插入一条 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	否	所属单位

逻辑说明

生成 blacklist_id UUID
join_time 自动设置为当前时间
added_by_id 自动取当前登录用户ID
校验重复：人员黑名单按姓名+手机号查重，车辆黑名单按车牌号查重（同一租户下）

接口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	状态

逻辑说明

按 blacklist_type 必选筛选
支持姓名、手机号、车牌号、所属单位模糊筛选，状态精确筛选
addedByName 通过 added_by_id 关联用户服务获取

接口9：删除黑名单

请求

POST /blacklist/remove

入参 `BlacklistRemoveCmd`

字段	类型	必填	说明
blacklistId	String	是	业务主键UUID

逻辑说明

逻辑删除：设置 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已过期（申请时间过期自动标记）

14 KiB Raw Blame History Unescape Escape

新益门禁后端接口开发文档

接口总览

接口1：获取部门审核人/审批人/确认人列表

请求

入参 DeptAuditorListQry

出参 List<DeptAuditorCO>

AuditorItemCO

逻辑说明

接口2：设置审核人/审批人/确认人

请求

入参 DeptAuditorSaveCmd

逻辑说明

接口3：获取外来人员/外来车辆管理列表

请求

入参 VisitorApplyPageQry

出参 PageData<VisitorApplyCO>

逻辑说明

接口4：新增外来人员/外来车辆管理

请求

入参 VisitorApplyAddCmd

VisitorPersonCmd

逻辑说明

接口5：删除外来人员/外来车辆管理

请求

入参 VisitorApplyRemoveCmd

逻辑说明

接口6：进场/出场确认

请求

入参 VisitorApplyConfirmCmd

逻辑说明

接口7：新增黑名单

请求

入参 BlacklistAddCmd

逻辑说明

接口8：获取黑名单列表

请求

入参 BlacklistPageQry

出参 PageData<BlacklistCO>

逻辑说明

接口9：删除黑名单

请求

入参 BlacklistRemoveCmd

逻辑说明

文件清单

模块一：DeptAuditor（部门审核人配置）

模块二：VisitorApply（来访申请）

模块三：Blacklist（黑名单）

状态流转图

14 KiB

Raw Blame History

入参 `DeptAuditorListQry`

出参 `List<DeptAuditorCO>`

`AuditorItemCO`

入参 `DeptAuditorSaveCmd`

入参 `VisitorApplyPageQry`

出参 `PageData<VisitorApplyCO>`

入参 `VisitorApplyAddCmd`

`VisitorPersonCmd`

入参 `VisitorApplyRemoveCmd`

入参 `VisitorApplyConfirmCmd`

入参 `BlacklistAddCmd`

入参 `BlacklistPageQry`

出参 `PageData<BlacklistCO>`

入参 `BlacklistRemoveCmd`