pig-farm-controller/bmad/api-contracts-main-zh.md

API 契约 - 主模块

本文档概述了猪场控制器应用程序中可用的 API 端点。

公共路由（无需身份验证）

方法	路径	描述
POST	/api/v1/users	用户注册
POST	/api/v1/users/login	用户登录
POST	/upstream	处理设备上行事件
GET	/swagger/*any	Swagger UI

认证路由（需要 JWT 身份验证和审计日志）

用户端点 (/api/v1/users)

方法	路径	描述
POST	/api/v1/users/:id/notifications/test	发送测试通知

设备端点 (/api/v1/devices)

方法	路径	描述
POST	/api/v1/devices	创建设备
GET	/api/v1/devices	获取设备列表
GET	/api/v1/devices/:id	获取单个设备
PUT	/api/v1/devices/:id	更新设备
DELETE	/api/v1/devices/:id	删除设备
POST	/api/v1/devices/manual-control/:id	手动控制设备

区域控制器端点 (/api/v1/area-controllers)

方法	路径	描述
POST	/api/v1/area-controllers	创建区域控制器
GET	/api/v1/area-controllers	获取区域控制器列表
GET	/api/v1/area-controllers/:id	获取单个区域控制器
PUT	/api/v1/area-controllers/:id	更新区域控制器
DELETE	/api/v1/area-controllers/:id	删除区域控制器

设备模板端点 (/api/v1/device-templates)

方法	路径	描述
POST	/api/v1/device-templates	创建设备模板
GET	/api/v1/device-templates	获取设备模板列表
GET	/api/v1/device-templates/:id	获取单个设备模板
PUT	/api/v1/device-templates/:id	更新设备模板
DELETE	/api/v1/device-templates/:id	删除设备模板

计划端点 (/api/v1/plans)

方法	路径	描述
POST	/api/v1/plans	创建计划
GET	/api/v1/plans	获取计划列表
GET	/api/v1/plans/:id	获取单个计划
PUT	/api/v1/plans/:id	更新计划
DELETE	/api/v1/plans/:id	删除计划
POST	/api/v1/plans/:id/start	启动计划
POST	/api/v1/plans/:id/stop	停止计划

猪舍端点 (/api/v1/pig-houses)

方法	路径	描述
POST	/api/v1/pig-houses	创建猪舍
GET	/api/v1/pig-houses	获取猪舍列表
GET	/api/v1/pig-houses/:id	获取单个猪舍
PUT	/api/v1/pig-houses/:id	更新猪舍
DELETE	/api/v1/pig-houses/:id	删除猪舍

猪圈端点 (/api/v1/pens)

方法	路径	描述
POST	/api/v1/pens	创建猪圈
GET	/api/v1/pens	获取猪圈列表
GET	/api/v1/pens/:id	获取单个猪圈
PUT	/api/v1/pens/:id	更新猪圈
DELETE	/api/v1/pens/:id	删除猪圈
PUT	/api/v1/pens/:id/status	更新猪圈状态

猪群端点 (/api/v1/pig-batches)

方法	路径	描述
POST	/api/v1/pig-batches	创建猪群
GET	/api/v1/pig-batches	获取猪群列表
GET	/api/v1/pig-batches/:id	获取单个猪群
PUT	/api/v1/pig-batches/:id	更新猪群
DELETE	/api/v1/pig-batches/:id	删除猪群
POST	/api/v1/pig-batches/assign-pens/:id	为猪群分配空栏
POST	/api/v1/pig-batches/reclassify-pen/:fromBatchID	将猪栏划拨到新群
DELETE	/api/v1/pig-batches/remove-pen/:penID/:batchID	从猪群移除空栏
POST	/api/v1/pig-batches/move-pigs-into-pen/:id	将猪只从“虚拟库存”移入指定猪栏
POST	/api/v1/pig-batches/sell-pigs/:id	处理卖猪业务
POST	/api/v1/pig-batches/buy-pigs/:id	处理买猪业务
POST	/api/v1/pig-batches/transfer-across-batches/:sourceBatchID	跨猪群调栏
POST	/api/v1/pig-batches/transfer-within-batch/:id	群内调栏
POST	/api/v1/pig-batches/record-sick-pigs/:id	记录新增病猪事件
POST	/api/v1/pig-batches/record-sick-pig-recovery/:id	记录病猪康复事件
POST	/api/v1/pig-batches/record-sick-pig-death/:id	记录病猪死亡事件
POST	/api/v1/pig-batches/record-sick-pig-cull/:id	记录病猪淘汰事件
POST	/api/v1/pig-batches/record-death/:id	记录正常猪只死亡事件
POST	/api/v1/pig-batches/record-cull/:id	记录正常猪只淘汰事件

监控端点 (/api/v1/monitor)

方法	路径	描述
GET	/api/v1/monitor/sensor-data	获取传感器数据
GET	/api/v1/monitor/device-command-logs	获取设备命令日志
GET	/api/v1/monitor/plan-execution-logs	获取计划执行日志
GET	/api/v1/monitor/task-execution-logs	获取任务执行日志
GET	/api/v1/monitor/pending-collections	获取待处理采集
GET	/api/v1/monitor/user-action-logs	获取用户操作日志
GET	/api/v1/monitor/raw-material-purchases	获取原材料采购记录
GET	/api/v1/monitor/raw-material-stock-logs	获取原材料库存日志
GET	/api/v1/monitor/feed-usage-records	获取饲料使用记录
GET	/api/v1/monitor/medication-logs	获取用药记录
GET	/api/v1/monitor/pig-batch-logs	获取猪群日志
GET	/api/v1/monitor/weighing-batches	获取称重批次
GET	/api/v1/monitor/weighing-records	获取称重记录
GET	/api/v1/monitor/pig-transfer-logs	获取猪只转栏日志
GET	/api/v1/monitor/pig-sick-logs	获取病猪日志
GET	/api/v1/monitor/pig-purchases	获取猪只采购记录
GET	/api/v1/monitor/pig-sales	获取猪只销售记录
GET	/api/v1/monitor/notifications	获取通知