jiebanke/docs/API-README.md

# 结伴客系统 API 使用指南

## 📖 概述

本文档提供了结伴客系统完整的API接口说明，包括认证、用户管理、旅行服务、动物认领、商家服务、推广奖励等核心功能接口。

## 🚀 快速开始

### 环境要求
- Node.js 16+ 
- MySQL 8.0+
- Redis (可选)
- RabbitMQ (可选)

### 安装依赖
```bash
cd scripts
npm install
```

### 运行测试
```bash
# 运行完整API测试
npm test

# 仅测试健康检查
npm run test:health
```

## 🔐 认证方式

所有需要认证的接口都需要在请求头中包含Bearer Token：

```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### 获取Token的流程：
1. 用户注册或登录
2. 从响应中获取token
3. 在后续请求的Header中包含token

## 📋 核心接口

### 用户认证
- `POST /api/v1/auth/register` - 用户注册
- `POST /api/v1/auth/login` - 用户登录  
- `POST /api/v1/auth/wechat-login` - 微信登录
- `GET /api/v1/auth/me` - 获取当前用户信息

### 旅行服务
- `POST /api/v1/travel/plans` - 创建旅行计划
- `GET /api/v1/travel/plans` - 获取旅行计划列表
- `GET /api/v1/travel/matches` - 匹配旅行伙伴

### 动物认领
- `GET /api/v1/animals` - 获取可认领动物列表
- `POST /api/v1/animals/{id}/claim` - 认领动物
- `GET /api/v1/animals/claims` - 获取认领记录

### 商家服务
- `POST /api/v1/merchants/register` - 商家注册
- `POST /api/v1/merchants/products` - 发布商品/服务
- `GET /api/v1/merchants/orders` - 获取商家订单

### 推广奖励
- `GET /api/v1/promotion/link` - 获取推广链接
- `GET /api/v1/promotion/stats` - 获取推广数据
- `POST /api/v1/promotion/withdraw` - 申请提现

### 官网接口
- `POST /api/v1/website/merchant/apply` - 提交商家入驻申请
- `GET /api/v1/website/cases` - 获取成功案例列表

## 🎯 响应格式

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

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

## ⚠️ 注意事项

1. **时间格式**: 所有时间字段使用ISO 8601格式 (YYYY-MM-DDTHH:mm:ss.sssZ)
2. **金额单位**: 人民币元，保留两位小数
3. **图片URL**: 必须使用HTTPS协议
4. **频率限制**: API调用频率限制为每分钟100次
5. **敏感操作**: 需要二次验证确保安全

## 🔧 开发建议

### 1. 错误处理
```javascript
try {
  const response = await api.post('/auth/login', credentials);
  // 处理成功响应
} catch (error) {
  if (error.response?.status === 401) {
    // 处理未授权错误
  } else if (error.response?.status === 429) {
    // 处理频率限制错误
  } else {
    // 处理其他错误
  }
}
```

### 2. 请求重试
对于重要的请求，建议实现重试机制：

```javascript
async function requestWithRetry(url, data, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await api.post(url, data);
    } catch (error) {
      if (i === retries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}
```

### 3. Token刷新
实现token自动刷新机制：

```javascript
// 响应拦截器处理token过期
api.interceptors.response.use(
  (response) => response,
  async (error) => {
    if (error.response?.status === 401) {
      // 刷新token逻辑
      const newToken = await refreshToken();
      error.config.headers.Authorization = `Bearer ${newToken}`;
      return api.request(error.config);
    }
    return Promise.reject(error);
  }
);
```

## 📊 监控和日志

建议对API调用进行监控和日志记录：

1. **性能监控**: 记录每个接口的响应时间
2. **错误监控**: 记录API调用错误和异常
3. **使用统计**: 统计接口调用频率和用户行为
4. **安全审计**: 记录敏感操作和登录尝试

## 🚨 常见问题

### Q1: 如何处理重复注册？
A: 注册接口会返回409状态码，提示"用户已存在"

### Q2: 如何重置密码？
A: 目前需要通过客服渠道重置，后续会开发密码重置功能

### Q3: 如何获取商家资质？
A: 商家需要准备营业执照等资质文件，通过官网提交申请

### Q4: API调用频率限制是多少？
A: 每分钟100次请求，超过限制会返回429状态码

## 📞 技术支持

如有API使用问题，请联系：
- 邮箱: support@jiebanke.com
- 电话: 400-123-4567
- 微信: jiebanke-support

## 📄 版本历史

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

---

**最后更新**: 2025-01-01  
**文档版本**: v1.0