修改文件结构，统一文档格式

design.md

@@ -347,31 +347,138 @@
 
 ## 5. 接口设计
 
-### 5.1 用户认证接口
-- POST /api/auth/login - 用户登录
-- POST /api/auth/logout - 用户登出
-- POST /api/auth/register - 用户注册
+### 5.1 通用API规范
+#### 5.1.1 响应格式
+所有API响应遵循统一格式：
+```json
+{
+  "success": true,
+  "data": {},
+  "message": "操作成功",
+  "timestamp": "2025-01-18T10:30:00Z"
+}
+```
 
-### 5.2 用户管理接口
-- GET /api/users - 获取用户列表
-- GET /api/users/{id} - 获取用户详情
-- POST /api/users - 创建用户
-- PUT /api/users/{id} - 更新用户信息
-- DELETE /api/users/{id} - 删除用户
+#### 5.1.2 错误处理
+- HTTP状态码：4xx客户端错误，5xx服务端错误
+- 错误信息：中英文错误描述
+- 错误日志：记录详细错误信息
 
-### 5.3 养殖场管理接口
-- GET /api/farms - 获取养殖场列表
-- GET /api/farms/{id} - 获取养殖场详情
-- POST /api/farms - 创建养殖场
-- PUT /api/farms/{id} - 更新养殖场信息
-- DELETE /api/farms/{id} - 删除养殖场
+#### 5.1.3 认证机制
+- Authorization: Bearer <token>
+- Token过期：401 Unauthorized
+- 权限不足：403 Forbidden
 
-### 5.4 产品管理接口
-- GET /api/products - 获取产品列表
-- GET /api/products/{id} - 获取产品详情
-- POST /api/products - 创建产品
-- PUT /api/products/{id} - 更新产品信息
-- DELETE /api/products/{id} - 删除产品
+### 5.2 用户认证接口
+- **POST /api/auth/login** - 用户登录
+  - 请求体：{username, password}
+  - 响应：JWT令牌和用户信息
+- **POST /api/auth/logout** - 用户登出
+  - 请求头：Authorization: Bearer <token>
+  - 响应：登出成功消息
+- **POST /api/auth/register** - 用户注册
+  - 请求体：{username, email, password}
+  - 响应：注册成功消息
+
+### 5.3 用户管理接口
+- **GET /api/users** - 获取用户列表（需要admin权限）
+  - 查询参数：page, limit, search
+  - 响应：用户列表分页数据
+- **GET /api/users/{id}** - 获取用户详情（需要认证）
+  - 路径参数：用户ID
+  - 响应：用户详细信息
+- **POST /api/users** - 创建用户（需要admin权限）
+  - 请求体：用户信息
+  - 响应：创建的用户信息
+- **PUT /api/users/{id}** - 更新用户信息（需要认证）
+  - 路径参数：用户ID
+  - 请求体：更新字段
+  - 响应：更新后的用户信息
+- **DELETE /api/users/{id}** - 删除用户（需要admin权限）
+  - 路径参数：用户ID
+  - 响应：删除成功消息
+
+### 5.4 养殖场管理接口
+- **GET /api/farms** - 获取养殖场列表（需要认证）
+  - 查询参数：page, limit, type, status
+  - 响应：养殖场列表分页数据
+- **GET /api/farms/{id}** - 获取养殖场详情（需要认证）
+  - 路径参数：养殖场ID
+  - 响应：养殖场详细信息
+- **POST /api/farms** - 创建养殖场（需要manager权限）
+  - 请求体：养殖场信息（包含地理位置JSON）
+  - 响应：创建的养殖场信息
+- **PUT /api/farms/{id}** - 更新养殖场信息（需要manager权限）
+  - 路径参数：养殖场ID
+  - 请求体：更新字段
+  - 响应：更新后的养殖场信息
+- **DELETE /api/farms/{id}** - 删除养殖场（需要admin权限）
+  - 路径参数：养殖场ID
+  - 响应：删除成功消息
+
+### 5.5 设备管理接口
+- **GET /api/devices** - 获取设备列表（需要认证）
+  - 查询参数：page, limit, farm_id, type, status
+  - 响应：设备列表分页数据
+- **GET /api/devices/{id}** - 获取设备详情（需要认证）
+  - 路径参数：设备ID
+  - 响应：设备详细信息（包含实时指标数据）
+- **POST /api/devices** - 创建设备（需要manager权限）
+  - 请求体：设备信息
+  - 响应：创建设备信息
+- **PUT /api/devices/{id}** - 更新设备信息（需要manager权限）
+  - 路径参数：设备ID
+  - 请求体：更新字段
+  - 响应：更新后的设备信息
+- **DELETE /api/devices/{id}** - 删除设备（需要admin权限）
+  - 路径参数：设备ID
+  - 响应：删除成功消息
+
+### 5.6 预警管理接口
+- **GET /api/alerts** - 获取预警列表（需要认证）
+  - 查询参数：page, limit, farm_id, level, status
+  - 响应：预警列表分页数据
+- **GET /api/alerts/{id}** - 获取预警详情（需要认证）
+  - 路径参数：预警ID
+  - 响应：预警详细信息
+- **PUT /api/alerts/{id}/acknowledge** - 确认预警（需要manager权限）
+  - 路径参数：预警ID
+  - 响应：确认成功消息
+- **PUT /api/alerts/{id}/resolve** - 解决预警（需要manager权限）
+  - 路径参数：预警ID
+  - 请求体：解决说明
+  - 响应：解决成功消息
+
+### 5.7 产品管理接口
+- **GET /api/products** - 获取产品列表（需要认证）
+  - 查询参数：page, limit, search
+  - 响应：产品列表分页数据
+- **GET /api/products/{id}** - 获取产品详情（需要认证）
+  - 路径参数：产品ID
+  - 响应：产品详细信息
+- **POST /api/products** - 创建产品（需要manager权限）
+  - 请求体：产品信息
+  - 响应：创建的产品信息
+- **PUT /api/products/{id}** - 更新产品信息（需要manager权限）
+  - 路径参数：产品ID
+  - 请求体：更新字段
+  - 响应：更新后的产品信息
+- **DELETE /api/products/{id}** - 删除产品（需要admin权限）
+  - 路径参数：产品ID
+  - 响应：删除成功消息
+
+### 5.8 统计分析接口
+- **GET /api/stats/overview** - 获取系统概览统计（需要认证）
+  - 响应：养殖场数、设备数、动物数、预警数等
+- **GET /api/stats/farms/{id}** - 获取养殖场统计（需要认证）
+  - 路径参数：养殖场ID
+  - 响应：养殖场详细统计数据
+- **GET /api/stats/alerts** - 获取预警统计（需要认证）
+  - 查询参数：timeRange（今日、本周、本月）
+  - 响应：预警级别分布统计
+- **GET /api/stats/animals** - 获取动物健康统计（需要认证）
+  - 查询参数：farm_id
+  - 响应：动物健康状态分布
 
 ## 6. 安全设计