aiotagro/xlxumu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b705622d30528911227bddc655defabf259a0442
xlxumu/docs/design/小程序app接口设计文档.md

54 KiB
Raw Blame History

小程序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 通用响应格式

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": 1705747200000
}

1.4 错误响应格式

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

1.5 分页响应格式

{
  "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

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

请求参数:

{
  "code": "wx_code_from_wechat",
  "encrypted_data": "encrypted_user_info",
  "iv": "initialization_vector"
}

响应数据:

{
  "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}

请求参数:

{
  "encrypted_data": "encrypted_phone_data",
  "iv": "initialization_vector"
}

响应数据:

{
  "success": true,
  "code": 200,
  "message": "绑定成功",
  "data": {
    "phone": "13800138000",
    "is_verified": true
  }
}

2.2 Token管理

2.2.1 刷新Token

接口地址: POST /auth/refresh

请求参数:

{
  "refresh_token": "refresh_token_123"
}

响应数据:

{
  "success": true,
  "code": 200,
  "message": "刷新成功",
  "data": {
    "token": "new_jwt_token",
    "expires_in": 7200
  }
}

2.2.2 获取用户信息

接口地址: GET /auth/user

请求头:

Authorization: Bearer {token}

响应数据:

{
  "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}

请求参数:

{
  "real_name": "张三三",
  "gender": 1,
  "birthday": "1990-01-01",
  "address": "北京市朝阳区某某街道"
}

响应数据:

{
  "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: 头像文件

响应数据:

{
  "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}

请求参数:

{
  "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"
}

响应数据:

{
  "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}

响应数据:

{
  "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 否 养殖场状态

响应数据:

{
  "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

响应数据:

{
  "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}

请求参数:

{
  "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": "现代化养鸡场"
}

响应数据:

{
  "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

响应数据:

{
  "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 否 搜索关键词

响应数据:

{
  "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

响应数据:

{
  "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}

请求参数:

{
  "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": "新引进种猪"
}

响应数据:

{
  "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

请求参数:

{
  "name": "小猪001号",
  "weight": 87.0,
  "health_status": "healthy",
  "notes": "体重增长正常"
}

响应数据:

{
  "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 否 记录类型

响应数据:

{
  "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

请求参数:

{
  "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"
  ]
}

响应数据:

{
  "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}

请求参数:

{
  "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": "支持实地看货"
}

响应数据:

{
  "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 否 商品类型

响应数据:

{
  "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

响应数据:

{
  "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

响应数据:

{
  "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}

请求参数:

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

响应数据:

{
  "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

响应数据:

{
  "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

响应数据:

{
  "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}

请求参数:

{
  "order_id": 1,
  "payment_method": "wechat_mini"
}

响应数据:

{
  "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

响应数据:

{
  "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 否 是否已读

响应数据:

{
  "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

响应数据:

{
  "success": true,
  "code": 200,
  "message": "标记成功"
}

8.1.3 批量标记已读

接口地址: POST /messages/batch-read

请求头:

Authorization: Bearer {token}

请求参数:

{
  "message_ids": [1, 2, 3]
}

响应数据:

{
  "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)

响应数据:

{
  "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: 图片类型

响应数据:

{
  "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

响应数据:

{
  "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}

请求参数:

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

响应数据:

{
  "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}

请求参数:

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

响应数据:

{
  "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 否 年份，默认当前年

响应数据:

{
  "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}

请求参数:

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

响应数据:

{
  "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}

响应数据:

{
  "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}

请求参数:

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

响应数据:

{
  "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

响应数据:

{
  "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}

响应数据:

{
  "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

响应数据:

{
  "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 否 上次同步时间戳

响应数据:

{
  "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}

请求参数:

{
  "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
    }
  ]
}

响应数据:

{
  "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}

请求参数:

{
  "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"
    }
  }
}

响应数据:

{
  "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

响应数据:

{
  "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

消息格式:

{
  "type": "message_type",
  "data": {},
  "timestamp": 1705747200000
}

14.3.2 消息类型定义

心跳消息:

{
  "type": "heartbeat",
  "data": {
    "status": "online"
  },
  "timestamp": 1705747200000
}

数据更新消息:

{
  "type": "data_update",
  "data": {
    "module": "animal",
    "action": "update",
    "record_id": 1,
    "changes": {
      "weight": 455.5,
      "health_status": "healthy"
    }
  },
  "timestamp": 1705747200000
}

系统通知消息:

{
  "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

请求参数:

{
  "auth_code": "alipay_auth_code",
  "encrypted_data": "encrypted_user_info",
  "signature": "data_signature"
}

响应数据:

{
  "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}

请求参数:

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

响应数据:

{
  "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

响应数据:

{
  "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-区

响应数据:

{
  "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 参数验证错误

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

17.2.2 权限不足错误

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

17.2.3 离线数据冲突错误

{
  "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技术提升用户体验
  • 数据分析: 增强数据分析和商业智能功能
  • 生态建设: 构建完整的畜牧养殖生态系统