aiotagro/jiebanke

Fork 0

Files

ylweng 23041faa2a 更新文件结构，统一文档格式

2025-09-01 03:32:45 +08:00

72 KiB

Raw Blame History

结伴客系统 API 接口文档

基础信息

Base URL: https://www.jiebanke.com/api/v1

认证方式: Bearer Token (JWT)

响应格式: JSON

API版本: v1

开发状态: 开发中

响应格式

成功响应

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

通用状态码

状态码	说明
200	请求成功
201	创建成功
400	请求参数错误
401	未授权访问
403	权限不足
404	资源不存在
429	请求过于频繁
500	服务器内部错误

认证接口

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@jiebanke.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, 密码"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "登录成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@jiebanke.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: GET /auth/me

认证: 需要Bearer Token

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

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@jiebanke.com",
      "phone": "13800138000",
      "avatar": "https://www.jiebanke.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"
    }
  }
}

4. 更新用户信息

Endpoint: PUT /auth/profile

认证: 需要Bearer Token

描述: 更新用户个人信息

请求体:

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

响应:

{
  "success": true,
  "code": 200,
  "message": "用户信息更新成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "新昵称",
      "avatar": "https://www.jiebanke.com/new-avatar.jpg",
      "gender": "male",
      "birthday": "1990-01-01",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

5. 微信登录

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": "测试用户",
      "avatar": "https://www.jiebanke.com/avatar.jpg",
      "gender": "male",
      "points": 100,
      "level": 2,
      "status": "active",
      "last_login_at": "2025-01-01T00:00:00.000Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

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://www.jiebanke.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"
    }
  }
}

6. 更新用户信息

Endpoint: PUT /auth/profile

认证: 需要Bearer Token

描述: 更新用户个人信息

请求体:

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

响应:

{
  "success": true,
  "code": 200,
  "message": "用户信息更新成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "新昵称",
      "avatar": "https://example.com/new-avatar.jpg",
      "gender": "male",
      "birthday": "1990-01-01",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

用户服务接口

1. 获取用户列表

Endpoint: GET /users

认证: 需要Bearer Token

描述: 获取用户列表（管理员权限）

查询参数:

page (可选): 页码，默认1
limit (可选): 每页数量，默认20
username (可选): 用户名模糊搜索
status (可选): 状态过滤

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "users": [
      {
        "id": 1,
        "username": "testuser",
        "nickname": "测试用户",
        "email": "test@example.com",
        "phone": "13800138000",
        "avatar": "https://www.jiebanke.com/avatar.jpg",
        "gender": "male",
        "points": 100,
        "level": 2,
        "status": "active",
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 20,
      "pages": 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://www.jiebanke.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"
    }
  }
}

8. 管理员接口

8.1 管理员登录

Endpoint: POST /api/v1/admin/login
认证要求: 无
描述: 管理员登录系统
请求体:

{
  "username": "admin",
  "password": "password123"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "admin": {
      "id": 1,
      "username": "admin",
      "email": "admin@jiebanke.com",
      "nickname": "超级管理员",
      "avatar": "https://example.com/avatar.jpg",
      "role": "super_admin",
      "status": 1,
      "last_login": "2024-01-15T10:30:00.000Z"
    }
  }
}

8.2 获取管理员信息

Endpoint: GET /api/v1/admin/profile
认证要求: Bearer Token
描述: 获取当前登录管理员信息
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "nickname": "超级管理员",
    "avatar": "https://example.com/avatar.jpg",
    "role": "super_admin",
    "status": 1,
    "last_login": "2024-01-15T10:30:00.000Z",
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

8.3 更新管理员信息

Endpoint: PUT /api/v1/admin/profile
认证要求: Bearer Token
描述: 更新当前登录管理员信息
请求体:

{
  "nickname": "新昵称",
  "email": "newemail@example.com",
  "avatar": "https://example.com/new-avatar.jpg"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "newemail@example.com",
    "nickname": "新昵称",
    "avatar": "https://example.com/new-avatar.jpg",
    "role": "super_admin",
    "status": 1
  }
}

8.4 修改密码

Endpoint: PUT /api/v1/admin/password
认证要求: Bearer Token
描述: 修改当前登录管理员密码
请求体:

{
  "old_password": "oldpassword123",
  "new_password": "newpassword456"
}

响应:

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

7. 获取管理员信息

Endpoint: GET /auth/admin/me

认证: 需要Bearer Token

描述: 获取当前登录管理员信息及权限

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@jiebanke.com",
      "real_name": "管理员",
      "avatar": "",
      "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"
    },
    "roles": [
      {
        "id": 2,
        "name": "admin",
        "description": "普通管理员"
      }
    ],
    "permissions": [
      "user:manage",
      "content:review",
      "content:publish",
      "data:view",
      "data:export"
    ]
  }
}

9. 管理员后台接口

9.1 用户管理接口

9.1.1 获取用户列表

Endpoint: GET /api/v1/admin/users
认证要求: Bearer Token，需要user:manage权限
查询参数:
- page (可选): 页码，默认1
- limit (可选): 每页数量，默认20
- username (可选): 用户名模糊搜索
- user_type (可选): 用户类型过滤（normal/merchant/farmer/organizer）
- status (可选): 状态过滤（active/inactive/banned）
- start_date (可选): 注册开始时间
- end_date (可选): 注册结束时间
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "users": [
      {
        "id": 1,
        "username": "testuser",
        "nickname": "测试用户",
        "email": "test@example.com",
        "phone": "13800138000",
        "user_type": "normal",
        "status": "active",
        "points": 100,
        "level": 2,
        "travel_count": 5,
        "animal_adopt_count": 2,
        "flower_order_count": 3,
        "created_at": "2025-01-01T00:00:00.000Z",
        "last_login_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 20,
      "pages": 5
    },
    "statistics": {
      "total_users": 100,
      "active_users": 80,
      "new_users_today": 5,
      "merchant_users": 15,
      "farmer_users": 10
    }
  }
}

9.1.2 获取用户详情

Endpoint: GET /api/v1/admin/users/{id}
认证要求: Bearer Token，需要user:manage权限
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "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",
      "user_type": "normal",
      "status": "active",
      "points": 1000,
      "level": 3,
      "balance": 500.00,
      "travel_count": 5,
      "animal_adopt_count": 2,
      "flower_order_count": 3,
      "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"
    },
    "activity_stats": {
      "last_7_days_login_count": 5,
      "total_travel_plans": 3,
      "total_animal_claims": 2,
      "total_flower_orders": 1
    }
  }
}

9.1.3 更新用户状态

Endpoint: PUT /api/v1/admin/users/{id}/status
认证要求: Bearer Token，需要user:manage权限
请求体:

{
  "status": "banned",
  "reason": "违反平台规则"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "用户状态更新成功"
}

9.1.4 导出用户数据

Endpoint: GET /api/v1/admin/users/export
认证要求: Bearer Token，需要user:manage权限
查询参数:
- format (可选): 导出格式（csv/excel），默认csv
- start_date (可选): 注册开始时间
- end_date (可选): 注册结束时间
- user_type (可选): 用户类型过滤
响应: 返回文件下载流

9.2 商家审核接口

9.2.1 获取待审核商家列表

Endpoint: GET /api/v1/admin/merchants/pending
认证要求: Bearer Token，需要merchant:review权限
查询参数:
- page (可选): 页码，默认1
- limit (可选): 每页数量，默认20
- merchant_type (可选): 商家类型（flower_shop/farm/activity_organizer）
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "merchants": [
      {
        "id": 1,
        "user_id": 2,
        "shop_name": "鲜花小店",
        "merchant_type": "flower_shop",
        "contact_name": "张老板",
        "contact_phone": "13800138001",
        "business_license": "https://www.jiebanke.com/license.jpg",
        "status": "pending",
        "apply_reason": "希望加入平台提供鲜花服务",
        "created_at": "2025-01-01T00:00:00.000Z",
        "user_info": {
          "username": "merchant1",
          "nickname": "花店老板",
          "email": "merchant@jiebanke.com"
        }
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}

9.2.2 审核商家申请

Endpoint: POST /api/v1/admin/merchants/{id}/review
认证要求: Bearer Token，需要merchant:review权限
请求体:

{
  "action": "approve",
  "review_notes": "资质齐全，符合要求",
  "reject_reason": ""
}

或者

{
  "action": "reject",
  "review_notes": "营业执照不清晰",
  "reject_reason": "营业执照图片模糊，无法辨认"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "商家审核完成"
}

9.2.3 获取商家列表

Endpoint: GET /api/v1/admin/merchants
认证要求: Bearer Token，需要merchant:manage权限
查询参数:
- page (可选): 页码，默认1
- limit (可选): 每页数量，默认20
- "shop_name" (可选): 店铺名称模糊搜索
- "merchant_type" (可选): 商家类型
- "status" (可选): 状态（active/inactive/rejected）
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "merchants": [
      {
        "id": 1,
        "user_id": 2,
        "shop_name": "鲜花小店",
        "merchant_type": "flower_shop",
        "contact_name": "张老板",
        "contact_phone": "13800138001",
        "business_license": "https://www.jiebanke.com/license.jpg",
        "status": "active",
        "total_products": 15,
        "total_orders": 120,
        "total_revenue": 5000.00,
        "avg_rating": 4.8,
        "created_at": "2025-01-01T00:00:00.000Z",
        "approved_at": "2025-01-02T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "limit": 20,
      "pages": 3
    },
    "statistics": {
      "total_merchants": 50,
      "active_merchants": 45,
      "flower_shops": 20,
      "farms": 15,
      "organizers": 15,
      "pending_reviews": 5
    }
  }
}

9.3 内容审核接口

9.3.1 获取待审核内容列表

Endpoint: GET /api/v1/admin/content/pending
认证要求: Bearer Token，需要content:review权限
查询参数:
- page (可选): 页码，默认1
- limit (可选): 每页数量，默认20
- content_type (可选): 内容类型（travel_plan/dynamic/comment）
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "contents": [
      {
        "id": 1,
        "type": "travel_plan",
        "title": "云南大理之旅",
        "content": "计划去大理游玩5天，寻找同行伙伴...",
        "author_id": 3,
        "author_name": "旅行爱好者",
        "status": "pending",
        "created_at": "2025-01-01T00:00:00.000Z",
        "review_count": 0
      },
      {
        "id": 2,
        "type": "dynamic", 
        "title": "",
        "content": "今天认领了一只可爱的小羊！",
        "images": ["https://www.jiebanke.com/sheep.jpg"],
        "author_id": 4,
        "author_name": "动物爱好者",
        "status": "pending",
        "created_at": "2025-01-01T00:00:00.000Z",
        "review_count": 0
      }
    ],
    "pagination": {
      "total": 25,
      "page": 1,
      "limit": 20,
      "pages": 2
    }
  }
}

9.3.2 审核内容

Endpoint: POST /api/v1/admin/content/{id}/review
认证要求: Bearer Token，需要content:review权限
请求体:

{
  "action": "approve",
  "review_notes": "内容符合规范"
}

或者

{
  "action": "reject",
  "review_notes": "包含不当内容",
  "reject_reason": "包含联系方式"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "内容审核完成"
}

9.3.3 获取内容统计

Endpoint: GET /api/v1/admin/content/statistics
认证要求: Bearer Token，需要content:review权限
查询参数:
- days (可选): 统计天数，默认7
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "total_contents": 1000,
    "pending_review": 25,
    "approved": 900,
    "rejected": 75,
    "daily_stats": [
      {
        "date": "2025-01-01",
        "total": 50,
        "approved": 45,
        "rejected": 5
      }
    ],
    "by_type": {
      "travel_plan": 300,
      "dynamic": 500,
      "comment": 200
    }
  }
}

9.4 数据统计接口

9.4.1 获取平台概览数据

Endpoint: GET /api/v1/admin/dashboard/overview
认证要求: Bearer Token，需要data:view权限
查询参数:
- days (可选): 统计天数，默认30
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "user_stats": {
      "total_users": 10000,
      "new_users_today": 50,
      "new_users_7d": 300,
      "new_users_30d": 1200,
      "active_users_7d": 2000,
      "active_users_30d": 6000
    },
    "order_stats": {
      "total_orders": 5000,
      "today_orders": 25,
      "revenue_today": 1250.00,
      "revenue_7d": 8500.00,
      "revenue_30d": 35000.00,
      "avg_order_value": 70.00
    },
    "content_stats": {
      "total_travel_plans": 2000,
      "total_animal_claims": 800,
      "total_flower_orders": 1200,
      "total_dynamics": 3000
    },
    "merchant_stats": {
      "total_merchants": 150,
      "active_merchants": 120,
      "flower_shops": 60,
      "farms": 50,
      "organizers": 40
    }
  }
}

9.4.2 获取用户增长图表

Endpoint: GET /api/v1/admin/dashboard/user-growth
认证要求: Bearer Token，需要data:view权限
查询参数:
- days (可选): 统计天数，默认30
- group_by (可选): 分组方式（day/week/month），默认day
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "chart_data": [
      {
        "date": "2025-01-01",
        "new_users": 45,
        "total_users": 10045
      },
      {
        "date": "2025-01-02", 
        "new_users": 52,
        "total_users": 10097
      }
    ],
    "summary": {
      "total_new_users": 1200,
      "growth_rate": 12.5,
      "avg_daily_new_users": 40
    }
  }
}

9.4.3 获取订单统计图表

Endpoint: GET /api/v1/admin/dashboard/order-stats
认证要求: Bearer Token，需要data:view权限
查询参数:
- days (可选): 统计天数，默认30
- order_type (可选): 订单类型（flower/animal/travel）
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "chart_data": [
      {
        "date": "2025-01-01",
        "total_orders": 28,
        "total_revenue": 1960.00,
        "flower_orders": 15,
        "animal_orders": 8,
        "travel_orders": 5
      }
    ],
    "summary": {
      "total_revenue": 35000.00,
      "avg_daily_revenue": 1166.67,
      "order_conversion_rate": 8.5
    }
  }
}

9.4.4 导出数据报表

Endpoint: GET /api/v1/admin/dashboard/export
认证要求: Bearer Token，需要data:export权限
查询参数:
- report_type (必选): 报表类型（users/orders/contents/merchants）
- format (可选): 格式（csv/excel），默认csv
- start_date (可选): 开始时间
- end_date (可选): 结束时间
响应: 返回文件下载流

9.5 权限管理接口

9.5.1 获取管理员列表

Endpoint: GET /api/v1/admin/administrators
认证要求: Bearer Token，需要admin:manage权限
查询参数:
- page (可选): 页码，默认1
- limit (可选): 每页数量，默认20
- username (可选): 用户名模糊搜索
- role (可选): 角色过滤
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "admins": [
      {
        "id": 1,
        "username": "admin",
        "email": "admin@example.com",
        "nickname": "超级管理员",
        "avatar": "https://example.com/avatar.jpg",
        "role": "super_admin",
        "status": 1,
        "last_login": "2025-01-15T10:30:00.000Z",
        "created_at": "2025-01-01T00:00:00.000Z",
        "permissions": ["user:manage", "content:review", "data:view", "data:export"]
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}

9.5.2 创建管理员账号

Endpoint: POST /api/v1/admin/administrators
认证要求: Bearer Token，需要admin:manage权限
请求体:

{
  "username": "newadmin",
  "password": "password123",
  "email": "newadmin@example.com",
  "nickname": "新管理员",
  "role": "content_admin",
  "permissions": ["content:review", "content:publish"]
}

响应:

{
  "success": true,
  "code": 201,
  "message": "管理员创建成功",
  "data": {
    "id": 2,
    "username": "newadmin",
    "email": "newadmin@example.com",
    "nickname": "新管理员",
    "role": "content_admin",
    "status": 1,
    "created_at": "2025-01-01T00:00:00.000Z"
  }
}

9.5.3 更新管理员权限

Endpoint: PUT /api/v1/admin/administrators/{id}/permissions
认证要求: Bearer Token，需要admin:manage权限
请求体:

{
  "permissions": ["content:review", "content:publish", "data:view"]
}

响应:

{
  "success": true,
  "code": 200,
  "message": "权限更新成功"
}

9.5.4 禁用/启用管理员账号

Endpoint: PUT /api/v1/admin/administrators/{id}/status
认证要求: Bearer Token，需要admin:manage权限
请求体:

{
  "status": 0
}

响应:

{
  "success": true,
  "code": 200,
  "message": "管理员状态更新成功"
}

9.5.5 获取权限列表

Endpoint: GET /api/v1/admin/permissions
认证要求: Bearer Token，需要admin:manage权限
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "permissions": [
      {
        "code": "user:manage",
        "name": "用户管理",
        "description": "管理用户账号和状态"
      },
      {
        "code": "content:review", 
        "name": "内容审核",
        "description": "审核用户发布的内容"
      },
      {
        "code": "content:publish",
        "name": "内容发布",
        "description": "发布和管理平台内容"
      },
      {
        "code": "data:view",
        "name": "数据查看",
        "description": "查看平台统计数据"
      },
      {
        "code": "data:export",
        "name": "数据导出",
        "description": "导出数据报表"
      },
      {
        "code": "merchant:review",
        "name": "商家审核",
        "description": "审核商家入驻申请"
      },
      {
        "code": "merchant:manage",
        "name": "商家管理",
        "description": "管理商家账号和信息"
      },
      {
        "code": "admin:manage",
        "name": "管理员管理",
        "description": "管理其他管理员账号"
      }
    ]
  }
}

9.6 操作日志接口

9.6.1 获取操作日志列表

Endpoint: GET /api/v1/admin/operation-logs
认证要求: Bearer Token，需要admin:manage权限
查询参数:
- page (可选): 页码，默认1
- limit (可选): 每页数量，默认20
- admin_id (可选): 操作管理员ID
- action_type (可选): 操作类型
- start_date (可选): 开始时间
- end_date (可选): 结束时间
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "logs": [
      {
        "id": 1,
        "admin_id": 1,
        "admin_name": "超级管理员",
        "action_type": "user_status_update",
        "target_type": "user",
        "target_id": 5,
        "target_name": "testuser",
        "old_value": "active",
        "new_value": "banned",
        "ip_address": "192.168.1.100",
        "user_agent": "Mozilla/5.0...",
        "created_at": "2025-01-01T10:30:00.000Z"
      }
    ],
    "pagination": {
      "total": 1000,
      "page": 1,
      "limit": 20,
      "pages": 50
    }
  }
}

9.6.2 导出操作日志

Endpoint: GET /api/v1/admin/operation-logs/export
认证要求: Bearer Token，需要admin:manage权限
查询参数:
- format (可选): 格式（csv/excel），默认csv
- start_date (可选): 开始时间
- end_date (可选): 结束时间
响应: 返回文件下载流 ], "pagination": { "total": 100, "page": 1, "limit": 20, "pages": 5 } } }


#### 9.2 获取用户详情
- **Endpoint**: GET /api/v1/users/{id}
- **认证要求**: Bearer Token，需要user:manage权限
- **响应**:
```json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "13800138000",
      "user_type": "farmer",
      "status": "active",
      "points": 100,
      "level": 2,
      "created_at": "2025-01-01T00:00:00.000Z",
      "last_login_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

9.3 更新用户状态

Endpoint: PUT /api/v1/users/{id}/status
认证要求: Bearer Token，需要user:manage权限
请求体:

{
  "status": "active"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "用户状态更新成功"
}

9.4 删除用户

Endpoint: DELETE /api/v1/users/{id}
认证要求: Bearer Token，需要user:manage权限
响应:

{
  "success": true,
  "code": 200,
  "message": "用户删除成功"
}

10. 系统管理接口

10.1 获取系统信息

Endpoint: GET /api/v1/admin/system/info
认证要求: Bearer Token，需要system:view权限
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "system": {
      "version": "1.0.0",
      "node_version": "v18.17.0",
      "platform": "linux",
      "arch": "x64",
      "uptime": 123456,
      "memory_usage": {
        "total": 17179869184,
        "used": 8589934592,
        "free": 8589934592
      },
      "cpu_usage": 25.5
    }
  }
}

10.2 获取系统服务列表

Endpoint: GET /api/v1/admin/system/services
认证要求: Bearer Token，需要system:manage权限
查询参数:
- page (可选): 页码，默认1
- limit (可选): 每页数量，默认20
- type (可选): 服务类型(database/cache/mq)
- status (可选): 服务状态(running/stopped)
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "services": [
      {
        "id": "mysql",
        "name": "MySQL数据库",
        "type": "database",
        "status": "running",
        "host": "mysql.jiebanke.com",
        "port": 3306,
        "description": "主数据库服务",
        "created_at": "2024-01-01T00:00:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
      }
    ],
    "pagination": {
      "total": 5,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}

10.3 更新服务状态

Endpoint: PUT /api/v1/admin/system/services/{id}/status
认证要求: Bearer Token，需要system:manage权限
请求体:

{
  "status": "stopped"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "服务状态更新成功"
}

10.4 获取系统配置

Endpoint: GET /api/v1/admin/system/configs
认证要求: Bearer Token，需要system:config权限
查询参数:
- page (可选): 页码，默认1
- limit (可选): 每页数量，默认20
- group (可选): 配置分组
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "configs": [
      {
        "id": "site_name",
        "name": "网站名称",
        "value": "结伴客",
        "type": "string",
        "group": "basic",
        "description": "网站显示名称",
        "created_at": "2024-01-01T00:00:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}

10.5 更新系统配置

Endpoint: PUT /api/v1/admin/system/configs/{id}
认证要求: Bearer Token，需要system:config权限
请求体:

{
  "value": "新网站名称"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "配置更新成功"
}

11. 内容管理接口

11.1 获取内容列表

Endpoint: GET /admin/contents
认证要求: Bearer Token，需要content:review权限
查询参数:
- page (可选): 页码，默认1
- limit (可选): 每页数量，默认20
- type (可选): 内容类型
- status (可选): 审核状态
响应:

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "contents": [
      {
        "id": 1,
        "title": "测试内容",
        "type": "article",
        "author": "测试用户",
        "status": "pending",
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "limit": 20,
      "pages": 3
    }
  }
}

9.2 获取内容详情

Endpoint: GET /admin/contents/{id}

认证: 需要Bearer Token，需要content:review权限

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "content": {
      "id": 1,
      "title": "测试内容",
      "type": "article",
      "content": "详细内容文本...",
      "author": {
        "id": 1,
        "username": "testuser",
        "nickname": "测试用户"
      },
      "images": ["https://www.jiebanke.com/image1.jpg"],
      "status": "pending",
      "created_at": "2025-01-01T12:00:00.000Z",
      "updated_at": "2025-01-01T12:00:00.000Z"
    }
  }
}

9.3 审核内容

Endpoint: PUT /admin/contents/{id}/review

认证: 需要Bearer Token，需要content:review权限

请求体:

{
  "status": "string, required, 审核状态(approved/rejected)",
  "review_comment": "string, optional, 审核意见"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "内容审核完成"
}

9.4 批量审核内容

Endpoint: POST /admin/contents/batch-review

认证: 需要Bearer Token，需要content:review权限

请求体:

{
  "content_ids": ["number, required, 内容ID列表"],
  "status": "string, required, 审核状态(approved/rejected)",
  "review_comment": "string, optional, 审核意见"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "批量审核完成",
  "data": {
    "success_count": 5,
    "failed_count": 0
  }
}

13. 商家管理接口

13.1 获取商家申请列表

Endpoint: GET /admin/merchant-applications

认证: 需要Bearer Token，需要merchant:approve权限

查询参数:

page (可选): 页码，默认1
limit (可选): 每页数量，默认20
status (可选): 状态过滤(pending/approved/rejected)
business_name (可选): 商家名称搜索

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "applications": [
      {
        "id": 1,
        "user_id": 1,
        "business_name": "XX农场",
        "contact_person": "张三",
        "contact_phone": "13800138000",
        "merchant_type": "farm_owner",
        "status": "pending",
        "created_at": "2025-01-01T12:00:00.000Z",
        "updated_at": "2025-01-01T12:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 15,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}

13.2 审核商家申请

Endpoint: PUT /admin/merchant-applications/{id}/review

认证: 需要Bearer Token，需要merchant:approve权限

请求体:

{
  "status": "string, required, 审核状态(approved/rejected)",
  "review_comment": "string, optional, 审核意见"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "商家申请审核完成"
}

13.3 获取商家列表

Endpoint: GET /admin/merchants

认证: 需要Bearer Token，需要merchant:view权限

查询参数:

page (可选): 页码，默认1
limit (可选): 每页数量，默认20
merchant_type (可选): 商家类型过滤
status (可选): 状态过滤(active/inactive)
business_name (可选): 商家名称搜索

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "merchants": [
      {
        "id": 1,
        "user_id": 1,
        "business_name": "XX农场",
        "merchant_type": "farm_owner",
        "contact_person": "张三",
        "contact_phone": "13800138000",
        "status": "active",
        "product_count": 5,
        "order_count": 20,
        "total_revenue": 50000.00,
        "created_at": "2025-01-01T12:00:00.000Z",
        "updated_at": "2025-01-01T12:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 25,
      "page": 1,
      "limit": 20,
      "pages": 2
    }
  }
}

13.4 更新商家状态

Endpoint: PUT /admin/merchants/{id}/status

认证: 需要Bearer Token，需要merchant:manage权限

请求体:

{
  "status": "string, required, 状态(active/inactive)"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "商家状态更新成功"
}

14. 系统配置接口

14.1 获取系统配置

Endpoint: GET /admin/system-configs

认证: 需要Bearer Token，需要system:config权限

查询参数:

group (可选): 配置组过滤

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "configs": [
      {
        "id": "site_name",
        "name": "网站名称",
        "value": "结伴客",
        "type": "string",
        "group": "general",
        "description": "网站显示的名称",
        "created_at": "2025-01-01T12:00:00.000Z",
        "updated_at": "2025-01-01T12:00:00.000Z"
      },
      {
        "id": "site_description",
        "name": "网站描述",
        "value": "专业的旅行结伴和动物认领平台",
        "type": "text",
        "group": "general",
        "description": "网站的简要描述",
        "created_at": "2025-01-01T12:00:00.000Z",
        "updated_at": "2025-01-01T12:00:00.000Z"
      },
      {
        "id": "max_file_size",
        "name": "最大文件大小",
        "value": "10",
        "type": "number",
        "group": "upload",
        "description": "允许上传的最大文件大小(MB)",
        "created_at": "2025-01-01T12:00:00.000Z",
        "updated_at": "2025-01-01T12:00:00.000Z"
      }
    ]
  }
}

14.2 更新系统配置

Endpoint: PUT /admin/system-configs/{id}

认证: 需要Bearer Token，需要system:config权限

请求体:

{
  "value": "string, required, 配置值"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "配置更新成功"
}

14.3 批量更新系统配置

Endpoint: POST /admin/system-configs/batch-update

认证: 需要Bearer Token，需要system:config权限

请求体:

{
  "configs": [
    {
      "id": "site_name",
      "value": "新网站名称"
    },
    {
      "id": "site_description",
      "value": "新的网站描述"
    }
  ]
}

响应:

{
  "success": true,
  "code": 200,
  "message": "批量配置更新成功",
  "data": {
    "success_count": 2,
    "failed_count": 0
  }
}

10. 数据统计接口

10.1 获取系统统计数据

Endpoint: GET /admin/statistics

认证: 需要Bearer Token，需要data:view权限

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "user_count": 1000,
    "active_user_count": 500,
    "new_user_today": 20,
    "order_count": 300,
    "revenue_today": 5000.00,
    "content_count": 200,
    "pending_review_count": 15,
    "animal_claim_count": 150,
    "travel_plan_count": 80,
    "flower_order_count": 120,
    "merchant_count": 25,
    "pending_merchant_approval_count": 8
  }
}

10.2 获取数据趋势图表

Endpoint: GET /admin/statistics/trend

认证: 需要Bearer Token，需要data:view权限

查询参数:

type (必选): 数据类型(user/order/revenue/content)
days (可选): 天数，默认7天

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "labels": ["2025-01-01", "2025-01-02", "2025-01-03", "2025-01-04", "2025-01-05", "2025-01-06", "2025-01-07"],
    "datasets": [
      {
        "label": "用户增长",
        "data": [100, 120, 150, 180, 200, 220, 250],
        "borderColor": "rgb(75, 192, 192)"
      }
    ]
  }
}

10.3 导出数据

Endpoint: GET /admin/export/{type}

认证: 需要Bearer Token，需要data:export权限

查询参数:

start_date (可选): 开始日期
end_date (可选): 结束日期
format (可选): 导出格式(csv/excel)，默认csv

响应: 返回CSV或Excel文件下载

11. 权限管理接口

11.1 获取角色列表

Endpoint: GET /admin/roles

认证: 需要Bearer Token，需要role:manage权限

查询参数:

page (可选): 页码，默认1
limit (可选): 每页数量，默认20

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "roles": [
      {
        "id": 1,
        "name": "super_admin",
        "description": "超级管理员",
        "permission_count": 20,
        "user_count": 3,
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z"
      },
      {
        "id": 2,
        "name": "content_admin",
        "description": "内容管理员",
        "permission_count": 8,
        "user_count": 5,
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "limit": 20,
      "pages": 1
    }
  }
}

11.2 创建角色

Endpoint: POST /admin/roles

认证: 需要Bearer Token，需要role:manage权限

请求体:

{
  "name": "string, required, 角色名称",
  "description": "string, required, 角色描述",
  "permissions": ["string, required, 权限列表"]
}

响应:

{
  "success": true,
  "code": 201,
  "message": "角色创建成功",
  "data": {
    "role": {
      "id": 3,
      "name": "data_admin",
      "description": "数据管理员",
      "permissions": ["data:view", "data:export"],
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

11.3 更新角色权限

Endpoint: PUT /admin/roles/{id}

认证: 需要Bearer Token，需要role:manage权限

请求体:

{
  "description": "string, optional, 角色描述",
  "permissions": ["string, required, 权限列表"]
}

响应:

{
  "success": true,
  "code": 200,
  "message": "角色更新成功"
}

11.4 删除角色

Endpoint: DELETE /admin/roles/{id}

认证: 需要Bearer Token，需要role:manage权限

响应:

{
  "success": true,
  "code": 200,
  "message": "角色删除成功"
}

11.5 获取权限列表

Endpoint: GET /admin/permissions

认证: 需要Bearer Token，需要role:manage权限

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "permissions": [
      {
        "id": "user:view",
        "name": "查看用户",
        "description": "允许查看用户列表和详情",
        "category": "用户管理"
      },
      {
        "id": "user:manage",
        "name": "管理用户",
        "description": "允许修改用户状态和信息",
        "category": "用户管理"
      },
      {
        "id": "content:review",
        "name": "审核内容",
        "description": "允许审核用户发布的内容",
        "category": "内容管理"
      },
      {
        "id": "content:publish",
        "name": "发布内容",
        "description": "允许发布系统公告和内容",
        "category": "内容管理"
      },
      {
        "id": "data:view",
        "name": "查看数据",
        "description": "允许查看系统统计数据",
        "category": "数据统计"
      },
      {
        "id": "data:export",
        "name": "导出数据",
        "description": "允许导出系统数据",
        "category": "数据统计"
      },
      {
        "id": "role:manage",
        "name": "管理角色",
        "description": "允许管理角色和权限",
        "category": "权限管理"
      },
      {
        "id": "merchant:approve",
        "name": "审核商家",
        "description": "允许审核商家入驻申请",
        "category": "商家管理"
      },
      {
        "id": "system:config",
        "name": "系统配置",
        "description": "允许修改系统配置参数",
        "category": "系统管理"
      }
    ]
  }
}

11.6 分配用户角色

Endpoint: POST /admin/users/{userId}/roles

认证: 需要Bearer Token，需要role:manage权限

请求体:

{
  "roleIds": ["number, required, 角色ID列表"]
}

响应:

{
  "success": true,
  "code": 200,
  "message": "角色分配成功"
}

12. 操作日志接口

12.1 获取操作日志列表

Endpoint: GET /admin/operation-logs

认证: 需要Bearer Token，需要audit:view权限

查询参数:

page (可选): 页码，默认1
limit (可选): 每页数量，默认20
admin_id (可选): 管理员ID过滤
module (可选): 操作模块过滤
operation (可选): 操作类型过滤
target_type (可选): 目标对象类型过滤
status (可选): 操作状态过滤(success/failed)
start_date (可选): 开始日期
end_date (可选): 结束日期
keyword (可选): 关键词搜索(管理员姓名/操作描述)

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "logs": [
      {
        "id": 1,
        "admin_id": 1,
        "admin_name": "管理员A",
        "module": "用户管理",
        "operation": "user:update",
        "operation_name": "更新用户",
        "target_id": "2",
        "target_type": "user",
        "target_name": "用户B",
        "request_method": "PUT",
        "request_url": "/admin/users/2",
        "request_params": "{\"status\":\"inactive\"}",
        "ip_address": "192.168.1.100",
        "user_agent": "Mozilla/5.0...",
        "status": "success",
        "execution_time": 150,
        "created_at": "2025-01-01T12:00:00.000Z"
      },
      {
        "id": 2,
        "admin_id": 2,
        "admin_name": "管理员B",
        "module": "内容审核",
        "operation": "content:review",
        "operation_name": "审核内容",
        "target_id": "5",
        "target_type": "content",
        "target_name": "测试文章",
        "request_method": "PUT",
        "request_url": "/admin/contents/5/review",
        "request_params": "{\"status\":\"approved\",\"review_comment\":\"内容符合规范\"}",
        "ip_address": "192.168.1.101",
        "user_agent": "Mozilla/5.0...",
        "status": "success",
        "execution_time": 200,
        "created_at": "2025-01-01T12:30:00.000Z"
      }
    ],
    "pagination": {
      "total": 1000,
      "page": 1,
      "limit": 20,
      "pages": 50
    }
  }
}

12.2 获取操作日志详情

Endpoint: GET /admin/operation-logs/{id}

认证: 需要Bearer Token，需要audit:view权限

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "log": {
      "id": 1,
      "admin_id": 1,
      "admin_name": "管理员A",
      "module": "用户管理",
      "operation": "user:update",
      "operation_name": "更新用户",
      "target_id": "2",
      "target_type": "user",
      "target_name": "用户B",
      "request_method": "PUT",
      "request_url": "/admin/users/2",
      "request_params": {
        "status": "inactive"
      },
      "request_headers": {
        "authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "user-agent": "Mozilla/5.0...",
        "accept": "application/json"
      },
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0...",
      "status": "success",
      "error_message": null,
      "execution_time": 150,
      "created_at": "2025-01-01T12:00:00.000Z"
    }
  }
}

12.3 导出操作日志

Endpoint: GET /admin/operation-logs/export

认证: 需要Bearer Token，需要audit:export权限

查询参数:

start_date (可选): 开始日期
end_date (可选): 结束日期
module (可选): 操作模块过滤
operation (可选): 操作类型过滤
status (可选): 操作状态过滤
format (可选): 导出格式(csv/excel)，默认csv

响应: 返回CSV或Excel文件下载

12.4 获取操作统计

Endpoint: GET /admin/operation-logs/statistics

认证: 需要Bearer Token，需要audit:view权限

查询参数:

start_date (可选): 开始日期
end_date (可选): 结束日期

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "total_operations": 1250,
    "success_count": 1200,
    "failed_count": 50,
    "avg_execution_time": 180,
    "top_modules": [
      {"module": "用户管理", "count": 450, "percentage": 36.0},
      {"module": "内容审核", "count": 300, "percentage": 24.0},
      {"module": "数据统计", "count": 200, "percentage": 16.0},
      {"module": "系统配置", "count": 150, "percentage": 12.0},
      {"module": "权限管理", "count": 100, "percentage": 8.0},
      {"module": "其他", "count": 50, "percentage": 4.0}
    ],
    "top_operations": [
      {"operation": "user:update", "count": 200, "percentage": 16.0},
      {"operation": "content:review", "count": 180, "percentage": 14.4},
      {"operation": "data:view", "count": 150, "percentage": 12.0},
      {"operation": "user:create", "count": 120, "percentage": 9.6},
      {"operation": "system:config", "count": 100, "percentage": 8.0}
    ],
    "top_admins": [
      {"admin_id": 1, "admin_name": "管理员A", "count": 500, "percentage": 40.0},
      {"admin_id": 2, "admin_name": "管理员B", "count": 400, "percentage": 32.0},
      {"admin_id": 3, "admin_name": "管理员C", "count": 350, "percentage": 28.0}
    ]
  }
}

旅行结伴接口

11. 发布旅行计划

Endpoint: POST /travel/plans

认证: 需要Bearer Token

请求体:

{
  "title": "string, required, 计划标题",
  "description": "string, required, 计划描述",
  "destination": "string, required, 目的地",
  "start_date": "string, required, 开始日期(YYYY-MM-DD)",
  "end_date": "string, required, 结束日期(YYYY-MM-DD)",
  "max_members": "number, required, 最大参与人数",
  "budget": "number, optional, 预算金额",
  "tags": "array, optional, 标签数组",
  "images": "array, optional, 图片URL数组"
}

响应:

{
  "success": true,
  "code": 201,
  "message": "旅行计划发布成功",
  "data": {
    "plan": {
      "id": 1,
      "title": "周末杭州西湖游",
      "description": "寻找志同道合的伙伴一起游玩西湖",
      "destination": "杭州西湖",
      "start_date": "2025-01-15",
      "end_date": "2025-01-16",
      "max_members": 6,
      "current_members": 1,
      "budget": 500,
      "status": "recruiting",
      "tags": ["休闲", "摄影", "美食"],
      "images": [],
      "creator_id": 1,
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

12. 获取旅行计划列表

Endpoint: GET /travel/plans

查询参数:

page (可选): 页码，默认1
limit (可选): 每页数量，默认20
destination (可选): 目的地搜索
start_date (可选): 开始日期筛选
end_date (可选): 结束日期筛选
status (可选): 状态筛选(recruiting/in_progress/completed/cancelled)
sort (可选): 排序方式(created_at/start_date)

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "plans": [
      {
        "id": 1,
        "title": "周末杭州西湖游",
        "destination": "杭州西湖",
        "start_date": "2025-01-15",
        "end_date": "2025-01-16",
        "max_members": 6,
        "current_members": 3,
        "budget": 500,
        "status": "recruiting",
        "tags": ["休闲", "摄影", "美食"],
        "creator": {
          "id": 1,
          "username": "testuser",
          "nickname": "测试用户",
          "avatar": ""
        },
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "limit": 20,
      "pages": 3
    }
  }
}

13. 加入旅行计划

Endpoint: POST /travel/plans/{id}/join

认证: 需要Bearer Token

请求体:

{
  "message": "string, optional, 加入留言"
}

响应:

{
  "success": true,
  "code": 200,
  "message": "成功加入旅行计划",
  "data": {
    "membership": {
      "id": 1,
      "plan_id": 1,
      "user_id": 2,
      "status": "pending",
      "message": "希望能一起游玩",
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

动物认领接口

14. 获取可认领动物列表

Endpoint: GET /animals/adoptable

查询参数:

page (可选): 页码，默认1
limit (可选): 每页数量，默认20
type (可选): 动物类型
breed (可选): 品种筛选
age_min (可选): 最小年龄
age_max (可选): 最大年龄
location (可选): 地理位置

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "animals": [
      {
        "id": 1,
        "name": "小白",
        "type": "dog",
        "breed": "中华田园犬",
        "age": 2,
        "gender": "male",
        "description": "温顺可爱的狗狗，寻找有爱心的主人",
        "vaccination_status": "vaccinated",
        "sterilization_status": "sterilized",
        "location": "北京市朝阳区",
        "images": ["https://www.jiebanke.com/animal1.jpg"],
        "status": "available",
        "shelter": {
          "id": 1,
          "name": "爱心动物救助站",
          "contact": "13800138000"
        },
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 30,
      "page": 1,
      "limit": 20,
      "pages": 2
    }
  }
}

15. 申请认领动物

Endpoint: POST /animals/{id}/adopt

认证: 需要Bearer Token

请求体:

{
  "application_reason": "string, required, 申请理由",
  "living_environment": "string, required, 居住环境描述",
  "experience": "string, optional, 养宠经验",
  "contact_info": "string, required, 联系方式"
}

响应:

{
  "success": true,
  "code": 201,
  "message": "认领申请已提交",
  "data": {
    "application": {
      "id": 1,
      "animal_id": 1,
      "applicant_id": 1,
      "status": "pending",
      "application_reason": "非常喜欢狗狗，有养宠经验",
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

花卉订购接口

16. 获取花卉商品列表

Endpoint: GET /flowers/products

查询参数:

page (可选): 页码，默认1
limit (可选): 每页数量，默认20
`category" (可选): 分类筛选
"min_price" (可选): 最低价格
"max_price" (可选): 最高价格
"sort" (可选): 排序方式(price/created_at/sales)

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "products": [
      {
        "id": 1,
        "name": "玫瑰花束",
        "description": "新鲜玫瑰花束，适合送礼",
        "category": "鲜花",
        "price": 99.00,
        "original_price": 129.00,
        "stock": 50,
        "sales": 120,
        "images": ["https://www.jiebanke.com/rose.jpg"],
        "merchant": {
          "id": 1,
          "name": "花语花店",
          "rating": 4.8
        },
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 20,
      "pages": 5
    }
  }
}

17. 创建花卉订单

Endpoint: POST /flowers/orders

认证: 需要Bearer Token

请求体:

{
  "items": [
    {
      "product_id": 1,
      "quantity": 2,
      "message": "string, optional, 留言卡片内容"
    }
  ],
  "shipping_address": {
    "recipient": "string, required, 收货人",
    "phone": "string, required, 联系电话",
    "address": "string, required, 详细地址",
    "postal_code": "string, optional, 邮政编码"
  },
  "delivery_date": "string, required, 配送日期(YYYY-MM-DD)",
  "delivery_time": "string, required, 配送时间段"
}

响应:

{
  "success": true,
  "code": 201,
  "message": "订单创建成功",
  "data": {
    "order": {
      "id": 1,
      "order_number": "F202501010001",
      "total_amount": 198.00,
      "status": "pending",
      "items": [
        {
          "product_id": 1,
          "product_name": "玫瑰花束",
          "quantity": 2,
          "price": 99.00,
          "subtotal": 198.00
        }
      ],
      "shipping_address": {
        "recipient": "张三",
        "phone": "13800138000",
        "address": "北京市朝阳区某某街道123号"
      },
      "delivery_date": "2025-01-15",
      "delivery_time": "14:00-16:00",
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

社交互动接口

18. 发布动态

Endpoint: POST /social/posts

认证: 需要Bearer Token

请求体:

{
  "content": "string, required, 动态内容",
  "images": "array, optional, 图片URL数组",
  "visibility": "string, optional, 可见性(public/friends/private)",
  "location": "string, optional, 位置信息"
}

响应:

{
  "success": true,
  "code": 201,
  "message": "动态发布成功",
  "data": {
    "post": {
      "id": 1,
      "content": "今天去了西湖，风景真美！",
      "images": ["https://www.jiebanke.com/westlake.jpg"],
      "visibility": "public",
      "location": "杭州西湖",
      "like_count": 0,
      "comment_count": 0,
      "author": {
        "id": 1,
        "username": "testuser",
        "nickname": "测试用户",
        "avatar": ""
      },
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

19. 点赞动态

Endpoint: POST /social/posts/{id}/like

认证: 需要Bearer Token

响应:

{
  "success": true,
  "code": 200,
  "message": "点赞成功",
  "data": {
    "like_count": 15
  }
}

20. 评论动态

Endpoint: POST /social/posts/{id}/comments

认证: 需要Bearer Token

请求体:

{
  "content": "string, required, 评论内容",
  "parent_id": "number, optional, 父评论ID"
}

响应:

{
  "success": true,
  "code": 201,
  "message": "评论成功",
  "data": {
    "comment": {
      "id": 1,
      "content": "照片拍得真漂亮！",
      "author": {
        "id": 2,
        "username": "user2",
        "nickname": "用户二",
        "avatar": ""
      },
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  }
}

错误码说明

错误码	说明
200	成功
201	创建成功
400	请求参数错误
401	未授权
403	权限不足
404	资源不存在
500	服务器内部错误

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": "密码修改成功"
}

7. 退出登录

Endpoint: POST /auth/logout

认证: 需要Bearer Token

描述: 用户退出登录，使token失效

响应:

{
  "success": true,
  "code": 200,
  "message": "退出登录成功"
}

8. 刷新token

Endpoint: POST /auth/refresh

认证: 需要Bearer Token

描述: 刷新访问令牌

响应:

{
  "success": true,
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

用户接口

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@jiebanke.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://www.jiebanke.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://www.jiebanke.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://www.jiebanke.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://www.jiebanke.com/promotion?ref=user123",
"qr_code": "https://www.jiebanke.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://www.jiebanke.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	优化错误处理机制

注意事项

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

72 KiB Raw Blame History Unescape Escape

结伴客系统 API 接口文档

基础信息

响应格式

成功响应

错误响应

通用状态码

认证接口

1. 用户注册

2. 用户登录

3. 获取当前用户信息

4. 更新用户信息

5. 微信登录

4. 获取当前用户信息

6. 更新用户信息

用户服务接口

1. 获取用户列表

2. 获取用户详情

8. 管理员接口

8.1 管理员登录

8.2 获取管理员信息

8.3 更新管理员信息

8.4 修改密码

7. 获取管理员信息

9. 管理员后台接口

9.1 用户管理接口

9.1.1 获取用户列表

9.1.2 获取用户详情

9.1.3 更新用户状态

9.1.4 导出用户数据

9.2 商家审核接口

9.2.1 获取待审核商家列表

9.2.2 审核商家申请

9.2.3 获取商家列表

9.3 内容审核接口

9.3.1 获取待审核内容列表

9.3.2 审核内容

9.3.3 获取内容统计

9.4 数据统计接口

9.4.1 获取平台概览数据

9.4.2 获取用户增长图表

9.4.3 获取订单统计图表

9.4.4 导出数据报表

9.5 权限管理接口

9.5.1 获取管理员列表

9.5.2 创建管理员账号

9.5.3 更新管理员权限

9.5.4 禁用/启用管理员账号

9.5.5 获取权限列表

9.6 操作日志接口

9.6.1 获取操作日志列表

9.6.2 导出操作日志

9.3 更新用户状态

9.4 删除用户

10. 系统管理接口

10.1 获取系统信息

10.2 获取系统服务列表

10.3 更新服务状态

10.4 获取系统配置

10.5 更新系统配置

11. 内容管理接口

11.1 获取内容列表

9.2 获取内容详情

9.3 审核内容

9.4 批量审核内容

13. 商家管理接口

13.1 获取商家申请列表

13.2 审核商家申请

13.3 获取商家列表

13.4 更新商家状态

14. 系统配置接口

14.1 获取系统配置

14.2 更新系统配置

14.3 批量更新系统配置

10. 数据统计接口

10.1 获取系统统计数据

10.2 获取数据趋势图表

10.3 导出数据

11. 权限管理接口

11.1 获取角色列表

72 KiB

Raw Blame History