修改文件结构

2025-09-01 02:20:36 +08:00
parent 5fbbe4a8a5
commit 7b73f2be33
24 changed files with 20878 additions and 47190 deletions
--- a/docs/API_DOCS.md
+++ b/docs/API_DOCS.md
@@ -0,0 +1,531 @@
+# 📚 结伴客API接口文档
+
+## 📋 文档说明
+本文档详细描述了结伴客项目的所有API接口，包括请求参数、响应格式和错误代码。结伴客是一个专注于结伴旅行和动物认领的社交平台。
+
+## 🔐 认证方式
+
+### JWT Token 认证
+所有需要认证的API必须在请求头中携带Token：
+```
+Authorization: Bearer <your_jwt_token>
+```
+
+### 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 <token>
+```
+
+**响应示例:**
+```json
+{
+  "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>
+```
+
+**请求参数:**
+```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 <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 | 最高预算 |
+
+**响应示例:**
+```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 <token>
+```
+
+**请求参数:**
+```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 <token>
+```
+
+**请求参数:**
+```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 <token>
+```
+
+**请求参数:**
+```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 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测试
+1. 导入Postman集合文件
+2. 设置环境变量（base_url, token等）
+3. 运行测试用例
+
+## 📝 更新日志
+
+### v1.0.0 (2024-01-01)
+- 微信用户登录接口
+- 旅行结伴管理接口
+- 动物认领管理接口
+- 送花服务接口
+- 基础认证系统
+
+---
+*最后更新: 2024年* 📅