jesxion/smart-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 确认河南三农推送协议，8个接口完整字段

Browse Source 
- 新增第0章：设备推送协议（认证+统一入口+塔吊4接口+升降机4接口）
- 架构图更新：数据流改为厂家主动推送
- 推送地址/appid/secret待部署时配置
- API文档结构重排，H5接口和设备接口分开
This commit is contained in:
Jesxion
2026-04-14 12:01:34 +08:00
parent 7b71edf17a
commit 6c8760c6c5
3 changed files with 179 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
SPEC.md
View File

@@ -39,7 +39,7 @@
| H5 前端 | 原生 HTML/CSS/JS，无框架依赖 | | H5 前端 | 原生 HTML/CSS/JS，无框架依赖 |
| 数据库 | SQLite（MVP 阶段） | | 数据库 | SQLite（MVP 阶段） |
| 文件存储 | 阿里云 OSS（Bucket: jesxion-ai-studio, Region: oss-cn-beijing） | | 文件存储 | 阿里云 OSS（Bucket: jesxion-ai-studio, Region: oss-cn-beijing） |
| 设备数据 | 已有第三方 API（塔吊/升降机） | | 设备数据 | 河南三农厂家系统推送（统一推送接口 POST /input/post/call） |
### 文档更新记录 ### 文档更新记录
@@ -49,3 +49,4 @@
| 2026-04-14 | v0.1.1 | 锁定预警轮询、JWT 7天、OSS Bucket 配置 | | 2026-04-14 | v0.1.1 | 锁定预警轮询、JWT 7天、OSS Bucket 配置 |
| 2026-04-14 | v0.1.2 | 锁定 SQLite 数据库 | | 2026-04-14 | v0.1.2 | 锁定 SQLite 数据库 |
| 2026-04-14 | v0.1.3 | 确认设备 API 自带预警判断，移除本地阈值配置 | | 2026-04-14 | v0.1.3 | 确认设备 API 自带预警判断，移除本地阈值配置 |
| 2026-04-14 | v0.1.4 | 确认河南三农推送协议（8个接口，appid/secret部署时配置） |

174
docs/api.md
View File

@@ -1,12 +1,177 @@
# 后台 API 接口设计 # 后台 API 接口设计
> 状态: 设计中（待设备 API 协议确认后细化） > 状态: 设计中（设备推送协议已确认，待服务器部署地址）
--- ---
## 1. API 概览 ## 0. 设备数据推送协议（厂家 → 后台）
- **Base URL**: `https://api.example.com/v1` > 数据流向：厂家系统 → 我们的后台 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>` - **认证**: `Authorization: Bearer <jwt_token>`
- **数据格式**: JSON - **数据格式**: JSON
- **字符编码**: UTF-8 - **字符编码**: UTF-8
@@ -294,4 +459,5 @@ GET /oss/download-url
- [x] JWT Secret 管理 → 环境变量 `JWT_SECRET_KEY` - [x] JWT Secret 管理 → 环境变量 `JWT_SECRET_KEY`
- [x] OSS 配置 → Bucket=`jesxion-ai-studio`, Region=`oss-cn-beijing` - [x] OSS 配置 → Bucket=`jesxion-ai-studio`, Region=`oss-cn-beijing`
- [x] 数据库 → SQLite（MVP） - [x] 数据库 → SQLite（MVP）
- [ ] 设备 API 协议格式（塔吊/升降机数据字段）— 厂家文档后续提供 - [x] 设备推送协议 → 河南三农统一推送接口（appid/secret 部署时配置）
- [ ] 后台 API 公网部署地址（阿里云服务器，部署时配置）

11
docs/architecture.md
View File

@@ -69,10 +69,10 @@
### 3.1 设备数据采集 ### 3.1 设备数据采集
``` ```
已有设备 API（自带预警判断） 河南三农厂家系统（推送）
│ (定时轮询: 每 30s 或设备主动推送) │ (统一推送接口 POST /input/post/call)
▼ ▼
device_adapter (协议解析) device_adapter (协议解析，统一入口)
│ │
▼ ▼
monitor (写入 DB) monitor (写入 DB)
@@ -86,6 +86,8 @@ SQLite alert_handler
alert_records (预警记录表) alert_records (预警记录表)
``` ```
> 注：数据为主动推送，无需后台定时轮询。推送频率由厂家控制。
### 3.2 H5 数据请求 ### 3.2 H5 数据请求
``` ```
@@ -131,5 +133,6 @@ MVP 阶段采用轻量部署：
## 6. 待细化 ## 6. 待细化
- [x] ~~预警阈值配置~~ → 设备 API 自带预警判断，本系统仅做聚合展示 - [x] ~~预警阈值配置~~ → 设备 API 自带预警判断，本系统仅做聚合展示
- [ ] 设备 API 协议细节（塔吊/升降机数据字段）— 厂家文档后续提供 - [x] ~~设备 API 协议细节~~ → 河南三农统一推送接口（8个接口，已确认）
- [ ] 后台 API 公网部署地址（阿里云服务器，部署时配置）
- [ ] 多租户隔离方案（目前 MVP 单租户设计） - [ ] 多租户隔离方案（目前 MVP 单租户设计）