aiotagro/jiebanke

Fork 0

Files

ylweng 7b73f2be33 修改文件结构

2025-09-01 02:20:36 +08:00

11 KiB

Raw Blame History

📚 结伴客API接口文档

📋 文档说明

本文档详细描述了结伴客项目的所有API接口，包括请求参数、响应格式和错误代码。结伴客是一个专注于结伴旅行和动物认领的社交平台。

🔐 认证方式

JWT Token 认证

所有需要认证的API必须在请求头中携带Token：

Authorization: Bearer <your_jwt_token>

Token 获取

通过微信登录接口获取Token，Token有效期为7天。

👥 用户模块

微信用户登录

Endpoint: POST /api/v1/auth/wechat-login

请求参数:

{
  "code": "string, required, 微信登录code",
  "userInfo": {
    "nickName": "string, required, 用户昵称",
    "avatarUrl": "string, required, 用户头像",
    "gender": "number, optional, 性别(0:未知,1:男,2:女)",
    "province": "string, optional, 省份",
    "city": "string, optional, 城市"
  }
}

响应示例:

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

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "openid": "wx1234567890",
    "nickname": "旅行达人",
    "avatar": "https://avatar.url",
    "gender": "male",
    "birthday": "1990-01-01",
    "phone": "13800138000",
    "email": "test@example.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 <token>

请求参数:

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

响应示例:

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

查询参数:

?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	最高预算

响应示例:

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

请求参数:

{
  "travelPlanId": "number, required, 旅行计划ID",
  "inviteeId": "number, required, 被邀请用户ID",
  "message": "string, optional, 邀请消息"
}

响应示例:

{
  "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	最高价格

响应示例:

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

请求参数:

{
  "animalId": "number, required, 动物ID",
  "duration": "number, required, 认领时长(月)",
  "agreementAccepted": "boolean, required, 是否接受协议"
}

响应示例:

{
  "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	最高价格

响应示例:

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

请求参数:

{
  "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, 祝福语"
}

响应示例:

{
  "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请求/分钟

限流响应

当超过限流阈值时返回：

{
  "code": 429,
  "message": "请求过于频繁，请稍后再试",
  "retryAfter": 60
}

🧪 接口测试

使用curl测试

# 微信用户登录
curl -X POST http://localhost:3000/api/v1/auth/wechat-login \
  -H "Content-Type: application/json" \
  -d '{"code":"wxlogincode123","userInfo":{"nickName":"测试用户","avatarUrl":"https://avatar.url","gender":1}}'

# 获取旅行计划列表
curl -X GET http://localhost:3000/api/v1/travel/plans \
  -H "Authorization: Bearer <token>"

使用Postman测试

导入Postman集合文件
设置环境变量（base_url, token等）
运行测试用例

📝 更新日志

v1.0.0 (2024-01-01)

微信用户登录接口
旅行结伴管理接口
动物认领管理接口
送花服务接口
基础认证系统

最后更新: 2024年 📅

11 KiB Raw Blame History Unescape Escape

📚 结伴客API接口文档

📋 文档说明

🔐 认证方式

JWT Token 认证

Token 获取

👥 用户模块

微信用户登录

获取用户信息

🧳 旅行结伴模块

发布旅行计划

获取旅行计划列表

发起结伴邀请

🐄 动物认领模块

获取可认领动物列表

认领动物

💐 送花服务模块

获取鲜花商品列表

下单送花

📊 数据字典

旅行计划状态

结伴邀请状态

动物认领状态

送花订单状态

错误代码

🔗 API 版本控制

📡 接口限流

限流策略

限流响应

🧪 接口测试

使用curl测试

使用Postman测试

📝 更新日志

v1.0.0 (2024-01-01)

11 KiB

Raw Blame History