zcloud_gbs_xinyi_gate/docs/新益公司门禁接口文档.md

# 新益公司门禁系统 接口文档

> 基础路径：`/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 | 出场 |