diff --git a/SPEC.md b/SPEC.md index 26d066d..595b001 100644 --- a/SPEC.md +++ b/SPEC.md @@ -39,7 +39,7 @@ | H5 前端 | 原生 HTML/CSS/JS,无框架依赖 | | 数据库 | SQLite(MVP 阶段) | | 文件存储 | 阿里云 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.2 | 锁定 SQLite 数据库 | | 2026-04-14 | v0.1.3 | 确认设备 API 自带预警判断,移除本地阈值配置 | +| 2026-04-14 | v0.1.4 | 确认河南三农推送协议(8个接口,appid/secret部署时配置) | diff --git a/docs/api.md b/docs/api.md index caafb24..5332c0a 100644 --- 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 ` + +### 0.2 统一推送接口 + +厂家所有数据通过此接口推送,`path` 指定具体业务接口: + +``` +POST /input/post/call +Authorization: Bearer +``` + +**请求体**: +```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 ` - **数据格式**: 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 公网部署地址(阿里云服务器,部署时配置) diff --git a/docs/architecture.md b/docs/architecture.md index 1e861e4..816b652 100644 --- 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 单租户设计)