gamegroup_fe/doc/api/API文档.md

# GameGroup API 文档

## 📚 文档说明

本文档记录 GameGroup 后端所有 API 接口的详细信息，包括请求方法、参数、响应格式等。

**基础信息**:
- **Base URL**: `http://localhost:3000/api`
- **认证方式**: Bearer Token (JWT)
- **内容类型**: `application/json`
- **Swagger 文档**: `http://localhost:3000/docs`

**版本**: v1.0  
**更新时间**: 2025-12-19

---

## 📋 目录

- [1. 认证相关 (Auth)](#1-认证相关-auth)
- [2. 用户管理 (Users)](#2-用户管理-users)
- [3. 小组管理 (Groups)](#3-小组管理-groups)
- [4. 游戏库 (Games)](#4-游戏库-games)
- [5. 预约管理 (Appointments)](#5-预约管理-appointments)
- [6. 账目管理 (Ledgers)](#6-账目管理-ledgers)
- [7. 排班助手 (Schedules)](#7-排班助手-schedules)
- [8. 系统接口 (System)](#8-系统接口-system)
- [9. 黑名单管理 (Blacklist)](#9-黑名单管理-blacklist)
- [10. 荣誉墙 (Honors)](#10-荣誉墙-honors)
- [11. 资产管理 (Assets)](#11-资产管理-assets)
- [12. 积分系统 (Points)](#12-积分系统-points)
- [13. 竞猜系统 (Bets)](#13-竞猜系统-bets)

---

## 🔐 认证说明

### 获取 Token

大部分接口需要在请求头中携带 JWT Token：

```http
Authorization: Bearer <your_access_token>
```

### Token 刷新

当 access_token 过期时，使用 refresh_token 获取新的 token：

```http
POST /api/auth/refresh
Content-Type: application/json

{
  "refreshToken": "your_refresh_token"
}
```

---

## 📦 统一响应格式

### 成功响应

```json
{
  "code": 0,
  "message": "success",
  "data": {
    // 业务数据
  },
  "timestamp": 1703001234567
}
```

### 错误响应

```json
{
  "code": 10001,
  "message": "用户不存在",
  "data": null,
  "timestamp": 1703001234567
}
```

### 错误码对照表

| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| 1 | 未知错误 |
| 2 | 参数错误 |
| 10001 | 用户不存在 |
| 10002 | 密码错误 |
| 10003 | 用户已存在 |
| 10004 | Token无效 |
| 10005 | Token已过期 |
| 10006 | 未授权 |
| 20001 | 小组不存在 |
| 20002 | 小组已满员 |
| 20003 | 无权限操作 |
| 20004 | 小组数量超限 |
| 20005 | 加入小组数量超限 |
| 20006 | 已在该小组中 |
| 20007 | 不在该小组中 |
| 30001 | 预约不存在 |
| 30002 | 预约已满 |
| 30003 | 预约已关闭 |
| 30004 | 已加入预约 |
| 30005 | 未加入预约 |
| 40001 | 游戏不存在 |
| 40002 | 游戏已存在 |
| 90001 | 服务器错误 |
| 90002 | 数据库错误 |

---

## 1. 认证相关 (Auth)

### 1.1 用户注册

**接口**: `POST /api/auth/register`  
**认证**: 无需认证  
**描述**: 新用户注册

**请求体**:
```json
{
  "username": "john_doe",
  "password": "Password123!",
  "email": "john@example.com",
  "phone": "13800138000"
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | 用户名，至少3个字符 |
| password | string | 是 | 密码，至少6个字符 |
| email | string | 否 | 邮箱地址 |
| phone | string | 否 | 手机号 |

**注意**: email 和 phone 至少填写一个

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "user": {
      "id": "uuid",
      "username": "john_doe",
      "email": "john@example.com",
      "phone": "13800138000",
      "avatar": null,
      "isMember": false
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

---

### 1.2 用户登录

**接口**: `POST /api/auth/login`  
**认证**: 无需认证  
**描述**: 用户登录，支持用户名/邮箱/手机号

**请求体**:
```json
{
  "account": "john_doe",
  "password": "Password123!"
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| account | string | 是 | 用户名/邮箱/手机号 |
| password | string | 是 | 密码 |

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "user": {
      "id": "uuid",
      "username": "john_doe",
      "email": "john@example.com",
      "phone": "13800138000",
      "avatar": "https://...",
      "role": "user",
      "isMember": false,
      "memberExpireAt": null
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

---

### 1.3 刷新令牌

**接口**: `POST /api/auth/refresh`  
**认证**: 无需认证  
**描述**: 使用 refresh token 获取新的 access token

**请求体**:
```json
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

---

## 2. 用户管理 (Users)

### 2.1 获取当前用户信息

**接口**: `GET /api/users/me`  
**认证**: 需要  
**描述**: 获取当前登录用户的详细信息

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "uuid",
    "username": "john_doe",
    "email": "john@example.com",
    "phone": "13800138000",
    "avatar": "https://...",
    "role": "user",
    "isMember": false,
    "memberExpireAt": null,
    "lastLoginAt": "2025-12-19T10:00:00.000Z",
    "createdAt": "2025-12-01T10:00:00.000Z"
  }
}
```

---

### 2.2 获取用户信息

**接口**: `GET /api/users/:id`  
**认证**: 需要  
**描述**: 获取指定用户的信息

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 用户ID |

**成功响应**: 同 2.1

---

### 2.3 更新用户信息

**接口**: `PUT /api/users/me`  
**认证**: 需要  
**描述**: 更新当前用户的资料

**请求体**:
```json
{
  "email": "newemail@example.com",
  "phone": "13900139000",
  "avatar": "https://..."
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| email | string | 否 | 邮箱地址 |
| phone | string | 否 | 手机号 |
| avatar | string | 否 | 头像URL |

**成功响应**: 返回更新后的用户信息

---

### 2.4 修改密码

**接口**: `PUT /api/users/me/password`  
**认证**: 需要  
**描述**: 修改当前用户的密码

**请求体**:
```json
{
  "oldPassword": "OldPassword123!",
  "newPassword": "NewPassword123!"
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| oldPassword | string | 是 | 原密码 |
| newPassword | string | 是 | 新密码，至少6个字符 |

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "密码修改成功"
  }
}
```

---

## 3. 小组管理 (Groups)

### 3.1 创建小组

**接口**: `POST /api/groups`  
**认证**: 需要  
**描述**: 创建新小组

**权限限制**:
- 非会员：最多创建 1 个小组
- 会员：最多创建 10 个小组
- 子组：仅会员可创建

**请求体**:
```json
{
  "name": "王者荣耀固定队",
  "description": "每晚8点开黑",
  "avatar": "https://...",
  "type": "normal",
  "parentId": null,
  "maxMembers": 50
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 小组名称 |
| description | string | 否 | 小组描述 |
| avatar | string | 否 | 小组头像 |
| type | string | 否 | 类型：normal/guild，默认normal |
| parentId | string | 否 | 父组ID（创建子组时使用） |
| maxMembers | number | 否 | 最大成员数，默认50，范围2-500 |

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "uuid",
    "name": "王者荣耀固定队",
    "description": "每晚8点开黑",
    "avatar": "https://...",
    "ownerId": "uuid",
    "type": "normal",
    "parentId": null,
    "announcement": null,
    "maxMembers": 50,
    "currentMembers": 1,
    "isActive": true,
    "createdAt": "2025-12-19T10:00:00.000Z",
    "members": [
      {
        "id": "uuid",
        "userId": "uuid",
        "username": "john_doe",
        "avatar": "https://...",
        "nickname": null,
        "role": "owner",
        "joinedAt": "2025-12-19T10:00:00.000Z"
      }
    ]
  }
}
```

---

### 3.2 加入小组

**接口**: `POST /api/groups/join`  
**认证**: 需要  
**描述**: 加入已存在的小组

**权限限制**:
- 非会员：最多加入 3 个小组
- 会员：无限制

**请求体**:
```json
{
  "groupId": "uuid",
  "nickname": "小明"
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| groupId | string | 是 | 小组ID |
| nickname | string | 否 | 组内昵称 |

**成功响应**: 返回小组详情

---

### 3.3 获取我的小组列表

**接口**: `GET /api/groups/my`  
**认证**: 需要  
**描述**: 获取当前用户加入的所有小组

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "uuid",
      "name": "王者荣耀固定队",
      "description": "每晚8点开黑",
      "avatar": "https://...",
      "ownerId": "uuid",
      "currentMembers": 5,
      "maxMembers": 50,
      "myRole": "admin",
      "myNickname": "小明",
      "createdAt": "2025-12-19T10:00:00.000Z"
    }
  ]
}
```

---

### 3.4 获取小组详情

**接口**: `GET /api/groups/:id`  
**认证**: 需要  
**描述**: 获取指定小组的详细信息

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 小组ID |

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "uuid",
    "name": "王者荣耀固定队",
    "description": "每晚8点开黑",
    "avatar": "https://...",
    "ownerId": "uuid",
    "announcement": "本周末团建活动！",
    "maxMembers": 50,
    "currentMembers": 5,
    "members": [
      {
        "id": "uuid",
        "userId": "uuid",
        "username": "john_doe",
        "avatar": "https://...",
        "nickname": "队长",
        "role": "owner",
        "joinedAt": "2025-12-19T10:00:00.000Z"
      }
    ]
  }
}
```

---

### 3.5 更新小组信息

**接口**: `PUT /api/groups/:id`  
**认证**: 需要  
**权限**: 组长、管理员  
**描述**: 更新小组的基本信息

**请求体**:
```json
{
  "name": "王者荣耀固定队 Pro",
  "description": "新的描述",
  "announcement": "重要通知",
  "maxMembers": 60
}
```

**成功响应**: 返回更新后的小组详情

---

### 3.6 设置成员角色

**接口**: `PUT /api/groups/:id/members/role`  
**认证**: 需要  
**权限**: 仅组长  
**描述**: 设置小组成员的角色

**请求体**:
```json
{
  "userId": "uuid",
  "role": "admin"
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| userId | string | 是 | 成员用户ID |
| role | string | 是 | 角色：owner/admin/member |

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "角色设置成功"
  }
}
```

---

### 3.7 踢出成员

**接口**: `DELETE /api/groups/:id/members`  
**认证**: 需要  
**权限**: 组长、管理员  
**描述**: 将成员移出小组

**请求体**:
```json
{
  "userId": "uuid"
}
```

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "成员已移除"
  }
}
```

---

### 3.8 退出小组

**接口**: `DELETE /api/groups/:id/leave`  
**认证**: 需要  
**描述**: 退出已加入的小组

**注意**: 组长不能直接退出，需先转让组长或解散小组

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "退出成功"
  }
}
```

---

### 3.9 解散小组

**接口**: `DELETE /api/groups/:id`  
**认证**: 需要  
**权限**: 仅组长  
**描述**: 解散小组（小组变为不活跃状态）

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "小组已解散"
  }
}
```

---

## 4. 游戏库 (Games)

### 4.1 获取游戏列表

**接口**: `GET /api/games`  
**认证**: 无需认证  
**描述**: 获取游戏列表，支持搜索和筛选

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| keyword | string | 否 | 搜索关键词（匹配游戏名称和描述） |
| platform | string | 否 | 游戏平台筛选 |
| tag | string | 否 | 游戏标签筛选 |
| page | number | 否 | 页码，默认1 |
| limit | number | 否 | 每页数量，默认10 |

**示例请求**:
```
GET /api/games?keyword=王者&page=1&limit=10
```

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "game-uuid-1",
        "name": "王者荣耀",
        "coverUrl": "https://example.com/cover.jpg",
        "description": "5v5公平竞技游戏",
        "maxPlayers": 10,
        "minPlayers": 1,
        "platform": "iOS/Android",
        "tags": ["MOBA", "5v5"],
        "isActive": true,
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 50,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}
```

### 4.2 获取游戏详情

**接口**: `GET /api/games/:id`  
**认证**: 无需认证  
**描述**: 获取指定游戏的详细信息

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 游戏ID |

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "game-uuid-1",
    "name": "王者荣耀",
    "coverUrl": "https://example.com/cover.jpg",
    "description": "5v5公平竞技游戏",
    "maxPlayers": 10,
    "minPlayers": 1,
    "platform": "iOS/Android",
    "tags": ["MOBA", "5v5"],
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}
```

### 4.3 创建游戏

**接口**: `POST /api/games`  
**认证**: 需要JWT认证  
**描述**: 创建新游戏（管理员功能）

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

**请求体**:
```json
{
  "name": "王者荣耀",
  "coverUrl": "https://example.com/cover.jpg",
  "description": "5v5公平竞技游戏",
  "maxPlayers": 10,
  "minPlayers": 1,
  "platform": "iOS/Android",
  "tags": ["MOBA", "5v5"]
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 游戏名称 |
| coverUrl | string | 否 | 游戏封面URL |
| description | string | 否 | 游戏描述 |
| maxPlayers | number | 是 | 最大玩家数，最小为1 |
| minPlayers | number | 否 | 最小玩家数，默认为1 |
| platform | string | 否 | 游戏平台 |
| tags | array | 否 | 游戏标签 |

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "game-uuid-1",
    "name": "王者荣耀",
    "coverUrl": "https://example.com/cover.jpg",
    "description": "5v5公平竞技游戏",
    "maxPlayers": 10,
    "minPlayers": 1,
    "platform": "iOS/Android",
    "tags": ["MOBA", "5v5"],
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}
```

### 4.4 更新游戏信息

**接口**: `PUT /api/games/:id`  
**认证**: 需要JWT认证  
**描述**: 更新游戏信息（管理员功能）

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

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 游戏ID |

**请求体**:
```json
{
  "name": "王者荣耀",
  "description": "更新后的描述",
  "maxPlayers": 12,
  "tags": ["MOBA", "5v5", "竞技"]
}
```

**参数说明**: 所有参数均为可选，只更新提供的字段

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "game-uuid-1",
    "name": "王者荣耀",
    "coverUrl": "https://example.com/cover.jpg",
    "description": "更新后的描述",
    "maxPlayers": 12,
    "minPlayers": 1,
    "platform": "iOS/Android",
    "tags": ["MOBA", "5v5", "竞技"],
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-02T00:00:00Z"
  }
}
```

### 4.5 删除游戏

**接口**: `DELETE /api/games/:id`  
**认证**: 需要JWT认证  
**描述**: 删除游戏（软删除，管理员功能）

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

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 游戏ID |

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "游戏已删除"
  }
}
```

### 4.6 获取热门游戏

**接口**: `GET /api/games/popular`  
**认证**: 无需认证  
**描述**: 获取热门游戏列表

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| limit | number | 否 | 数量限制，默认10 |

**示例请求**:
```
GET /api/games/popular?limit=5
```

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "game-uuid-1",
      "name": "王者荣耀",
      "coverUrl": "https://example.com/cover.jpg",
      "description": "5v5公平竞技游戏",
      "maxPlayers": 10,
      "minPlayers": 1,
      "platform": "iOS/Android",
      "tags": ["MOBA", "5v5"]
    }
  ]
}
```

### 4.7 获取所有游戏标签

**接口**: `GET /api/games/tags`  
**认证**: 无需认证  
**描述**: 获取系统中所有游戏标签

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": ["MOBA", "5v5", "竞技", "FPS", "RPG"]
}
```

### 4.8 获取所有游戏平台

**接口**: `GET /api/games/platforms`  
**认证**: 无需认证  
**描述**: 获取系统中所有游戏平台

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": ["iOS/Android", "PC", "PS5", "Xbox"]
}
```

---

## 5. 预约管理 (Appointments)

### 5.1 创建预约

**接口**: `POST /api/appointments`  
**认证**: 需要JWT认证  
**描述**: 创建新预约

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

**请求体**:
```json
{
  "groupId": "group-uuid",
  "gameId": "game-uuid",
  "title": "今晚开黑",
  "description": "一起排位冲分",
  "startTime": "2024-01-20T19:00:00Z",
  "endTime": "2024-01-20T23:00:00Z",
  "maxParticipants": 5
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| groupId | string | 是 | 小组ID |
| gameId | string | 是 | 游戏ID |
| title | string | 是 | 预约标题 |
| description | string | 否 | 预约描述 |
| startTime | string | 是 | 预约开始时间（ISO 8601格式） |
| endTime | string | 否 | 预约结束时间（ISO 8601格式） |
| maxParticipants | number | 是 | 最大参与人数 |

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "appointment-uuid",
    "groupId": "group-uuid",
    "gameId": "game-uuid",
    "initiatorId": "user-uuid",
    "title": "今晚开黑",
    "description": "一起排位冲分",
    "startTime": "2024-01-20T19:00:00Z",
    "endTime": "2024-01-20T23:00:00Z",
    "maxParticipants": 5,
    "currentParticipants": 1,
    "status": "open",
    "participantCount": 1,
    "isParticipant": true,
    "isCreator": true,
    "isFull": false,
    "group": {...},
    "game": {...},
    "participants": [...]
  }
}
```

### 5.2 获取预约列表

**接口**: `GET /api/appointments`  
**认证**: 需要JWT认证  
**描述**: 获取预约列表，支持筛选

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

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| groupId | string | 否 | 小组ID筛选 |
| gameId | string | 否 | 游戏ID筛选 |
| status | string | 否 | 状态筛选（open/full/cancelled/finished） |
| startTime | string | 否 | 开始时间筛选 |
| endTime | string | 否 | 结束时间筛选 |
| page | number | 否 | 页码，默认1 |
| limit | number | 否 | 每页数量，默认10 |

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [...],
    "total": 50,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}
```

### 5.3 获取我参与的预约

**接口**: `GET /api/appointments/my`  
**认证**: 需要JWT认证  
**描述**: 获取当前用户参与的所有预约

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

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | string | 否 | 状态筛选 |
| page | number | 否 | 页码 |
| limit | number | 否 | 每页数量 |

**成功响应**: 同获取预约列表

### 5.4 获取预约详情

**接口**: `GET /api/appointments/:id`  
**认证**: 需要JWT认证  
**描述**: 获取指定预约的详细信息

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

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 预约ID |

**成功响应**: 同创建预约

### 5.5 加入预约

**接口**: `POST /api/appointments/join`  
**认证**: 需要JWT认证  
**描述**: 加入指定预约

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

**请求体**:
```json
{
  "appointmentId": "appointment-uuid"
}
```

**成功响应**: 返回更新后的预约详情

**错误响应**:
- 30002: 预约已满
- 30004: 已加入预约
- 20007: 不在该小组中

### 5.6 退出预约

**接口**: `DELETE /api/appointments/:id/leave`  
**认证**: 需要JWT认证  
**描述**: 退出指定预约（创建者不能退出）

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

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 预约ID |

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "已退出预约"
  }
}
```

### 5.7 更新预约

**接口**: `PUT /api/appointments/:id`  
**认证**: 需要JWT认证  
**描述**: 更新预约信息（需要创建者或小组管理员权限）

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

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 预约ID |

**请求体**: 所有字段均为可选
```json
{
  "title": "更新后的标题",
  "description": "更新后的描述",
  "startTime": "2024-01-20T20:00:00Z",
  "maxParticipants": 6,
  "status": "full"
}
```

**成功响应**: 返回更新后的预约详情

### 5.8 确认预约

**接口**: `PUT /api/appointments/:id/confirm`  
**认证**: 需要JWT认证  
**描述**: 确认预约（需要创建者或小组管理员权限）

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

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 预约ID |

**成功响应**: 返回更新后的预约详情

### 5.9 完成预约

**接口**: `PUT /api/appointments/:id/complete`  
**认证**: 需要JWT认证  
**描述**: 标记预约为已完成（需要创建者或小组管理员权限）

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

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 预约ID |

**成功响应**: 返回更新后的预约详情

### 5.10 取消预约

**接口**: `DELETE /api/appointments/:id`  
**认证**: 需要JWT认证  
**描述**: 取消预约（需要创建者或小组管理员权限）

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

**路径参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| id | string | 预约ID |

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "预约已取消"
  }
}
```

---

## 6. 账目管理 (Ledgers)

### 6.1 创建账目

**接口**: `POST /ledgers`

**描述**: 为小组创建账目记录

**请求参数**:
```json
{
  "groupId": "group-uuid",
  "amount": 100.00,
  "type": "income",
  "category": "聚餐AA",
  "description": "周五聚餐",
  "remark": "备注信息"
}
```

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": "ledger-uuid",
    "groupId": "group-uuid",
    "creatorId": "user-uuid",
    "amount": "100.00",
    "type": "income",
    "category": "聚餐AA",
    "description": "周五聚餐",
    "remark": "备注信息",
    "createdAt": "2025-12-19T10:00:00.000Z"
  }
}
```

---

### 6.2 获取账目列表

**接口**: `GET /ledgers`

**描述**: 查询小组账目记录，支持筛选和分页

**查询参数**:
- `groupId`: 小组ID（必填）
- `type`: 账目类型（income/expense）
- `category`: 类别
- `startDate`: 开始日期
- `endDate`: 结束日期
- `page`: 页码（默认1）
- `limit`: 每页数量（默认10）

**响应**:
```json
{
  "code": 0,
  "data": {
    "items": [...],
    "total": 50,
    "page": 1,
    "limit": 10
  }
}
```

---

### 6.3 获取账目详情

**接口**: `GET /ledgers/:id`

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": "ledger-uuid",
    "group": {...},
    "creator": {...},
    "amount": "100.00",
    "type": "income",
    "category": "聚餐AA"
  }
}
```

---

### 6.4 更新账目

**接口**: `PUT /ledgers/:id`

**权限**: 创建者或管理员

**请求参数**:
```json
{
  "amount": 150.00,
  "category": "新类别",
  "description": "更新后的描述"
}
```

---

### 6.5 删除账目

**接口**: `DELETE /ledgers/:id`

**权限**: 创建者或管理员

---

### 6.6 月度统计

**接口**: `GET /ledgers/statistics/monthly`

**查询参数**:
- `groupId`: 小组ID（必填）
- `year`: 年份（默认当前年）
- `month`: 月份（默认当前月）

**响应**:
```json
{
  "code": 0,
  "data": {
    "totalIncome": "500.00",
    "totalExpense": "300.00",
    "balance": "200.00",
    "incomeByCategory": {
      "聚餐AA": "300.00",
      "场地费": "200.00"
    },
    "expenseByCategory": {
      "桌游购买": "300.00"
    }
  }
}
```

---

### 6.7 层级统计

**接口**: `GET /ledgers/statistics/hierarchical/:groupId`

**描述**: 汇总父小组和所有子小组的账目统计

**响应**:
```json
{
  "code": 0,
  "data": {
    "totalIncome": "1000.00",
    "totalExpense": "600.00",
    "balance": "400.00",
    "groupStatistics": [
      {
        "groupId": "parent-group",
        "groupName": "总小组",
        "income": "500.00",
        "expense": "300.00"
      },
      {
        "groupId": "child-group-1",
        "groupName": "子小组1",
        "income": "500.00",
        "expense": "300.00"
      }
    ]
  }
}
```

---

## 7. 排班助手 (Schedules)

### 7.1 创建排班

**接口**: `POST /schedules`

**描述**: 为小组提交个人空闲时间

**请求参数**:
```json
{
  "groupId": "group-uuid",
  "title": "本周空闲时间",
  "description": "可以参加活动的时间段",
  "availableSlots": [
    {
      "startTime": "2024-01-20T19:00:00Z",
      "endTime": "2024-01-20T23:00:00Z",
      "note": "晚上空闲"
    },
    {
      "startTime": "2024-01-21T14:00:00Z",
      "endTime": "2024-01-21T18:00:00Z",
      "note": "周日下午"
    }
  ]
}
```

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": "schedule-uuid",
    "userId": "user-uuid",
    "groupId": "group-uuid",
    "title": "本周空闲时间",
    "availableSlots": [...],
    "createdAt": "2025-12-19T10:00:00.000Z"
  }
}
```

---

### 7.2 获取排班列表

**接口**: `GET /schedules`

**查询参数**:
- `groupId`: 小组ID（可选，不填则返回用户所在所有小组排班）
- `userId`: 用户ID（可选，筛选特定用户）
- `startTime`: 开始时间
- `endTime`: 结束时间
- `page`: 页码
- `limit`: 每页数量

**响应**:
```json
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "schedule-uuid",
        "user": {...},
        "group": {...},
        "title": "本周空闲时间",
        "availableSlots": [...]
      }
    ],
    "total": 10,
    "page": 1,
    "limit": 10
  }
}
```

---

### 7.3 查找共同空闲时间

**接口**: `POST /schedules/common-slots`

**描述**: 计算小组成员的共同空闲时间段，推荐最佳活动时间

**请求参数**:
```json
{
  "groupId": "group-uuid",
  "startTime": "2024-01-20T00:00:00Z",
  "endTime": "2024-01-27T23:59:59Z",
  "minParticipants": 3
}
```

**响应**:
```json
{
  "code": 0,
  "data": {
    "commonSlots": [
      {
        "startTime": "2024-01-20T19:00:00Z",
        "endTime": "2024-01-20T21:30:00Z",
        "participants": ["user-1", "user-2", "user-3", "user-4"],
        "participantCount": 4
      },
      {
        "startTime": "2024-01-21T14:00:00Z",
        "endTime": "2024-01-21T17:00:00Z",
        "participants": ["user-1", "user-2", "user-3"],
        "participantCount": 3
      }
    ],
    "totalParticipants": 5,
    "minParticipants": 3
  }
}
```

---

### 7.4 获取排班详情

**接口**: `GET /schedules/:id`

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": "schedule-uuid",
    "user": {...},
    "group": {...},
    "title": "本周空闲时间",
    "description": "可以参加活动的时间段",
    "availableSlots": [...]
  }
}
```

---

### 7.5 更新排班

**接口**: `PUT /schedules/:id`

**权限**: 仅创建者

**请求参数**:
```json
{
  "title": "更新后的标题",
  "availableSlots": [...]
}
```

---

### 7.6 删除排班

**接口**: `DELETE /schedules/:id`

**权限**: 仅创建者

**响应**:
```json
{
  "code": 0,
  "data": {
    "message": "排班已删除"
  }
}
```

---

## 8. 系统接口 (System)

### 8.1 系统欢迎信息

**接口**: `GET /api`  
**认证**: 无需认证  
**描述**: 系统欢迎信息

**成功响应**:
```json
"Hello World!"
```

---

### 8.2 健康检查

**接口**: `GET /api/health`  
**认证**: 无需认证  
**描述**: 检查服务健康状态

**成功响应**:
```json
{
  "status": "ok",
  "timestamp": "2025-12-19T10:00:00.000Z"
}
```

---

## 9. 黑名单管理 (Blacklist)

### 9.1 提交举报

**接口**: `POST /api/blacklist`  
**认证**: 需要  
**描述**: 提交黑名单举报请求

**请求体**:
```json
{
  "type": "USER",
  "targetGameId": "123456",
  "reason": "恶意挂机",
  "evidence": "https://..."
}
```

---

### 9.2 查询黑名单列表

**接口**: `GET /api/blacklist`  
**认证**: 需要  
**描述**: 查询黑名单记录

**查询参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| page | number | 页码 |
| limit | number | 每页数量 |
| status | string | 状态 (PENDING/APPROVED/REJECTED) |
| type | string | 类型 (USER/GUILD) |

---

### 9.3 检查游戏ID

**接口**: `GET /api/blacklist/check/:targetGameId`  
**认证**: 需要  
**描述**: 检查指定游戏ID是否在黑名单中

---

### 9.4 审核黑名单 (管理员)

**接口**: `PATCH /api/blacklist/:id/review`  
**认证**: 需要 (管理员)  
**描述**: 审核黑名单举报

**请求体**:
```json
{
  "status": "APPROVED",
  "reviewNote": "证据确凿"
}
```

---

## 10. 荣誉墙 (Honors)

### 10.1 创建荣誉记录

**接口**: `POST /api/honors`  
**认证**: 需要  
**描述**: 创建新的荣誉记录

**请求体**:
```json
{
  "groupId": "uuid",
  "title": "年度最佳新人",
  "description": "表现优异",
  "type": "YEARLY",
  "year": 2025,
  "recipientIds": ["uuid1", "uuid2"]
}
```

---

### 10.2 获取荣誉时间轴

**接口**: `GET /api/honors/timeline/:groupId`  
**认证**: 需要  
**描述**: 获取小组荣誉时间轴数据

---

## 11. 资产管理 (Assets)

### 11.1 创建资产 (管理员)

**接口**: `POST /api/assets`  
**认证**: 需要 (管理员)  
**描述**: 录入新资产

**请求体**:
```json
{
  "groupId": "uuid",
  "name": "公会备用账号",
  "type": "ACCOUNT",
  "identifier": "account_001",
  "value": 500
}
```

---

### 11.2 查询小组资产

**接口**: `GET /api/assets/group/:groupId`  
**认证**: 需要  
**描述**: 查询指定小组的所有资产

---

### 11.3 借用资产

**接口**: `POST /api/assets/:id/borrow`  
**认证**: 需要  
**描述**: 登记借用资产

**请求体**:
```json
{
  "expectedReturnDate": "2026-02-01T00:00:00.000Z",
  "note": "临时借用"
}
```

---

### 11.4 归还资产

**接口**: `POST /api/assets/:id/return`  
**认证**: 需要  
**描述**: 登记归还资产

**请求体**:
```json
{
  "condition": "GOOD",
  "note": "已归还，无损坏"
}
```

---

### 11.5 查询流转记录

**接口**: `GET /api/assets/:id/logs`  
**认证**: 需要  
**描述**: 查询资产的借还历史记录

---

## 12. 积分系统 (Points)

### 12.1 添加积分记录 (管理员)

**接口**: `POST /api/points`  
**认证**: 需要 (管理员)  
**描述**: 手动增加或扣除积分

**请求体**:
```json
{
  "userId": "uuid",
  "groupId": "uuid",
  "amount": 100,
  "type": "ACTIVITY",
  "reason": "参加周赛奖励"
}
```

---

### 12.2 查询积分余额

**接口**: `GET /api/points/balance/:userId/:groupId`  
**认证**: 需要  
**描述**: 查询用户在指定小组的积分情况

---

### 12.3 小组积分排行榜

**接口**: `GET /api/points/ranking/:groupId`  
**认证**: 需要  
**描述**: 获取小组积分排行

---

## 13. 竞猜系统 (Bets)

### 13.1 创建竞猜

**接口**: `POST /api/bets`  
**认证**: 需要  
**描述**: 基于预约创建竞猜活动

**请求体**:
```json
{
  "appointmentId": "uuid",
  "title": "本场比赛谁获得MVP？",
  "options": ["PlayerA", "PlayerB"],
  "minBet": 10,
  "maxBet": 1000,
  "deadline": "2026-01-20T20:00:00.000Z"
}
```

---

### 13.2 结算竞猜 (管理员)

**接口**: `POST /api/bets/appointment/:appointmentId/settle`  
**认证**: 需要 (管理员)  
**描述**: 结算竞猜结果并分发奖励

**请求体**:
```json
{
  "winningOption": "PlayerA",
  "note": "结算说明"
}
```

---

## 📝 更新日志

### 2026-01-11
- ✅ 补充 Blacklist 模块 API
- ✅ 补充 Honors 模块 API
- ✅ 补充 Assets 模块 API
- ✅ 补充 Points 模块 API
- ✅ 补充 Bets 模块 API
- ✅ 修正 System 接口描述

### 2025-12-19
- ✅ 初始版本发布
- ✅ 认证模块 API（3个接口）
- ✅ 用户模块 API（4个接口）
- ✅ 小组模块 API（9个接口）
- ✅ 游戏库模块 API（8个接口）
- ✅ 预约模块 API（10个接口）
- ✅ 账目模块 API（6个接口）
- ✅ 排班助手模块 API（6个接口）

---

## 🔗 相关文档

- [开发步骤文档](开发步骤文档.md)
- [修改记录](修改记录.md)
- [README](README.md)
- [Swagger 在线文档](http://localhost:3000/docs)