Jesxion
6c8760c6c5
- 新增第0章：设备推送协议（认证+统一入口+塔吊4接口+升降机4接口） - 架构图更新：数据流改为厂家主动推送 - 推送地址/appid/secret待部署时配置 - API文档结构重排，H5接口和设备接口分开
464 lines
11 KiB
Markdown
464 lines
11 KiB
Markdown
# 后台 API 接口设计
|
||
|
||
> 状态: 设计中（设备推送协议已确认，待服务器部署地址）
|
||
|
||
---
|
||
|
||
## 0. 设备数据推送协议（厂家 → 后台）
|
||
|
||
> 数据流向：厂家系统 → 我们的后台 API（统一入口 `/input/post/call`）
|
||
|
||
### 0.1 认证接口
|
||
|
||
```
|
||
POST /input/auth/fetch
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"appid": "项目专用appid（TBD）",
|
||
"secret": "项目专用secret（TBD）"
|
||
}
|
||
```
|
||
|
||
**响应** (200):
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"appid": "xxx",
|
||
"access_token": "eyJhbGci...",
|
||
"expires_in": 7200
|
||
}
|
||
}
|
||
```
|
||
|
||
> `access_token` 有效期 2 小时，后续调用统一推送接口时需在 Header 携带 `Authorization: Bearer <access_token>`
|
||
|
||
### 0.2 统一推送接口
|
||
|
||
厂家所有数据通过此接口推送，`path` 指定具体业务接口：
|
||
|
||
```
|
||
POST /input/post/call
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"path": "/towercranedataservice/pushRealTimeInfo",
|
||
"data": { /* 具体接口的参数对象 */ }
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 0.3 塔吊接口（towercranedataservice）
|
||
|
||
#### 3.1 基础信息 `pushBasicInfo`
|
||
|
||
| 参数 | 类型 | 必须 | 说明 |
|
||
|------|------|------|------|
|
||
| deviceSN | C50 | 是 | 设备序列号 |
|
||
| deviceID | C50 | 否 | 设备ID |
|
||
| deviceAuthCode | C50 | 否 | 设备授权码 |
|
||
| monitorDateTime | C50 | 是 | 数据发送时间 yyyy-MM-dd HH:mm:ss |
|
||
| craneType | C1 | 是 | 塔机类型：0动臂吊/1塔头平臂吊/2平头平臂吊 |
|
||
| weightSet/windSpeedSet/rangeSet/heightSet/angleSet/obliguitySet/gpsSet/idSet/multiFunSet | C1 | 是 | 各功能配置：0未配置/1已配置 |
|
||
| bodyHeight | N5.2 | 是 | 塔身高度(m) |
|
||
| topHeight | N5.2 | 是 | 塔顶高度 |
|
||
| magnification | N4 | 是 | 绳索倍率 |
|
||
| frontArmLength | N5.2 | 是 | 前臂长 0.00~99.99m |
|
||
| backArmLength | N5.2 | 是 | 尾臂长 |
|
||
| maxWeight | N5.2 | 是 | 最大吊重 0.00~99.99t |
|
||
| ratedWindSpeed | N5.2 | 是 | 额定风速 0.00~36.90m/s |
|
||
| ratedWindLevel | N2 | 是 | 额定风级 0~12级 |
|
||
| minRange/maxRange | N5.2 | 是 | 最小/最大变幅 |
|
||
| maxHeight | N6.2 | 是 | 最大高度 0.00~655.35m |
|
||
| maxAngle | N5.2 | 是 | 最大角度 0.0~540.0° |
|
||
| minAngle | N6.1 | 是 | 最小角度 -540.0°~0.0° |
|
||
| ratedObliguity | N4.2 | 是 | 额定倾角 0.00~9.99° |
|
||
|
||
#### 3.2 实时数据 `pushRealTimeInfo`
|
||
|
||
| 参数 | 类型 | 必须 | 说明 |
|
||
|------|------|------|------|
|
||
| deviceSN | C50 | 是 | 设备序列号 |
|
||
| monitorDateTime | C50 | 是 | 数据发送时间 |
|
||
| name | C20 | 是 | 操作人员姓名 |
|
||
| idNo | C20 | 是 | 操作人员身份证号 |
|
||
| multiple | N2 | 是 | 倍率 0~655% |
|
||
| moment | N10.2 | 是 | 力矩百分比 0.00~655.35% |
|
||
| weight | N5.2 | 是 | 载重 0.00~99.99t |
|
||
| windSpeed | N5.2 | 是 | 风速 0.00~36.90m/s |
|
||
| windLevel | N2 | 是 | 风级 0~12级 |
|
||
| rrange | N5.2 | 是 | 幅度 0.00~99.99m |
|
||
| height | N6.2 | 是 | 高度 0.00~655.35m |
|
||
| angle | N5.1 | 是 | 角度 0.0~359.9° |
|
||
| obliguity | N4.2 | 是 | 倾角 -9.99~9.99° |
|
||
|
||
#### 3.3 工作循环 `pushworkCycleInfo`
|
||
|
||
记录每次吊装作业的完整数据，字段包含：workStartDateTime/workEndDateTime/workWeight/workMaxTorqueRange/workMaxTorque/workMaxWindSpeed/workMaxHeight/workMaxForce 等。
|
||
|
||
#### 3.4 报警信息 `pushAlarmInfo`
|
||
|
||
| 参数 | 类型 | 必须 | 说明 |
|
||
|------|------|------|------|
|
||
| deviceSN | C50 | 是 | 设备序列号 |
|
||
| alarmDateTime | C20 | 是 | 警报时间 |
|
||
| warnType | C20 | 是 | 报警类型：A:高度 B:力矩 C:碰撞 D:风速 E:幅度 F:回转 G:倾角 H:重量 |
|
||
| momentAlarm/collideAlarm/windSpeedAlarm/heightAlarm/rangeAlarm/angleAlarm/obliguityAlarm/weightAlarm | C1 | 是 | 各报警状态：0正常/1报警/2预警 |
|
||
| weight | N5.2 | 是 | 报警时刻载重 |
|
||
| windSpeed | N5.2 | 是 | 报警时刻风速 |
|
||
| range | N5.2 | 是 | 报警时刻幅度 |
|
||
| height | N6.2 | 是 | 报警时刻高度 |
|
||
| tiltAngle | N4.2 | 是 | 倾角 |
|
||
|
||
### 0.4 升降机接口（elevatordataservice）
|
||
|
||
#### 4.1 基础信息 `pushBasicInfo`
|
||
|
||
| 参数 | 类型 | 必须 | 说明 |
|
||
|------|------|------|------|
|
||
| deviceSN | C50 | 是 | 设备序列号 |
|
||
| monitorDateTime | C50 | 是 | 数据发送时间 |
|
||
| craneType | C1 | 是 | 升降机类型：1单笼/2双笼 |
|
||
| idExist/peopleExist/weightExist/speedExist/heightExist/floorExist/obliguityXExist/obliguityYExist/windExist/gpsExist/wirelessExist/topExist/antiDropExist | C1 | 是 | 各功能配置 |
|
||
| ratedPeople | N2 | 是 | 额定运载人数 1~20 |
|
||
| ratedWeight | N4.2 | 是 | 额定载重 0.00~9.99t |
|
||
| ratedUpSpeed/ratedDownSpeed | N4.2 | 是 | 额定上/下行速度 |
|
||
| ratedHeight | N5.1 | 是 | 额定高度 0.0~999.9m |
|
||
| ratedObliguityX/ratedObliguityY | N4.2 | 是 | 额定X/Y轴倾角 |
|
||
| ratedWindSpeed | N5.2 | 是 | 额定风速 |
|
||
| ratedWindLevel | N2 | 是 | 额定风级 |
|
||
|
||
#### 4.2 实时数据 `pushRealTimeInfo`
|
||
|
||
| 参数 | 类型 | 必须 | 说明 |
|
||
|------|------|------|------|
|
||
| deviceSN | C50 | 是 | 设备序列号 |
|
||
| monitorDateTime | C50 | 是 | 数据发送时间 |
|
||
| name | C25 | 是 | 操作人员姓名 |
|
||
| idNo | C18 | 是 | 身份证号 |
|
||
| realtimeWeight | N4.2 | 是 | 实时载重 0.00~9.99t |
|
||
| realtimeSpeed | N4.2 | 是 | 实时运行速度 |
|
||
| realtimeHeight | N5.1 | 是 | 实时高度 0.0~999.9m |
|
||
| realtimeDipX/realtimeDipY | N4.2 | 是 | 实时X/Y倾角 |
|
||
| outDoorStatus | C1 | 是 | 笼门状态：0全部关闭/1全部打开/2内笼门打开/3外笼门打开 |
|
||
|
||
#### 4.3 工作循环 `pushWorkCycleInfo`
|
||
|
||
记录每次运行的完整数据，字段包含：maxPeople/maxWeight/maxSpeed/startHeight/endHeight 等。
|
||
|
||
#### 4.4 报警信息 `pushAlarmInfo`
|
||
|
||
| 参数 | 类型 | 必须 | 说明 |
|
||
|------|------|------|------|
|
||
| deviceSN | C50 | 是 | 设备序列号 |
|
||
| alarmDateTime | C20 | 是 | 警报时间 |
|
||
| alarmType | C20 | 是 | 报警类型：A:高度 B:速度 C:载重 D:人数 E:倾角 F:门状态 G:防坠器 |
|
||
| alarmFloor | N3 | 是 | 报警楼层 0~100 |
|
||
| alarmHeight | N5.2 | 是 | 报警高度 |
|
||
| alarmSpeed | N4.2 | 是 | 报警速度 |
|
||
| alarmWeight | N4.2 | 是 | 报警载重 |
|
||
| alarmDipX/alarmDipY | N4.2 | 是 | 报警X/Y倾角 |
|
||
| outDoorStatus | C1 | 是 | 报警时笼门状态 |
|
||
|
||
---
|
||
|
||
## 1. API 概览（H5 客户端 → 后台 API）
|
||
|
||
- **Base URL**: `https://api.example.com/v1`（部署时配置）
|
||
- **认证**: `Authorization: Bearer <jwt_token>`
|
||
- **数据格式**: JSON
|
||
- **字符编码**: UTF-8
|
||
|
||
---
|
||
|
||
## 2. 认证接口
|
||
|
||
### 2.1 登录
|
||
|
||
```
|
||
POST /auth/login
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"username": "string",
|
||
"password": "string"
|
||
}
|
||
```
|
||
|
||
**响应** (200):
|
||
```json
|
||
{
|
||
"token": "eyJhbGciOiJIUzI1NiIs...",
|
||
"expires_at": "2026-04-15T11:00:00Z",
|
||
"user": {
|
||
"id": 1,
|
||
"username": "admin",
|
||
"role": "admin"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 设备接口
|
||
|
||
### 3.1 获取设备台账列表
|
||
|
||
```
|
||
GET /devices
|
||
```
|
||
|
||
**Query 参数**:
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| type | string | 设备类型: `tower_crane` / `elevator` / 空(全部) |
|
||
| status | string | 在线状态: `online` / `offline` / 空(全部) |
|
||
| page | int | 页码，默认 1 |
|
||
| page_size | int | 每页数量，默认 20 |
|
||
|
||
**响应** (200):
|
||
```json
|
||
{
|
||
"total": 100,
|
||
"page": 1,
|
||
"page_size": 20,
|
||
"items": [
|
||
{
|
||
"id": "device_001",
|
||
"name": "1号塔吊",
|
||
"type": "tower_crane",
|
||
"model": "QTZ500",
|
||
"location": "A区施工现场",
|
||
"status": "online",
|
||
"last_seen": "2026-04-14T10:30:00Z",
|
||
"install_date": "2026-01-15"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 3.2 获取设备实时数据
|
||
|
||
```
|
||
GET /devices/{device_id}/realtime
|
||
```
|
||
|
||
**响应** (200):
|
||
```json
|
||
{
|
||
"device_id": "device_001",
|
||
"timestamp": "2026-04-14T10:30:00Z",
|
||
"data": {
|
||
// 塔吊
|
||
"load": 45.2, // 当前载重 (kN)
|
||
"range": 30.5, // 回转幅度 (m)
|
||
"height": 85.0, // 起升高度 (m)
|
||
"wind_speed": 5.2, // 风速 (m/s)
|
||
"torque": 320.5, // 力矩 (kN·m)
|
||
"angle": 120.5, // 回转角度 (°)
|
||
// 升降机
|
||
"speed": 1.2, // 升降速度 (m/s)
|
||
"floor": 12, // 当前楼层
|
||
"door_status": "closed"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.3 获取设备历史数据
|
||
|
||
```
|
||
GET /devices/{device_id}/history
|
||
```
|
||
|
||
**Query 参数**:
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| start | datetime | 开始时间 ISO8601 |
|
||
| end | datetime | 结束时间 ISO8601 |
|
||
| metric | string | 指标字段名（可选，默认全量） |
|
||
| page | int | 页码 |
|
||
| page_size | int | 每页数量，默认 100 |
|
||
|
||
**响应** (200):
|
||
```json
|
||
{
|
||
"device_id": "device_001",
|
||
"total": 1000,
|
||
"items": [
|
||
{
|
||
"timestamp": "2026-04-14T10:00:00Z",
|
||
"load": 44.8,
|
||
"range": 30.2,
|
||
"height": 84.8
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 预警接口
|
||
|
||
### 4.1 获取预警列表
|
||
|
||
```
|
||
GET /alerts
|
||
```
|
||
|
||
**Query 参数**:
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| device_id | string | 设备ID（可选） |
|
||
| level | string | 预警级别: `warning` / `danger` / 空(全部) |
|
||
| status | string | 处理状态: `unread` / `handled` / `ignored` / 空(全部) |
|
||
| page | int | 页码 |
|
||
| page_size | int | 每页数量，默认 20 |
|
||
|
||
**响应** (200):
|
||
```json
|
||
{
|
||
"total": 50,
|
||
"unread_count": 3,
|
||
"items": [
|
||
{
|
||
"id": "alert_001",
|
||
"device_id": "device_001",
|
||
"device_name": "1号塔吊",
|
||
"level": "danger",
|
||
"message": "载重超限: 当前45.2kN，超过额定值40kN",
|
||
"metric": "load",
|
||
"value": 45.2,
|
||
"created_at": "2026-04-14T10:25:00Z",
|
||
"status": "unread"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 4.2 获取预警详情
|
||
|
||
```
|
||
GET /alerts/{alert_id}
|
||
```
|
||
|
||
### 4.3 处理预警
|
||
|
||
```
|
||
POST /alerts/{alert_id}/handle
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"action": "handled",
|
||
"note": "已现场确认，正常作业"
|
||
}
|
||
```
|
||
|
||
### 4.4 忽略预警
|
||
|
||
```
|
||
POST /alerts/{alert_id}/ignore
|
||
```
|
||
|
||
---
|
||
|
||
## 5. OSS 文件接口
|
||
|
||
> OSS 配置（开发测试）: Bucket=`jesxion-ai-studio`, Region=`oss-cn-beijing`
|
||
|
||
### 5.1 获取上传凭证（预签名 URL）
|
||
|
||
```
|
||
POST /oss/upload-token
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"filename": "report_2026_04.pdf",
|
||
"content_type": "application/pdf"
|
||
}
|
||
```
|
||
|
||
**响应** (200):
|
||
```json
|
||
{
|
||
"upload_url": "https://bucket.oss-cn-beijing.aliyuncs.com/...",
|
||
"object_key": "reports/2026/04/report_xxx.pdf",
|
||
"expires_at": "2026-04-14T11:00:00Z"
|
||
}
|
||
```
|
||
|
||
### 5.2 获取文件下载链接
|
||
|
||
```
|
||
GET /oss/download-url
|
||
```
|
||
|
||
**Query 参数**:
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| object_key | string | OSS 对象路径 |
|
||
|
||
**响应** (200):
|
||
```json
|
||
{
|
||
"download_url": "https://bucket.oss-cn-beijing.aliyuncs.com/...?Signature=...",
|
||
"expires_at": "2026-04-14T12:00:00Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 通用响应格式
|
||
|
||
**成功**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**错误**:
|
||
```json
|
||
{
|
||
"code": 1001,
|
||
"message": "设备不存在",
|
||
"detail": "device_id: device_999 不在系统中"
|
||
}
|
||
```
|
||
|
||
**HTTP 状态码**:
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 成功 |
|
||
| 400 | 参数错误 |
|
||
| 401 | 未认证 |
|
||
| 403 | 无权限 |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 7. 待确认
|
||
|
||
- [x] 预警推送机制 → 轮询（前端每 30s）
|
||
- [x] JWT 有效期 → 7 天
|
||
- [x] JWT Secret 管理 → 环境变量 `JWT_SECRET_KEY`
|
||
- [x] OSS 配置 → Bucket=`jesxion-ai-studio`, Region=`oss-cn-beijing`
|
||
- [x] 数据库 → SQLite（MVP）
|
||
- [x] 设备推送协议 → 河南三农统一推送接口（appid/secret 部署时配置）
|
||
- [ ] 后台 API 公网部署地址（阿里云服务器，部署时配置）
|