xlxumu/docs/design/小程序app接口设计文档.md

# 小程序APP接口设计文档

## 版本历史
| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|----------|
| 1.0 | 2024-01-20 | 后端团队 | 初始版本 |
| 1.1 | 2024-09-21 | 后端团队 | 更新API实现状态，补充缺失接口 |

## 1. 接口概述

### 1.1 设计原则
- **移动优先**: 专为移动端设计，优化网络请求和数据传输
- **轻量化**: 接口响应数据精简，减少不必要的字段
- **离线支持**: 支持关键数据的本地缓存和离线访问
- **实时性**: 关键业务数据支持实时推送和更新
- **安全性**: 完善的身份认证和数据加密机制
- **易用性**: 简化的接口调用和错误处理

### 1.2 基础信息
- **Base URL**: `https://api.xlxumu.com/app/v1`
- **Content-Type**: `application/json`
- **字符编码**: `UTF-8`
- **认证方式**: `Bearer Token (JWT)`
- **小程序平台**: 微信小程序、支付宝小程序

### 1.3 通用响应格式
```json
{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": 1705747200000
}
```

### 1.4 错误响应格式
```json
{
  "success": false,
  "code": 400,
  "message": "参数错误",
  "errors": [
    {
      "field": "phone",
      "message": "手机号格式不正确"
    }
  ],
  "timestamp": 1705747200000
}
```

### 1.5 分页响应格式
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [],
    "has_more": true,
    "next_cursor": "cursor_123",
    "total": 100
  }
}
```

## 2. 用户认证

### 2.1 微信小程序登录

#### 2.1.1 微信授权登录
**接口地址**: `POST /auth/wechat/login`

**实现状态**: ❌ 未实现 - 需要开发

**请求参数**:
```json
{
  "code": "wx_code_from_wechat",
  "encrypted_data": "encrypted_user_info",
  "iv": "initialization_vector"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "refresh_token_123",
    "expires_in": 7200,
    "is_new_user": false,
    "user": {
      "id": 1,
      "openid": "wx_openid_123",
      "unionid": "wx_unionid_123",
      "nickname": "张三",
      "avatar": "https://wx.qlogo.cn/avatar.jpg",
      "phone": "138****8000",
      "is_verified": true
    }
  }
}
```

#### 2.1.2 手机号绑定
**接口地址**: `POST /auth/bind-phone`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "encrypted_data": "encrypted_phone_data",
  "iv": "initialization_vector"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "绑定成功",
  "data": {
    "phone": "13800138000",
    "is_verified": true
  }
}
```

### 2.2 Token管理

#### 2.2.1 刷新Token
**接口地址**: `POST /auth/refresh`

**请求参数**:
```json
{
  "refresh_token": "refresh_token_123"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "刷新成功",
  "data": {
    "token": "new_jwt_token",
    "expires_in": 7200
  }
}
```

#### 2.2.2 获取用户信息
**接口地址**: `GET /auth/user`

**请求头**:
```
Authorization: Bearer {token}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "openid": "wx_openid_123",
    "nickname": "张三",
    "avatar": "https://wx.qlogo.cn/avatar.jpg",
    "phone": "138****8000",
    "real_name": "张三",
    "gender": 1,
    "birthday": "1990-01-01",
    "address": "北京市朝阳区",
    "is_verified": true,
    "user_type": "farmer",
    "created_at": "2024-01-15 09:00:00"
  }
}
```

## 3. 用户管理

### 3.1 个人信息

#### 3.1.1 更新个人信息
**接口地址**: `PUT /user/profile`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "real_name": "张三三",
  "gender": 1,
  "birthday": "1990-01-01",
  "address": "北京市朝阳区某某街道"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "real_name": "张三三",
    "gender": 1,
    "birthday": "1990-01-01",
    "address": "北京市朝阳区某某街道",
    "updated_at": "2024-01-20 10:30:00"
  }
}
```

#### 3.1.2 上传头像
**接口地址**: `POST /user/avatar`

**请求头**:
```
Authorization: Bearer {token}
Content-Type: multipart/form-data
```

**请求参数**:
- avatar: 头像文件

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "上传成功",
  "data": {
    "avatar": "https://cdn.xlxumu.com/avatars/user_1_avatar.jpg"
  }
}
```

### 3.2 实名认证

#### 3.2.1 提交实名认证
**接口地址**: `POST /user/verification`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "real_name": "张三",
  "id_card": "110101199001010001",
  "id_card_front": "https://cdn.xlxumu.com/id_front.jpg",
  "id_card_back": "https://cdn.xlxumu.com/id_back.jpg"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "提交成功",
  "data": {
    "verification_id": 1,
    "status": "pending",
    "submitted_at": "2024-01-20 11:00:00"
  }
}
```

#### 3.2.2 获取认证状态
**接口地址**: `GET /user/verification/status`

**请求头**:
```
Authorization: Bearer {token}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "verification_id": 1,
    "status": "approved",
    "real_name": "张三",
    "id_card": "110101199001010001",
    "submitted_at": "2024-01-20 11:00:00",
    "reviewed_at": "2024-01-20 15:00:00",
    "review_notes": "认证通过"
  }
}
```

## 4. 养殖场管理

### 4.1 我的养殖场

#### 4.1.1 获取养殖场列表
**接口地址**: `GET /farms`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cursor | string | 否 | 游标，用于分页 |
| limit | int | 否 | 每页数量，默认20 |
| status | int | 否 | 养殖场状态 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "张三养猪场",
        "code": "FARM001",
        "type": "pig",
        "type_name": "生猪养殖",
        "area": 5000.00,
        "capacity": 500,
        "address": "北京市朝阳区某某村",
        "status": 1,
        "status_name": "正常运营",
        "animal_count": 150,
        "health_rate": 96.7,
        "created_at": "2024-01-15 09:00:00"
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "total": 1
  }
}
```

#### 4.1.2 获取养殖场详情
**接口地址**: `GET /farms/{id}`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 养殖场ID |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "name": "张三养猪场",
    "code": "FARM001",
    "type": "pig",
    "type_name": "生猪养殖",
    "area": 5000.00,
    "capacity": 500,
    "address": "北京市朝阳区某某村123号",
    "longitude": 116.407526,
    "latitude": 39.904030,
    "license_number": "京农许字[2024]001号",
    "description": "专业养猪场，采用现代化养殖技术",
    "status": 1,
    "status_name": "正常运营",
    "statistics": {
      "total_animals": 150,
      "healthy_animals": 145,
      "sick_animals": 5,
      "health_rate": 96.7,
      "avg_weight": 85.5,
      "total_value": 150000.00
    },
    "weather": {
      "temperature": 15,
      "humidity": 65,
      "weather": "晴",
      "updated_at": "2024-01-20 12:00:00"
    },
    "created_at": "2024-01-15 09:00:00"
  }
}
```

#### 4.1.3 创建养殖场
**接口地址**: `POST /farms`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "name": "李四养鸡场",
  "type": "chicken",
  "area": 3000.00,
  "capacity": 1000,
  "address": "上海市浦东新区某某镇",
  "longitude": 121.473701,
  "latitude": 31.230416,
  "license_number": "沪农许字[2024]002号",
  "license_image": "https://cdn.xlxumu.com/license.jpg",
  "description": "现代化养鸡场"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 2,
    "name": "李四养鸡场",
    "code": "FARM002",
    "type": "chicken",
    "status": 0,
    "status_name": "待审核",
    "created_at": "2024-01-20 14:00:00"
  }
}
```

### 4.2 养殖场统计

#### 4.2.1 获取养殖场统计数据
**接口地址**: `GET /farms/{id}/statistics`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 养殖场ID |

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| period | string | 否 | 统计周期：day,week,month,year |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "overview": {
      "total_animals": 150,
      "healthy_animals": 145,
      "sick_animals": 5,
      "dead_animals": 0,
      "health_rate": 96.7,
      "avg_weight": 85.5,
      "total_value": 150000.00
    },
    "breed_distribution": [
      {
        "breed": "杜洛克猪",
        "count": 80,
        "percentage": 53.33
      },
      {
        "breed": "长白猪",
        "count": 70,
        "percentage": 46.67
      }
    ],
    "growth_trend": [
      {
        "date": "2024-01-15",
        "count": 148,
        "avg_weight": 82.3
      },
      {
        "date": "2024-01-20",
        "count": 150,
        "avg_weight": 85.5
      }
    ],
    "health_trend": [
      {
        "date": "2024-01-15",
        "healthy": 143,
        "sick": 5,
        "health_rate": 96.6
      },
      {
        "date": "2024-01-20",
        "healthy": 145,
        "sick": 5,
        "health_rate": 96.7
      }
    ]
  }
}
```

## 5. 动物管理

### 5.1 动物列表

#### 5.1.1 获取动物列表
**接口地址**: `GET /animals`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| farm_id | int | 否 | 养殖场ID |
| cursor | string | 否 | 游标，用于分页 |
| limit | int | 否 | 每页数量，默认20 |
| breed | string | 否 | 品种筛选 |
| health_status | string | 否 | 健康状态筛选 |
| keyword | string | 否 | 搜索关键词 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "code": "PIG001",
        "name": "小猪001",
        "breed": "杜洛克猪",
        "gender": 1,
        "gender_name": "公",
        "birth_date": "2023-06-15",
        "age_days": 219,
        "weight": 85.5,
        "health_status": "healthy",
        "health_status_name": "健康",
        "farm": {
          "id": 1,
          "name": "张三养猪场"
        },
        "avatar": "https://cdn.xlxumu.com/animals/pig001.jpg",
        "last_checkup": "2024-01-15",
        "next_checkup": "2024-02-15"
      }
    ],
    "has_more": true,
    "next_cursor": "cursor_123",
    "total": 150
  }
}
```

#### 5.1.2 获取动物详情
**接口地址**: `GET /animals/{id}`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 动物ID |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "code": "PIG001",
    "name": "小猪001",
    "breed": "杜洛克猪",
    "gender": 1,
    "gender_name": "公",
    "birth_date": "2023-06-15",
    "age_days": 219,
    "weight": 85.5,
    "health_status": "healthy",
    "health_status_name": "健康",
    "farm": {
      "id": 1,
      "name": "张三养猪场"
    },
    "avatar": "https://cdn.xlxumu.com/animals/pig001.jpg",
    "parents": {
      "father": {
        "id": 10,
        "code": "PIG010",
        "name": "种猪公001"
      },
      "mother": {
        "id": 11,
        "code": "PIG011",
        "name": "种猪母001"
      }
    },
    "purchase_info": {
      "price": 800.00,
      "date": "2023-06-15",
      "source": "本地养殖场"
    },
    "current_value": 1200.00,
    "growth_records": [
      {
        "date": "2024-01-01",
        "weight": 80.0,
        "height": 60.0
      },
      {
        "date": "2024-01-20",
        "weight": 85.5,
        "height": 62.0
      }
    ],
    "health_summary": {
      "last_checkup": "2024-01-15",
      "next_checkup": "2024-02-15",
      "vaccination_count": 3,
      "health_record_count": 5
    },
    "notes": "生长良好，无疾病史",
    "created_at": "2023-06-15 10:00:00"
  }
}
```

### 5.2 动物操作

#### 5.2.1 添加动物
**接口地址**: `POST /animals`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "farm_id": 1,
  "code": "PIG002",
  "name": "小猪002",
  "breed": "长白猪",
  "gender": 0,
  "birth_date": "2023-08-01",
  "weight": 65.0,
  "purchase_price": 750.00,
  "purchase_date": "2023-08-01",
  "purchase_source": "外地养殖场",
  "father_id": 10,
  "mother_id": 11,
  "notes": "新引进种猪"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 201,
  "message": "添加成功",
  "data": {
    "id": 2,
    "code": "PIG002",
    "name": "小猪002",
    "breed": "长白猪",
    "gender": 0,
    "birth_date": "2023-08-01",
    "weight": 65.0,
    "health_status": "healthy",
    "created_at": "2024-01-20 15:00:00"
  }
}
```

#### 5.2.2 更新动物信息
**接口地址**: `PUT /animals/{id}`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 动物ID |

**请求参数**:
```json
{
  "name": "小猪001号",
  "weight": 87.0,
  "health_status": "healthy",
  "notes": "体重增长正常"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "name": "小猪001号",
    "weight": 87.0,
    "health_status": "healthy",
    "updated_at": "2024-01-20 15:30:00"
  }
}
```

### 5.3 健康管理

#### 5.3.1 获取健康记录
**接口地址**: `GET /animals/{id}/health-records`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 动物ID |

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cursor | string | 否 | 游标，用于分页 |
| limit | int | 否 | 每页数量，默认20 |
| record_type | string | 否 | 记录类型 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "record_type": "checkup",
        "record_type_name": "健康检查",
        "record_date": "2024-01-15",
        "symptoms": null,
        "diagnosis": "健康状况良好",
        "treatment": null,
        "medicine": null,
        "veterinarian": "李兽医",
        "cost": 50.00,
        "next_checkup_date": "2024-02-15",
        "notes": "定期健康检查",
        "images": [
          "https://cdn.xlxumu.com/health1.jpg"
        ],
        "created_at": "2024-01-15 14:00:00"
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "total": 5
  }
}
```

#### 5.3.2 添加健康记录
**接口地址**: `POST /animals/{id}/health-records`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 动物ID |

**请求参数**:
```json
{
  "record_type": "vaccination",
  "record_date": "2024-01-20",
  "medicine": "猪瘟疫苗",
  "dosage": "2ml",
  "veterinarian": "王兽医",
  "cost": 30.00,
  "next_vaccination_date": "2024-07-20",
  "notes": "年度疫苗接种",
  "images": [
    "https://cdn.xlxumu.com/vaccination1.jpg"
  ]
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 201,
  "message": "添加成功",
  "data": {
    "id": 2,
    "record_type": "vaccination",
    "record_date": "2024-01-20",
    "medicine": "猪瘟疫苗",
    "veterinarian": "王兽医",
    "cost": 30.00,
    "created_at": "2024-01-20 16:00:00"
  }
}
```

## 6. 交易管理

### 6.1 商品发布

#### 6.1.1 发布动物商品
**接口地址**: `POST /products/animals`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "animal_id": 1,
  "title": "优质杜洛克猪出售",
  "description": "健康状况良好，体重85kg，适合繁殖",
  "price": 1200.00,
  "unit": "头",
  "stock": 1,
  "images": [
    "https://cdn.xlxumu.com/product1.jpg",
    "https://cdn.xlxumu.com/product2.jpg"
  ],
  "shipping_fee": 100.00,
  "shipping_method": "express",
  "contact_phone": "13800138000",
  "contact_wechat": "zhang123",
  "notes": "支持实地看货"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 201,
  "message": "发布成功",
  "data": {
    "id": 1,
    "product_no": "PRD202401200001",
    "title": "优质杜洛克猪出售",
    "price": 1200.00,
    "status": "pending",
    "status_name": "待审核",
    "created_at": "2024-01-20 16:30:00"
  }
}
```

#### 6.1.2 获取我的商品
**接口地址**: `GET /products/my`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cursor | string | 否 | 游标，用于分页 |
| limit | int | 否 | 每页数量，默认20 |
| status | string | 否 | 商品状态 |
| product_type | string | 否 | 商品类型 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "product_no": "PRD202401200001",
        "title": "优质杜洛克猪出售",
        "price": 1200.00,
        "unit": "头",
        "stock": 1,
        "sold_count": 0,
        "status": "active",
        "status_name": "销售中",
        "cover_image": "https://cdn.xlxumu.com/product1.jpg",
        "view_count": 25,
        "favorite_count": 3,
        "created_at": "2024-01-20 16:30:00"
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "total": 1
  }
}
```

### 6.2 商品浏览

#### 6.2.1 获取商品列表
**接口地址**: `GET /products`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cursor | string | 否 | 游标，用于分页 |
| limit | int | 否 | 每页数量，默认20 |
| category | string | 否 | 商品分类 |
| keyword | string | 否 | 搜索关键词 |
| min_price | decimal | 否 | 最低价格 |
| max_price | decimal | 否 | 最高价格 |
| province | string | 否 | 省份 |
| city | string | 否 | 城市 |
| sort | string | 否 | 排序方式：price_asc,price_desc,time_desc |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "product_no": "PRD202401200001",
        "title": "优质杜洛克猪出售",
        "price": 1200.00,
        "unit": "头",
        "stock": 1,
        "cover_image": "https://cdn.xlxumu.com/product1.jpg",
        "seller": {
          "id": 1,
          "nickname": "张三",
          "avatar": "https://wx.qlogo.cn/avatar.jpg",
          "location": "北京市朝阳区"
        },
        "farm": {
          "id": 1,
          "name": "张三养猪场"
        },
        "view_count": 25,
        "favorite_count": 3,
        "is_favorited": false,
        "distance": 15.6,
        "created_at": "2024-01-20 16:30:00"
      }
    ],
    "has_more": true,
    "next_cursor": "cursor_456",
    "total": 100
  }
}
```

#### 6.2.2 获取商品详情
**接口地址**: `GET /products/{id}`

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 商品ID |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "product_no": "PRD202401200001",
    "title": "优质杜洛克猪出售",
    "description": "健康状况良好，体重85kg，适合繁殖",
    "price": 1200.00,
    "unit": "头",
    "stock": 1,
    "sold_count": 0,
    "images": [
      "https://cdn.xlxumu.com/product1.jpg",
      "https://cdn.xlxumu.com/product2.jpg"
    ],
    "shipping_fee": 100.00,
    "shipping_method": "express",
    "shipping_method_name": "快递配送",
    "seller": {
      "id": 1,
      "nickname": "张三",
      "avatar": "https://wx.qlogo.cn/avatar.jpg",
      "location": "北京市朝阳区",
      "is_verified": true,
      "rating": 4.8,
      "product_count": 5
    },
    "farm": {
      "id": 1,
      "name": "张三养猪场",
      "address": "北京市朝阳区某某村"
    },
    "animal": {
      "id": 1,
      "code": "PIG001",
      "breed": "杜洛克猪",
      "gender": 1,
      "age_days": 219,
      "weight": 85.5,
      "health_status": "healthy"
    },
    "contact_info": {
      "phone": "138****8000",
      "wechat": "zhang123"
    },
    "view_count": 26,
    "favorite_count": 3,
    "is_favorited": false,
    "distance": 15.6,
    "notes": "支持实地看货",
    "created_at": "2024-01-20 16:30:00"
  }
}
```

### 6.3 订单管理

#### 6.3.1 创建订单
**接口地址**: `POST /orders`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "product_id": 1,
  "quantity": 1,
  "shipping_address": {
    "name": "李四",
    "phone": "13900139000",
    "province": "上海市",
    "city": "上海市",
    "district": "浦东新区",
    "address": "张江镇某某路123号"
  },
  "notes": "请尽快发货"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 201,
  "message": "订单创建成功",
  "data": {
    "id": 1,
    "order_no": "ORD202401200001",
    "total_amount": 1200.00,
    "shipping_fee": 100.00,
    "actual_amount": 1300.00,
    "status": "pending_payment",
    "status_name": "待支付",
    "created_at": "2024-01-20 17:00:00"
  }
}
```

#### 6.3.2 获取我的订单
**接口地址**: `GET /orders/my`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cursor | string | 否 | 游标，用于分页 |
| limit | int | 否 | 每页数量，默认20 |
| status | string | 否 | 订单状态 |
| order_type | string | 否 | 订单类型：buy,sell |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "order_no": "ORD202401200001",
        "order_type": "buy",
        "total_amount": 1200.00,
        "shipping_fee": 100.00,
        "actual_amount": 1300.00,
        "status": "pending_payment",
        "status_name": "待支付",
        "product": {
          "id": 1,
          "title": "优质杜洛克猪出售",
          "cover_image": "https://cdn.xlxumu.com/product1.jpg",
          "price": 1200.00,
          "quantity": 1
        },
        "seller": {
          "id": 1,
          "nickname": "张三",
          "avatar": "https://wx.qlogo.cn/avatar.jpg"
        },
        "created_at": "2024-01-20 17:00:00"
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "total": 1
  }
}
```

#### 6.3.3 获取订单详情
**接口地址**: `GET /orders/{id}`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 订单ID |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "order_no": "ORD202401200001",
    "order_type": "buy",
    "total_amount": 1200.00,
    "shipping_fee": 100.00,
    "actual_amount": 1300.00,
    "payment_method": null,
    "status": "pending_payment",
    "status_name": "待支付",
    "product": {
      "id": 1,
      "title": "优质杜洛克猪出售",
      "cover_image": "https://cdn.xlxumu.com/product1.jpg",
      "price": 1200.00,
      "quantity": 1,
      "unit": "头"
    },
    "seller": {
      "id": 1,
      "nickname": "张三",
      "avatar": "https://wx.qlogo.cn/avatar.jpg",
      "phone": "138****8000"
    },
    "buyer": {
      "id": 2,
      "nickname": "李四",
      "avatar": "https://wx.qlogo.cn/avatar2.jpg",
      "phone": "139****9000"
    },
    "shipping_address": {
      "name": "李四",
      "phone": "13900139000",
      "province": "上海市",
      "city": "上海市",
      "district": "浦东新区",
      "address": "张江镇某某路123号",
      "full_address": "上海市上海市浦东新区张江镇某某路123号"
    },
    "tracking_number": null,
    "notes": "请尽快发货",
    "created_at": "2024-01-20 17:00:00",
    "paid_at": null,
    "shipped_at": null,
    "delivered_at": null,
    "completed_at": null
  }
}
```

## 7. 支付管理

### 7.1 微信支付

#### 7.1.1 创建支付订单
**接口地址**: `POST /payments/wechat/create`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "order_id": 1,
  "payment_method": "wechat_mini"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "支付订单创建成功",
  "data": {
    "payment_id": "pay_123456",
    "prepay_id": "wx_prepay_123456",
    "payment_params": {
      "timeStamp": "1705747200",
      "nonceStr": "random_string",
      "package": "prepay_id=wx_prepay_123456",
      "signType": "RSA",
      "paySign": "signature_string"
    }
  }
}
```

#### 7.1.2 查询支付状态
**接口地址**: `GET /payments/{payment_id}/status`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| payment_id | string | 是 | 支付ID |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "payment_id": "pay_123456",
    "order_id": 1,
    "amount": 1300.00,
    "status": "paid",
    "status_name": "已支付",
    "payment_method": "wechat_mini",
    "transaction_id": "wx_transaction_123456",
    "paid_at": "2024-01-20 17:30:00"
  }
}
```

## 8. 消息通知

### 8.1 系统消息

#### 8.1.1 获取消息列表
**接口地址**: `GET /messages`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cursor | string | 否 | 游标，用于分页 |
| limit | int | 否 | 每页数量，默认20 |
| type | string | 否 | 消息类型 |
| is_read | int | 否 | 是否已读 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "type": "order",
        "type_name": "订单消息",
        "title": "您有新的订单",
        "content": "用户李四购买了您的商品：优质杜洛克猪出售",
        "data": {
          "order_id": 1,
          "order_no": "ORD202401200001"
        },
        "is_read": 0,
        "created_at": "2024-01-20 17:00:00"
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "unread_count": 5
  }
}
```

#### 8.1.2 标记消息已读
**接口地址**: `POST /messages/{id}/read`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | int | 是 | 消息ID |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "标记成功"
}
```

#### 8.1.3 批量标记已读
**接口地址**: `POST /messages/batch-read`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "message_ids": [1, 2, 3]
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "批量标记成功",
  "data": {
    "updated_count": 3
  }
}
```

## 9. 文件上传

### 9.1 图片上传

#### 9.1.1 上传单张图片
**接口地址**: `POST /upload/image`

**请求头**:
```
Authorization: Bearer {token}
Content-Type: multipart/form-data
```

**请求参数**:
- image: 图片文件
- type: 图片类型 (avatar, product, health_record, license)

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "上传成功",
  "data": {
    "file_id": "img_123456",
    "file_name": "product.jpg",
    "file_size": 204800,
    "file_url": "https://cdn.xlxumu.com/uploads/2024/01/20/product_123456.jpg",
    "thumbnail_url": "https://cdn.xlxumu.com/uploads/2024/01/20/thumb_product_123456.jpg"
  }
}
```

#### 9.1.2 批量上传图片
**接口地址**: `POST /upload/images`

**请求头**:
```
Authorization: Bearer {token}
Content-Type: multipart/form-data
```

**请求参数**:
- images[]: 图片文件数组
- type: 图片类型

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "上传成功",
  "data": {
    "uploaded_files": [
      {
        "file_id": "img_123456",
        "file_name": "product1.jpg",
        "file_url": "https://cdn.xlxumu.com/uploads/2024/01/20/product1_123456.jpg",
        "thumbnail_url": "https://cdn.xlxumu.com/uploads/2024/01/20/thumb_product1_123456.jpg"
      },
      {
        "file_id": "img_123457",
        "file_name": "product2.jpg",
        "file_url": "https://cdn.xlxumu.com/uploads/2024/01/20/product2_123457.jpg",
        "thumbnail_url": "https://cdn.xlxumu.com/uploads/2024/01/20/thumb_product2_123457.jpg"
      }
    ],
    "failed_files": [],
    "success_count": 2,
    "failed_count": 0
  }
}
```

## 10. AI智能服务

### 10.1 体况评估

#### 10.1.1 上传动物照片进行体况评估
**接口地址**: `POST /ai/body-condition-assessment`

**请求头**:
```
Authorization: Bearer {token}
Content-Type: multipart/form-data
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| animal_id | int | 是 | 动物ID |
| images | file[] | 是 | 动物照片（最多3张） |
| assessment_type | string | 否 | 评估类型：body_condition,health_check |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "评估完成",
  "data": {
    "assessment_id": "ai_20240120_001",
    "animal_id": 1,
    "body_condition_score": 3.5,
    "health_status": "healthy",
    "weight_estimate": 450.5,
    "recommendations": [
      "建议增加蛋白质饲料比例",
      "注意观察食欲变化",
      "定期称重监控"
    ],
    "confidence": 0.92,
    "processed_images": [
      "/uploads/ai/processed_001.jpg",
      "/uploads/ai/processed_002.jpg"
    ],
    "created_at": "2024-01-20 14:30:00"
  }
}
```

### 10.2 饲料配方推荐

#### 10.2.1 获取智能饲料配方
**接口地址**: `POST /ai/feed-formula`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "animal_type": "cattle",
  "breed": "西门塔尔牛",
  "age_months": 18,
  "weight": 450.5,
  "growth_stage": "fattening",
  "target_weight": 550.0,
  "target_days": 90,
  "available_feeds": [
    "玉米",
    "豆粕",
    "麦麸",
    "青贮饲料"
  ]
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "配方生成成功",
  "data": {
    "formula_id": "formula_20240120_001",
    "daily_intake": 12.5,
    "formula_components": [
      {
        "feed_name": "玉米",
        "percentage": 45.0,
        "daily_amount": 5.625,
        "unit": "kg"
      },
      {
        "feed_name": "豆粕",
        "percentage": 20.0,
        "daily_amount": 2.5,
        "unit": "kg"
      },
      {
        "feed_name": "青贮饲料",
        "percentage": 30.0,
        "daily_amount": 3.75,
        "unit": "kg"
      },
      {
        "feed_name": "麦麸",
        "percentage": 5.0,
        "daily_amount": 0.625,
        "unit": "kg"
      }
    ],
    "nutrition_analysis": {
      "crude_protein": 16.5,
      "metabolizable_energy": 11.8,
      "crude_fiber": 18.2,
      "calcium": 0.65,
      "phosphorus": 0.45
    },
    "expected_daily_gain": 1.2,
    "cost_per_day": 28.50,
    "created_at": "2024-01-20 14:30:00"
  }
}
```

### 10.3 疾病诊断辅助

#### 10.3.1 症状诊断
**接口地址**: `POST /ai/disease-diagnosis`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "animal_id": 1,
  "symptoms": [
    "食欲不振",
    "体温升高",
    "咳嗽"
  ],
  "duration_days": 3,
  "severity": "moderate",
  "additional_info": "最近天气变化较大"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "诊断完成",
  "data": {
    "diagnosis_id": "diag_20240120_001",
    "possible_diseases": [
      {
        "disease_name": "牛流感",
        "probability": 0.75,
        "severity": "moderate",
        "description": "病毒性呼吸道疾病"
      },
      {
        "disease_name": "肺炎",
        "probability": 0.60,
        "severity": "high",
        "description": "细菌性肺部感染"
      }
    ],
    "recommendations": [
      "建议立即隔离患病动物",
      "联系兽医进行进一步检查",
      "注意观察其他动物是否有类似症状"
    ],
    "emergency_level": "medium",
    "suggested_treatments": [
      "抗病毒药物治疗",
      "加强营养支持",
      "保持环境通风"
    ],
    "created_at": "2024-01-20 14:30:00"
  }
}
```

## 11. 政府监管服务

### 11.1 防疫管理

#### 11.1.1 获取防疫计划
**接口地址**: `GET /government/vaccination-plan`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| farm_id | int | 否 | 养殖场ID |
| year | int | 否 | 年份，默认当前年 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "plan_id": 1,
    "year": 2024,
    "farm_id": 1,
    "vaccinations": [
      {
        "id": 1,
        "vaccine_name": "口蹄疫疫苗",
        "target_animals": "所有牛只",
        "scheduled_date": "2024-03-15",
        "status": "pending",
        "veterinarian": "张兽医",
        "notes": "春季强制免疫"
      },
      {
        "id": 2,
        "vaccine_name": "布鲁氏菌病疫苗",
        "target_animals": "繁殖母牛",
        "scheduled_date": "2024-04-20",
        "status": "completed",
        "veterinarian": "李兽医",
        "completion_date": "2024-04-18",
        "notes": "已完成免疫"
      }
    ],
    "compliance_rate": 85.5,
    "next_inspection": "2024-06-15"
  }
}
```

#### 11.1.2 上报防疫记录
**接口地址**: `POST /government/vaccination-record`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "vaccination_plan_id": 1,
  "animal_ids": [1, 2, 3],
  "vaccine_batch": "VAC20240315001",
  "veterinarian_id": 1,
  "vaccination_date": "2024-03-15",
  "notes": "免疫正常，无不良反应"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "上报成功",
  "data": {
    "record_id": 1,
    "vaccination_count": 3,
    "compliance_updated": true,
    "next_vaccination": "2024-09-15"
  }
}
```

### 11.2 补贴申请

#### 11.2.1 获取可申请补贴列表
**接口地址**: `GET /government/subsidies/available`

**请求头**:
```
Authorization: Bearer {token}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "2024年生猪养殖补贴",
      "type": "breeding",
      "amount_per_head": 50.00,
      "max_amount": 10000.00,
      "application_deadline": "2024-06-30",
      "requirements": [
        "养殖规模不少于50头",
        "具备合法养殖手续",
        "通过环保验收"
      ],
      "status": "active"
    },
    {
      "id": 2,
      "name": "设备购置补贴",
      "type": "equipment",
      "subsidy_rate": 0.30,
      "max_amount": 50000.00,
      "application_deadline": "2024-12-31",
      "requirements": [
        "购买指定设备清单内设备",
        "提供正规发票",
        "设备已安装使用"
      ],
      "status": "active"
    }
  ]
}
```

#### 11.2.2 提交补贴申请
**接口地址**: `POST /government/subsidies/apply`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "subsidy_id": 1,
  "application_amount": 5000.00,
  "animal_count": 100,
  "supporting_documents": [
    "/uploads/documents/license.pdf",
    "/uploads/documents/inspection_report.pdf"
  ],
  "description": "申请生猪养殖补贴，当前存栏100头"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "申请提交成功",
  "data": {
    "application_id": "SUB20240120001",
    "status": "under_review",
    "estimated_review_days": 15,
    "tracking_number": "GOV20240120001"
  }
}
```

## 12. 数据中台服务

### 12.1 数据查询

#### 12.1.1 获取行业数据统计
**接口地址**: `GET /data-platform/industry-stats`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| region | string | 否 | 地区代码 |
| animal_type | string | 否 | 动物类型 |
| time_range | string | 否 | 时间范围：month,quarter,year |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "overview": {
      "total_farms": 1250,
      "total_animals": 125000,
      "avg_farm_size": 100,
      "industry_output_value": 1500000000
    },
    "regional_distribution": [
      {
        "region": "锡林浩特市",
        "farm_count": 450,
        "animal_count": 45000,
        "output_value": 540000000
      },
      {
        "region": "东乌旗",
        "farm_count": 380,
        "animal_count": 38000,
        "output_value": 456000000
      }
    ],
    "price_trends": [
      {
        "date": "2024-01",
        "cattle_price": 28.50,
        "pig_price": 15.20,
        "chicken_price": 8.80
      },
      {
        "date": "2024-02",
        "cattle_price": 29.20,
        "pig_price": 15.80,
        "chicken_price": 9.10
      }
    ],
    "market_analysis": {
      "trend": "rising",
      "confidence": 0.85,
      "factors": [
        "春节需求增加",
        "饲料成本上升",
        "政策支持力度加大"
      ]
    }
  }
}
```

### 12.2 数据共享

#### 12.2.1 获取共享数据权限
**接口地址**: `GET /data-platform/sharing-permissions`

**请求头**:
```
Authorization: Bearer {token}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "user_level": "premium",
    "available_datasets": [
      {
        "dataset_id": "market_prices",
        "name": "市场价格数据",
        "description": "实时市场价格信息",
        "access_level": "read",
        "update_frequency": "daily"
      },
      {
        "dataset_id": "weather_data",
        "name": "气象数据",
        "description": "地区气象信息",
        "access_level": "read",
        "update_frequency": "hourly"
      }
    ],
    "usage_quota": {
      "daily_requests": 1000,
      "used_requests": 150,
      "remaining_requests": 850
    }
  }
}
```

## 13. 数据统计

### 13.1 个人统计

#### 13.1.1 获取个人数据统计
**接口地址**: `GET /statistics/personal`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| period | string | 否 | 统计周期：week,month,year |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "overview": {
      "farm_count": 1,
      "animal_count": 150,
      "product_count": 5,
      "order_count": 10,
      "total_income": 15000.00
    },
    "farm_stats": [
      {
        "farm_id": 1,
        "farm_name": "张三养猪场",
        "animal_count": 150,
        "health_rate": 96.7,
        "avg_weight": 85.5
      }
    ],
    "income_trend": [
      {
        "date": "2024-01-01",
        "income": 5000.00,
        "order_count": 3
      },
      {
        "date": "2024-01-20",
        "income": 15000.00,
        "order_count": 10
      }
    ],
    "animal_growth": [
      {
        "date": "2024-01-01",
        "total_count": 145,
        "avg_weight": 80.0
      },
      {
        "date": "2024-01-20",
        "total_count": 150,
        "avg_weight": 85.5
      }
    ]
  }
}
```

## 14. 小程序特有功能

### 14.1 离线数据缓存

#### 14.1.1 获取离线数据包
**接口地址**: `GET /offline/data-package`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| modules | string | 否 | 模块列表，逗号分隔：farms,animals,products |
| last_sync | timestamp | 否 | 上次同步时间戳 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "package_id": "offline_20240120_001",
    "sync_timestamp": 1705747200000,
    "modules": {
      "farms": {
        "version": "1.0.1",
        "data": [
          {
            "id": 1,
            "name": "张三养殖场",
            "location": "锡林浩特市",
            "animal_count": 150
          }
        ]
      },
      "animals": {
        "version": "1.0.2",
        "data": [
          {
            "id": 1,
            "ear_tag": "XL001",
            "name": "小花",
            "breed": "西门塔尔牛"
          }
        ]
      }
    },
    "cache_duration": 86400
  }
}
```

#### 14.1.2 上传离线操作记录
**接口地址**: `POST /offline/sync-operations`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "operations": [
    {
      "operation_id": "local_001",
      "type": "create",
      "module": "feeding_record",
      "data": {
        "animal_id": 1,
        "feed_type": "玉米",
        "amount": 5.5,
        "feeding_time": "2024-01-20 08:00:00"
      },
      "timestamp": 1705747200000
    },
    {
      "operation_id": "local_002",
      "type": "update",
      "module": "animal",
      "data": {
        "id": 1,
        "weight": 455.5
      },
      "timestamp": 1705747260000
    }
  ]
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "同步成功",
  "data": {
    "sync_id": "sync_20240120_001",
    "processed_count": 2,
    "success_count": 2,
    "failed_count": 0,
    "conflicts": [],
    "next_sync_time": 1705833600000
  }
}
```

### 14.2 推送通知

#### 14.2.1 订阅推送通知
**接口地址**: `POST /notifications/subscribe`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "platform": "wechat_mini",
  "device_token": "wx_device_token_123",
  "notification_types": [
    "feeding_reminder",
    "health_alert",
    "order_status",
    "system_notice"
  ],
  "settings": {
    "feeding_reminder": {
      "enabled": true,
      "time": "08:00"
    },
    "health_alert": {
      "enabled": true,
      "severity": "medium"
    }
  }
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "订阅成功",
  "data": {
    "subscription_id": "sub_20240120_001",
    "status": "active",
    "subscribed_types": [
      "feeding_reminder",
      "health_alert",
      "order_status",
      "system_notice"
    ]
  }
}
```

#### 14.2.2 获取通知历史
**接口地址**: `GET /notifications/history`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| limit | int | 否 | 每页数量，默认20 |
| type | string | 否 | 通知类型筛选 |
| status | string | 否 | 状态：unread,read,all |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "type": "feeding_reminder",
        "title": "饲喂提醒",
        "content": "该给小花喂食了",
        "data": {
          "animal_id": 1,
          "feeding_time": "08:00"
        },
        "status": "unread",
        "created_at": "2024-01-20 08:00:00"
      },
      {
        "id": 2,
        "type": "health_alert",
        "title": "健康预警",
        "content": "壮壮体温异常，请及时检查",
        "data": {
          "animal_id": 2,
          "alert_type": "temperature"
        },
        "status": "read",
        "created_at": "2024-01-19 15:30:00"
      }
    ],
    "has_more": false,
    "total": 2,
    "unread_count": 1
  }
}
```

### 14.3 实时消息

#### 14.3.1 建立WebSocket连接
**连接地址**: `wss://api.xlxumu.com/app/v1/ws`

**连接参数**:
```
Authorization: Bearer {token}
platform: wechat_mini
```

**消息格式**:
```json
{
  "type": "message_type",
  "data": {},
  "timestamp": 1705747200000
}
```

#### 14.3.2 消息类型定义

**心跳消息**:
```json
{
  "type": "heartbeat",
  "data": {
    "status": "online"
  },
  "timestamp": 1705747200000
}
```

**数据更新消息**:
```json
{
  "type": "data_update",
  "data": {
    "module": "animal",
    "action": "update",
    "record_id": 1,
    "changes": {
      "weight": 455.5,
      "health_status": "healthy"
    }
  },
  "timestamp": 1705747200000
}
```

**系统通知消息**:
```json
{
  "type": "system_notification",
  "data": {
    "title": "系统维护通知",
    "content": "系统将于今晚22:00-24:00进行维护",
    "level": "info",
    "action_url": "/notices/detail/123"
  },
  "timestamp": 1705747200000
}
```

## 15. 支付宝小程序适配

### 15.1 支付宝登录

#### 15.1.1 支付宝授权登录
**接口地址**: `POST /auth/alipay/login`

**请求参数**:
```json
{
  "auth_code": "alipay_auth_code",
  "encrypted_data": "encrypted_user_info",
  "signature": "data_signature"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "refresh_token_123",
    "expires_in": 7200,
    "is_new_user": false,
    "user": {
      "id": 1,
      "alipay_user_id": "alipay_user_123",
      "nickname": "张三",
      "avatar": "https://tfs.alipayobjects.com/avatar.jpg",
      "phone": "138****8000",
      "is_verified": true
    }
  }
}
```

### 15.2 支付宝支付

#### 15.2.1 创建支付宝支付订单
**接口地址**: `POST /payments/alipay/create`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "order_id": "ORD20240120001",
  "amount": 268.00,
  "subject": "优质牛肉礼盒装",
  "body": "来自锡林浩特优质牧场的新鲜牛肉",
  "buyer_id": "alipay_user_123"
}
```

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "支付订单创建成功",
  "data": {
    "trade_no": "ALIPAY20240120001",
    "order_string": "alipay_sdk=alipay-sdk-java...",
    "qr_code": "https://qr.alipay.com/pay_code_123"
  }
}
```

## 16. 系统配置

### 16.1 应用配置

#### 16.1.1 获取应用配置
**接口地址**: `GET /config/app`

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "app_name": "畜牧养殖助手",
    "app_version": "1.0.0",
    "api_version": "v1",
    "upload_config": {
      "max_file_size": 10485760,
      "allowed_types": ["jpg", "jpeg", "png", "gif"],
      "max_files_per_upload": 9
    },
    "payment_config": {
      "supported_methods": ["wechat_mini", "alipay_mini"],
      "min_amount": 0.01,
      "max_amount": 50000.00
    },
    "business_config": {
      "animal_categories": [
        {
          "code": "cattle",
          "name": "牛",
          "breeds": ["西门塔尔牛", "安格斯牛", "夏洛莱牛"]
        },
        {
          "code": "pig",
          "name": "生猪",
          "breeds": ["杜洛克猪", "长白猪", "大白猪"]
        }
      ],
      "shipping_methods": [
        {
          "code": "express",
          "name": "快递配送"
        },
        {
          "code": "pickup",
          "name": "自提"
        }
      ]
    }
  }
}
```

### 16.2 地区数据

#### 16.2.1 获取省市区数据
**接口地址**: `GET /config/regions`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| parent_code | string | 否 | 父级区域代码 |
| level | int | 否 | 级别：1-省，2-市，3-区 |

**响应数据**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "code": "150000",
      "name": "内蒙古自治区",
      "level": 1,
      "parent_code": null
    },
    {
      "code": "152500",
      "name": "锡林郭勒盟",
      "level": 2,
      "parent_code": "150000"
    }
  ]
}
```

## 17. 错误处理

### 17.1 错误码定义

| 错误码 | HTTP状态码 | 错误信息 | 说明 |
|--------|------------|----------|------|
| 10001 | 400 | 参数错误 | 请求参数格式错误或缺失 |
| 10002 | 401 | 未授权 | Token无效或已过期 |
| 10003 | 403 | 禁止访问 | 权限不足 |
| 10004 | 404 | 资源不存在 | 请求的资源不存在 |
| 10005 | 422 | 参数验证失败 | 参数格式正确但验证失败 |
| 10006 | 429 | 请求过于频繁 | 触发限流 |
| 10007 | 500 | 服务器内部错误 | 系统异常 |
| 20001 | 400 | 微信授权失败 | 微信登录授权失败 |
| 20002 | 400 | 支付宝授权失败 | 支付宝登录授权失败 |
| 20003 | 400 | 手机号绑定失败 | 手机号绑定失败 |
| 20004 | 400 | 用户未实名认证 | 需要先完成实名认证 |
| 30001 | 400 | 养殖场审核中 | 养殖场正在审核中 |
| 30002 | 400 | 养殖场已存在 | 养殖场名称或编码已存在 |
| 40001 | 400 | 动物不存在 | 指定的动物不存在 |
| 40002 | 400 | 动物已售出 | 动物已经售出 |
| 50001 | 400 | 商品已下架 | 商品已经下架 |
| 50002 | 400 | 库存不足 | 商品库存不足 |
| 60001 | 400 | 订单状态错误 | 订单状态不允许此操作 |
| 60002 | 400 | 支付失败 | 支付处理失败 |
| 70001 | 400 | AI服务不可用 | AI分析服务暂时不可用 |
| 70002 | 400 | 图片格式不支持 | 上传的图片格式不支持 |
| 80001 | 400 | 离线数据冲突 | 离线数据与服务器数据冲突 |
| 80002 | 400 | 同步失败 | 数据同步失败 |

### 17.2 错误响应示例

#### 17.2.1 参数验证错误
```json
{
  "success": false,
  "code": 10005,
  "message": "参数验证失败",
  "errors": [
    {
      "field": "phone",
      "message": "手机号格式不正确"
    },
    {
      "field": "farm_name",
      "message": "养殖场名称不能为空"
    }
  ],
  "timestamp": 1705747200000
}
```

#### 17.2.2 权限不足错误
```json
{
  "success": false,
  "code": 10003,
  "message": "权限不足，请先完成实名认证",
  "timestamp": 1705747200000
}
```

#### 17.2.3 离线数据冲突错误
```json
{
  "success": false,
  "code": 80001,
  "message": "离线数据与服务器数据冲突",
  "data": {
    "conflicts": [
      {
        "operation_id": "local_001",
        "conflict_type": "version_mismatch",
        "server_version": "1.0.2",
        "local_version": "1.0.1",
        "resolution_options": ["use_server", "use_local", "merge"]
      }
    ]
  },
  "timestamp": 1705747200000
}
```

## 18. 接口安全

### 18.1 认证机制
- **JWT Token**: 基于JWT的身份认证
- **Token刷新**: 支持Token自动刷新机制
- **设备绑定**: Token与设备信息绑定
- **过期处理**: 自动处理Token过期情况
- **多平台支持**: 支持微信小程序和支付宝小程序

### 18.2 数据加密
- **HTTPS传输**: 所有接口使用HTTPS加密传输
- **敏感数据**: 手机号、身份证等敏感信息加密存储
- **签名验证**: 关键接口支持签名验证
- **小程序加密**: 支持小程序平台的数据加密机制

### 18.3 防护措施
- **频率限制**: 接口调用频率限制
- **参数验证**: 严格的参数格式和内容验证
- **SQL注入防护**: 防止SQL注入攻击
- **XSS防护**: 防止跨站脚本攻击
- **CSRF防护**: 防止跨站请求伪造

## 19. 性能优化

### 19.1 缓存策略
- **接口缓存**: 静态数据接口缓存
- **图片CDN**: 图片资源CDN加速
- **数据预加载**: 关键数据预加载
- **离线缓存**: 支持关键数据离线缓存
- **小程序缓存**: 利用小程序本地存储优化

### 19.2 网络优化
- **数据压缩**: 响应数据Gzip压缩
- **分页加载**: 列表数据分页加载
- **图片优化**: 图片自动压缩和格式转换
- **请求合并**: 相关接口请求合并
- **游标分页**: 大数据量采用游标分页

### 19.3 小程序优化
- **包体积优化**: 减少不必要的依赖和资源
- **启动优化**: 优化小程序启动速度
- **渲染优化**: 优化页面渲染性能
- **内存管理**: 合理管理内存使用

## 20. 总结

本文档详细定义了畜牧养殖管理平台小程序APP的所有API接口，涵盖了完整的业务功能和技术特性。

### 20.1 核心特性
- **移动端优化**: 专为移动端设计的轻量化接口
- **多平台支持**: 支持微信小程序和支付宝小程序
- **实时数据同步**: 支持关键业务数据实时更新
- **离线功能支持**: 关键功能支持离线访问
- **完善的支付体系**: 集成微信支付和支付宝支付
- **AI智能服务**: 体况评估、饲料配方、疾病诊断等AI功能

### 20.2 技术亮点
- **游标分页**: 采用游标分页提升大数据量加载性能
- **图片处理**: 自动生成缩略图和多尺寸图片
- **数据统计**: 丰富的个人和业务数据统计
- **消息推送**: 完善的消息通知和推送机制
- **文件上传**: 支持单张和批量图片上传
- **WebSocket**: 实时消息推送和数据同步
- **离线同步**: 支持离线操作和数据同步

### 20.3 业务覆盖
- **用户管理**: 多平台授权登录、实名认证、个人信息管理
- **养殖管理**: 养殖场和动物的全生命周期管理
- **交易功能**: 商品发布、浏览、下单、支付完整流程
- **AI服务**: 智能体况评估、饲料配方推荐、疾病诊断
- **政府监管**: 防疫管理、补贴申请等政府服务
- **数据中台**: 行业数据统计和数据共享服务
- **数据分析**: 个人和养殖场的多维度数据统计
- **消息通知**: 系统消息和业务通知的统一管理

### 20.4 后续优化方向
- **功能扩展**: 根据用户反馈持续优化功能
- **性能提升**: 接口响应速度和用户体验优化
- **平台扩展**: 支持更多小程序平台和移动应用
- **智能化升级**: 引入更多AI技术提升用户体验
- **数据分析**: 增强数据分析和商业智能功能
- **生态建设**: 构建完整的畜牧养殖生态系统