zcloud_gbs
/
zcloud_gbs_xinyi_gate
15
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

6-10 update

master
tianxinlei 2026-06-10 15:26:18 +08:00
parent 33b1186d4d
commit 85632fa004
8 changed files with 569 additions and 1033 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

631
docs/开发指南.md
View File

@ -1,631 +0,0 @@
# 信义门禁开发指南
## 一、项目概览
| 项目 | 值 |
|------|-----|
| groupId | `com.zcloud.xinyigate` |
| artifactId | `zcloud_gbs_xinyi_gate` |
| 包名 | `com.zcloud.xinyigate` |
| 应用名 | `jjb-saas-zcloud-xinyi-gate` |
| 网关名 | `xinyiGate` |
| 父POM | `com.jjb.saas:jjb-saas-parent:2.2.0-SNAPSHOT` |
| 公共库 | `com.zcloud.gbscommon:zcloud_gbscommon:1.0.0-SNAPSHOT` |
| 技术栈 | Spring Boot 2.6 + Spring Cloud + Nacos + MyBatis-Plus + XXL-Job |
## 二、模块结构
```
zcloud_gbs_xinyi_gate/
├── start/ # 启动模块
│ └── src/main/
│ ├── java/.../Application.java # Spring Boot 入口
│ └── resources/
│ ├── nacos.yml # Nacos配置（开发）
│ ├── nacos-prod.yml # Nacos配置（生产）
│ ├── bootstrap.yml # 引导配置
│ └── templates/xinyiGate/ # 前端模板
│
├── web-adapter/ # 适配层 - 接收外部请求
│ └── src/main/java/.../
│ ├── web/{module}/ # REST Controller
│ │ └── XxxController.java
│ └── job/ # 定时任务
│ └── XxxJob.java
│
├── web-app/ # 应用层 - 业务编排
│ └── src/main/java/.../
│ ├── command/{module}/ # 写操作执行器
│ │ ├── XxxAddExe.java
│ │ ├── XxxEditExe.java
│ │ └── XxxRemoveExe.java
│ ├── command/query/{module}/ # 读操作执行器
│ │ └── XxxQueryExe.java
│ ├── command/convertor/{module}/ # 对象转换器
│ │ └── XxxCoConvertor.java
│ └── service/{module}/ # Service实现
│ └── XxxServiceImpl.java
│
├── web-client/ # 客户端层 - 接口定义 + DTO
│ └── src/main/java/.../
│ ├── api/{module}/ # 服务接口
│ │ └── XxxServiceI.java
│ ├── dto/{module}/ # 入参（Cmd/Qry）
│ │ ├── XxxAddCmd.java
│ │ ├── XxxEditCmd.java
│ │ └── XxxPageQry.java
│ ├── dto/clientobject/{module}/ # 出参（CO）
│ │ └── XxxCO.java
│ └── config/ # 配置类
│
├── web-domain/ # 领域层 - 核心业务模型
│ └── src/main/java/.../
│ └── domain/
│ ├── model/{module}/ # 领域实体
│ │ └── XxxE.java
│ ├── gateway/{module}/ # 网关接口
│ │ └── XxxGateway.java
│ ├── enums/ # 枚举
│ └── util/ # 领域工具
│
├── web-infrastructure/ # 基础设施层 - 数据库对接
│ └── src/main/
│ ├── java/.../
│ │ ├── gatewayimpl/{module}/ # 网关实现
│ │ │ └── XxxGatewayImpl.java
│ │ ├── persistence/
│ │ │ ├── dataobject/{module}/ # 数据对象
│ │ │ │ └── XxxDO.java
│ │ │ ├── mapper/{module}/ # Mapper接口
│ │ │ │ └── XxxMapper.java
│ │ │ ├── repository/{module}/ # Repository接口
│ │ │ │ └── XxxRepository.java
│ │ │ └── repository/impl/{module}/ # Repository实现
│ │ │ └── XxxRepositoryImpl.java
│ │ └── utils/ # 工具类
│ └── resources/
│ ├── mapper/{module}/ # MyBatis XML
│ │ └── XxxMapper.xml
│ └── mybatis/mybatis-config.xml
│
└── pom.xml # 父POM
```
## 三、模块依赖关系
```
start → adapter → app → client → domain
↓
infrastructure → domain
```
| 模块 | 可依赖 |
|------|--------|
| web-domain | 无（纯核心，不依赖任何业务模块） |
| web-client | web-domain |
| web-infrastructure | web-domain |
| web-app | web-client, web-infrastructure |
| web-adapter | web-app, web-client |
| start | web-adapter |
## 四、调用链路
```
HTTP请求
→ Controller (adapter层，参数校验、权限控制)
→ ServiceI (client层，接口定义)
→ ServiceImpl (app层，业务编排)
→ XxxExe (app层，单一职责执行器)
→ XxxGateway (domain层，网关接口)
→ XxxGatewayImpl (infrastructure层，网关实现)
→ XxxMapper (infrastructure层，MyBatis接口)
→ XxxMapper.xml (SQL映射)
→ 数据库
```
## 五、各层代码模板
### 5.1 web-client — 服务接口 + DTO
#### 服务接口 `XxxServiceI.java`
```java
package com.zcloud.xinyigate.api.module;
import com.jjb.saas.framework.client.ResponseData;
import com.zcloud.xinyigate.dto.module.XxxAddCmd;
import com.zcloud.xinyigate.dto.module.XxxEditCmd;
import com.zcloud.xinyigate.dto.module.XxxPageQry;
import com.zcloud.xinyigate.dto.clientobject.module.XxxCO;
public interface XxxServiceI {
ResponseData addXxx(XxxAddCmd cmd);
ResponseData editXxx(XxxEditCmd cmd);
ResponseData removeXxx(Long id);
ResponseData<XxxCO> getXxx(Long id);
ResponseData queryXxxPage(XxxPageQry qry);
}
```
#### 新增命令 `XxxAddCmd.java`
```java
package com.zcloud.xinyigate.dto.module;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import javax.validation.constraints.NotBlank;
@Data
@ApiModel("Xxx新增命令")
public class XxxAddCmd {
@NotBlank(message = "名称不能为空")
@ApiModelProperty("名称")
private String name;
@ApiModelProperty("备注")
private String remark;
}
```
#### 分页查询 `XxxPageQry.java`
```java
package com.zcloud.xinyigate.dto.module;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel("Xxx分页查询")
public class XxxPageQry {
@ApiModelProperty("页码")
private Integer pageIndex = 1;
@ApiModelProperty("每页条数")
private Integer pageSize = 10;
@ApiModelProperty("名称（模糊查询）")
private String name;
}
```
#### 返回对象 `XxxCO.java`
```java
package com.zcloud.xinyigate.dto.clientobject.module;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel("Xxx返回对象")
public class XxxCO {
@ApiModelProperty("ID")
private Long id;
@ApiModelProperty("名称")
private String name;
@ApiModelProperty("备注")
private String remark;
}
```
### 5.2 web-domain — 领域实体 + 网关接口
#### 领域实体 `XxxE.java`
```java
package com.zcloud.xinyigate.domain.model.module;
import lombok.Data;
@Data
public class XxxE {
private Long id;
private String name;
private String remark;
}
```
#### 网关接口 `XxxGateway.java`
```java
package com.zcloud.xinyigate.domain.gateway.module;
import com.zcloud.xinyigate.domain.model.module.XxxE;
public interface XxxGateway {
void add(XxxE xxxE);
void edit(XxxE xxxE);
void remove(Long id);
XxxE getById(Long id);
}
```
### 5.3 web-app — Service实现 + 执行器
#### Service实现 `XxxServiceImpl.java`
```java
package com.zcloud.xinyigate.service.module;
import com.jjb.saas.framework.client.ResponseData;
import com.zcloud.xinyigate.api.module.XxxServiceI;
import com.zcloud.xinyigate.command.module.XxxAddExe;
import com.zcloud.xinyigate.command.module.XxxEditExe;
import com.zcloud.xinyigate.command.query.module.XxxQueryExe;
import com.zcloud.xinyigate.dto.module.XxxAddCmd;
import com.zcloud.xinyigate.dto.module.XxxEditCmd;
import com.zcloud.xinyigate.dto.module.XxxPageQry;
import com.zcloud.xinyigate.dto.clientobject.module.XxxCO;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
@Service
@RequiredArgsConstructor
public class XxxServiceImpl implements XxxServiceI {
private final XxxAddExe xxxAddExe;
private final XxxEditExe xxxEditExe;
private final XxxQueryExe xxxQueryExe;
@Override
public ResponseData addXxx(XxxAddCmd cmd) {
xxxAddExe.execute(cmd);
return ResponseData.success();
}
@Override
public ResponseData editXxx(XxxEditCmd cmd) {
xxxEditExe.execute(cmd);
return ResponseData.success();
}
@Override
public ResponseData removeXxx(Long id) {
// 直接调用Gateway或写RemoveExe
return ResponseData.success();
}
@Override
public ResponseData<XxxCO> getXxx(Long id) {
return ResponseData.success(xxxQueryExe.getById(id));
}
@Override
public ResponseData queryXxxPage(XxxPageQry qry) {
return ResponseData.success(xxxQueryExe.queryPage(qry));
}
}
```
#### 新增执行器 `XxxAddExe.java`
```java
package com.zcloud.xinyigate.command.module;
import com.zcloud.xinyigate.domain.gateway.module.XxxGateway;
import com.zcloud.xinyigate.domain.model.module.XxxE;
import com.zcloud.xinyigate.dto.module.XxxAddCmd;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Component;
@Component
@RequiredArgsConstructor
public class XxxAddExe {
private final XxxGateway xxxGateway;
public void execute(XxxAddCmd cmd) {
XxxE xxxE = new XxxE();
xxxE.setName(cmd.getName());
xxxE.setRemark(cmd.getRemark());
xxxGateway.add(xxxE);
}
}
```
#### 查询执行器 `XxxQueryExe.java`
```java
package com.zcloud.xinyigate.command.query.module;
import com.zcloud.xinyigate.domain.gateway.module.XxxGateway;
import com.zcloud.xinyigate.domain.model.module.XxxE;
import com.zcloud.xinyigate.dto.clientobject.module.XxxCO;
import com.zcloud.xinyigate.dto.module.XxxPageQry;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Component;
@Component
@RequiredArgsConstructor
public class XxxQueryExe {
private final XxxGateway xxxGateway;
public XxxCO getById(Long id) {
XxxE xxxE = xxxGateway.getById(id);
// E → CO 转换
XxxCO co = new XxxCO();
co.setId(xxxE.getId());
co.setName(xxxE.getName());
co.setRemark(xxxE.getRemark());
return co;
}
public Object queryPage(XxxPageQry qry) {
// 调用Gateway分页查询，转换返回
return null;
}
}
```
### 5.4 web-infrastructure — 数据库对接
#### 数据对象 `XxxDO.java`
```java
package com.zcloud.xinyigate.persistence.dataobject.module;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
@Data
@TableName("t_xxx")
public class XxxDO {
@TableId(type = IdType.AUTO)
private Long id;
private String name;
private String remark;
}
```
#### Mapper接口 `XxxMapper.java`
```java
package com.zcloud.xinyigate.persistence.mapper.module;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.zcloud.xinyigate.persistence.dataobject.module.XxxDO;
import org.apache.ibatis.annotations.Mapper;
@Mapper
public interface XxxMapper extends BaseMapper<XxxDO> {
}
```
#### Mapper XML `XxxMapper.xml`
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
"http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.zcloud.xinyigate.persistence.mapper.module.XxxMapper">
</mapper>
```
#### 网关实现 `XxxGatewayImpl.java`
```java
package com.zcloud.xinyigate.gatewayimpl.module;
import com.zcloud.xinyigate.domain.gateway.module.XxxGateway;
import com.zcloud.xinyigate.domain.model.module.XxxE;
import com.zcloud.xinyigate.persistence.dataobject.module.XxxDO;
import com.zcloud.xinyigate.persistence.mapper.module.XxxMapper;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Component;
@Component
@RequiredArgsConstructor
public class XxxGatewayImpl implements XxxGateway {
private final XxxMapper xxxMapper;
@Override
public void add(XxxE xxxE) {
XxxDO xxxDO = new XxxDO();
xxxDO.setName(xxxE.getName());
xxxDO.setRemark(xxxE.getRemark());
xxxMapper.insert(xxxDO);
}
@Override
public void edit(XxxE xxxE) {
XxxDO xxxDO = new XxxDO();
xxxDO.setId(xxxE.getId());
xxxDO.setName(xxxE.getName());
xxxDO.setRemark(xxxE.getRemark());
xxxMapper.updateById(xxxDO);
}
@Override
public void remove(Long id) {
xxxMapper.deleteById(id);
}
@Override
public XxxE getById(Long id) {
XxxDO xxxDO = xxxMapper.selectById(id);
if (xxxDO == null) return null;
XxxE xxxE = new XxxE();
xxxE.setId(xxxDO.getId());
xxxE.setName(xxxDO.getName());
xxxE.setRemark(xxxDO.getRemark());
return xxxE;
}
}
```
### 5.5 web-adapter — Controller
#### REST接口 `XxxController.java`
```java
package com.zcloud.xinyigate.web.module;
import com.jjb.saas.framework.client.ResponseData;
import com.zcloud.xinyigate.api.module.XxxServiceI;
import com.zcloud.xinyigate.dto.module.XxxAddCmd;
import com.zcloud.xinyigate.dto.module.XxxEditCmd;
import com.zcloud.xinyigate.dto.module.XxxPageQry;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;
import javax.validation.Valid;
@RestController
@RequestMapping("/xxx")
@Api(tags = "Xxx管理")
@RequiredArgsConstructor
public class XxxController {
private final XxxServiceI xxxService;
@PostMapping("/add")
@ApiOperation("新增")
public ResponseData add(@Valid @RequestBody XxxAddCmd cmd) {
return xxxService.addXxx(cmd);
}
@PostMapping("/edit")
@ApiOperation("编辑")
public ResponseData edit(@Valid @RequestBody XxxEditCmd cmd) {
return xxxService.editXxx(cmd);
}
@PostMapping("/remove/{id}")
@ApiOperation("删除")
public ResponseData remove(@PathVariable Long id) {
return xxxService.removeXxx(id);
}
@GetMapping("/get/{id}")
@ApiOperation("详情")
public ResponseData get(@PathVariable Long id) {
return xxxService.getXxx(id);
}
@PostMapping("/page")
@ApiOperation("分页查询")
public ResponseData page(@RequestBody XxxPageQry qry) {
return xxxService.queryXxxPage(qry);
}
}
```
### 5.6 定时任务（web-adapter）
#### `XxxJob.java`
```java
package com.zcloud.xinyigate.job;
import com.jjb.saas.framework.job.Job;
import com.jjb.saas.framework.job.annotation.JobRegister;
import com.xxl.job.core.biz.model.ReturnT;
import com.xxl.job.core.handler.annotation.XxlJob;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
@Component
@RequiredArgsConstructor
@Slf4j
public class XxxJob implements Job {
private final XxxServiceI xxxService;
@Override
@JobRegister(cron = "0 0 0 * * ?", jobDesc = "Xxx定时任务", triggerStatus = 1)
@XxlJob("com.zcloud.xinyigate.job.XxxJob")
public ReturnT<String> execute(String param) {
log.info("【Xxx定时任务】开始执行");
try {
// xxxService.doSomething();
log.info("【Xxx定时任务】执行完成");
} catch (Exception e) {
log.error("【Xxx定时任务】执行异常", e);
return new ReturnT<>(ReturnT.FAIL_CODE, e.getMessage());
}
return ReturnT.SUCCESS;
}
}
```
## 六、开发步骤清单
实现一个新接口时，按以下顺序创建文件：
| 步骤 | 模块 | 文件 | 说明 |
|------|------|------|------|
| 1 | web-client | `dto/module/XxxAddCmd.java` | 定义入参 |
| 2 | web-client | `dto/module/XxxPageQry.java` | 定义查询参数 |
| 3 | web-client | `dto/clientobject/module/XxxCO.java` | 定义出参 |
| 4 | web-client | `api/module/XxxServiceI.java` | 定义服务接口 |
| 5 | web-domain | `domain/model/module/XxxE.java` | 定义领域实体 |
| 6 | web-domain | `domain/gateway/module/XxxGateway.java` | 定义网关接口 |
| 7 | web-infrastructure | `persistence/dataobject/module/XxxDO.java` | 定义数据对象 |
| 8 | web-infrastructure | `persistence/mapper/module/XxxMapper.java` | 定义Mapper接口 |
| 9 | web-infrastructure | `resources/mapper/module/XxxMapper.xml` | 编写SQL |
| 10 | web-infrastructure | `gatewayimpl/module/XxxGatewayImpl.java` | 实现网关 |
| 11 | web-app | `command/module/XxxAddExe.java` | 实现新增逻辑 |
| 12 | web-app | `command/query/module/XxxQueryExe.java` | 实现查询逻辑 |
| 13 | web-app | `service/module/XxxServiceImpl.java` | 实现Service |
| 14 | web-adapter | `web/module/XxxController.java` | 暴露REST接口 |
## 七、命名规范
| 类型 | 命名 | 示例 |
|------|------|------|
| Controller | `{业务}Controller` | `GateRecordController` |
| Service接口 | `{业务}ServiceI` | `GateRecordServiceI` |
| Service实现 | `{业务}ServiceImpl` | `GateRecordServiceImpl` |
| 新增执行器 | `{业务}AddExe` | `GateRecordAddExe` |
| 编辑执行器 | `{业务}EditExe` | `GateRecordEditExe` |
| 删除执行器 | `{业务}RemoveExe` | `GateRecordRemoveExe` |
| 查询执行器 | `{业务}QueryExe` | `GateRecordQueryExe` |
| 领域实体 | `{业务}E` | `GateRecordE` |
| 网关接口 | `{业务}Gateway` | `GateRecordGateway` |
| 网关实现 | `{业务}GatewayImpl` | `GateRecordGatewayImpl` |
| 数据对象 | `{业务}DO` | `GateRecordDO` |
| Mapper接口 | `{业务}Mapper` | `GateRecordMapper` |
| 新增命令 | `{业务}AddCmd` | `GateRecordAddCmd` |
| 编辑命令 | `{业务}EditCmd` | `GateRecordEditCmd` |
| 分页查询 | `{业务}PageQry` | `GateRecordPageQry` |
| 返回对象 | `{业务}CO` | `GateRecordCO` |
| 定时任务 | `{业务}Job` | `GateRecordJob` |
## 八、注意事项
1. **包名统一为 `com.zcloud.xinyigate`**，Java目录对应 `com/zcloud/xinyigate/`
2. **Application.java** 中的 `mapperPackages` 已配置为 `com.zcloud.xinyigate.persistence.mapper`，新Mapper会自动扫描
3. **分页参数**统一使用 `pageIndex`（页码）和 `pageSize`（每页条数），参考 `Query.java` 工具类
4. **定时任务**必须实现 `Job` 接口，同时加 `@JobRegister` 和 `@XxlJob` 注解
5. **对象转换**：Cmd → E（在Exe中），DO → E（在GatewayImpl中），E → CO（在QueryExe中）
6. **Flyway** 已集成，数据库变更脚本放在 `start/src/main/resources/db/migration/` 下

394
docs/接口开发文档.md
View File

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

547
docs/新益公司门禁接口文档.md Normal file
View File

@ -0,0 +1,547 @@
# 新益公司门禁系统 接口文档
> 基础路径：`/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 | 出场 |

2
web-adapter/src/main/java/com/zcloud/xinyiGate/web/blacklist/BlacklistController.java
View File

@ -18,7 +18,7 @@ import org.springframework.web.bind.annotation.RestController;
import javax.validation.Valid;
@RestController
@RequestMapping("/blacklist")
@RequestMapping("/${application.gateway}/blacklist")
@Api(tags = "黑名单管理")
@RequiredArgsConstructor
public class BlacklistController {

2
web-adapter/src/main/java/com/zcloud/xinyiGate/web/deptAuditor/DeptAuditorController.java
View File

@ -17,7 +17,7 @@ import org.springframework.web.bind.annotation.RestController;
import javax.validation.Valid;
@RestController
@RequestMapping("/deptAuditor")
@RequestMapping("/${application.gateway}/deptAuditor")
@Api(tags = "部门审核人配置")
@RequiredArgsConstructor
public class DeptAuditorController {

14
web-adapter/src/main/java/com/zcloud/xinyiGate/web/visitorApply/VisitorApplyController.java
View File

@ -20,17 +20,23 @@ import org.springframework.web.bind.annotation.RestController;
import javax.validation.Valid;
@RestController
@RequestMapping("/visitorApply")
@RequestMapping("/${application.gateway}/visitorApply")
@Api(tags = "来访申请管理")
@RequiredArgsConstructor
public class VisitorApplyController {
private final VisitorApplyServiceI visitorApplyService;
@PostMapping("/add")
@PostMapping("/save")
@ApiOperation("新增外来人员/外来车辆管理")
public Response add(@Valid @RequestBody VisitorApplyAddCmd cmd) {
return visitorApplyService.add(cmd);
public Response save(@Valid @RequestBody VisitorApplyAddCmd cmd) {
return visitorApplyService.save(cmd);
}
@PostMapping("/scanSave")
@ApiOperation("外部接口 - 扫码 - 新增外来人员/外来车辆管理")
public Response scanSave(@Valid @RequestBody VisitorApplyAddCmd cmd) {
return visitorApplyService.scanSave(cmd);
}
@PostMapping("/remove")

8
web-app/src/main/java/com/zcloud/xinyiGate/service/visitorApply/VisitorApplyServiceImpl.java
View File

@ -29,7 +29,7 @@ public class VisitorApplyServiceImpl implements VisitorApplyServiceI {
private final VisitorApplyQueryExe visitorApplyQueryExe;
@Override
public Response add(VisitorApplyAddCmd cmd) {
public Response save(VisitorApplyAddCmd cmd) {
SSOUser user = AuthContext.getCurrentUser();
if (user == null) {
@ -47,6 +47,12 @@ public class VisitorApplyServiceImpl implements VisitorApplyServiceI {
return Response.buildSuccess();
}
@Override
public Response scanSave(VisitorApplyAddCmd cmd) {
visitorApplyAddExe.execute(cmd);
return Response.buildSuccess();
}
@Override
public Response remove(VisitorApplyRemoveCmd cmd) {
visitorApplyRemoveExe.execute(cmd);

4
web-client/src/main/java/com/zcloud/xinyiGate/api/visitorApply/VisitorApplyServiceI.java
View File

@ -11,7 +11,9 @@ import com.zcloud.xinyiGate.dto.visitorApply.VisitorApplyRemoveCmd;
public interface VisitorApplyServiceI {
Response add(VisitorApplyAddCmd cmd);
Response save(VisitorApplyAddCmd cmd);
Response scanSave(VisitorApplyAddCmd cmd);
Response remove(VisitorApplyRemoveCmd cmd);