From 85632fa0044503cbc5791414d5d0a5dc96af5b2a Mon Sep 17 00:00:00 2001 From: tianxinlei Date: Wed, 10 Jun 2026 15:26:18 +0800 Subject: [PATCH] 6-10 update --- docs/开发指南.md | 631 ------------------ docs/接口开发文档.md | 394 ----------- docs/新益公司门禁接口文档.md | 547 +++++++++++++++ .../web/blacklist/BlacklistController.java | 2 +- .../deptAuditor/DeptAuditorController.java | 2 +- .../visitorApply/VisitorApplyController.java | 14 +- .../visitorApply/VisitorApplyServiceImpl.java | 8 +- .../visitorApply/VisitorApplyServiceI.java | 4 +- 8 files changed, 569 insertions(+), 1033 deletions(-) delete mode 100644 docs/开发指南.md delete mode 100644 docs/接口开发文档.md create mode 100644 docs/新益公司门禁接口文档.md diff --git a/docs/开发指南.md b/docs/开发指南.md deleted file mode 100644 index 3262cac..0000000 --- a/docs/开发指南.md +++ /dev/null @@ -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 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 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 { -} -``` - -#### Mapper XML `XxxMapper.xml` - -```xml - - - - - -``` - -#### 网关实现 `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 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/` 下 diff --git a/docs/接口开发文档.md b/docs/接口开发文档.md deleted file mode 100644 index 7090824..0000000 --- a/docs/接口开发文档.md +++ /dev/null @@ -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` - -| 字段 | 类型 | 说明 | -|------|------|------| -| 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 | 用户姓名 | - -### 逻辑说明 - -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 | 是 | 相关人员数组（可多个） | - -### 逻辑说明 - -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 | 否 | 状态列表（多选筛选） | -| applyStartTime | String | 否 | 申请时间起（yyyy-MM-dd） | -| applyEndTime | String | 否 | 申请时间止（yyyy-MM-dd） | - -### 出参 `PageData` - -| 字段 | 类型 | 说明 | -|------|------|------| -| 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 | 是 | 人员列表（姓名+手机号，可多条） | -| 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` - -| 字段 | 类型 | 说明 | -|------|------|------| -| 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已过期（申请时间过期自动标记） -``` diff --git a/docs/新益公司门禁接口文档.md b/docs/新益公司门禁接口文档.md new file mode 100644 index 0000000..69033ff --- /dev/null +++ b/docs/新益公司门禁接口文档.md @@ -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\）： + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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\）： + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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\ | 否 | 相关人员用户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\ | 否 | 状态列表（多选筛选） | +| 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\）： + +| 字段 | 类型 | 说明 | +|------|------|------| +| 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 | 出场 | diff --git a/web-adapter/src/main/java/com/zcloud/xinyiGate/web/blacklist/BlacklistController.java b/web-adapter/src/main/java/com/zcloud/xinyiGate/web/blacklist/BlacklistController.java index 4db8628..96f3920 100644 --- a/web-adapter/src/main/java/com/zcloud/xinyiGate/web/blacklist/BlacklistController.java +++ b/web-adapter/src/main/java/com/zcloud/xinyiGate/web/blacklist/BlacklistController.java @@ -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 { diff --git a/web-adapter/src/main/java/com/zcloud/xinyiGate/web/deptAuditor/DeptAuditorController.java b/web-adapter/src/main/java/com/zcloud/xinyiGate/web/deptAuditor/DeptAuditorController.java index 031f39c..00cbef4 100644 --- a/web-adapter/src/main/java/com/zcloud/xinyiGate/web/deptAuditor/DeptAuditorController.java +++ b/web-adapter/src/main/java/com/zcloud/xinyiGate/web/deptAuditor/DeptAuditorController.java @@ -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 { diff --git a/web-adapter/src/main/java/com/zcloud/xinyiGate/web/visitorApply/VisitorApplyController.java b/web-adapter/src/main/java/com/zcloud/xinyiGate/web/visitorApply/VisitorApplyController.java index a5aa625..e560bd2 100644 --- a/web-adapter/src/main/java/com/zcloud/xinyiGate/web/visitorApply/VisitorApplyController.java +++ b/web-adapter/src/main/java/com/zcloud/xinyiGate/web/visitorApply/VisitorApplyController.java @@ -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") diff --git a/web-app/src/main/java/com/zcloud/xinyiGate/service/visitorApply/VisitorApplyServiceImpl.java b/web-app/src/main/java/com/zcloud/xinyiGate/service/visitorApply/VisitorApplyServiceImpl.java index 1b2bdbb..d33124b 100644 --- a/web-app/src/main/java/com/zcloud/xinyiGate/service/visitorApply/VisitorApplyServiceImpl.java +++ b/web-app/src/main/java/com/zcloud/xinyiGate/service/visitorApply/VisitorApplyServiceImpl.java @@ -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); diff --git a/web-client/src/main/java/com/zcloud/xinyiGate/api/visitorApply/VisitorApplyServiceI.java b/web-client/src/main/java/com/zcloud/xinyiGate/api/visitorApply/VisitorApplyServiceI.java index 7bfd7c5..3757ac7 100644 --- a/web-client/src/main/java/com/zcloud/xinyiGate/api/visitorApply/VisitorApplyServiceI.java +++ b/web-client/src/main/java/com/zcloud/xinyiGate/api/visitorApply/VisitorApplyServiceI.java @@ -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);