喂食计划鉴权接口文档
概览
- 基础路径: /api
- 文档范围: 鉴权路由中的喂食计划接口
- 鉴权方式: 请求头 X-Token
- Content-Type: application/json
鉴权头
| 字段 |
类型 |
必填 |
说明 |
| X-Token |
string |
是 |
用户登录后获得的 JWT Token |
统一响应格式
{
"code": 200,
"msg": "操作成功",
"data": {}
}
返回字段说明
| 字段 |
类型 |
说明 |
| code |
integer |
业务状态码，200 表示成功，其他值表示失败 |
| msg |
string |
响应消息 |
| data |
object/array/null |
业务数据 |
通用鉴权失败响应
{
"code": 401,
"msg": "未登录或登录过期",
"data": null
}
{
"code": 401,
"msg": "登录已过期，请重新登录",
"data": null
}
喂食计划对象字段说明
| 字段 |
类型 |
说明 |
| id |
integer |
计划 ID |
| deviceId |
string |
设备唯一标识 |
| time |
string |
喂食时间，格式 HH:mm |
| amount |
integer |
喂食份量 |
| days |
string |
执行星期，格式如 1,2,3,4,5,6,7 |
| enabled |
boolean |
是否启用 |
| createdAt |
string |
创建时间 |
| updatedAt |
string |
更新时间 |
1. 获取喂食计划列表
- 路径: /api/feeding/list
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| deviceId |
string |
是 |
设备唯一标识 |
请求示例
{
"deviceId": "dev_001"
}
成功响应示例
{
"code": 200,
"msg": "操作成功",
"data": [
{
"id": 1,
"deviceId": "dev_001",
"time": "08:30",
"amount": 20,
"days": "1,2,3,4,5,6,7",
"enabled": true,
"createdAt": "2026-05-09T08:00:00Z",
"updatedAt": "2026-05-09T08:00:00Z"
}
]
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 操作成功 |
| data |
array |
喂食计划列表 |
| data[].* |
object |
喂食计划对象，字段见上方喂食计划对象字段说明 |
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 500,
"msg": "获取计划列表失败",
"data": null
}
2. 添加喂食计划
- 路径: /api/feeding/add
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| deviceId |
string |
是 |
设备唯一标识 |
| time |
string |
是 |
喂食时间，格式 HH:mm |
| amount |
integer |
是 |
喂食份量 |
| days |
string |
是 |
执行星期，格式如 1,2,3,4,5,6,7 |
| enabled |
boolean |
否 |
是否启用；未传时按 false 的零值进入 handler |
请求示例
{
"deviceId": "dev_001",
"time": "08:30",
"amount": 20,
"days": "1,2,3,4,5,6,7",
"enabled": true
}
成功响应示例
{
"code": 200,
"msg": "计划添加成功",
"data": {
"id": 1,
"deviceId": "dev_001",
"time": "08:30",
"amount": 20,
"days": "1,2,3,4,5,6,7",
"enabled": true,
"createdAt": "2026-05-09T08:00:00Z",
"updatedAt": "2026-05-09T08:00:00Z"
}
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 计划添加成功 |
| data |
object |
新建的喂食计划 |
| data.* |
mixed |
喂食计划对象字段，见上方喂食计划对象字段说明 |
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 400,
"msg": "设备不存在",
"data": null
}
{
"code": 400,
"msg": "无权限，只有管理员可以操作喂食计划",
"data": null
}
3. 更新喂食计划
- 路径: /api/feeding/update
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| id |
integer |
是 |
计划 ID |
| deviceId |
string |
是 |
设备唯一标识。当前 handler 会校验必填，但 service 实际按 id 查计划，不使用该字段参与更新 |
| time |
string |
否 |
新喂食时间，格式 HH:mm |
| amount |
integer |
否 |
新喂食份量。仅当大于 0 时才会更新 |
| days |
string |
否 |
新执行星期 |
| enabled |
boolean |
否 |
新启用状态 |
请求示例
{
"id": 1,
"deviceId": "dev_001",
"time": "09:00",
"amount": 25,
"days": "1,2,3,4,5",
"enabled": true
}
成功响应示例
{
"code": 200,
"msg": "计划更新成功",
"data": null
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 计划更新成功 |
| data |
null |
无返回数据 |
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 400,
"msg": "计划不存在",
"data": null
}
{
"code": 400,
"msg": "无权限，只有管理员可以操作喂食计划",
"data": null
}
4. 删除喂食计划
- 路径: /api/feeding/delete
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| id |
integer |
是 |
计划 ID |
| deviceId |
string |
是 |
设备唯一标识。当前 handler 会校验必填，但 service 实际按 id 查计划，不使用该字段参与删除 |
请求示例
{
"id": 1,
"deviceId": "dev_001"
}
成功响应示例
{
"code": 200,
"msg": "计划已删除",
"data": null
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 计划已删除 |
| data |
null |
无返回数据 |
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 400,
"msg": "计划不存在",
"data": null
}
{
"code": 400,
"msg": "无权限，只有管理员可以操作喂食计划",
"data": null
}
5. 手动喂食
- 路径: /api/feeding/manual
- 方法: POST
- 是否鉴权: 是
请求 Body 参数
| 字段 |
类型 |
必填 |
说明 |
| deviceId |
string |
是 |
设备唯一标识 |
| amount |
integer |
是 |
本次手动喂食份量 |
请求示例
{
"deviceId": "dev_001",
"amount": 20
}
成功响应示例
{
"code": 200,
"msg": "喂食指令已发送",
"data": {
"deviceId": "dev_001",
"userId": 1,
"userName": "小明",
"planId": 0,
"amount": 20,
"feedTime": 1752297600,
"createdAt": "2026-05-09T10:00:00Z"
}
}
返回参数说明
| 字段 |
类型 |
说明 |
| code |
integer |
成功时为 200 |
| msg |
string |
成功时为 喂食指令已发送 |
| data |
object |
本次手动喂食产生的记录 |
| data.* |
mixed |
喂食记录对象字段，见上方喂食记录对象字段说明 |
失败响应示例
{
"code": 400,
"msg": "参数错误",
"data": null
}
{
"code": 400,
"msg": "设备不存在",
"data": null
}
{
"code": 400,
"msg": "设备离线，无法执行喂食",
"data": null
}
{
"code": 400,
"msg": "发送喂食指令失败",
"data": null
}
附录
说明
- 获取喂食计划返回数组；无数据时返回空数组，而不是 null。
- 更新和删除接口的请求体里虽然要求传 deviceId，但当前 service 实现实际是通过 id 查找计划后执行操作，deviceId 仅在 handler 层做必填校验。
- 喂食计划变更成功后，服务端会尝试把全量计划重新同步到设备；设备离线时会延后同步。