# 📚 结伴客API接口文档 ## 📋 文档说明 本文档详细描述了结伴客项目的所有API接口，包括请求参数、响应格式和错误代码。结伴客是一个专注于结伴旅行和动物认领的社交平台。 ## 🔐 认证方式 ### JWT Token 认证 所有需要认证的API必须在请求头中携带Token： ``` Authorization: Bearer ``` ### Token 获取 通过微信登录接口获取Token，Token有效期为7天。 ## 👥 用户模块 ### 微信用户登录 **Endpoint:** `POST /api/v1/auth/wechat-login` **请求参数:** ```json { "code": "string, required, 微信登录code", "userInfo": { "nickName": "string, required, 用户昵称", "avatarUrl": "string, required, 用户头像", "gender": "number, optional, 性别(0:未知,1:男,2:女)", "province": "string, optional, 省份", "city": "string, optional, 城市" } } ``` **响应示例:** ```json { "code": 200, "message": "登录成功", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "user": { "id": 1, "openid": "wx1234567890", "nickname": "旅行达人", "avatar": "https://avatar.url", "gender": "male", "phone": "13800138000" } } } ``` **错误代码:** - `400`: 参数验证失败 - `401`: 登录失败 - `500`: 服务器内部错误 ### 获取用户信息 **Endpoint:** `GET /api/v1/users/profile` **请求头:** ``` Authorization: Bearer ``` **响应示例:** ```json { "code": 200, "message": "获取成功", "data": { "id": 1, "openid": "wx1234567890", "nickname": "旅行达人", "avatar": "https://avatar.url", "gender": "male", "birthday": "1990-01-01", "phone": "13800138000", "email": "test@jiebanke.com", "travelCount": 5, "animalClaimCount": 2, "createdAt": "2024-01-01T00:00:00.000Z", "updatedAt": "2024-01-01T00:00:00.000Z" } } ``` **错误代码:** - `401`: 未授权访问 - `404`: 用户不存在 - `500`: 服务器内部错误 ## 🧳 旅行结伴模块 ### 发布旅行计划 **Endpoint:** `POST /api/v1/travel/plans` **请求头:** ``` Authorization: Bearer ``` **请求参数:** ```json { "destination": "string, required, 目的地", "startDate": "string, required, 开始日期(YYYY-MM-DD)", "endDate": "string, required, 结束日期(YYYY-MM-DD)", "budget": "number, optional, 预算", "interests": "string, optional, 兴趣偏好", "description": "string, optional, 行程描述", "visibility": "string, optional, 可见性(public/friends/private)" } ``` **响应示例:** ```json { "code": 200, "message": "旅行计划发布成功", "data": { "id": 1001, "userId": 1, "destination": "云南大理", "startDate": "2024-06-01", "endDate": "2024-06-07", "budget": 2000, "interests": "美食,摄影,文化", "status": "active", "createdAt": "2024-01-01T00:00:00.000Z" } } ``` ### 获取旅行计划列表 **Endpoint:** `GET /api/v1/travel/plans` **请求头:** ``` Authorization: Bearer ``` **查询参数:** ``` ?page=1&limit=10&destination=大理&startDate=2024-06-01&endDate=2024-06-30 ``` | 参数 | 类型 | 说明 | |------|------|------| | page | number | 页码，默认1 | | limit | number | 每页数量，默认10 | | destination | string | 目的地过滤 | | startDate | string | 开始日期过滤 | | endDate | string | 结束日期过滤 | | budgetMin | number | 最低预算 | | budgetMax | number | 最高预算 | **响应示例:** ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 1001, "userId": 1, "userInfo": { "nickname": "旅行达人", "avatar": "https://avatar.url" }, "destination": "云南大理", "startDate": "2024-06-01", "endDate": "2024-06-07", "budget": 2000, "interests": "美食,摄影,文化", "matchScore": 85, "createdAt": "2024-01-01T00:00:00.000Z" } ], "pagination": { "page": 1, "limit": 10, "total": 100, "pages": 10 } } } ``` ### 发起结伴邀请 **Endpoint:** `POST /api/v1/travel/invitations` **请求头:** ``` Authorization: Bearer ``` **请求参数:** ```json { "travelPlanId": "number, required, 旅行计划ID", "inviteeId": "number, required, 被邀请用户ID", "message": "string, optional, 邀请消息" } ``` **响应示例:** ```json { "code": 200, "message": "邀请发送成功", "data": { "id": 5001, "travelPlanId": 1001, "inviterId": 1, "inviteeId": 2, "status": "pending", "message": "一起结伴去大理吧！", "createdAt": "2024-01-01T00:00:00.000Z" } } ``` ## 🐄 动物认领模块 ### 获取可认领动物列表 **Endpoint:** `GET /api/v1/animals/available` **查询参数:** ``` ?page=1&limit=10&species=牛&farmLocation=云南 ``` | 参数 | 类型 | 说明 | |------|------|------| | page | number | 页码，默认1 | | limit | number | 每页数量，默认10 | | species | string | 动物种类过滤 | | breed | string | 品种过滤 | | farmLocation | string | 农场位置过滤 | | priceMin | number | 最低价格 | | priceMax | number | 最高价格 | **响应示例:** ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 2001, "name": "小白", "species": "牛", "breed": "荷斯坦", "birthDate": "2023-01-15", "personality": "温顺亲人", "farmLocation": "云南大理幸福农场", "price": 2999, "images": ["https://animal.image1.jpg", "https://animal.image2.jpg"], "merchantInfo": { "businessName": "幸福农场", "contactPerson": "张老板" }, "claimCount": 3, "createdAt": "2024-01-01T00:00:00.000Z" } ], "pagination": { "page": 1, "limit": 10, "total": 50, "pages": 5 } } } ``` ### 认领动物 **Endpoint:** `POST /api/v1/animals/claim` **请求头:** ``` Authorization: Bearer ``` **请求参数:** ```json { "animalId": "number, required, 动物ID", "duration": "number, required, 认领时长(月)", "agreementAccepted": "boolean, required, 是否接受协议" } ``` **响应示例:** ```json { "code": 200, "message": "认领成功", "data": { "id": 3001, "userId": 1, "animalId": 2001, "animalName": "小白", "duration": 12, "totalAmount": 35988, "status": "paid", "startDate": "2024-01-01", "endDate": "2025-01-01", "createdAt": "2024-01-01T00:00:00.000Z" } } ``` ## 💐 送花服务模块 ### 获取鲜花商品列表 **Endpoint:** `GET /api/v1/flower/products` **查询参数:** ``` ?page=1&limit=10&category=情人节&merchantId=1 ``` | 参数 | 类型 | 说明 | |------|------|------| | page | number | 页码，默认1 | | limit | number | 每页数量，默认10 | | category | string | 商品分类过滤 | | merchantId | number | 商家ID过滤 | | priceMin | number | 最低价格 | | priceMax | number | 最高价格 | **响应示例:** ```json { "code": 200, "message": "获取成功", "data": { "items": [ { "id": 4001, "name": "红玫瑰礼盒", "description": "11朵红玫瑰精美礼盒", "price": 199, "originalPrice": 259, "images": ["https://flower.image1.jpg"], "category": "情人节", "merchantInfo": { "businessName": "爱之花店", "contactPhone": "13800138000" }, "salesCount": 150, "rating": 4.8, "status": "active", "createdAt": "2024-01-01T00:00:00.000Z" } ], "pagination": { "page": 1, "limit": 10, "total": 100, "pages": 10 } } } ``` ### 下单送花 **Endpoint:** `POST /api/v1/flower/orders` **请求头:** ``` Authorization: Bearer ``` **请求参数:** ```json { "productId": "number, required, 商品ID", "quantity": "number, required, 数量", "recipientInfo": { "name": "string, required, 收花人姓名", "phone": "string, required, 收花人电话", "address": "string, required, 配送地址" }, "deliveryDate": "string, required, 配送日期(YYYY-MM-DD)", "message": "string, optional, 祝福语" } ``` **响应示例:** ```json { "code": 200, "message": "下单成功", "data": { "id": 5001, "orderNo": "FLOWER202401010001", "productId": 4001, "productName": "红玫瑰礼盒", "quantity": 1, "totalAmount": 199, "recipientName": "李小姐", "recipientPhone": "13800138001", "deliveryAddress": "北京市朝阳区xxx路xxx号", "deliveryDate": "2024-02-14", "status": "pending", "createdAt": "2024-01-01T00:00:00.000Z" } } ``` ## 📊 数据字典 ### 旅行计划状态 | 状态值 | 描述 | |--------|------| | active | 活跃中 | | completed | 已完成 | | cancelled | 已取消 | ### 结伴邀请状态 | 状态值 | 描述 | |--------|------| | pending | 待接受 | | accepted | 已接受 | | rejected | 已拒绝 | | cancelled | 已取消 | ### 动物认领状态 | 状态值 | 描述 | |--------|------| | pending | 待支付 | | paid | 已支付 | | active | 认领中 | | completed | 已完成 | | cancelled | 已取消 | ### 送花订单状态 | 状态值 | 描述 | |--------|------| | pending | 待支付 | | paid | 已支付 | | confirmed | 商家已确认 | | delivering | 配送中 | | completed | 已完成 | | cancelled | 已取消 | ### 错误代码 | 代码 | 描述 | |------|------| | 200 | 成功 | | 400 | 请求参数错误 | | 401 | 未授权访问 | | 403 | 禁止访问 | | 404 | 资源不存在 | | 409 | 资源冲突 | | 429 | 请求过于频繁 | | 500 | 服务器内部错误 | | 503 | 服务不可用 | ## 🔗 API 版本控制 当前API版本为v1，所有接口前缀为`/api/v1/`。 版本更新策略： - 向后兼容的修改直接更新 - 不兼容的修改创建新版本v2 - 旧版本API保持维护至少6个月 ## 📡 接口限流 ### 限流策略 - 匿名用户: 60请求/分钟 - 认证用户: 120请求/分钟 - VIP用户: 300请求/分钟 ### 限流响应 当超过限流阈值时返回： ```json { "code": 429, "message": "请求过于频繁，请稍后再试", "retryAfter": 60 } ``` ## 🧪 接口测试 ### 使用curl测试 ```bash # 微信用户登录 curl -X POST https://api.jiebanke.com/api/v1/auth/wechat-login \ -H "Content-Type: application/json" \ -d '{"code":"wxlogincode123","userInfo":{"nickName":"测试用户","avatarUrl":"https://avatar.url","gender":1}}' # 获取旅行计划列表 curl -X GET https://api.jiebanke.com/api/v1/travel/plans \ -H "Authorization: Bearer " ``` ### 使用Postman测试 1. 导入Postman集合文件 2. 设置环境变量（base_url, token等） 3. 运行测试用例 ## 📝 更新日志 ### v1.0.0 (2024-01-01) - 微信用户登录接口 - 旅行结伴管理接口 - 动物认领管理接口 - 送花服务接口 - 基础认证系统 --- *最后更新: 2024年* 📅