# 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` | 获取通知 |