首页 / 文档中心 / 宠物喂食器（ODM 案例） / 设备统一上报

设备统一上报

宠物喂食器（ODM 案例） · 设备上报接口

设备上报接口文档

1. 接口信息

接口名称: 设备统一上报
路径: /api/device/report
方法: POST
Content-Type: application/json
鉴权方式: 设备签名认证
处理函数: deviceH.Report

2. 功能说明

设备通过同一个接口上报不同类型的数据，使用 action 区分业务类型。

支持的 action:

status: 上报设备状态
feedlog: 上报喂食记录
alarm: 上报告警信息

3. 鉴权规则

当服务端配置了 reportSecret 时，必须校验 token 与 timestamp。

token 计算规则:

md5(reportSecret + ":" + deviceId + ":" + timestamp + ":" + action)

timestamp 单位: 秒
timestamp 有效期: reportTokenTTL（默认 300 秒）
失败返回:
- 401 + code=401 + msg=设备认证已过期
- 401 + code=401 + msg=设备认证失败

4. 通用请求体

字段	类型	必填	说明
deviceId	string	是	设备唯一标识
action	string	是	status/feedlog/alarm
timestamp	int64	是	请求时间戳（秒）
token	string	是	设备签名
data	string	否	由 action 决定结构的 JSON 字符串，服务端会按 action 解析

5. 各 action 的 data 结构

5.1 action = status

字段	类型	必填	说明
batteryLevel	int	否	电量百分比
isCharging	bool	否	是否充电
foodLevel	int	否	余粮百分比
wifiName	string	否	当前连接的 WiFi 名称
wifiSignal	int	否	WiFi 信号强度
firmwareVersion	string	否	固件版本

示例:

{
  "deviceId": "dev_001",
  "action": "status",
  "timestamp": 1752297600,
  "token": "md5签名",
  "data": "{\"batteryLevel\":90,\"isCharging\":false,\"foodLevel\":80,\"wifiName\":\"Home-2.4G\",\"wifiSignal\":-58,\"firmwareVersion\":\"1.0.2\"}"
}

5.2 action = feedlog

字段	类型	必填	说明
amount	int	否	喂食份量
planId	int64	否	计划 ID，手动喂食可为 0
feedTime	int64	否	喂食时间戳（秒）
userId	int64	否	用户 ID
userName	string	否	用户昵称

示例:

{
  "deviceId": "dev_001",
  "action": "feedlog",
  "timestamp": 1752297600,
  "token": "md5签名",
  "data": "{\"amount\":20,\"planId\":1,\"feedTime\":1752297600,\"userId\":10001,\"userName\":\"Tom\"}"
}

5.3 action = alarm

字段	类型	必填	说明
alarmType	string	否	告警类型
message	string	否	告警内容

示例:

{
  "deviceId": "dev_001",
  "action": "alarm",
  "timestamp": 1752297600,
  "token": "md5签名",
  "data": "{\"alarmType\":\"low_battery\",\"message\":\"电量低于10%\"}"
}

6. 响应说明

统一响应结构:

字段	类型	说明
code	int	业务状态码
msg	string	响应消息
data	any	返回数据，本接口成功时一般为 null

6.1 成功响应

HTTP 状态码: 200
响应示例:

{
  "code": 200,
  "msg": "上报成功",
  "data": null
}

6.2 失败响应（常见）

参数错误或业务处理失败

{
  "code": 400,
  "msg": "参数错误",
  "data": null
}

未知 action

{
  "code": 400,
  "msg": "未知的 action: xxx",
  "data": null
}

认证过期或失败（HTTP 401）

{
  "code": 401,
  "msg": "设备认证失败",
  "data": null
}

7. 备注

代码位置:
- 路由注册: cmd/main.go
- 处理函数: internal/handler/device_handler.go
data 字段对接约定为 JSON 字符串，服务端会在对应 action 分支中继续解析。
如果 data 为空字符串或缺失，解析不会报错，但业务层可能因字段为空导致失败。

← 手动喂食（ToDeviceFeedManual）文档中心注册登录 →

这份文档没解决你的问题？联系我们，技术工程师直接对接。