<!--
* @Author: donghao donghao@supervision.ltd
* @Date: 2025-03-11 14:18:06
* @LastEditors: donghao donghao@supervision.ltd
* @LastEditTime: 2025-03-11 14:35:45
* @FilePath: \5G-Loading-Bay-Web\api.md
* @Description: 接口备注文档
-->
# 系统接口文档
## 一、登录模块（Login）
### 1.1 用户登录接口
- **接口地址**：/api/login
- **请求方式**：POST
- **请求参数**：
| 参数名 | 类型 | 是否必填 | 说明 |
|----------|--------|----------|--------------|
| username | string | 是 | 用户账号 |
| password | string | 是 | 登录密码 |
- **响应示例**：
```json
{
"code": 200,
"message": "登录成功",
"data": {
"token": "xxx-xxx-xxx" // 登录成功返回的 token
}
}
```
### 1.2 用户登录接口
- **接口地址**：/api/logout
- **请求方式**：POST
- **请求参数**：
| 参数名 | 类型 | 是否必填 | 说明 |
|----------|--------|----------|--------------|
| token | string | 是 | 登录成功返回的 token |
- **响应示例**：
```json
{
"code": 200,
}
```
# 检测总量汇总接口文档
## 1. 接口基本信息
- **接口名称**：获取检测总量汇总数据
- **请求方法**：`GET`
- **接口路径**：`/api/detection/summary`
- **功能描述**：根据传入的时间类型（月/周），获取检测时间、车体检测数量、撑杆检测数量的汇总数据，用于展示柱状图。
## 2. 请求参数
| 参数名 | 类型 | 是否必填 | 描述 | 示例值 |
|-----------|--------|----------|--------------------------|--------|
| dateType | string | 是 | 时间类型，取值`月`或`周` | 月 |
## 3. 响应参数
| 参数名 | 类型 | 描述 |
|-------------------|---------|--------------------------|
| code | number | 状态码，`200`表示成功 |
| message | string | 提示信息，如成功或失败描述 |
| data | object | 响应数据主体 |
| ├─ dateArr | array | 所有时间的汇总数组 |
| ├─ vehicleDetection| array | 所有车辆检测数量汇总数组 |
| ├─ poleDetection | array | 所有撑杆检测数量汇总数组 |
## 4. 响应示例
```json
{
"code": 200,
"message": "获取检测总量汇总数据成功",
"data": {
"dateArr": ["1月", "2月", "3月", "4月", "5月", "6月"],
"vehicleDetection": [220, 220, 170, 190, 160, 250],
"poleDetection": [80, 150, 80, 100, 200, 80]
}
}
```
# 设备信息接口文档
## 1. 接口基本信息
- **接口名称**：获取设备信息数据
- **请求方法**：`GET`
- **接口路径**：`/api/device/info`
- **功能描述**：获取设备总数，以及车体检测、撑杆检测、钩机检测设备的总量，同时包含各类设备的在线、离线、故障数量状态。
## 2. 请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|--------|--------|----------|--------------|
| 无 | 无 | 无 | 无请求参数 |
## 3. 响应参数
| 参数分类 | 参数名 | 类型 | 描述 |
|----------------------|---------------------------|---------|--------------------------|
| **设备总数** | deviceTotal | number | 设备总数 |
| **车体检测设备** | vehicleDetectionDevice | number | 车体检测设备总量 |
| **车体检测状态** | vehicleStatus | object | 车体检测设备状态信息 |
| ├─ 在线数量 | ├─ onlineCount | number | 车体检测设备在线数量 |
| ├─ 离线数量 | ├─ outlineCount | number | 车体检测设备离线数量 |
| ├─ 故障数量 | ├─ errorCount | number | 车体检测设备故障数量 |
| **撑杆检测设备** | poleDetectionDevice | number | 撑杆检测设备总量 |
| **撑杆检测状态** | poleStatus | object | 撑杆检测设备状态信息 |
| ├─ 在线数量 | ├─ onlineCount | number | 撑杆检测设备在线数量 |
| ├─ 离线数量 | ├─ outlineCount | number | 撑杆检测设备离线数量 |
| ├─ 故障数量 | ├─ errorCount | number | 撑杆检测设备故障数量 |
| **钩机检测设备** | machineDetectionDevice | number | 钩机检测设备总量 |
| **钩机检测状态** | machineStatus | object | 钩机检测设备状态信息 |
| ├─ 在线数量 | ├─ onlineCount | number | 钩机检测设备在线数量 |
| ├─ 离线数量 | ├─ outlineCount | number | 钩机检测设备离线数量 |
| ├─ 故障数量 | ├─ errorCount | number | 钩机检测设备故障数量 |
## 4. 响应示例
```json
{
"code": 200,
"message": "获取设备信息成功",
"data": {
"deviceTotal": 37,
"vehicleDetectionDevice": 12,
"vehicleStatus": {
"onlineCount": 8,
"outlineCount": 2,
"errorCount": 2
},
"poleDetectionDevice": 10,
"poleStatus": {
"onlineCount": 9,
"outlineCount": 1,
"errorCount": 0
},
"machineDetectionDevice": 15,
"machineStatus": {
"onlineCount": 8,
"outlineCount": 2,
"errorCount": 2
}
}
}
```
# 车体检测问题分布接口文档
## 1. 接口基本信息
- **接口名称**：获取车体检测问题分布数据
- **请求方法**：`GET`
- **接口路径**：`/api/vehicle/detection/problem/distribution`
- **功能描述**：根据传入的时间类型，获取车体检测的问题类型及对应占比数据，用于展示饼图。
## 2. 请求参数
| 参数名 | 类型 | 是否必填 | 描述 | 示例值 |
|-----------|--------|----------|----------------------|--------|
| dateType | string | 是 | 时间类型（如月份） | 1月 |
## 3. 响应参数
| 参数名 | 类型 | 描述 |
|----------|---------|--------------------------|
| code | number | 状态码，`200`表示成功 |
| message | string | 提示信息（成功或失败描述） |
| data | array | 车体检测问题分布数据数组 |
| ├─ name | string | 问题类型（如搭扣未搭） |
| ├─ value | number | 问题占比数值（非百分制） |
## 4. 响应示例
```json
{
"code": 200,
"message": "获取车体检测问题分布数据成功",
"data": [
{ "name": "搭扣未搭", "value": 25 },
{ "name": "下侧门板缺失", "value": 35 },
{ "name": "小门搭扣丢失", "value": 15 },
{ "name": "门折页座脱落", "value": 15 },
{ "name": "小门外胀", "value": 10 },
{ "name": "小窗裂纹", "value": 5 }
]
}
```
# 撑杆检测问题分布接口文档
## 1. 接口基本信息
- **接口名称**：获取撑杆检测问题分布数据
- **请求方法**：`GET`
- **接口路径**：`/api/pole/detection/problem/distribution`
- **功能描述**：根据传入的时间类型，获取撑杆检测的问题类型及对应占比数据，用于展示饼图。
## 2. 请求参数
| 参数名 | 类型 | 是否必填 | 描述 | 示例值 |
|-----------|--------|----------|----------------------|--------|
| dateType | string | 是 | 时间类型（如月份） | 1月 |
## 3. 响应参数
| 参数名 | 类型 | 描述 |
|----------|---------|--------------------------|
| code | number | 状态码，`200`表示成功 |
| message | string | 提示信息（成功或失败描述） |
| data | array | 撑杆检测问题分布数据数组 |
| ├─ name | string | 问题类型（如撑杆断折） |
| ├─ value | number | 问题占比数值（非百分制） |
## 4. 响应示例
```json
{
"code": 200,
"message": "获取撑杆检测问题分布数据成功",
"data": [
{ "name": "撑杆断折", "value": 65 },
{ "name": "撑杆弯曲", "value": 35 }
]
}
```
# 实时监控画面接口文档
## 1. 接口基本信息
- **接口名称**：获取实时监控画面
- **请求方法**：`GET`
- **接口路径**：`/api/realTime/monitor`
- **功能描述**：获取实时监控画面数据，展示设备状态及问题（如搭扣未搭、撑杆断裂等）。
## 2. 请求参数
| 参数名 | 类型 | 是否必填 | 描述 | 示例值 |
|--------------|--------|----------|--------------------------|--------------|
| deviceType | string | 否 | 设备类型（如车体、撑杆） | vehicle |
## 3. 响应参数
| 参数名 | 类型 | 描述 |
|----------------|---------|--------------------------|
| code | number | 状态码，`200`表示成功 |
| message | string | 提示信息（如成功或失败） |
| data | array | 监控画面数据数组 |
| ├─ imageUrl | string | 监控画面图片/视频URL |
| ├─ problemDesc | string | 问题描述（如搭扣未搭） |
## 4. 响应示例
```json
{
"code": 200,
"message": "获取实时监控画面成功",
"data": [
{
"imageUrl": "https://example.com/train_vehicle_monitor.jpg",
"problemDesc": "搭扣未搭"
},
{
"imageUrl": "https://example.com/pole_monitor.jpg",
"problemDesc": "撑杆断裂"
}
]
}
```
