zcloud-gbs-primeport/口门信息管理 - 后端需求文档.md

# 口门信息管理 - 后端需求文档

## 一、模块概述

### 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