# 小程序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 请求头 ```http Content-Type: application/json Authorization: Bearer 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 成功响应 ```json { "code": 200, "message": "操作成功", "data": { // 具体数据 }, "timestamp": "2024-01-15T10:30:00Z", "request_id": "req_123456789" } ``` #### 2.2.2 分页响应 ```json { "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 错误响应 ```json { "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` - **接口描述**：微信小程序登录 - **是否需要认证**：否 #### 请求参数 ```json { "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 | 否 | 数据签名 | #### 响应示例 ```json { "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` - **接口描述**：刷新访问令牌 - **是否需要认证**：否 #### 请求参数 ```json { "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` #### 响应示例 ```json { "code": 200, "message": "令牌刷新成功", "data": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_in": 7200, "token_type": "Bearer" } } ``` ### 3.3 获取用户信息 #### 接口信息 - **接口路径**：`GET /api/v1/auth/me` - **接口描述**：获取当前用户信息 - **是否需要认证**：是 #### 响应示例 ```json { "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` - **接口描述**：更新用户个人信息 - **是否需要认证**：是 #### 请求参数 ```json { "nickname": "新昵称", "avatar_url": "https://example.com/new_avatar.jpg", "gender": 2, "birthday": "1995-05-15", "location": "上海市", "bio": "更新的个人简介", "interests": ["旅行", "摄影", "美食"], "occupation": "软件工程师" } ``` #### 响应示例 ```json { "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-是 | #### 响应示例 ```json { "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}` - **接口描述**：获取旅行活动详细信息 - **是否需要认证**：否 #### 响应示例 ```json { "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` - **接口描述**：创建新的旅行活动 - **是否需要认证**：是 #### 请求参数 ```json { "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": ["西藏", "文化", "朝圣"] } ``` #### 响应示例 ```json { "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` - **接口描述**：申请参加旅行活动 - **是否需要认证**：是 #### 请求参数 ```json { "join_reason": "对大理文化很感兴趣，希望能参加这次深度游", "contact_info": { "wechat": "xiaoming123", "phone": "13900139000" }, "emergency_contact": { "name": "李四", "phone": "13800138000", "relationship": "朋友" }, "special_requirements": "素食主义者，需要素食安排", "travel_experience": "去过云南多次，有丰富的旅行经验" } ``` #### 响应示例 ```json { "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 | 否 | 每页数量 | #### 响应示例 ```json { "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-是 | #### 响应示例 ```json { "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}` - **接口描述**：获取动物详细信息 - **是否需要认证**：否 #### 响应示例 ```json { "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` - **接口描述**：申请认领动物 - **是否需要认证**：是 #### 请求参数 ```json { "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": "希望能定期收到小花的照片和视频" } ``` #### 响应示例 ```json { "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 | 否 | 每页数量 | #### 响应示例 ```json { "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` - **接口描述**：获取认领动物的成长动态 - **是否需要认证**：是 #### 响应示例 ```json { "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` - **接口描述**：创建支付订单 - **是否需要认证**：是 #### 请求参数 ```json { "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" } } ``` #### 响应示例 ```json { "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` - **接口描述**：发起微信支付 - **是否需要认证**：是 #### 请求参数 ```json { "payment_method": "wechat", "openid": "wx_openid_123456" } ``` #### 响应示例 ```json { "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}` - **接口描述**：查询订单详情和支付状态 - **是否需要认证**：是 #### 响应示例 ```json { "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 | 否 | 每页数量 | #### 响应示例 ```json { "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 | 否 | 每页数量 | #### 响应示例 ```json { "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` - **接口描述**：标记消息为已读 - **是否需要认证**：是 #### 响应示例 ```json { "code": 200, "message": "标记成功" } ``` ### 7.3 批量标记已读 #### 接口信息 - **接口路径**：`PUT /api/v1/messages/batch-read` - **接口描述**：批量标记消息为已读 - **是否需要认证**：是 #### 请求参数 ```json { "message_ids": [1, 2, 3, 4, 5] } ``` #### 响应示例 ```json { "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 | #### 响应示例 ```json { "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 | 否 | 分类 | #### 响应示例 ```json { "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 | 否 | 每页数量 | #### 响应示例 ```json { "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 | #### 响应示例 ```json { "code": 200, "message": "获取成功", "data": { "suggestions": [ "大理古城", "大理洱海", "大理三塔", "大理旅游" ] } } ``` ## 10. 收藏点赞接口 ### 10.1 点赞/取消点赞 #### 接口信息 - **接口路径**：`POST /api/v1/likes` - **接口描述**：点赞或取消点赞 - **是否需要认证**：是 #### 请求参数 ```json { "target_type": "travel", "target_id": 1, "action": "like" } ``` | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | target_type | string | 是 | 目标类型：travel,animal | | target_id | integer | 是 | 目标ID | | action | string | 是 | 操作：like-点赞，unlike-取消点赞 | #### 响应示例 ```json { "code": 200, "message": "点赞成功", "data": { "is_liked": true, "like_count": 24 } } ``` ### 10.2 收藏/取消收藏 #### 接口信息 - **接口路径**：`POST /api/v1/favorites` - **接口描述**：收藏或取消收藏 - **是否需要认证**：是 #### 请求参数 ```json { "target_type": "animal", "target_id": 1, "action": "favorite" } ``` #### 响应示例 ```json { "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 | 否 | 每页数量 | #### 响应示例 ```json { "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 | 否 | 每页数量 | #### 响应示例 ```json { "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` - **接口描述**：发表评论 - **是否需要认证**：是 #### 请求参数 ```json { "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（回复时填写） | #### 响应示例 ```json { "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` - **接口描述**：获取小程序相关配置 - **是否需要认证**：否 #### 响应示例 ```json { "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` - **接口描述**：获取首页配置信息 - **是否需要认证**：否 #### 响应示例 ```json { "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 登录测试 ```bash 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 获取旅行列表测试 ```bash curl -X GET "https://api-test.jiebanke.com/api/v1/travels?page=1&size=10" \ -H "Accept: application/json" ``` #### 14.3.3 创建旅行活动测试 ```bash 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数据 - **版本管理**：清晰的版本规划和更新记录 本接口设计文档将作为小程序前端开发的重要参考，确保前后端协作的高效进行。