# API接口设计详设文档

> **文档版本**: v1.0  
> **撰写人**: 后端架构师  
> **创建日期**: 2024年9月11日  

## 1. 设计原则与规范

- **RESTful风格**: API遵循RESTful设计原则，使用标准的HTTP方法 (`GET`, `POST`, `PUT`, `DELETE`)。
- **JSON格式**: 所有请求体和响应体均使用`application/json`格式。
- **URL版本控制**: API版本通过URL前缀进行管理，例如 `/api/v1/...`。
- **身份认证**: 所有需要认证的接口都通过`Authorization: Bearer <JWT>`头进行身份验证。
- **统一响应格式**: 所有API响应都遵循统一的数据结构，便于客户端处理。
- **错误处理**: 使用标准的HTTP状态码表示请求结果，并在响应体中提供详细的错误信息。

## 2. 统一响应格式

### 2.1 成功响应 (`2xx`)

```json
{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {
    "key1": "value1",
    "key2": "value2"
  }
}
```

### 2.2 失败响应 (`4xx`, `5xx`)

```json
{
  "success": false,
  "code": 401,
  "message": "身份认证失败",
  "error": {
    "type": "AuthenticationError",
    "details": "JWT token is invalid or expired."
  }
}
```

## 3. API接口详解

### 3.1 用户认证模块 (`/api/v1/auth`)

#### 3.1.1 `POST /auth/login`
- **功能**: 微信小程序登录。客户端使用`wx.login()`获取`code`后调用此接口。
- **请求体**:
  ```json
  {
    "code": "wx-login-code-from-miniprogram"
  }
  ```
- **成功响应 (`200 OK`)**:
  - **描述**: 返回JWT和新/老用户信息。
  - **响应体**:
    ```json
    {
      "success": true,
      "code": 200,
      "message": "登录成功",
      "data": {
        "token": "jwt.string.here",
        "isNewUser": false,
        "user": {
          "id": "user-openid",
          "nickname": "张三",
          "avatarUrl": "url-to-avatar"
        }
      }
    }
    ```
- **失败响应**:
  - `400 Bad Request`: `code`无效或缺失。
  - `500 Internal Server Error`: 微信服务器接口调用失败。

#### 3.1.2 `PUT /auth/profile`
- **功能**: 更新用户信息（昵称、头像）。
- **认证**: 需要JWT。
- **请求体**:
  ```json
  {
    "nickname": "新的昵称",
    "avatarUrl": "新的头像URL"
  }
  ```
- **成功响应 (`200 OK`)**:
  - **描述**: 返回更新后的用户信息。
  - **响应体**:
    ```json
    {
      "success": true,
      "code": 200,
      "message": "用户信息更新成功",
      "data": {
        "id": "user-openid",
        "nickname": "新的昵称",
        "avatarUrl": "新的头像URL"
        // ...
      }
    }
    ```

### 3.2 用户信息模块 (`/api/v1/users`)

#### 3.2.1 `GET /users/me`
- **功能**: 获取当前登录用户的详细信息。
- **认证**: 需要JWT。
- **成功响应 (`200 OK`)**:
  - **描述**: 返回包含统计数据的完整用户信息。
  - **响应体**:
    ```json
    {
      "success": true,
      "code": 200,
      "message": "获取成功",
      "data": {
        "id": "user-openid",
        "nickname": "张三",
        "avatarUrl": "url-to-avatar",
        "stats": {
          "gamesPlayed": 100,
          "gamesWon": 60,
          "winRate": 60.0,
          "eloRating": 1350
        },
        "createdAt": "2024-09-10T..."
      }
    }
    ```

#### 3.2.2 `GET /users/:id`
- **功能**: 获取指定ID用户的公开信息。
- **认证**: 可选。
- **成功响应 (`200 OK`)**:
  - **描述**: 返回用户的公开信息（不含敏感数据）。
  - **响应体**:
    ```json
    {
      "success": true,
      "code": 200,
      "message": "获取成功",
      "data": {
        "id": "other-user-id",
        "nickname": "李四",
        "avatarUrl": "url-to-avatar",
        "stats": {
          "gamesPlayed": 120,
          "winRate": 55.0,
          "eloRating": 1300
        }
      }
    }
    ```
- **失败响应**:
  - `404 Not Found`: 用户不存在。

### 3.3 游戏模块 (`/api/v1/games`)

#### 3.3.1 `GET /games/history`
- **功能**: 获取当前用户的历史对局列表（分页）。
- **认证**: 需要JWT。
- **查询参数**:
  - `page` (number, default: 1): 页码。
  - `limit` (number, default: 10): 每页数量。
- **成功响应 (`200 OK`)**:
  - **描述**: 返回分页的游戏历史记录。
  - **响应体**:
    ```json
    {
      "success": true,
      "code": 200,
      "message": "获取成功",
      "data": {
        "games": [
          {
            "gameId": "game-id-1",
            "opponent": { "id": "user-id-2", "nickname": "李四" },
            "result": "win", // "win" | "loss"
            "finishedAt": "2024-09-11T...",
            "duration": 600 // 秒
          }
        ],
        "pagination": {
          "currentPage": 1,
          "totalPages": 10,
          "totalGames": 100
        }
      }
    }
    ```

#### 3.3.2 `GET /games/:id`
- **功能**: 获取指定游戏对局的详细信息（用于复盘）。
- **认证**: 需要JWT，且用户必须是该对局的参与者。
- **成功响应 (`200 OK`)**:
  - **描述**: 返回完整的游戏会话数据。
  - **响应体**: (完整的 `GameSession` 对象)
- **失败响应**:
  - `403 Forbidden`: 无权访问该对局。
  - `404 Not Found`: 游戏不存在。

### 3.4 排行榜模块 (`/api/v1/leaderboard`)

#### 3.4.1 `GET /leaderboard`
- **功能**: 获取Elo积分排行榜。
- **认证**: 可选。
- **查询参数**:
  - `limit` (number, default: 100): 返回的条目数。
- **成功响应 (`200 OK`)**:
  - **描述**: 返回排名列表。
  - **响应体**:
    ```json
    {
      "success": true,
      "code": 200,
      "message": "获取成功",
      "data": {
        "ranking": [
          {
            "rank": 1,
            "user": { "id": "user-id-1", "nickname": "高手" },
            "eloRating": 2000
          },
          {
            "rank": 2,
            "user": { "id": "user-id-2", "nickname": "大师" },
            "eloRating": 1950
          }
        ],
        "lastUpdatedAt": "2024-09-11T..."
      }
    }
    ```

## 4. WebSocket API

WebSocket通信不属于RESTful API，但其认证和初始状态获取与HTTP API紧密相关。

- **连接地址**: `wss://your-domain.com/ws`
- **认证流程**:
  1. 客户端通过`POST /api/v1/auth/login`获取JWT。
  2. 建立WebSocket连接。
  3. 连接成功后，发送第一条消息进行认证。
- **认证消息**:
  ```json
  {
    "type": "AUTHENTICATE",
    "payload": {
      "token": "jwt.string.here"
    }
  }
  ```
- **认证成功响应**:
  ```json
  {
    "type": "AUTHENTICATED",
    "payload": {
      "userId": "user-id",
      // ...
    }
  }
  ```
- **后续通信**: 详见《实时通信模块详设文档》。