132 lines
6.3 KiB
Markdown
132 lines
6.3 KiB
Markdown
# 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` | 获取通知 |
|