aiotagro/jiebanke
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0cad74b06ffce56ebfd49154e9b9e1d042119b7f
jiebanke/docs/api-documentation.md
mapleaf 7f9bfbb381 Generating commit message...
2025-08-30 14:33:49 +08:00

17 KiB
Raw Blame History

结伴客系统 API 接口文档

基础信息

Base URL: http://localhost:3000/api/v1

认证方式: Bearer Token (JWT)

响应格式: JSON

响应格式

成功响应

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体数据
  },
  "timestamp": "2025-01-01T00:00:00.000Z"
}

错误响应

{
  "success": false,
  "code": 400,
  "message": "错误信息",
  "error": "详细错误描述",
  "timestamp": "2025-01-01T00:00:00.000Z"
}

认证接口

1. 用户注册

Endpoint: POST /auth/register

描述: 创建新用户账号

请求体:

{
  "username": "string, required, 用户名(4-20字符)",
  "password": "string, required, 密码(6-20字符)",
  "nickname": "string, optional, 昵称",
  "email": "string, optional, 邮箱",
  "phone": "string, optional, 手机号",
  "gender": "string, optional, 性别(male/female/unknown)",
  "birthday": "string, optional, 生日(YYYY-MM-DD)"
}

响应:

{
  "success": true,
  "code": 201,
  "message": "注册成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "13800138000",
      "avatar": "",
      "gender": "unknown",
      "points": 0,
      "level": 1,
      "status": "active",
      "created_at": "2025-01-01T00:00:00.000Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

2. 用户登录

Endpoint: POST /auth/login

描述: 用户登录获取访问令牌

请求体:

{
  "username": "string, required, 用户名/邮箱/手机号",
  "password": "string, required, 密码"
}

2.1 微信登录

Endpoint: POST /auth/wechat-login

描述: 微信授权登录

请求体:

{
  "code": "string, required, 微信授权码",
  "userInfo": {
    "nickName": "string, optional, 微信昵称",
    "avatarUrl": "string, optional, 微信头像",
    "gender": "number, optional, 性别(0:未知,1:男,2:女)"
  }
}

响应: 同登录接口

响应:

{
  "success": true,
  "code": 200,
  "message": "登录成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "13800138000",
      "avatar": "",
      "gender": "unknown",
      "points": 100,
      "level": 2,
      "status": "active",
      "last_login_at": "2025-01-01T00:00:00.000Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

3. 微信登录

Endpoint: POST /auth/wechat-login

描述: 微信授权登录

请求体:

{
  "code": "string, required, 微信授权码",
  "userInfo": {
    "nickName": "string, optional, 微信昵称",
    "avatarUrl": "string, optional, 微信头像",
    "gender": "number, optional, 性别(0:未知,1:男,2:女)"
  }
}

响应: 同登录接口

4. 获取当前用户信息

Endpoint: GET /auth/me

认证: 需要Bearer Token

描述: 获取当前登录用户信息

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "13800138000",
      "avatar": "https://example.com/avatar.jpg",
      "gender": "male",
      "birthday": "1990-01-01",
      "points": 1000,
      "level": 3,
      "balance": 500.00,
      "travel_count": 5,
      "animal_adopt_count": 2,
      "flower_order_count": 3,
      "status": "active",
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z",
      "last_login_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

5. 更新用户信息

Endpoint: PUT /auth/profile

认证: 需要Bearer Token

描述: 更新用户个人信息

请求体:

{
  "nickname": "string, optional, 昵称",
  "avatar": "string, optional, 头像URL",
  "gender": "string, optional, 性别(male/female/unknown)",
  "birthday": "string, optional, 生日(YYYY-MM-DD)"
}

响应: 同获取用户信息接口

6. 修改密码

Endpoint: PUT /auth/password

认证: 需要Bearer Token

描述: 修改用户密码

请求体:

{
  "currentPassword": "string, required, 当前密码",
  "newPassword": "string, required, 新密码(6-20字符)"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "密码修改成功"
}

用户接口

1. 获取用户列表

Endpoint: GET /users

认证: 需要Bearer Token (管理员权限)

查询参数:

  • page: number, optional, 页码 (默认: 1)
  • pageSize: number, optional, 每页数量 (默认: 20)
  • search: string, optional, 搜索关键词
  • status: string, optional, 状态过滤(active/inactive/banned)

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "users": [
      {
        "id": 1,
        "username": "user1",
        "nickname": "用户1",
        "email": "user1@example.com",
        "phone": "13800138001",
        "status": "active",
        "level": 2,
        "created_at": "2025-01-01极速版T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "pageSize": 20,
      "totalPages": 5
    }
  }
}

2. 获取用户详情

Endpoint: GET /users/:id

认证: 需要Bearer Token

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "13800138000",
      "avatar": "https://example.com/avatar.jpg",
      "gender": "male",
      "points": 1000,
      "level": 3,
      "status": "active",
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

旅行接口

1. 创建旅行计划

Endpoint: POST /travel/plans

认证: 需要Bearer Token

请求体:

{
  "destination": "string, required, 目的地",
  "start_date": "string, required, 开始日期(YYYY-MM-DD)",
  "end_date": "string, required, 结束日期(YYYY-MM-DD)",
  "budget": "number, required, 预算",
  "interests": "string, optional, 兴趣偏好",
  "visibility": "string, optional, 可见范围(public/friends/private)"
}

响应:

{
  "success": true,
  "code": 201,
  "message": "旅行计划创建成功",
  "data": {
    "plan": {
      "id": 1,
      "title": "西藏自驾游",
      "description": "寻找志同道合的旅友一起探索西藏",
      "destination": "西藏",
      "start_date": "2025-07-01",
      "end_date": "2025-07-15",
      "budget": 5000,
      "max_members": 4,
      "current_members": 1,
      "status": "recruiting",
      "tags": ["自驾", "摄影", "探险"],
      "creator_id": 1,
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

2. 获取旅行计划列表

Endpoint: GET /travel/plans

查询参数:

  • page: number, optional, 页码
  • pageSize: number, optional, 每页数量
  • destination: string, optional, 目的地搜索
  • start_date: string, optional, 开始日期之后
  • end_date: string, optional, 结束日期之前
  • status: string, optional, 状态(recruiting/in_progress/completed/cancelled)
  • tags: string, optional, 标签过滤(多个用逗号分隔)

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "plans": [
      {
        "id": 1,
        "destination": "西藏",
        "start_date": "2025-07-01",
        "end_date": "2025-07-15",
        "budget": 5000.00,
        "interests": "自驾,摄影,探险",
        "visibility": "public",
        "creator": {
          "id": 1,
          "nickname": "旅行达人",
          "avatar": "https://example.com/avatar.jpg"
        },
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "pageSize": 20,
      "totalPages": 3
    }
  }
}

3. 匹配旅行伙伴

Endpoint: GET /travel/matches

认证: 需要Bearer Token

查询参数:

  • plan_id: number, required, 旅行计划ID
  • page: number, optional, 页码
  • pageSize: number, optional, 每页数量

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "list": [
      {
        "id": 2,
        "destination": "西藏",
        "start_date": "2025-07-02",
        "end_date": "2025-07-08",
        "budget": 4500.00,
        "interests": "徒步,美食",
        "match_score": 0.85,
        "user": {
          "id": 2,
          "nickname": "旅行伙伴",
          "avatar": "https://example.com/avatar2.jpg"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "size": 10,
      "total": 1
    }
  }
}

动物认领接口

1. 发布动物认领

Endpoint: POST /animals

认证: 需要Bearer Token

请求体:

{
  "name": "string, required, 动物名称",
  "species": "string, required, 物种",
  "breed": "string, optional, 品种",
  "age": "number, optional, 年龄",
  "gender": "string, optional, 性别(male/female/unknown)",
  "description": "string, required, 描述",
  "location": "string, required, 位置",
  "images": "array, optional, 图片URL数组",
  "vaccination_status": "string, optional, 疫苗接种情况",
  "sterilization_status": "string, optional, 绝育情况"
}

响应:

{
  "success": true,
  "code": 201,
  "message": "动物认领发布成功",
  "data": {
    "animal": {
      "id": 1,
      "name": "小白",
      "species": "猫",
      "breed": "中华田园猫",
      "age": 2,
      "gender": "male",
      "description": "非常温顺的猫咪，寻找有爱心的主人",
      "location": "北京市朝阳区",
      "status": "available",
      "images": ["https://example.com/cat1.jpg"],
      "creator_id": 1,
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

商家服务接口

1. 商家注册

Endpoint: POST /merchants/register

认证: 需要Bearer Token

请求体:

{
  "merchant_type": "string, required, 商家类型(flower_shop/activity_organizer/farm_owner)",
  "business_name": "string, required, 商家名称",
  "business_license": "string, optional, 营业执照URL",
  "contact_person": "string, required, 联系人",
  "contact_phone": "string, required, 联系电话",
  "address": "string, optional, 地址",
  "description": "string, optional, 商家介绍"
}

响应:

{
  "success": true,
  "code": 201,
  "message": "商家注册申请已提交",
  "data": {
    "merchant": {
      "id": 1,
      "user_id": 1,
      "merchant_type": "farm_owner",
      "business_name": "XX农场",
      "business_license": "https://example.com/license.jpg",
      "contact_person": "张三",
      "contact_phone": "13800138000",
      "address": "北京市朝阳区XX路XX号",
      "description": "专业养殖羊驼的农场",
      "status": "pending",
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

2. 发布商品/服务

Endpoint: POST /merchants/products

认证: 需要Bearer Token

请求体:

{
  "name": "string, required, 商品名称",
  "description": "string, required, 商品描述",
  "price": "number, required, 价格",
  "image_url": "string, optional, 图片URL",
  "category": "string, required, 商品类别",
  "status": "string, optional, 状态(available/unavailable)"
}

响应:

{
  "success": true,
  "code": 201,
  "message": "商品发布成功",
  "data": {
    "product": {
      "id": 1,
      "merchant_id": 1,
      "name": "羊驼认领体验",
      "description": "提供一个月的羊驼认领体验服务",
      "price": 1000.00,
      "image_url": "https://example.com/product.jpg",
      "category": "animal_claim",
      "status": "available",
      "created_at": "202极速版5-01-01T00:00:00.000Z"
    }
  }
}

3. 获取商家订单

Endpoint: GET /merchants/orders

认证: 需要Bearer Token

查询参数:

  • page: number, optional, 页码
  • pageSize: number, optional, 每页数量
  • status: string, optional, 订单状态

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "orders": [
      {
        "id": 1,
        "user_id": 2,
        "order_number": "ORD202501010001",
        "total_amount": 1000.00,
        "status": "paid",
        "ordered_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "pageSize": 20,
      "totalPages": 3
    }
  }
}

鲜花订购接口

1. 创建鲜花订单

Endpoint: POST /flowers/orders

认证: 需要Bearer Token

请求体:

{
  "product_id": "number, required, 商品ID",
  "quantity": "number, required, 数量",
  "recipient_name": "string, required, 收花人姓名",
  "recipient_phone": "string, required, 收花人电话",
  "delivery_address": "string, required, 配送地址",
  "delivery_date": "string, required, 配送日期(YYYY-MM-DD)",
  "delivery_time": "string, required, 配送时间段",
  "message": "string, optional, 祝福语",
  "special_instructions": "string, optional, 特殊说明"
}

响应:

{
  "success": true,
  "code": 201,
  "message": "订单创建成功",
  "data": {
    "order": {
      "极速版id": 1,
      "order_number": "F202501010001",
      "product_id": 1,
      "quantity": 1,
      "total_amount": 199.00,
      "status": "pending",
      "recipient_name": "张三",
      "recipient_phone": "13800138000",
      "delivery_address": "北京市朝阳区xxx路xxx号",
      "delivery_date": "2025-01-01",
      "delivery_time": "09:00-12:00",
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

推广奖励接口

1. 获取推广链接

Endpoint: GET /promotion/link

认证: 需要Bearer Token

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "promotion_link": "https://example.com/promotion?ref=user123",
    "qr_code": "https://example.com/qrcode.png"
  }
}

2. 获取推广数据

Endpoint: GET /promotion/stats

认证: 需要Bearer Token

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "total_referrals": 50,
    "successful_registrations": 25,
    "total_rewards": 500.00,
    "available_rewards": 300.00,
    "withdrawn_rewards": 200.00
  }
}

3. 申请提现

Endpoint: POST /promotion/withdraw

认证: 需要Bearer Token

请求体:

{
  "amount": "number, required, 提现金额",
  "payment_method": "string, required, 支付方式(wechat/alipay)"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "提现申请已提交",
  "data": {
    "withdrawal_id": "WD202501010001",
    "status": "processing"
  }
}

系统接口

1. 健康检查

Endpoint: GET /health

描述: 检查服务健康状态

响应:

{
  "status": "OK",
  "timestamp": "2025-01-01T00:00:00.000Z",
  "uptime": 12345.67,
  "environment": "development",
  "services": {
    "database": "connected",
    "redis": "disconnected",
    "rabbitmq": "disconnected"
  }
}

官网接口

1. 提交商家入驻申请

Endpoint: POST /website/merchant/apply

请求体:

{
  "business_name": "string, required, 商家名称",
  "contact_person": "string, required, 联系人",
  "contact_phone": "string, required, 联系电话",
  "email": "string, optional, 邮箱",
  "description": "string, optional, 商家描述"
}

响应:

{
  "success": true,
  "code": 201,
  "message": "入驻申请已提交",
  "data": {
    "application_id": 1,
    "status": "pending"
  }
}

2. 获取成功案例列表

Endpoint: GET /website/cases

查询参数:

  • page: number, optional, 页码
  • pageSize: number, optional, 每页数量

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "cases": [
      {
        "id": 1,
        "title": "XX农场成功入驻案例",
        "description": "XX农场通过平台实现了数字化转型",
        "image_url": "https://example.com/case1.jpg",
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "pageSize": 20,
      "totalPages": 3
    }
  }
}

错误码说明

错误码 说明 处理建议
200 成功 操作成功
201 创建成功 资源创建成功
400 请求错误 检查请求参数
401 未授权 需要登录认证
403 禁止访问 权限不足
404 资源不存在 检查资源ID
409 资源冲突 资源已存在
429 请求过多 降低请求频率
500 服务器错误 联系管理员

版本历史

版本 日期 说明
v1.0 2025-01-01 初始版本发布
v1.1 2025-02-01 新增微信登录接口
v1.2 2025-03-01 优化错误处理机制

注意事项

  1. 所有时间格式均为 ISO 8601 格式 (YYYY-MM-DDTHH:mm:ss.sssZ)
  2. 金额单位为元，保留两位小数
  3. 图片URL需要支持HTTPS
  4. 敏感操作需要二次验证
  5. API调用频率限制为每分钟100次