smart-project/docs/api.md

后台 API 接口设计

状态: 设计中（待设备 API 协议确认后细化）

---

1. 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,
      "threshold": 40.0,
      "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 天
• OSS 配置 → Bucket=jesxion-ai-studio, Region=oss-cn-beijing
• 设备 API 协议格式（塔吊/升降机数据字段）— 厂家文档后续提供
• JWT Secret 如何管理