jiebanke/API_DOCS.md

# 📚 API 接口文档

## 📋 文档说明
本文档详细描述了杰邦科项目的所有API接口，包括请求参数、响应格式和错误代码。

## 🔐 认证方式

### JWT Token 认证
所有需要认证的API必须在请求头中携带Token：
```
Authorization: Bearer <your_jwt_token>
```

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

## 👥 用户模块

### 用户注册

**Endpoint:** `POST /api/v1/users/register`

**请求参数:**
```json
{
  "username": "string, required, 3-20字符",
  "password": "string, required, 6-20字符",
  "email": "string, optional, 邮箱格式",
  "phone": "string, optional, 手机号格式"
}
```

**响应示例:**
```json
{
  "code": 200,
  "message": "注册成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}
```

**错误代码:**
- `400`: 参数验证失败
- `409`: 用户名已存在
- `500`: 服务器内部错误

### 用户登录

**Endpoint:** `POST /api/v1/users/login`

**请求参数:**
```json
{
  "username": "string, required",
  "password": "string, required"
}
```

**响应示例:**
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "testuser",
      "email": "test@example.com"
    }
  }
}
```

**错误代码:**
- `400`: 参数验证失败
- `401`: 用户名或密码错误
- `500`: 服务器内部错误

### 获取用户信息

**Endpoint:** `GET /api/v1/users/profile`

**请求头:**
```
Authorization: Bearer <token>
```

**响应示例:**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "phone": "13800138000",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

**错误代码:**
- `401`: 未授权访问
- `404`: 用户不存在
- `500`: 服务器内部错误

## 🛒 订单模块

### 创建订单

**Endpoint:** `POST /api/v1/orders`

**请求头:**
```
Authorization: Bearer <token>
```

**请求参数:**
```json
{
  "items": [
    {
      "productId": 1,
      "quantity": 2,
      "price": 100.00
    }
  ],
  "shippingAddress": {
    "recipient": "张三",
    "phone": "13800138000",
    "address": "北京市朝阳区xxx路xxx号"
  },
  "remark": "string, optional"
}
```

**响应示例:**
```json
{
  "code": 200,
  "message": "订单创建成功",
  "data": {
    "id": 1001,
    "orderNo": "ORDER202401010001",
    "totalAmount": 200.00,
    "status": "pending",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### 查询订单列表

**Endpoint:** `GET /api/v1/orders`

**请求头:**
```
Authorization: Bearer <token>
```

**查询参数:**
```
?page=1&limit=10&status=pending
```

| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码，默认1 |
| limit | number | 每页数量，默认10 |
| status | string | 订单状态过滤 |

**响应示例:**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1001,
        "orderNo": "ORDER202401010001",
        "totalAmount": 200.00,
        "status": "pending",
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 100,
      "pages": 10
    }
  }
}
```

## 📦 商品模块

### 获取商品列表

**Endpoint:** `GET /api/v1/products`

**查询参数:**
```
?page=1&limit=10&category=electronics&sort=price_desc
```

| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码，默认1 |
| limit | number | 每页数量，默认10 |
| category | string | 商品分类过滤 |
| sort | string | 排序方式 |

**响应示例:**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "iPhone 15",
        "price": 5999.00,
        "originalPrice": 6999.00,
        "image": "/images/iphone15.jpg",
        "category": "electronics",
        "stock": 100,
        "description": "最新款iPhone手机"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1000,
      "pages": 100
    }
  }
}
```

### 获取商品详情

**Endpoint:** `GET /api/v1/products/:id`

**路径参数:**
- `id`: 商品ID

**响应示例:**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "name": "iPhone 15",
    "price": 5999.00,
    "originalPrice": 6999.00,
    "images": [
      "/images/iphone15-1.jpg",
      "/images/iphone15-2.jpg"
    ],
    "category": "electronics",
    "brand": "Apple",
    "stock": 100,
    "description": "最新款iPhone手机",
    "specifications": {
      "color": "黑色",
      "storage": "256GB",
      "screen": "6.1英寸"
    },
    "reviews": {
      "averageRating": 4.8,
      "totalReviews": 150
    }
  }
}
```

## 📊 数据字典

### 订单状态
| 状态值 | 描述 |
|--------|------|
| pending | 待支付 |
| paid | 已支付 |
| shipped | 已发货 |
| completed | 已完成 |
| cancelled | 已取消 |

### 商品分类
| 分类值 | 描述 |
|--------|------|
| electronics | 电子产品 |
| clothing | 服装服饰 |
| books | 图书文具 |
| home | 家居生活 |
| sports | 运动户外 |

### 错误代码
| 代码 | 描述 |
|------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权访问 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 409 | 资源冲突 |
| 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/users/login \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"password123"}'

# 获取用户信息
curl -X GET http://localhost:3000/api/v1/users/profile \
  -H "Authorization: Bearer <token>"
```

### 使用Postman测试
1. 导入Postman集合文件
2. 设置环境变量（base_url, token等）
3. 运行测试用例

## 📝 更新日志

### v1.0.0 (2024-01-01)
- 用户注册登录接口
- 订单管理接口
- 商品管理接口
- 基础认证系统

---
*最后更新: 2024年* 📅