OTA 设备管理平台

API Reference

设备管理后端接口

本文档描述前端与后端之间的接口约定，涵盖账号登录校验、固件上传、设备信息读取等能力。所有接口以 JSON 作为请求/响应主体（文件上传除外），统一返回结构为 { code, message, data }。

约定：code = 0 表示成功；非 0 表示业务错误。
登录态基于 Session-Cookie（starsessions + Redis）：登录成功后服务端下发 ota_session Cookie（HttpOnly; Secure; SameSite=Lax），后续请求由浏览器自动携带， 前端 fetch 必须带 credentials: 'include'。
接口基础路径（Base URL）：/api

概览

前端按下列顺序与后端交互：登录获取 token → 携带 token 调用设备/固件相关接口。建议统一封装请求层（axios / fetch），在拦截器中自动附加 token 与处理 401 过期跳转登录。

1. 登录校验

POST /api/auth/login

校验用户名与密码，成功后返回 token 及用户信息。前端「确定」按钮触发此请求。

额外提供 POST /api/auth/logout、GET /api/auth/status、POST /api/auth/heartbeat、GET /api/auth/captcha。

请求参数（application/x-www-form-urlencoded，同时兼容 JSON）

字段类型必填说明
usernamestring必填登录用户名（≤ 64 字符）
passwordstring必填登录密码（≥ 6 位，明文传输必须走 HTTPS）
remember0/1可选1 = 空闲超时延长到 7 天，默认 30 分钟
websitestring可选蜜罐字段，真人恒为空，非空即判为机器人
elapsed_msint可选页面加载到提交的毫秒数，过小判为脚本提交
captcha_token / captcha_answerstring条件必填连续失败达到阈值后由后端要求

请求示例

// POST /api/auth/login
// Content-Type: application/x-www-form-urlencoded
username=admin&password=••••••&remember=1&website=&elapsed_ms=4820

响应示例（成功）

{
  "code": 0,
  "message": "success",
  "data": {
    "user": { "id": 1, "username": "admin", "role": "admin", "login_ip": "1.2.3.4" },
    "idle_timeout": 1800,
    "remaining_seconds": 1800
  }
}
// 响应头同时下发：Set-Cookie: ota_session=...; Path=/; Max-Age=...; HttpOnly; Secure; SameSite=Lax

响应示例（失败）

// 401 用户名或密码错误（不区分账号是否存在，防账号枚举）
{ "code": 401, "message": "用户名或密码错误",
  "data": { "captcha_required": true, "retry_after": 0 } }

// 423 触发防撞库锁定，retry_after 为剩余锁定秒数
{ "code": 423, "message": "失败次数过多，请 60 秒后再试",
  "data": { "retry_after": 60, "captcha_required": true } }
前端要求：提交前做非空与长度（密码 ≥ 6 位）校验；勾选「记住我」时仅持久化用户名到 localStorage；收到 401 跳回登录页。会话空闲超时后 /api/auth/heartbeat 返回 401，前端据此弹出断开提示。

2. 固件上传

POST /api/firmware/upload

前端点击「固件上传」选择文件后，以 multipart/form-data 提交。后端接收二进制流，保存到存储路径（如 /data/firmware/{日期}/{uuid}.bin），并将文件名、版本、大小、存储路径、上传时间写入 firmware 表。

请求参数（multipart/form-data）

字段类型必填说明
filefile必填固件二进制（建议 .bin / .img）
versionstring必填固件版本号，如 1.2.0
deviceTypestring可选适用设备类型

响应示例（成功）

{
  "code": 0,
  "message": "success",
  "data": {
    "firmwareId": 12,
    "fileName": "ota_v1.2.0.bin",
    "version": "1.2.0",
    "size": 1048576,
    "storagePath": "/data/firmware/2026/08/4f3a9c.bin",
    "uploadedAt": "2026-08-30T10:00:00Z"
  }
}
前端要求：限制文件类型与大小，使用 XMLHttpRequest.upload.onprogress 或 axios 的 onUploadProgress 展示上传进度；成功后提示「上传完成」并展示存储路径。后端须保证 storagePath 唯一且可回查。

3. 读取设备信息（列表）

GET /api/devices

返回全部已注册设备的基础信息列表，用于设备总览页渲染。

响应示例

{
  "code": 0,
  "data": [
    { "id": 1, "name": "设备-A", "type": "EInk2608", "status": "online", "lastSeen": "2026-08-30T09:58:00Z" },
    { "id": 2, "name": "设备-B", "type": "EInk2608", "status": "offline", "lastSeen": "2026-08-29T22:10:00Z" }
  ]
}

4. 当前在线设备

GET /api/devices/online

仅返回当前在线设备，供状态看板/在线统计使用。

响应示例

{
  "code": 0,
  "data": [
    { "id": 1, "name": "设备-A", "type": "EInk2608", "ip": "192.168.1.20" }
  ]
}

5. 设备信息获取（电量等）

GET /api/devices/{deviceId}

获取指定设备的详细状态，包括当前电量、信号、固件版本、位置等。前端设备详情页调用。

路径参数

字段类型必填说明
deviceIdnumber必填设备 ID（URL 路径）

响应示例

{
  "code": 0,
  "data": {
    "id": 1,
    "name": "设备-A",
    "type": "EInk2608",
    "status": "online",
    "battery": 78,
    "signal": -52,
    "firmwareVersion": "1.1.3",
    "location": "会议室-3F",
    "lastSeen": "2026-08-30T09:58:00Z"
  }
}
前端要求：电量 battery 以百分比（0–100）展示并配低电量告警（如 < 20 变红）；可定时轮询（建议 10–30s）刷新状态。