smart-project/docs/api.md

后台 API 接口设计

状态: 设计中（设备推送协议已确认，待服务器部署地址）

---

0. 设备数据推送协议（厂家 → 后台）

数据流向：厂家系统 → 我们的后台 API（统一入口 /input/post/call）

0.1 认证接口

POST /input/auth/fetch

请求体:

{
  "appid": "项目专用appid（TBD）",
  "secret": "项目专用secret（TBD）"
}

响应 (200):

{
  "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>

请求体:

{
  "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

请求体:

{
  "username": "string",
  "password": "string"
}

响应 (200):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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

请求体:

{
  "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

请求体:

{
  "filename": "report_2026_04.pdf",
  "content_type": "application/pdf"
}

响应 (200):

{
  "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):

{
  "download_url": "https://bucket.oss-cn-beijing.aliyuncs.com/...?Signature=...",
  "expires_at": "2026-04-14T12:00:00Z"
}

---

6. 通用响应格式

成功:

{
  "code": 0,
  "message": "success",
  "data": {}
}

错误:

{
  "code": 1001,
  "message": "设备不存在",
  "detail": "device_id: device_999 不在系统中"
}

HTTP 状态码:

状态码	说明
200	成功
400	参数错误
401	未认证
403	无权限
404	资源不存在
500	服务器内部错误

---

7. 待确认

• 预警推送机制 → 轮询（前端每 30s）
• JWT 有效期 → 7 天
• JWT Secret 管理 → 环境变量 JWT_SECRET_KEY
• OSS 配置 → Bucket=jesxion-ai-studio, Region=oss-cn-beijing
• 数据库 → SQLite（MVP）
• 设备推送协议 → 河南三农统一推送接口（appid/secret 部署时配置）
• 后台 API 公网部署地址（阿里云服务器，部署时配置）