1274 lines
28 KiB
Markdown
1274 lines
28 KiB
Markdown
# 口门信息管理 - 后端需求文档
|
||
|
||
## 一、模块概述
|
||
|
||
### 1.1 模块名称
|
||
口门信息管理（后端）
|
||
|
||
### 1.2 所属模块
|
||
监管端 → 一级口门管理
|
||
|
||
### 1.3 功能描述
|
||
管理口门的基础信息，包括口门的增删改查、口门属性配置，以及口门关联的通道、闸机、摄像头设备的管理功能。
|
||
|
||
### 1.4 用户角色
|
||
- 监管端超级管理员
|
||
- 监管端系统管理员
|
||
|
||
### 1.5 数据表
|
||
| 表名 | 说明 |
|
||
|------|------|
|
||
| `mkmj` | 门口信息管理表（主表） |
|
||
| `mkmj_passage` | 口门门禁通道表 |
|
||
| `mkmj_gate` | 门口闸机表 |
|
||
| `video` | 摄像头表 |
|
||
|
||
---
|
||
|
||
## 二、数据字典（前端静态配置）
|
||
|
||
以下数据字典由前端静态配置，无需后端提供接口：
|
||
|
||
### 2.1 口门级别 (mkmj_level)
|
||
| 值 | 名称 |
|
||
|----|------|
|
||
| 1 | 一级 |
|
||
| 2 | 二级 |
|
||
|
||
### 2.2 口门类型 (mkmj_type)
|
||
| 值 | 名称 |
|
||
|----|------|
|
||
| 1 | 人行 |
|
||
| 2 | 车行 |
|
||
| 3 | 综合 |
|
||
|
||
### 2.3 口门状态 (mkmj_status)
|
||
| 值 | 名称 |
|
||
|----|------|
|
||
| 1 | 停用 |
|
||
| 2 | 正常 |
|
||
| 3 | 暂时管理 |
|
||
|
||
### 2.4 所属港区 (hg_auth_area)
|
||
| 值 | 名称 |
|
||
|----|------|
|
||
| qianwan | 前湾港区 |
|
||
| dongjiakou | 董家口港区 |
|
||
| huangdao | 黄岛港区 |
|
||
| other | 其他港区 |
|
||
|
||
### 2.5 闸机状态 (gate_status)
|
||
| 值 | 名称 |
|
||
|----|------|
|
||
| 1 | 停用 |
|
||
| 2 | 正常 |
|
||
|
||
### 2.6 通道类型 (passage_type)
|
||
| 值 | 名称 |
|
||
|----|------|
|
||
| 1 | 人行 |
|
||
| 2 | 车行 |
|
||
| 3 | 综合 |
|
||
|
||
### 2.7 通道状态 (passage_status)
|
||
| 值 | 名称 |
|
||
|----|------|
|
||
| 1 | 停用 |
|
||
| 2 | 正常 |
|
||
|
||
### 2.8 摄像头类型 (video_type)
|
||
| 值 | 名称 |
|
||
|----|------|
|
||
| 1 | 移动 |
|
||
| 2 | 平台 |
|
||
|
||
### 2.9 设备类型 (device_type)
|
||
| 值 | 名称 |
|
||
|----|------|
|
||
| 1 | 口门 |
|
||
| 2 | 闸机 |
|
||
|
||
---
|
||
|
||
## 三、口门管理接口
|
||
|
||
### 3.1 查询口门列表
|
||
|
||
**接口：** `GET /api/mkmj/list`
|
||
|
||
**描述：** 分页查询口门列表，支持条件筛选
|
||
|
||
**请求参数：**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| page | int | 是 | 页码，默认 1 |
|
||
| pageSize | int | 是 | 每页条数，默认 20，最大 100 |
|
||
| mkmjName | String | 否 | 口门名称，模糊查询 |
|
||
| hgAuthArea | String | 否 | 所属港区编码 |
|
||
| mkmjStatus | Integer | 否 | 口门状态 |
|
||
| mkmjLevel | Integer | 否 | 口门级别 |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 101,
|
||
"mkmjName": "一号口门",
|
||
"hgAuthArea": "qianwan",
|
||
"hgAuthAreaName": "前湾港区",
|
||
"mkmjLevel": 1,
|
||
"mkmjType": "3",
|
||
"mkmjTypeName": "综合",
|
||
"mkmjStatus": 2,
|
||
"mkmjStatusName": "正常",
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"passageCount": 5,
|
||
"gateCount": 10,
|
||
"videoCount": 8
|
||
}
|
||
],
|
||
"total": 50,
|
||
"page": 1,
|
||
"pageSize": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
**实现逻辑：**
|
||
1. 根据条件动态构建查询语句
|
||
2. `hgAuthAreaName`、`mkmjTypeName`、`mkmjStatusName` 根据数据字典转换
|
||
3. 仅查询 `delete_enum = 'FALSE'` 的记录
|
||
4. passageCount、gateCount、videoCount 是统计的相关联的表统计出来的。
|
||
|
||
---
|
||
|
||
### 3.2 获取口门详情
|
||
|
||
**接口：** `GET /api/mkmj/detail/{id}`
|
||
|
||
**描述：** 获取口门详细信息及关联设备统计
|
||
|
||
**路径参数：**
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 口门 ID |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 101,
|
||
"mkmjName": "一号口门",
|
||
"hgAuthArea": "qianwan",
|
||
"hgAuthAreaName": "前湾港区",
|
||
"mkmjLevel": 1,
|
||
"mkmjLevelName": "一级",
|
||
"mkmjType": "3",
|
||
"mkmjTypeName": "综合",
|
||
"mkmjStatus": 2,
|
||
"mkmjStatusName": "正常",
|
||
"inDirectionArea": null,
|
||
"inDirectionAreaName": null,
|
||
"outDirectionArea": null,
|
||
"outDirectionAreaName": null,
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"remarks": "备注信息",
|
||
"createName": "管理员",
|
||
"createTime": "2026-03-01 10:00:00",
|
||
"updateName": "管理员",
|
||
"updateTime": "2026-03-05 14:30:00"
|
||
|
||
}
|
||
}
|
||
```
|
||
|
||
**实现逻辑：**
|
||
1. 查询口门基本信息
|
||
2. 统计关联的通道、闸机、摄像头数量（`delete_enum = 'FALSE'`）
|
||
3. 数据字典字段转换名称
|
||
|
||
---
|
||
|
||
### 3.3 新增口门
|
||
|
||
**接口：** `POST /api/mkmj/add`
|
||
|
||
**描述：** 新增口门信息
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"mkmjName": "一号口门",
|
||
"hgAuthArea": "qianwan",
|
||
"hgAuthAreaName": "前湾港区",
|
||
"mkmjLevel": 1,
|
||
"mkmjType": "3",
|
||
"mkmjStatus": 2,
|
||
"inDirectionArea": null,
|
||
"inDirectionAreaName": null,
|
||
"outDirectionArea": null,
|
||
"outDirectionAreaName": null,
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"remarks": "备注信息"
|
||
}
|
||
```
|
||
|
||
**请求参数说明：**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| mkmjName | String | 是 | 口门名称，2-50 字符 |
|
||
| hgAuthArea | String | 是 | 所属港区编码 |
|
||
| hgAuthAreaName | String | 是 | 所属港区名称 |
|
||
| mkmjLevel | Integer | 是 | 口门级别：1-一级，2-二级 |
|
||
| mkmjType | String | 是 | 口门类型：1-人行，2-车行，3-综合 |
|
||
| mkmjStatus | Integer | 是 | 口门状态：1-停用，2-正常，3-暂时管理 |
|
||
| inDirectionArea | Long | 否 | 入方向区域 ID |
|
||
| inDirectionAreaName | String | 否 | 入方向区域名称 |
|
||
| outDirectionArea | Long | 否 | 出方向区域 ID |
|
||
| outDirectionAreaName | String | 否 | 出方向区域名称 |
|
||
| longitude | String | 是 | 经度，-180~180 |
|
||
| latitude | String | 是 | 纬度，-90~90 |
|
||
| remarks | String | 否 | 备注，≤255 字符 |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 101
|
||
}
|
||
}
|
||
```
|
||
|
||
**实现逻辑：**
|
||
1. 校验必填参数
|
||
|
||
---
|
||
|
||
### 3.4 编辑口门
|
||
|
||
**接口：** `PUT /api/mkmj/update`
|
||
|
||
**描述：** 编辑口门信息
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"id": 101,
|
||
"mkmjName": "一号口门",
|
||
"hgAuthArea": "qianwan",
|
||
"hgAuthAreaName": "前湾港区",
|
||
"mkmjLevel": 1,
|
||
"mkmjType": "3",
|
||
"mkmjStatus": 2,
|
||
"inDirectionArea": null,
|
||
"inDirectionAreaName": null,
|
||
"outDirectionArea": null,
|
||
"outDirectionAreaName": null,
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"remarks": "更新备注"
|
||
}
|
||
```
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success"
|
||
}
|
||
```
|
||
|
||
**实现逻辑：**
|
||
1. 校验 ID 存在性
|
||
2. 校验口门名称唯一性（排除当前记录）
|
||
3. 校验经度、纬度范围
|
||
4. 填充更新字段：
|
||
- `update_time` = 当前时间
|
||
- `update_id` = 当前用户 ID
|
||
- `update_name` = 当前用户姓名
|
||
5. 更新数据库
|
||
|
||
---
|
||
|
||
### 3.5 删除口门
|
||
|
||
**接口：** `DELETE /api/mkmj/delete/{id}`
|
||
|
||
**描述：** 删除口门（软删除），同步停用关联设备
|
||
|
||
**路径参数：**
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 口门 ID |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success"
|
||
}
|
||
```
|
||
|
||
**实现逻辑：**
|
||
1. 校验 ID 存在性
|
||
2. 检查关联数据：
|
||
- 查询关联通道数量（`mkmj_passage`，`mkmj_id = id`，`delete_enum = 'FALSE'`）
|
||
- 查询关联闸机数量（`mkmj_gate`，`mkmj_id = id`，`delete_enum = 'FALSE'`）
|
||
- 查询关联摄像头数量（`video`，`foreign_id = id`，`device_type = 1`，`delete_enum = 'FALSE'`）
|
||
- 查询关联审批人数量（`mkmj_approval_user`，`mkmj_id = id`，`delete_enum = 'FALSE'`）
|
||
3. 如存在关联数据，返回错误码 `2002` 及关联详情
|
||
4. 执行软删除：`update mkmj set delete_enum = 'TRUE' where id = ?`
|
||
5. 同步停用关联的通道、闸机、摄像头（更新 `delete_enum = 'TRUE'`）
|
||
6. 记录操作日志
|
||
|
||
**错误响应（有关联数据时）：**
|
||
```json
|
||
{
|
||
"code": 2002,
|
||
"message": "该口门下有关联数据，无法删除",
|
||
"data": {
|
||
"passageCount": 5,
|
||
"gateCount": 10,
|
||
"videoCount": 8,
|
||
"approvalUserCount": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.6 口门名称唯一性校验
|
||
|
||
**接口：** `GET /api/mkmj/check-name`
|
||
|
||
**描述：** 校验口门名称是否重复
|
||
|
||
**请求参数：**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| mkmjName | String | 是 | 口门名称 |
|
||
| id | Long | 否 | 当前口门 ID（编辑时传） |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"available": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**实现逻辑：**
|
||
1. 查询 `mkmj` 表，条件：`mkmjName = ?` AND `delete_enum = 'FALSE'`
|
||
2. 如传入 `id`，则排除该记录：`AND id != ?`
|
||
3. 查询结果为空则 `available = true`，否则 `available = false`
|
||
|
||
---
|
||
|
||
## 四、通道管理接口
|
||
|
||
### 4.1 查询通道列表
|
||
|
||
**接口：** `GET /api/mkmj/passage/list`
|
||
|
||
**描述：** 分页查询通道列表，支持按口门筛选
|
||
|
||
**请求参数：**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| page | int | 是 | 页码，默认 1 |
|
||
| pageSize | int | 是 | 每页条数，默认 20 |
|
||
| mkmjId | Long | 否 | 口门 ID |
|
||
| passageName | String | 否 | 通道名称，模糊查询 |
|
||
| passageType | Integer | 否 | 通道类型 |
|
||
| passageStatus | Integer | 否 | 通道状态 |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 1001,
|
||
"mkmjId": 101,
|
||
"mkmjName": "一号口门",
|
||
"passageName": "A 通道",
|
||
"passageType": 1,
|
||
"passageTypeName": "人行",
|
||
"passageStatus": 2,
|
||
"passageStatusName": "正常",
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"createName": "管理员",
|
||
"createTime": "2026-03-01 10:00:00"
|
||
}
|
||
],
|
||
"total": 50,
|
||
"page": 1,
|
||
"pageSize": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.2 获取通道详情
|
||
|
||
**接口：** `GET /api/mkmj/passage/detail/{id}`
|
||
|
||
**描述：** 获取通道详细信息
|
||
|
||
**路径参数：**
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 通道 ID |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1001,
|
||
"mkmjId": 101,
|
||
"mkmjName": "一号口门",
|
||
"passageName": "A 通道",
|
||
"passageType": 1,
|
||
"passageTypeName": "人行",
|
||
"passageStatus": 2,
|
||
"passageStatusName": "正常",
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"remarks": "备注信息",
|
||
"createName": "管理员",
|
||
"createTime": "2026-03-01 10:00:00",
|
||
"updateName": "管理员",
|
||
"updateTime": "2026-03-05 14:30:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.3 新增通道
|
||
|
||
**接口：** `POST /api/mkmj/passage/add`
|
||
|
||
**描述：** 新增通道信息
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"mkmjId": 101,
|
||
"passageName": "A 通道",
|
||
"passageType": 1,
|
||
"passageStatus": 2,
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"remarks": "备注信息"
|
||
}
|
||
```
|
||
|
||
**请求参数说明：**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| mkmjId | Long | 是 | 所属口门 ID |
|
||
| passageName | String | 是 | 通道名称，2-50 字符 |
|
||
| passageType | Integer | 是 | 通道类型：1-人行，2-车行，3-综合 |
|
||
| passageStatus | Integer | 是 | 通道状态：1-停用，2-正常 |
|
||
| longitude | String | 否 | 经度 |
|
||
| latitude | String | 否 | 纬度 |
|
||
| remarks | String | 否 | 备注，≤255 字符 |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1001
|
||
}
|
||
}
|
||
```
|
||
|
||
**实现逻辑：**
|
||
1. 校验必填参数
|
||
2. 校验口门 ID 存在性（`mkmj` 表，`delete_enum = 'FALSE'`）
|
||
3. 校验通道名称在同一口门下唯一
|
||
4. 填充公共字段
|
||
5. 插入数据库
|
||
|
||
---
|
||
|
||
### 4.4 编辑通道
|
||
|
||
**接口：** `PUT /api/mkmj/passage/update`
|
||
|
||
**描述：** 编辑通道信息
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"id": 1001,
|
||
"mkmjId": 101,
|
||
"passageName": "A 通道",
|
||
"passageType": 1,
|
||
"passageStatus": 2,
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"remarks": "更新备注"
|
||
}
|
||
```
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.5 删除通道
|
||
|
||
**接口：** `DELETE /api/mkmj/passage/delete/{id}`
|
||
|
||
**描述：** 删除通道（软删除），同步停用关联闸机
|
||
|
||
**路径参数：**
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 通道 ID |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success"
|
||
}
|
||
```
|
||
|
||
**实现逻辑：**
|
||
1. 校验 ID 存在性
|
||
2. 检查关联的闸机数量（`mkmj_gate`，`passage_id = id`，`delete_enum = 'FALSE'`）
|
||
3. 如存在关联闸机，返回错误
|
||
4. 执行软删除
|
||
5. 同步停用关联的闸机
|
||
|
||
---
|
||
|
||
### 4.6 按口门查询通道列表（简化版）
|
||
|
||
**接口：** `GET /api/mkmj/passage/by-mkmj/{mkmjId}`
|
||
|
||
**描述：** 获取指定口门下的所有通道（用于下拉选择）
|
||
|
||
**路径参数：**
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| mkmjId | Long | 口门 ID |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"id": 1001,
|
||
"passageName": "A 通道",
|
||
"passageType": 1,
|
||
"passageTypeName": "人行"
|
||
},
|
||
{
|
||
"id": 1002,
|
||
"passageName": "B 通道",
|
||
"passageType": 2,
|
||
"passageTypeName": "车行"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、闸机管理接口
|
||
|
||
### 5.1 查询闸机列表
|
||
|
||
**接口：** `GET /api/mkmj/gate/list`
|
||
|
||
**描述：** 分页查询闸机列表，支持按口门、通道筛选
|
||
|
||
**请求参数：**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| page | int | 是 | 页码，默认 1 |
|
||
| pageSize | int | 是 | 每页条数，默认 20 |
|
||
| mkmjId | Long | 否 | 口门 ID |
|
||
| passageId | String | 否 | 通道 ID |
|
||
| gateName | String | 否 | 闸机名称，模糊查询 |
|
||
| gateType | String | 否 | 闸机类型 |
|
||
| gateStatus | Integer | 否 | 闸机状态 |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 2001,
|
||
"mkmjId": 101,
|
||
"mkmjName": "一号口门",
|
||
"passageId": "1001",
|
||
"passageName": "A 通道",
|
||
"gateNumber": "GATE-001",
|
||
"gateName": "1 号闸机",
|
||
"gateType": "1",
|
||
"gateTypeName": "人行闸机",
|
||
"gateStatus": 2,
|
||
"gateStatusName": "正常",
|
||
"gateCategory": "tripod",
|
||
"gateCategoryName": "三辊闸",
|
||
"gateModel": "ZK-100",
|
||
"gatePosition": "入口处",
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"createName": "管理员",
|
||
"createTime": "2026-03-01 10:00:00"
|
||
}
|
||
],
|
||
"total": 100,
|
||
"page": 1,
|
||
"pageSize": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.2 获取闸机详情
|
||
|
||
**接口：** `GET /api/mkmj/gate/detail/{id}`
|
||
|
||
**描述：** 获取闸机详细信息
|
||
|
||
**路径参数：**
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 闸机 ID |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 2001,
|
||
"mkmjId": 101,
|
||
"mkmjName": "一号口门",
|
||
"passageId": "1001",
|
||
"passageName": "A 通道",
|
||
"gateNumber": "GATE-001",
|
||
"gateName": "1 号闸机",
|
||
"gateType": "1",
|
||
"gateTypeName": "人行闸机",
|
||
"gateStatus": 2,
|
||
"gateStatusName": "正常",
|
||
"gateCategory": "tripod",
|
||
"gateCategoryName": "三辊闸",
|
||
"gateModel": "ZK-100",
|
||
"gatePosition": "入口处",
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"remarks": "备注信息",
|
||
"createName": "管理员",
|
||
"createTime": "2026-03-01 10:00:00",
|
||
"updateName": "管理员",
|
||
"updateTime": "2026-03-05 14:30:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.3 新增闸机
|
||
|
||
**接口：** `POST /api/mkmj/gate/add`
|
||
|
||
**描述：** 新增闸机信息
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"mkmjId": 101,
|
||
"passageId": "1001",
|
||
"gateNumber": "GATE-001",
|
||
"gateName": "1 号闸机",
|
||
"gateType": "1",
|
||
"gateStatus": 2,
|
||
"gateCategory": "tripod",
|
||
"gateCategoryName": "三辊闸",
|
||
"gateModel": "ZK-100",
|
||
"gatePosition": "入口处",
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"remarks": "备注信息"
|
||
}
|
||
```
|
||
|
||
**请求参数说明：**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| mkmjId | Long | 是 | 所属口门 ID |
|
||
| passageId | String | 是 | 所属通道 ID |
|
||
| gateNumber | String | 是 | 闸机标识，唯一 |
|
||
| gateName | String | 是 | 闸机名称，2-50 字符 |
|
||
| gateType | String | 是 | 闸机类型 |
|
||
| gateStatus | Integer | 是 | 闸机状态：1-停用，2-正常 |
|
||
| gateCategory | String | 否 | 闸机类别编码 |
|
||
| gateCategoryName | String | 否 | 闸机类别名称 |
|
||
| gateModel | String | 否 | 闸机型号，≤255 字符 |
|
||
| gatePosition | String | 否 | 闸机位置，≤255 字符 |
|
||
| longitude | String | 否 | 经度 |
|
||
| latitude | String | 否 | 纬度 |
|
||
| remarks | String | 否 | 备注，≤255 字符 |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 2001
|
||
}
|
||
}
|
||
```
|
||
|
||
**实现逻辑：**
|
||
1. 校验必填参数
|
||
2. 校验口门 ID 存在性
|
||
3. 校验通道 ID 存在性（且属于该口门）
|
||
4. 校验闸机标识唯一性（`gateNumber`）
|
||
5. 填充公共字段
|
||
6. 插入数据库
|
||
|
||
---
|
||
|
||
### 5.4 编辑闸机
|
||
|
||
**接口：** `PUT /api/mkmj/gate/update`
|
||
|
||
**描述：** 编辑闸机信息
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"id": 2001,
|
||
"mkmjId": 101,
|
||
"passageId": "1001",
|
||
"gateNumber": "GATE-001",
|
||
"gateName": "1 号闸机",
|
||
"gateType": "1",
|
||
"gateStatus": 2,
|
||
"gateCategory": "tripod",
|
||
"gateCategoryName": "三辊闸",
|
||
"gateModel": "ZK-100",
|
||
"gatePosition": "入口处",
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"remarks": "更新备注"
|
||
}
|
||
```
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.5 删除闸机
|
||
|
||
**接口：** `DELETE /api/mkmj/gate/delete/{id}`
|
||
|
||
**描述：** 删除闸机（软删除），同步停用关联摄像头
|
||
|
||
**路径参数：**
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 闸机 ID |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success"
|
||
}
|
||
```
|
||
|
||
**实现逻辑：**
|
||
1. 校验 ID 存在性
|
||
2. 检查关联的摄像头数量（`video`，`foreign_id = id`，`device_type = 2`，`delete_enum = 'FALSE'`）
|
||
3. 如存在关联摄像头，返回错误
|
||
4. 执行软删除
|
||
5. 同步停用关联的摄像头
|
||
|
||
---
|
||
|
||
### 5.6 闸机标识唯一性校验
|
||
|
||
**接口：** `GET /api/mkmj/gate/check-number`
|
||
|
||
**描述：** 校验闸机标识是否重复
|
||
|
||
**请求参数：**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| gateNumber | String | 是 | 闸机标识 |
|
||
| id | Long | 否 | 当前闸机 ID（编辑时传） |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"available": true
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5.7 按口门/通道查询闸机列表（简化版）
|
||
|
||
**接口：** `GET /api/mkmj/gate/by-passage`
|
||
|
||
**描述：** 获取指定通道下的所有闸机（用于下拉选择）
|
||
|
||
**请求参数：**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| passageId | String | 是 | 通道 ID |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"id": 2001,
|
||
"gateNumber": "GATE-001",
|
||
"gateName": "1 号闸机",
|
||
"gateType": "1",
|
||
"gateTypeName": "人行闸机"
|
||
},
|
||
{
|
||
"id": 2002,
|
||
"gateNumber": "GATE-002",
|
||
"gateName": "2 号闸机",
|
||
"gateType": "1",
|
||
"gateTypeName": "人行闸机"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、摄像头管理接口
|
||
|
||
### 6.1 查询摄像头列表
|
||
|
||
**接口：** `GET /api/mkmj/video/list`
|
||
|
||
**描述：** 分页查询摄像头列表，支持按口门、闸机筛选
|
||
|
||
**请求参数：**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| page | int | 是 | 页码，默认 1 |
|
||
| pageSize | int | 是 | 每页条数，默认 20 |
|
||
| foreignId | Long | 否 | 关联 ID（口门 ID 或闸机 ID） |
|
||
| deviceType | Integer | 否 | 设备类型：1-口门，2-闸机 |
|
||
| videoResourceName | String | 否 | 摄像头名称，模糊查询 |
|
||
| videoType | Integer | 否 | 摄像头类型 |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"id": 3001,
|
||
"foreignId": 101,
|
||
"deviceType": 1,
|
||
"deviceTypeName": "口门",
|
||
"videoResourceId": "CAM-001",
|
||
"videoResourceName": "1 号口门摄像头",
|
||
"videoType": 2,
|
||
"videoTypeName": "平台",
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"createName": "管理员",
|
||
"createTime": "2026-03-01 10:00:00"
|
||
}
|
||
],
|
||
"total": 200,
|
||
"page": 1,
|
||
"pageSize": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6.2 获取摄像头详情
|
||
|
||
**接口：** `GET /api/mkmj/video/detail/{id}`
|
||
|
||
**描述：** 获取摄像头详细信息
|
||
|
||
**路径参数：**
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 摄像头 ID |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 3001,
|
||
"foreignId": 101,
|
||
"deviceType": 1,
|
||
"deviceTypeName": "口门",
|
||
"mkmjName": "一号口门",
|
||
"gateName": null,
|
||
"videoResourceId": "CAM-001",
|
||
"videoResourceName": "1 号口门摄像头",
|
||
"videoType": 2,
|
||
"videoTypeName": "平台",
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"remarks": "备注信息",
|
||
"createName": "管理员",
|
||
"createTime": "2026-03-01 10:00:00",
|
||
"updateName": "管理员",
|
||
"updateTime": "2026-03-05 14:30:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6.3 新增摄像头
|
||
|
||
**接口：** `POST /api/mkmj/video/add`
|
||
|
||
**描述：** 新增摄像头信息
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"foreignId": 101,
|
||
"deviceType": 1,
|
||
"videoResourceId": "CAM-001",
|
||
"videoResourceName": "1 号口门摄像头",
|
||
"videoType": 2,
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"remarks": "备注信息"
|
||
}
|
||
```
|
||
|
||
**请求参数说明：**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| foreignId | Long | 是 | 关联 ID（口门 ID 或闸机 ID） |
|
||
| deviceType | Integer | 是 | 设备类型：1-口门，2-闸机 |
|
||
| videoResourceId | String | 是 | 摄像头 ID，唯一 |
|
||
| videoResourceName | String | 是 | 摄像头名称，2-50 字符 |
|
||
| videoType | Integer | 是 | 摄像头类型：1-移动，2-平台 |
|
||
| longitude | String | 否 | 经度 |
|
||
| latitude | String | 否 | 纬度 |
|
||
| remarks | String | 否 | 备注，≤255 字符 |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 3001
|
||
}
|
||
}
|
||
```
|
||
|
||
**实现逻辑：**
|
||
1. 校验必填参数
|
||
2. 校验关联 ID 存在性（根据 `deviceType` 查询 `mkmj` 或 `mkmj_gate` 表）
|
||
3. 校验摄像头 ID 唯一性（`videoResourceId`）
|
||
4. 填充公共字段
|
||
5. 插入数据库
|
||
|
||
---
|
||
|
||
### 6.4 编辑摄像头
|
||
|
||
**接口：** `PUT /api/mkmj/video/update`
|
||
|
||
**描述：** 编辑摄像头信息
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"id": 3001,
|
||
"foreignId": 101,
|
||
"deviceType": 1,
|
||
"videoResourceId": "CAM-001",
|
||
"videoResourceName": "1 号口门摄像头",
|
||
"videoType": 2,
|
||
"longitude": "120.123456",
|
||
"latitude": "36.123456",
|
||
"remarks": "更新备注"
|
||
}
|
||
```
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6.5 删除摄像头
|
||
|
||
**接口：** `DELETE /api/mkmj/video/delete/{id}`
|
||
|
||
**描述：** 删除摄像头（软删除）
|
||
|
||
**路径参数：**
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 摄像头 ID |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success"
|
||
}
|
||
```
|
||
|
||
**实现逻辑：**
|
||
1. 校验 ID 存在性
|
||
2. 执行软删除：`update video set delete_enum = 'TRUE' where id = ?`
|
||
|
||
---
|
||
|
||
### 6.6 摄像头 ID 唯一性校验
|
||
|
||
**接口：** `GET /api/mkmj/video/check-id`
|
||
|
||
**描述：** 校验摄像头 ID 是否重复
|
||
|
||
**请求参数：**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| videoResourceId | String | 是 | 摄像头 ID |
|
||
| id | Long | 否 | 当前摄像头 ID（编辑时传） |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"available": true
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6.7 按设备查询摄像头列表（简化版）
|
||
|
||
**接口：** `GET /api/mkmj/video/by-device`
|
||
|
||
**描述：** 获取指定设备下的所有摄像头（用于展示或下拉选择）
|
||
|
||
**请求参数：**
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| foreignId | Long | 是 | 关联 ID（口门 ID 或闸机 ID） |
|
||
| deviceType | Integer | 是 | 设备类型：1-口门，2-闸机 |
|
||
|
||
**响应数据：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"id": 3001,
|
||
"videoResourceId": "CAM-001",
|
||
"videoResourceName": "1 号摄像头",
|
||
"videoType": 2,
|
||
"videoTypeName": "平台"
|
||
},
|
||
{
|
||
"id": 3002,
|
||
"videoResourceId": "CAM-002",
|
||
"videoResourceName": "2 号摄像头",
|
||
"videoType": 2,
|
||
"videoTypeName": "平台"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 七、数据校验规则
|
||
|
||
### 7.1 通用校验
|
||
| 字段 | 规则 | 错误码 | 错误提示 |
|
||
|------|------|--------|----------|
|
||
| 名称类字段 | 必填，2-50 字符 | 400 | 名称长度为 2-50 个字符 |
|
||
| 备注 | ≤255 字符 | 400 | 备注长度不能超过 255 字符 |
|
||
| 经度 | -180~180，支持小数 | 400 | 请输入有效的经度（-180~180） |
|
||
| 纬度 | -90~90，支持小数 | 400 | 请输入有效的纬度（-90~90） |
|
||
|
||
### 7.2 口门校验
|
||
| 字段 | 规则 | 错误码 | 错误提示 |
|
||
|------|------|--------|----------|
|
||
| mkmjName | 唯一性 | 2001 | 该口门名称已存在 |
|
||
| mkmjLevel | 固定值校验 | 400 | 口门级别无效 |
|
||
| hgAuthArea | 有效性 | 400 | 所属港区无效 |
|
||
|
||
### 7.3 通道校验
|
||
| 字段 | 规则 | 错误码 | 错误提示 |
|
||
|------|------|--------|----------|
|
||
| mkmjId | 存在性 | 2003 | 所属口门不存在 |
|
||
| passageName | 同口门下唯一 | 2004 | 该口门下通道名称已存在 |
|
||
|
||
### 7.4 闸机校验
|
||
| 字段 | 规则 | 错误码 | 错误提示 |
|
||
|------|------|--------|----------|
|
||
| mkmjId | 存在性 | 2003 | 所属口门不存在 |
|
||
| passageId | 存在性且属于该口门 | 2005 | 所属通道不存在或不属于该口门 |
|
||
| gateNumber | 唯一性 | 2006 | 该闸机标识已存在 |
|
||
|
||
### 7.5 摄像头校验
|
||
| 字段 | 规则 | 错误码 | 错误提示 |
|
||
|------|------|--------|----------|
|
||
| foreignId | 存在性（根据 deviceType） | 2007 | 关联设备不存在 |
|
||
| videoResourceId | 唯一性 | 2008 | 该摄像头 ID 已存在 |
|
||
|
||
---
|
||
|
||
## 八、删除关联检查逻辑
|
||
|
||
### 8.1 删除口门检查
|
||
```sql
|
||
-- 检查关联通道
|
||
SELECT COUNT(*) FROM mkmj_passage WHERE mkmj_id = ? AND delete_enum = 'FALSE';
|
||
|
||
-- 检查关联闸机
|
||
SELECT COUNT(*) FROM mkmj_gate WHERE mkmj_id = ? AND delete_enum = 'FALSE';
|
||
|
||
-- 检查关联摄像头（口门类）
|
||
SELECT COUNT(*) FROM video WHERE foreign_id = ? AND device_type = 1 AND delete_enum = 'FALSE';
|
||
|
||
-- 检查关联审批人
|
||
SELECT COUNT(*) FROM mkmj_approval_user WHERE mkmj_id = ? AND delete_enum = 'FALSE';
|
||
```
|
||
|
||
### 8.2 删除通道检查
|
||
```sql
|
||
-- 检查关联闸机
|
||
SELECT COUNT(*) FROM mkmj_gate WHERE passage_id = ? AND delete_enum = 'FALSE';
|
||
```
|
||
|
||
### 8.3 删除闸机检查
|
||
```sql
|
||
-- 检查关联摄像头（闸机类）
|
||
SELECT COUNT(*) FROM video WHERE foreign_id = ? AND device_type = 2 AND delete_enum = 'FALSE';
|
||
```
|
||
|
||
---
|
||
|
||
## 九、错误码定义
|
||
|
||
---
|
||
|
||
## 十、公共字段处理
|
||
|
||
### 10.1 查询条件
|
||
所有列表查询必须附加条件：`delete_enum = 'FALSE'`
|
||
|
||
---
|
||
|
||
## 十一、实现注意事项
|
||
|
||
### 11.1 事务处理
|
||
- 新增、编辑、删除操作需使用事务
|
||
- 删除口门时，同步停用关联数据需在同一事务中完成
|
||
|
||
### 11.2 级联删除
|
||
- 删除口门 → 停用通道、闸机、摄像头、审批人
|
||
- 删除通道 → 停用闸机
|
||
- 删除闸机 → 停用摄像头
|
||
|
||
### 11.4 性能优化
|
||
- 列表查询使用分页
|
||
|
||
### 11.5 日志记录
|
||
- 关键操作（新增、编辑、删除）记录操作日志
|
||
- 日志内容：操作人、操作时间、操作类型、操作对象 ID、变更内容
|
||
|
||
---
|
||
|
||
## 十二、附录
|
||
|
||
### 12.1 相关文档
|
||
|
||
|
||
### 12.2 表结构参考
|
||
- `mkmj` - 门口信息管理表
|
||
- `mkmj_passage` - 口门门禁通道表
|
||
- `mkmj_gate` - 门口闸机表
|
||
- `video` - 摄像头表
|
||
|
||
---
|
||
|
||
**文档版本：** V1.0
|
||
**最后更新：** 2026-03-09
|