aiotagro/jiebanke

Fork 0

Files

aiotagro 62d122cff6 删除过时的API文档和README文件

2025-09-19 18:45:48 +08:00

10 KiB

Raw Blame History

📚 结伴客API接口文档

📋 文档说明

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

基础信息：

基础URL：https://api.jiebanke.com
API版本：v1
数据格式：JSON
字符编码：UTF-8

🔐 认证方式

JWT Token 认证

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

Authorization: Bearer <your_jwt_token>

Token 获取

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

📊 通用响应格式

成功响应

{
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体数据内容
  }
}

错误响应

{
  "code": 400,
  "message": "错误描述",
  "error": "详细错误信息"
}

状态码说明

200: 请求成功
400: 请求参数错误
401: 未授权访问
403: 权限不足
404: 资源不存在
500: 服务器内部错误

👥 用户管理模块

微信用户登录

接口地址： POST /api/v1/auth/wechat-login

接口描述： 用户通过微信授权登录系统

请求参数：

{
  "code": "string, required, 微信登录授权码",
  "userInfo": {
    "nickName": "string, required, 用户昵称",
    "avatarUrl": "string, required, 用户头像URL",
    "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",
      "isNewUser": false
    }
  }
}

获取用户信息

接口地址： 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": "user@jiebanke.com",
    "travelCount": 5,
    "animalClaimCount": 2,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

更新用户信息

接口地址： PUT /api/v1/users/profile

接口描述： 更新用户个人信息

请求参数：

{
  "nickname": "string, optional, 用户昵称",
  "avatar": "string, optional, 头像URL",
  "birthday": "string, optional, 生日(YYYY-MM-DD)",
  "phone": "string, optional, 手机号码",
  "email": "string, optional, 邮箱地址",
  "interests": "array, optional, 兴趣爱好标签"
}

🧳 旅行结伴模块

发布旅行计划

接口地址： POST /api/v1/travel/plans

接口描述： 用户发布新的旅行计划

请求参数：

{
  "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)",
  "maxParticipants": "number, optional, 最大参与人数"
}

响应示例：

{
  "code": 200,
  "message": "旅行计划发布成功",
  "data": {
    "id": 1001,
    "userId": 1,
    "destination": "云南大理",
    "startDate": "2024-06-01",
    "endDate": "2024-06-07",
    "budget": 2000,
    "interests": "美食,摄影,文化",
    "status": "active",
    "participantCount": 1,
    "maxParticipants": 4,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

获取旅行计划列表

接口地址： GET /api/v1/travel/plans

接口描述： 获取旅行计划列表，支持筛选和分页

查询参数：

page: number, optional, 页码(默认1)
limit: number, optional, 每页数量(默认10)
destination: string, optional, 目的地筛选
startDate: string, optional, 开始日期筛选
endDate: string, optional, 结束日期筛选
budget: number, optional, 预算筛选
status: string, optional, 状态筛选(active/completed/cancelled)

响应示例：

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "plans": [
      {
        "id": 1001,
        "user": {
          "id": 1,
          "nickname": "旅行达人",
          "avatar": "https://avatar.url"
        },
        "destination": "云南大理",
        "startDate": "2024-06-01",
        "endDate": "2024-06-07",
        "budget": 2000,
        "participantCount": 2,
        "maxParticipants": 4,
        "status": "active"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3
    }
  }
}

申请加入旅行计划

接口地址： POST /api/v1/travel/plans/{planId}/join

接口描述： 申请加入指定的旅行计划

请求参数：

{
  "message": "string, optional, 申请留言"
}

🐄 动物认领模块

获取可认领动物列表

接口地址： GET /api/v1/animals/available

接口描述： 获取可认领的动物列表

查询参数：

type: string, optional, 动物类型(cow/sheep/pig/chicken)
farmId: number, optional, 农场ID筛选
page: number, optional, 页码
limit: number, optional, 每页数量

响应示例：

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "animals": [
      {
        "id": 2001,
        "name": "小花牛",
        "type": "cow",
        "age": 6,
        "gender": "female",
        "description": "温顺可爱的小花牛",
        "images": ["https://image1.url", "https://image2.url"],
        "price": 1200,
        "farm": {
          "id": 101,
          "name": "阳光农场",
          "location": "四川成都"
        },
        "status": "available"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 15
    }
  }
}

认领动物

接口地址： POST /api/v1/animals/{animalId}/claim

接口描述： 认领指定的动物

请求参数：

{
  "duration": "number, required, 认领时长(月)",
  "message": "string, optional, 认领留言"
}

获取我的认领记录

接口地址： GET /api/v1/animals/my-claims

接口描述： 获取当前用户的动物认领记录

🏪 商家服务模块

商家注册

接口地址： POST /api/v1/merchants/register

接口描述： 商家用户注册

请求参数：

{
  "businessName": "string, required, 商家名称",
  "businessType": "string, required, 商家类型(flower_shop/farm/activity_organizer)",
  "contactName": "string, required, 联系人姓名",
  "contactPhone": "string, required, 联系电话",
  "businessLicense": "string, required, 营业执照号",
  "address": "string, required, 经营地址",
  "description": "string, optional, 商家描述"
}

获取商家产品列表

接口地址： GET /api/v1/merchants/{merchantId}/products

接口描述： 获取指定商家的产品列表

📦 订单管理模块

创建订单

接口地址： POST /api/v1/orders

接口描述： 创建新订单

请求参数：

{
  "type": "string, required, 订单类型(animal_claim/product_purchase/activity_booking)",
  "items": [
    {
      "itemId": "number, required, 商品/服务ID",
      "quantity": "number, required, 数量",
      "price": "number, required, 单价"
    }
  ],
  "totalAmount": "number, required, 总金额",
  "deliveryAddress": "object, optional, 配送地址信息"
}

获取订单列表

接口地址： GET /api/v1/orders

接口描述： 获取用户订单列表

查询参数：

status: string, optional, 订单状态筛选
type: string, optional, 订单类型筛选
page: number, optional, 页码
limit: number, optional, 每页数量

🎯 活动管理模块

获取活动列表

接口地址： GET /api/v1/activities

接口描述： 获取活动列表

查询参数：

type: string, optional, 活动类型
location: string, optional, 地点筛选
date: string, optional, 日期筛选
status: string, optional, 状态筛选

报名参加活动

接口地址： POST /api/v1/activities/{activityId}/register

接口描述： 报名参加指定活动

💬 消息通知模块

获取消息列表

接口地址： GET /api/v1/messages

接口描述： 获取用户消息列表

发送消息

接口地址： POST /api/v1/messages

接口描述： 发送消息给其他用户

🔧 系统管理模块

获取系统配置

接口地址： GET /api/v1/system/config

接口描述： 获取系统配置信息

文件上传

接口地址： POST /api/v1/upload

接口描述： 上传文件（图片、文档等）

请求格式： multipart/form-data

请求参数：

file: File, required, 上传的文件
type: string, optional, 文件类型(avatar/product/document)

📱 错误代码参考

错误代码	错误描述	解决方案
400	请求参数错误	检查请求参数格式和必填项
401	未授权访问	检查Token是否有效
403	权限不足	检查用户权限
404	资源不存在	检查请求的资源ID
409	资源冲突	检查是否重复操作
429	请求频率限制	降低请求频率
500	服务器内部错误	联系技术支持

📞 技术支持

如有API使用问题，请联系技术支持：

邮箱：tech-support@jiebanke.com
微信群：结伴客开发者群

文档版本：v1.0
最后更新：2025年1月

10 KiB Raw Blame History Unescape Escape

📚 结伴客API接口文档

📋 文档说明

🔐 认证方式

JWT Token 认证

Token 获取

📊 通用响应格式

成功响应

错误响应

状态码说明

👥 用户管理模块

微信用户登录

获取用户信息

更新用户信息

🧳 旅行结伴模块

发布旅行计划

获取旅行计划列表

申请加入旅行计划

🐄 动物认领模块

获取可认领动物列表

认领动物

获取我的认领记录

🏪 商家服务模块

商家注册

获取商家产品列表

📦 订单管理模块

创建订单

获取订单列表

🎯 活动管理模块

获取活动列表

报名参加活动

💬 消息通知模块

获取消息列表

发送消息

🔧 系统管理模块

获取系统配置

文件上传

📱 错误代码参考

📞 技术支持

10 KiB

Raw Blame History