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

- 新增第0章：设备推送协议（认证+统一入口+塔吊4接口+升降机4接口） - 架构图更新：数据流改为厂家主动推送 - 推送地址/appid/secret待部署时配置 - API文档结构重排，H5接口和设备接口分开
2026-04-14 12:01:34 +08:00
parent 7b71edf17a
commit 6c8760c6c5
3 changed files with 179 additions and 9 deletions
--- a/docs/api.md
+++ b/docs/api.md
@@ -1,12 +1,177 @@
 # 后台 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>`
 - **数据格式**: JSON
 - **字符编码**: UTF-8
@@ -294,4 +459,5 @@ GET /oss/download-url
 - [x] JWT Secret 管理 → 环境变量 `JWT_SECRET_KEY`
 - [x] OSS 配置 → Bucket=`jesxion-ai-studio`, Region=`oss-cn-beijing`
 - [x] 数据库 → SQLite（MVP）
- [ ] 设备 API 协议格式（塔吊/升降机数据字段）— 厂家文档后续提供
+- [x] 设备推送协议 → 河南三农统一推送接口（appid/secret 部署时配置）
+- [ ] 后台 API 公网部署地址（阿里云服务器，部署时配置）
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -69,10 +69,10 @@
 ### 3.1 设备数据采集

 ```
-已有设备 API（自带预警判断）
-     │ (定时轮询: 每 30s 或设备主动推送)
+河南三农厂家系统（推送）
+     │ (统一推送接口 POST /input/post/call)
     ▼
-device_adapter (协议解析)
+device_adapter (协议解析，统一入口)
     │
     ▼
 monitor (写入 DB)
@@ -86,6 +86,8 @@ SQLite              alert_handler
                  alert_records (预警记录表)
 ```

+> 注：数据为主动推送，无需后台定时轮询。推送频率由厂家控制。
+
 ### 3.2 H5 数据请求

 ```
@@ -131,5 +133,6 @@ MVP 阶段采用轻量部署：
 ## 6. 待细化

 - [x] ~~预警阈值配置~~ → 设备 API 自带预警判断，本系统仅做聚合展示
- [ ] 设备 API 协议细节（塔吊/升降机数据字段）— 厂家文档后续提供
+- [x] ~~设备 API 协议细节~~ → 河南三农统一推送接口（8个接口，已确认）
+- [ ] 后台 API 公网部署地址（阿里云服务器，部署时配置）
 - [ ] 多租户隔离方案（目前 MVP 单租户设计）