aiotagro/jiebanke

Fork 0

Files

ylweng 47c816270d 重构动物模型和路由系统，优化查询逻辑并新增商户和促销活动功能

2025-09-22 02:04:07 +08:00

40 KiB

Raw Blame History

小程序app接口设计文档

1. 概述

1.1 项目简介

本文档详细描述了解班客小程序端的所有API接口设计，包括用户系统、旅行结伴、动物认领、支付系统、消息通知等模块的接口规范。

1.2 接口设计原则

RESTful风格：遵循REST架构风格
统一响应格式：所有接口采用统一的响应格式
微信生态集成：深度集成微信小程序能力
安全认证：基于微信授权和JWT Token
性能优化：针对移动端网络环境优化

1.3 技术规范

协议：HTTPS
数据格式：JSON
字符编码：UTF-8
认证方式：微信授权 + JWT Token
API版本：v1

2. 通用规范

2.1 请求格式

2.1.1 请求头

Content-Type: application/json
Authorization: Bearer <JWT_TOKEN>
Accept: application/json
User-Agent: JieBanKe-MiniProgram/1.0.0
X-Platform: miniprogram
X-Version: 1.0.0

2.1.2 请求参数

路径参数：用于资源标识，如 /api/v1/travels/{id}
查询参数：用于过滤、排序、分页等，如 ?page=1&size=10&sort=created_at:desc
请求体：JSON格式的数据

2.2 响应格式

2.2.1 成功响应

{
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体数据
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}

2.2.2 分页响应

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      // 数据列表
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 50,
      "pages": 5,
      "has_next": true,
      "has_prev": false
    }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}

2.2.3 错误响应

{
  "code": 400,
  "message": "请求参数错误",
  "error": {
    "type": "VALIDATION_ERROR",
    "details": [
      {
        "field": "phone",
        "message": "手机号格式不正确"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_123456789"
}

2.3 状态码规范

状态码	说明	使用场景
200	成功	请求成功处理
201	创建成功	资源创建成功
204	无内容	删除成功或更新成功无返回内容
400	请求错误	参数错误、格式错误
401	未授权	未登录或token无效
403	禁止访问	权限不足
404	资源不存在	请求的资源不存在
422	实体错误	业务逻辑错误
500	服务器错误	内部服务器错误

2.4 分页参数

参数名	类型	默认值	说明
page	integer	1	页码，从1开始
size	integer	10	每页数量，最大50
sort	string	created_at:desc	排序字段和方向

3. 用户认证接口

3.1 微信登录

接口信息

接口路径：POST /api/v1/auth/wechat/login
接口描述：微信小程序登录
是否需要认证：否

请求参数

{
  "code": "wx_code_from_login",
  "encrypted_data": "encrypted_user_info",
  "iv": "initialization_vector",
  "raw_data": "raw_user_data",
  "signature": "data_signature"
}

参数名	类型	必填	说明
code	string	是	微信登录凭证
encrypted_data	string	否	加密的用户信息
iv	string	否	加密算法的初始向量
raw_data	string	否	原始数据字符串
signature	string	否	数据签名

响应示例

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200,
    "token_type": "Bearer",
    "user_info": {
      "id": 1,
      "uuid": "user_123456",
      "openid": "wx_openid_123",
      "unionid": "wx_unionid_456",
      "nickname": "微信用户",
      "real_name": "",
      "avatar": "https://wx.qlogo.cn/avatar.jpg",
      "user_type": "regular",
      "balance": 0.00,
      "status": "active",
      "is_new_user": false,
      "profile_completed": true
    }
  }
}

3.2 刷新令牌

接口信息

接口路径：POST /api/v1/auth/refresh
接口描述：刷新访问令牌
是否需要认证：否

请求参数

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

响应示例

{
  "code": 200,
  "message": "令牌刷新成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200,
    "token_type": "Bearer"
  }
}

3.3 获取用户信息

接口信息

接口路径：GET /api/v1/auth/me
接口描述：获取当前用户信息
是否需要认证：是

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "uuid": "user_123456",
    "nickname": "旅行达人",
    "real_name": "张三",
    "avatar_url": "https://example.com/avatar.jpg",
    "user_type": "normal",
    "balance": 1500.00,
    "status": 1,
    "profile_completed": true,
    "created_at": "2024-01-01T10:00:00Z",
    "statistics": {
      "travel_count": 5,
      "adoption_count": 2,
      "following_count": 15,
      "followers_count": 8,
      "like_count": 23
    }
  }
}

3.4 更新用户信息

接口信息

接口路径：PUT /api/v1/auth/profile
接口描述：更新用户个人信息
是否需要认证：是

请求参数

{
  "nickname": "新昵称",
  "avatar_url": "https://example.com/new_avatar.jpg",
  "gender": 2,
  "birthday": "1995-05-15",
  "location": "上海市",
  "bio": "更新的个人简介",
  "interests": ["旅行", "摄影", "美食"],
  "occupation": "软件工程师"
}

响应示例

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "nickname": "新昵称",
    "avatar": "https://example.com/new_avatar.jpg",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

4. 旅行结伴接口

4.1 获取旅行列表

接口信息

接口路径：GET /api/v1/travels
接口描述：分页获取旅行活动列表
是否需要认证：否

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认10
sort	string	否	排序，默认created_at:desc
keyword	string	否	搜索关键词
destination	string	否	目的地
travel_type	string	否	旅行类型
start_date	string	否	开始日期（YYYY-MM-DD）
end_date	string	否	结束日期（YYYY-MM-DD）
budget_min	number	否	预算下限
budget_max	number	否	预算上限
status	integer	否	状态：1-招募中，2-进行中，3-已完成
is_featured	integer	否	是否精选：1-是

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "uuid": "travel_123456",
        "title": "云南大理古城深度游",
        "description": "探索大理古城的历史文化...",
        "destination": "云南大理",
        "start_date": "2024-03-01",
        "end_date": "2024-03-05",
        "duration_days": 5,
        "max_participants": 8,
        "current_participants": 3,
        "price_per_person": 2500.00,
        "includes": "住宿、早餐、门票、导游",
        "excludes": "午餐、晚餐、个人消费",
        "travel_type": "cultural",
        "status": "recruiting",
        "is_featured": true,
        "view_count": 156,
        "like_count": 23,
        "comment_count": 8,
        "creator": {
          "id": 1,
          "nickname": "旅行达人",
          "avatar": "https://example.com/avatar.jpg"
        },
        "cover_image": "https://example.com/cover.jpg",
        "images": [
          "https://example.com/image1.jpg",
          "https://example.com/image2.jpg"
        ],
        "tags": ["文化", "古城", "摄影"],
        "created_at": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 50,
      "pages": 5,
      "has_next": true,
      "has_prev": false
    }
  }
}

4.2 获取旅行详情

接口信息

接口路径：GET /api/v1/travels/{id}
接口描述：获取旅行活动详细信息
是否需要认证：否

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "uuid": "travel_123456",
    "title": "云南大理古城深度游",
    "description": "探索大理古城的历史文化，体验白族风情，品尝当地美食...",
    "destination": "云南大理",
    "destination_detail": {
      "province": "云南省",
      "city": "大理市",
      "district": "大理古城",
      "address": "大理古城南门",
      "latitude": 25.6916,
      "longitude": 100.1669
    },
    "start_date": "2024-03-01",
    "end_date": "2024-03-05",
    "duration_days": 5,
    "max_participants": 8,
    "current_participants": 3,
    "price_per_person": 2500.00,
    "includes": "住宿、早餐、门票、导游",
    "excludes": "午餐、晚餐、个人消费",
    "travel_type": "cultural",
    "itinerary": [
      {
        "day": 1,
        "title": "抵达大理",
        "activities": ["接机", "入住客栈", "古城夜游"]
      },
      {
        "day": 2,
        "title": "大理古城游览",
        "activities": ["洱海骑行", "三塔寺参观", "古城购物"]
      }
    ],
    "requirements": "身体健康，有一定体力，热爱文化旅行",
    "included_services": ["住宿", "早餐", "景点门票", "导游服务"],
    "excluded_services": ["往返交通", "午晚餐", "个人消费"],
    "contact_info": {
      "wechat": "traveler001",
      "phone": "13800138000"
    },
    "images": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg"
    ],
    "tags": ["文化", "古城", "摄影"],
    "status": "recruiting",
    "is_featured": true,
    "view_count": 156,
    "like_count": 23,
    "comment_count": 8,
    "share_count": 5,
    "creator": {
      "id": 1,
      "nickname": "旅行达人",
      "avatar": "https://example.com/avatar.jpg",
      "travel_count": 15,
      "rating": 4.8,
      "verified": true
    },
    "participants": [
      {
        "id": 1,
        "user": {
          "id": 2,
          "nickname": "小明",
          "avatar": "https://example.com/avatar2.jpg",
          "age": 28,
          "gender": 1
        },
        "status": "confirmed",
        "applied_at": "2024-01-10T15:30:00Z"
      }
    ],
    "is_liked": false,
    "is_applied": false,
    "can_apply": true,
    "created_at": "2024-01-15T10:00:00Z"
  }
}

4.3 创建旅行活动

接口信息

接口路径：POST /api/v1/travels
接口描述：创建新的旅行活动
是否需要认证：是

请求参数

{
  "title": "西藏拉萨朝圣之旅",
  "description": "深度体验西藏文化，朝圣布达拉宫...",
  "destination": "西藏拉萨",
  "start_date": "2024-04-01",
  "end_date": "2024-04-07",
  "max_participants": 6,
  "price_per_person": 6500.00,
  "includes": "住宿、早餐、景点门票",
  "excludes": "往返机票、午晚餐",
  "travel_type": "cultural",
  "itinerary": [
    {
      "day": 1,
      "title": "抵达拉萨",
      "activities": ["接机", "入住酒店", "适应高原"]
    }
  ],
  "requirements": "身体健康，无高原反应病史",
  "contact_info": {
    "wechat": "tibet_lover",
    "phone": "13900139000"
  },
  "images": [
    "https://example.com/tibet1.jpg",
    "https://example.com/tibet2.jpg"
  ],
  "tags": ["西藏", "文化", "朝圣"]
}

响应示例

{
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 101,
    "uuid": "travel_654321",
    "title": "西藏拉萨朝圣之旅",
    "status": 0,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

4.4 申请参加旅行

接口信息

接口路径：POST /api/v1/travels/{id}/apply
接口描述：申请参加旅行活动
是否需要认证：是

请求参数

{
  "join_reason": "对大理文化很感兴趣，希望能参加这次深度游",
  "contact_info": {
    "wechat": "xiaoming123",
    "phone": "13900139000"
  },
  "emergency_contact": {
    "name": "李四",
    "phone": "13800138000",
    "relationship": "朋友"
  },
  "special_requirements": "素食主义者，需要素食安排",
  "travel_experience": "去过云南多次，有丰富的旅行经验"
}

响应示例

{
  "code": 200,
  "message": "申请成功",
  "data": {
    "application_id": 1,
    "status": 0,
    "applied_at": "2024-01-15T10:30:00Z",
    "message": "申请已提交，请等待组织者审核"
  }
}

4.5 获取我的旅行

接口信息

接口路径：GET /api/v1/travels/mine
接口描述：获取我创建和参与的旅行活动
是否需要认证：是

查询参数

参数名	类型	必填	说明
type	string	否	类型：created-我创建的，joined-我参与的，applied-我申请的
status	integer	否	状态筛选
page	integer	否	页码
size	integer	否	每页数量

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "title": "云南大理古城深度游",
        "destination": "云南大理",
        "start_date": "2024-03-01",
        "end_date": "2024-03-05",
        "status": 1,
        "my_role": "creator",
        "my_status": 1,
        "participants_count": 3,
        "max_participants": 8,
        "cover_image": "https://example.com/cover.jpg",
        "created_at": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 5,
      "pages": 1
    }
  }
}

5. 动物认领接口

5.1 获取动物列表

接口信息

接口路径：GET /api/v1/animals
接口描述：分页获取可认领动物列表
是否需要认证：否

查询参数

参数名	类型	必填	说明
page	integer	否	页码，默认1
size	integer	否	每页数量，默认10
sort	string	否	排序，默认created_at:desc
keyword	string	否	搜索关键词（动物名称）
type	string	否	动物类型：cat,dog,rabbit,other
breed	string	否	品种
gender	string	否	性别：male,female
age_min	integer	否	年龄下限（月）
age_max	integer	否	年龄上限（月）
location	string	否	所在地
status	string	否	状态：available,claimed,unavailable
is_featured	integer	否	是否精选：1-是

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "uuid": "animal_123456",
        "name": "小花",
        "type": "猫",
        "breed": "英国短毛猫",
        "gender": "female",
        "age": 24,
        "price": 500.00,
        "daily_cost": 15.00,
        "location": "北京市朝阳区",
        "status": "available",
        "health_status": "健康",
        "description": "性格温顺，喜欢晒太阳",
        "images": [
          "https://example.com/cat1.jpg",
          "https://example.com/cat2.jpg"
        ],
        "vaccination_records": [
          {
            "vaccine": "狂犬疫苗",
            "date": "2024-01-01",
            "next_date": "2025-01-01"
          }
        ],
        "farmer": {
          "id": 1,
          "name": "爱心动物农场",
          "location": "北京市朝阳区"
        },
        "view_count": 89,
        "like_count": 15,
        "created_at": "2024-01-10T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 30,
      "pages": 3
    }
  }
}

5.2 获取动物详情

接口信息

接口路径：GET /api/v1/animals/{id}
接口描述：获取动物详细信息
是否需要认证：否

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "uuid": "animal_123456",
    "name": "小花",
    "type": "猫",
    "breed": "英国短毛猫",
    "gender": "female",
    "age": 24,
    "price": 500.00,
    "daily_cost": 15.00,
    "location": "北京市朝阳区",
    "status": "available",
    "health_status": "健康",
    "description": "小花是一只非常温顺的英国短毛猫，喜欢晒太阳和玩毛线球...",
    "images": [
      "https://example.com/cat1.jpg",
      "https://example.com/cat2.jpg"
    ],
    "vaccination_records": [
      {
        "vaccine": "狂犬疫苗",
        "date": "2024-01-01",
        "next_date": "2025-01-01"
      }
    ],
    "farmer": {
      "id": 1,
      "name": "爱心动物农场",
      "location": "北京市朝阳区",
      "contact_phone": "13800138000"
    },
    "view_count": 89,
    "like_count": 15,
    "is_liked": false,
    "can_adopt": true,
    "created_at": "2024-01-10T10:00:00Z"
  }
}

5.3 申请认领动物

接口信息

接口路径：POST /api/v1/animals/{id}/adopt
接口描述：申请认领动物
是否需要认证：是

请求参数

{
  "adoption_type": 1,
  "duration_months": 12,
  "start_date": "2024-02-01",
  "adoption_reason": "非常喜欢小花，希望能给它一个温暖的家",
  "experience": "养过猫咪，有丰富的养宠经验",
  "living_condition": "独居公寓，环境安静，适合猫咪生活",
  "contact_info": {
    "wechat": "cat_lover",
    "phone": "13900139000"
  },
  "emergency_contact": {
    "name": "李四",
    "phone": "13800138000",
    "relationship": "朋友"
  },
  "special_requirements": "希望能定期收到小花的照片和视频"
}

响应示例

{
  "code": 200,
  "message": "申请成功",
  "data": {
    "adoption_id": 1,
    "status": 0,
    "total_fee": 2400.00,
    "applied_at": "2024-01-15T10:30:00Z",
    "message": "认领申请已提交，请等待农场审核"
  }
}

5.4 获取我的认领

接口信息

接口路径：GET /api/v1/adoptions/mine
接口描述：获取我的动物认领记录
是否需要认证：是

查询参数

参数名	类型	必填	说明
status	integer	否	状态：0-申请中，1-已通过，2-已拒绝，3-进行中，4-已完成
page	integer	否	页码
size	integer	否	每页数量

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "uuid": "adoption_123456",
        "animal": {
          "id": 1,
          "name": "小花",
          "species": "cat",
          "breed": "英国短毛猫",
          "cover_image": "https://example.com/cat_cover.jpg"
        },
        "adoption_type": 1,
        "duration_months": 12,
        "start_date": "2024-02-01",
        "end_date": "2025-02-01",
        "monthly_fee": 200.00,
        "total_fee": 2400.00,
        "status": 3,
        "progress": {
          "days_passed": 15,
          "total_days": 365,
          "percentage": 4.1
        },
        "next_update_date": "2024-02-15",
        "applied_at": "2024-01-15T10:30:00Z",
        "approved_at": "2024-01-16T09:00:00Z",
        "started_at": "2024-02-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 2,
      "pages": 1
    }
  }
}

5.5 获取认领动态

接口信息

接口路径：GET /api/v1/adoptions/{id}/updates
接口描述：获取认领动物的成长动态
是否需要认证：是

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "type": "daily_care",
        "title": "小花今日状况",
        "content": "小花今天很活泼，吃了很多猫粮，还玩了新玩具",
        "images": [
          "https://example.com/update1.jpg",
          "https://example.com/update2.jpg"
        ],
        "videos": [
          "https://example.com/update_video.mp4"
        ],
        "caretaker": {
          "name": "张三",
          "avatar_url": "https://example.com/caretaker.jpg"
        },
        "created_at": "2024-02-15T14:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 20,
      "pages": 2
    }
  }
}

6. 支付系统接口

6.1 创建订单

接口信息

接口路径：POST /api/v1/orders
接口描述：创建支付订单
是否需要认证：是

请求参数

{
  "order_type": "adoption",
  "related_id": 1,
  "items": [
    {
      "name": "认领小花（英国短毛猫）",
      "description": "12个月长期认领",
      "quantity": 1,
      "unit_price": 2400.00
    }
  ],
  "amount": 2400.00,
  "currency": "CNY",
  "payment_method": "wechat",
  "metadata": {
    "adoption_id": 1,
    "source": "miniprogram"
  }
}

响应示例

{
  "code": 201,
  "message": "订单创建成功",
  "data": {
    "order_id": 1,
    "order_no": "ORD202401150001",
    "amount": 2400.00,
    "currency": "CNY",
    "status": 0,
    "expires_at": "2024-01-15T11:00:00Z",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

6.2 发起支付

接口信息

接口路径：POST /api/v1/orders/{id}/pay
接口描述：发起微信支付
是否需要认证：是

请求参数

{
  "payment_method": "wechat",
  "openid": "wx_openid_123456"
}

响应示例

{
  "code": 200,
  "message": "支付参数获取成功",
  "data": {
    "payment_id": 1,
    "payment_no": "PAY202401150001",
    "payment_params": {
      "appId": "wx_app_id",
      "timeStamp": "1705312200",
      "nonceStr": "random_string",
      "package": "prepay_id=wx_prepay_123456",
      "signType": "RSA",
      "paySign": "signature_string"
    },
    "expires_at": "2024-01-15T11:00:00Z"
  }
}

6.3 查询订单状态

接口信息

接口路径：GET /api/v1/orders/{id}
接口描述：查询订单详情和支付状态
是否需要认证：是

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "order_no": "ORD202401150001",
    "order_type": "adoption",
    "related_id": 1,
    "related_info": {
      "animal": {
        "id": 1,
        "name": "小花",
        "species": "cat",
        "cover_image": "https://example.com/cat_cover.jpg"
      }
    },
    "title": "认领小花（英国短毛猫）",
    "description": "12个月长期认领",
    "amount": 2400.00,
    "currency": "CNY",
    "status": 2,
    "payment_method": "wechat",
    "payment_status": 2,
    "paid_at": "2024-01-15T10:35:00Z",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

6.4 获取我的订单

接口信息

接口路径：GET /api/v1/orders/mine
接口描述：获取我的订单列表
是否需要认证：是

查询参数

参数名	类型	必填	说明
status	integer	否	订单状态
order_type	string	否	订单类型
page	integer	否	页码
size	integer	否	每页数量

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "order_no": "ORD202401150001",
        "order_type": "adoption",
        "title": "认领小花（英国短毛猫）",
        "amount": 2400.00,
        "status": 2,
        "payment_status": 2,
        "cover_image": "https://example.com/cat_cover.jpg",
        "paid_at": "2024-01-15T10:35:00Z",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 5,
      "pages": 1
    }
  }
}

7. 消息通知接口

7.1 获取消息列表

接口信息

接口路径：GET /api/v1/messages
接口描述：获取用户消息列表
是否需要认证：是

查询参数

参数名	类型	必填	说明
type	string	否	消息类型：system,travel,adoption,order
status	integer	否	状态：0-未读，1-已读
page	integer	否	页码
size	integer	否	每页数量

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "type": "adoption",
        "title": "认领申请通过",
        "content": "您的动物认领申请已通过审核，请及时完成支付",
        "avatar": "https://example.com/system_avatar.jpg",
        "related_type": "adoption",
        "related_id": 1,
        "status": 0,
        "created_at": "2024-01-16T09:00:00Z"
      },
      {
        "id": 2,
        "type": "travel",
        "title": "旅行申请通过",
        "content": "您申请参加的"云南大理古城深度游"已通过审核",
        "avatar": "https://example.com/travel_avatar.jpg",
        "related_type": "travel",
        "related_id": 1,
        "status": 1,
        "created_at": "2024-01-15T16:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 15,
      "pages": 2
    },
    "unread_count": 3
  }
}

7.2 标记消息已读

接口信息

接口路径：PUT /api/v1/messages/{id}/read
接口描述：标记消息为已读
是否需要认证：是

响应示例

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

7.3 批量标记已读

接口信息

接口路径：PUT /api/v1/messages/batch-read
接口描述：批量标记消息为已读
是否需要认证：是

请求参数

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

响应示例

{
  "code": 200,
  "message": "批量标记成功",
  "data": {
    "updated_count": 5
  }
}

8. 文件上传接口

8.1 上传图片

接口信息

接口路径：POST /api/v1/upload/image
接口描述：上传图片文件
是否需要认证：是

请求参数

Content-Type：multipart/form-data

参数名	类型	必填	说明
file	file	是	图片文件
category	string	否	分类：avatar,travel,animal,other

响应示例

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "file_id": 1,
    "file_url": "https://cdn.example.com/uploads/images/2024/01/15/image_123456.jpg",
    "file_size": 1024000,
    "width": 1920,
    "height": 1080,
    "uploaded_at": "2024-01-15T10:30:00Z"
  }
}

8.2 批量上传图片

接口信息

接口路径：POST /api/v1/upload/images
接口描述：批量上传多张图片
是否需要认证：是

请求参数

Content-Type：multipart/form-data

参数名	类型	必填	说明
files[]	file[]	是	图片文件数组
category	string	否	分类

响应示例

{
  "code": 200,
  "message": "批量上传完成",
  "data": {
    "success_count": 3,
    "failed_count": 0,
    "files": [
      {
        "file_id": 1,
        "file_url": "https://cdn.example.com/uploads/images/image1.jpg"
      },
      {
        "file_id": 2,
        "file_url": "https://cdn.example.com/uploads/images/image2.jpg"
      }
    ]
  }
}

9. 搜索接口

9.1 综合搜索

接口信息

接口路径：GET /api/v1/search
接口描述：综合搜索旅行和动物
是否需要认证：否

查询参数

参数名	类型	必填	说明
keyword	string	是	搜索关键词
type	string	否	搜索类型：all,travel,animal，默认all
page	integer	否	页码
size	integer	否	每页数量

响应示例

{
  "code": 200,
  "message": "搜索成功",
  "data": {
    "travels": {
      "items": [
        {
          "id": 1,
          "title": "云南大理古城深度游",
          "destination": "云南大理",
          "cover_image": "https://example.com/travel_cover.jpg",
          "creator": {
            "nickname": "旅行达人"
          }
        }
      ],
      "total": 5
    },
    "animals": {
      "items": [
        {
          "id": 1,
          "name": "小花",
          "species": "cat",
          "breed": "英国短毛猫",
          "cover_image": "https://example.com/cat_cover.jpg",
          "farm": {
            "name": "爱心动物农场"
          }
        }
      ],
      "total": 3
    },
    "total_count": 8
  }
}

9.2 搜索建议

接口信息

接口路径：GET /api/v1/search/suggestions
接口描述：获取搜索建议
是否需要认证：否

查询参数

参数名	类型	必填	说明
keyword	string	是	搜索关键词
type	string	否	类型：travel,animal

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "suggestions": [
      "大理古城",
      "大理洱海",
      "大理三塔",
      "大理旅游"
    ]
  }
}

10. 收藏点赞接口

10.1 点赞/取消点赞

接口信息

接口路径：POST /api/v1/likes
接口描述：点赞或取消点赞
是否需要认证：是

请求参数

{
  "target_type": "travel",
  "target_id": 1,
  "action": "like"
}

参数名	类型	必填	说明
target_type	string	是	目标类型：travel,animal
target_id	integer	是	目标ID
action	string	是	操作：like-点赞，unlike-取消点赞

响应示例

{
  "code": 200,
  "message": "点赞成功",
  "data": {
    "is_liked": true,
    "like_count": 24
  }
}

10.2 收藏/取消收藏

接口信息

接口路径：POST /api/v1/favorites
接口描述：收藏或取消收藏
是否需要认证：是

请求参数

{
  "target_type": "animal",
  "target_id": 1,
  "action": "favorite"
}

响应示例

{
  "code": 200,
  "message": "收藏成功",
  "data": {
    "is_favorited": true,
    "favorite_count": 16
  }
}

10.3 获取我的收藏

接口信息

接口路径：GET /api/v1/favorites/mine
接口描述：获取我的收藏列表
是否需要认证：是

查询参数

参数名	类型	必填	说明
type	string	否	类型：travel,animal
page	integer	否	页码
size	integer	否	每页数量

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "target_type": "travel",
        "target_id": 1,
        "target_info": {
          "id": 1,
          "title": "云南大理古城深度游",
          "destination": "云南大理",
          "cover_image": "https://example.com/travel_cover.jpg"
        },
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 8,
      "pages": 1
    }
  }
}

11. 评论接口

11.1 获取评论列表

接口信息

接口路径：GET /api/v1/comments
接口描述：获取评论列表
是否需要认证：否

查询参数

参数名	类型	必填	说明
target_type	string	是	目标类型：travel,animal
target_id	integer	是	目标ID
page	integer	否	页码
size	integer	否	每页数量

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "content": "这个旅行计划看起来很不错，很想参加！",
        "user": {
          "id": 2,
          "nickname": "旅行爱好者",
          "avatar_url": "https://example.com/avatar.jpg"
        },
        "like_count": 3,
        "is_liked": false,
        "replies": [
          {
            "id": 2,
            "content": "欢迎加入我们！",
            "user": {
              "id": 1,
              "nickname": "旅行达人",
              "avatar_url": "https://example.com/avatar2.jpg"
            },
            "created_at": "2024-01-15T11:00:00Z"
          }
        ],
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 8,
      "pages": 1
    }
  }
}

11.2 发表评论

接口信息

接口路径：POST /api/v1/comments
接口描述：发表评论
是否需要认证：是

请求参数

{
  "target_type": "travel",
  "target_id": 1,
  "content": "这个旅行计划很棒，期待参加！",
  "parent_id": null
}

参数名	类型	必填	说明
target_type	string	是	目标类型：travel,animal
target_id	integer	是	目标ID
content	string	是	评论内容
parent_id	integer	否	父评论ID（回复时填写）

响应示例

{
  "code": 201,
  "message": "评论成功",
  "data": {
    "id": 10,
    "content": "这个旅行计划很棒，期待参加！",
    "user": {
      "id": 3,
      "nickname": "我的昵称",
      "avatar_url": "https://example.com/my_avatar.jpg"
    },
    "like_count": 0,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

12. 系统配置接口

12.1 获取小程序配置

接口信息

接口路径：GET /api/v1/config/miniprogram
接口描述：获取小程序相关配置
是否需要认证：否

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "app_info": {
      "name": "解班客",
      "version": "1.0.0",
      "description": "专业的旅行结伴和动物认领平台"
    },
    "features": {
      "travel_enabled": true,
      "adoption_enabled": true,
      "payment_enabled": true,
      "share_enabled": true
    },
    "upload": {
      "max_image_size": 5242880,
      "max_images_count": 9,
      "allowed_image_types": ["jpg", "jpeg", "png"]
    },
    "payment": {
      "min_amount": 0.01,
      "max_amount": 50000.00,
      "supported_methods": ["wechat"]
    },
    "contact": {
      "customer_service": "kefu001",
      "phone": "400-123-4567",
      "email": "support@jiebanke.com"
    }
  }
}

12.2 获取首页配置

接口信息

接口路径：GET /api/v1/config/home
接口描述：获取首页配置信息
是否需要认证：否

响应示例

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "banners": [
      {
        "id": 1,
        "title": "春节特惠旅行",
        "image_url": "https://example.com/banner1.jpg",
        "link_type": "travel",
        "link_value": "1",
        "sort_order": 1
      }
    ],
    "featured_travels": [
      {
        "id": 1,
        "title": "云南大理古城深度游",
        "cover_image": "https://example.com/travel_cover.jpg",
        "destination": "云南大理"
      }
    ],
    "featured_animals": [
      {
        "id": 1,
        "name": "小花",
        "species": "cat",
        "cover_image": "https://example.com/cat_cover.jpg"
      }
    ],
    "announcements": [
      {
        "id": 1,
        "title": "平台升级公告",
        "content": "为了提供更好的服务...",
        "created_at": "2024-01-15T10:00:00Z"
      }
    ]
  }
}

13. 错误码说明

13.1 通用错误码

错误码	HTTP状态码	说明
200	200	请求成功
400	400	请求参数错误
401	401	未授权，需要登录
403	403	权限不足
404	404	资源不存在
422	422	业务逻辑错误
429	429	请求频率限制
500	500	服务器内部错误

13.2 业务错误码

错误码	说明
10001	微信授权失败
10002	用户信息不完整
10003	手机号格式错误
10004	用户不存在
20001	旅行活动不存在
20002	旅行活动已满员
20003	旅行活动已结束
20004	重复申请旅行活动
20005	不能申请自己创建的活动
30001	动物不存在
30002	动物已被认领
30003	重复申请认领
30004	认领申请不存在
40001	订单不存在
40002	订单已支付
40003	订单已过期
40004	支付失败
40005	退款失败
50001	文件上传失败
50002	文件格式不支持
50003	文件大小超限
60001	评论不存在
60002	不能删除他人评论

14. 接口测试

14.1 测试环境

测试域名：https://api-test.jiebanke.com
文档地址：https://api-test.jiebanke.com/docs
测试账号：
- 测试用户1：openid_test_001
- 测试用户2：openid_test_002

14.2 测试工具

推荐使用以下工具进行接口测试：

Postman：图形化接口测试工具
curl：命令行测试工具
微信开发者工具：小程序调试工具

14.3 测试示例

14.3.1 登录测试

curl -X POST https://api-test.jiebanke.com/api/v1/auth/wechat/login \
  -H "Content-Type: application/json" \
  -d '{
    "code": "test_wx_code_123456"
  }'

14.3.2 获取旅行列表测试

curl -X GET "https://api-test.jiebanke.com/api/v1/travels?page=1&size=10" \
  -H "Accept: application/json"

14.3.3 创建旅行活动测试

curl -X POST https://api-test.jiebanke.com/api/v1/travels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "title": "测试旅行活动",
    "description": "这是一个测试活动",
    "destination": "北京",
    "start_date": "2024-03-01",
    "end_date": "2024-03-03",
    "max_participants": 5,
    "budget_min": 1000.00,
    "budget_max": 2000.00,
    "travel_type": "leisure"
  }'

14.4 Mock数据

为了方便前端开发，提供以下Mock数据接口：

Mock服务地址：https://mock.jiebanke.com
数据更新频率：每日更新
支持接口：所有小程序端接口

15. 版本更新记录

v1.0.0 (2024-01-15)

初始版本发布
完成用户认证、旅行结伴、动物认领、支付系统等核心功能接口
支持微信小程序登录和支付
实现文件上传、消息通知等辅助功能

后续版本规划

v1.1.0 (计划2024-02-15)

增加社交功能接口（关注、私信）
优化搜索算法和推荐系统
增加用户等级和积分系统

v1.2.0 (计划2024-03-15)

增加直播功能接口
支持多语言国际化
增加AI智能推荐接口

16. 总结

本文档详细描述了解班客小程序端的所有API接口设计，涵盖了：

16.1 核心功能

用户系统：微信登录、用户信息管理
旅行结伴：活动发布、申请、管理
动物认领：动物展示、认领申请、动态更新
支付系统：订单创建、微信支付集成
消息通知：系统消息、业务通知

16.2 辅助功能

文件上传：图片上传、批量处理
搜索功能：综合搜索、智能建议
社交功能：点赞、收藏、评论
系统配置：动态配置、首页内容

16.3 技术特点

RESTful设计：遵循REST架构原则
统一响应格式：标准化的API响应
微信生态集成：深度集成微信小程序能力
安全认证：JWT Token + 微信授权
性能优化：分页、缓存、CDN加速

16.4 开发支持

完整的错误码体系：便于问题定位和处理
详细的接口文档：包含请求参数、响应示例
测试环境支持：提供测试环境和Mock数据
版本管理：清晰的版本规划和更新记录

本接口设计文档将作为小程序前端开发的重要参考，确保前后端协作的高效进行。

40 KiB Raw Blame History Unescape Escape

小程序app接口设计文档

1. 概述

1.1 项目简介

1.2 接口设计原则

1.3 技术规范

2. 通用规范

2.1 请求格式

2.1.1 请求头

2.1.2 请求参数

2.2 响应格式

2.2.1 成功响应

2.2.2 分页响应

2.2.3 错误响应

2.3 状态码规范

2.4 分页参数

3. 用户认证接口

3.1 微信登录

接口信息

请求参数

响应示例

3.2 刷新令牌

接口信息

请求参数

响应示例

3.3 获取用户信息

接口信息

响应示例

3.4 更新用户信息

接口信息

请求参数

响应示例

4. 旅行结伴接口

4.1 获取旅行列表

接口信息

查询参数

响应示例

4.2 获取旅行详情

接口信息

响应示例

4.3 创建旅行活动

接口信息

请求参数

响应示例

4.4 申请参加旅行

接口信息

请求参数

响应示例

4.5 获取我的旅行

接口信息

查询参数

响应示例

5. 动物认领接口

5.1 获取动物列表

接口信息

查询参数

响应示例

5.2 获取动物详情

接口信息

响应示例

5.3 申请认领动物

接口信息

请求参数

响应示例

5.4 获取我的认领

接口信息

查询参数

响应示例

5.5 获取认领动态

接口信息

响应示例

6. 支付系统接口

6.1 创建订单

接口信息

请求参数

响应示例

6.2 发起支付

接口信息

请求参数

响应示例

40 KiB

Raw Blame History