Files

UGREEN USER b25aa5b143 初始化游戏小组管理系统后端项目

- 基于 NestJS + TypeScript + MySQL + Redis 架构
- 完整的模块化设计（认证、用户、小组、游戏、预约等）
- JWT 认证和 RBAC 权限控制系统
- Docker 容器化部署支持
- 添加 CLAUDE.md 项目开发指南
- 配置 .gitignore 忽略文件

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-01-28 10:42:06 +08:00

35 KiB

Raw Blame History

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

🔐 认证说明

获取 Token

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

Authorization: Bearer <your_access_token>

Token 刷新

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

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

{
  "refreshToken": "your_refresh_token"
}

📦 统一响应格式

成功响应

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

错误响应

{
  "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
认证: 无需认证
描述: 新用户注册

请求体:

{
  "username": "john_doe",
  "password": "Password123!",
  "email": "john@example.com",
  "phone": "13800138000"
}

参数说明:

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

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

成功响应:

{
  "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
认证: 无需认证
描述: 用户登录，支持用户名/邮箱/手机号

请求体:

{
  "account": "john_doe",
  "password": "Password123!"
}

参数说明:

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

成功响应:

{
  "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

请求体:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

成功响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

2. 用户管理 (Users)

2.1 获取当前用户信息

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

成功响应:

{
  "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
认证: 需要
描述: 更新当前用户的资料

请求体:

{
  "email": "newemail@example.com",
  "phone": "13900139000",
  "avatar": "https://..."
}

参数说明:

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

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

2.4 修改密码

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

请求体:

{
  "oldPassword": "OldPassword123!",
  "newPassword": "NewPassword123!"
}

参数说明:

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

成功响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "密码修改成功"
  }
}

3. 小组管理 (Groups)

3.1 创建小组

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

权限限制:

非会员：最多创建 1 个小组
会员：最多创建 10 个小组
子组：仅会员可创建

请求体:

{
  "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

成功响应:

{
  "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 个小组
会员：无限制

请求体:

{
  "groupId": "uuid",
  "nickname": "小明"
}

参数说明:

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

成功响应: 返回小组详情

3.3 获取我的小组列表

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

成功响应:

{
  "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

成功响应:

{
  "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
认证: 需要
权限: 组长、管理员
描述: 更新小组的基本信息

请求体:

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

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

3.6 设置成员角色

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

请求体:

{
  "userId": "uuid",
  "role": "admin"
}

参数说明:

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

成功响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "角色设置成功"
  }
}

3.7 踢出成员

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

请求体:

{
  "userId": "uuid"
}

成功响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "成员已移除"
  }
}

3.8 退出小组

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

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

成功响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "退出成功"
  }
}

3.9 解散小组

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

成功响应:

{
  "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

成功响应:

{
  "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

成功响应:

{
  "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>

请求体:

{
  "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	否	游戏标签

成功响应:

{
  "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

请求体:

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

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

成功响应:

{
  "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

成功响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "游戏已删除"
  }
}

4.6 获取热门游戏

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

查询参数:

参数	类型	必填	说明
limit	number	否	数量限制，默认10

示例请求:

GET /api/games/popular?limit=5

成功响应:

{
  "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
认证: 无需认证
描述: 获取系统中所有游戏标签

成功响应:

{
  "code": 0,
  "message": "success",
  "data": ["MOBA", "5v5", "竞技", "FPS", "RPG"]
}

4.8 获取所有游戏平台

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

成功响应:

{
  "code": 0,
  "message": "success",
  "data": ["iOS/Android", "PC", "PS5", "Xbox"]
}

5. 预约管理 (Appointments)

5.1 创建预约

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

请求头:

Authorization: Bearer <access_token>

请求体:

{
  "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	是	最大参与人数

成功响应:

{
  "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

成功响应:

{
  "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>

请求体:

{
  "appointmentId": "appointment-uuid"
}

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

错误响应:

30002: 预约已满
30004: 已加入预约
20007: 不在该小组中

5.6 退出预约

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

请求头:

Authorization: Bearer <access_token>

路径参数:

参数	类型	说明
id	string	预约ID

成功响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "已退出预约"
  }
}

5.7 更新预约

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

请求头:

Authorization: Bearer <access_token>

路径参数:

参数	类型	说明
id	string	预约ID

请求体: 所有字段均为可选

{
  "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

成功响应:

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "预约已取消"
  }
}

6. 账目管理 (Ledgers)

6.1 创建账目

接口: POST /ledgers

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

请求参数:

{
  "groupId": "group-uuid",
  "amount": 100.00,
  "type": "income",
  "category": "聚餐AA",
  "description": "周五聚餐",
  "remark": "备注信息"
}

响应:

{
  "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）

响应:

{
  "code": 0,
  "data": {
    "items": [...],
    "total": 50,
    "page": 1,
    "limit": 10
  }
}

6.3 获取账目详情

接口: GET /ledgers/:id

响应:

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

6.4 更新账目

接口: PUT /ledgers/:id

权限: 创建者或管理员

请求参数:

{
  "amount": 150.00,
  "category": "新类别",
  "description": "更新后的描述"
}

6.5 删除账目

接口: DELETE /ledgers/:id

权限: 创建者或管理员

6.6 月度统计

接口: GET /ledgers/statistics/monthly

查询参数:

groupId: 小组ID（必填）
year: 年份（默认当前年）
month: 月份（默认当前月）

响应:

{
  "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

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

响应:

{
  "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

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

请求参数:

{
  "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": "周日下午"
    }
  ]
}

响应:

{
  "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: 每页数量

响应:

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

7.3 查找共同空闲时间

接口: POST /schedules/common-slots

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

请求参数:

{
  "groupId": "group-uuid",
  "startTime": "2024-01-20T00:00:00Z",
  "endTime": "2024-01-27T23:59:59Z",
  "minParticipants": 3
}

响应:

{
  "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

响应:

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

7.5 更新排班

接口: PUT /schedules/:id

权限: 仅创建者

请求参数:

{
  "title": "更新后的标题",
  "availableSlots": [...]
}

7.6 删除排班

接口: DELETE /schedules/:id

权限: 仅创建者

响应:

{
  "code": 0,
  "data": {
    "message": "排班已删除"
  }
}

8. 系统接口 (System)

8.1 系统欢迎信息

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

成功响应:

"Hello World!"

8.2 健康检查

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

成功响应:

{
  "status": "ok",
  "timestamp": "2025-12-19T10:00:00.000Z"
}

9. 黑名单管理 (Blacklist)

9.1 提交举报

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

请求体:

{
  "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
认证: 需要 (管理员)
描述: 审核黑名单举报

请求体:

{
  "status": "APPROVED",
  "reviewNote": "证据确凿"
}

10. 荣誉墙 (Honors)

10.1 创建荣誉记录

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

请求体:

{
  "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
认证: 需要 (管理员)
描述: 录入新资产

请求体:

{
  "groupId": "uuid",
  "name": "公会备用账号",
  "type": "ACCOUNT",
  "identifier": "account_001",
  "value": 500
}

11.2 查询小组资产

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

11.3 借用资产

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

请求体:

{
  "expectedReturnDate": "2026-02-01T00:00:00.000Z",
  "note": "临时借用"
}

11.4 归还资产

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

请求体:

{
  "condition": "GOOD",
  "note": "已归还，无损坏"
}

11.5 查询流转记录

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

12. 积分系统 (Points)

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

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

请求体:

{
  "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
认证: 需要
描述: 基于预约创建竞猜活动

请求体:

{
  "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
认证: 需要 (管理员)
描述: 结算竞猜结果并分发奖励

请求体:

{
  "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个接口）

35 KiB Raw Blame History Unescape Escape

GameGroup API 文档

📚 文档说明

📋 目录

🔐 认证说明

获取 Token

Token 刷新

📦 统一响应格式

成功响应

错误响应

错误码对照表

1. 认证相关 (Auth)

1.1 用户注册

1.2 用户登录

1.3 刷新令牌

2. 用户管理 (Users)

2.1 获取当前用户信息

2.2 获取用户信息

2.3 更新用户信息

2.4 修改密码

3. 小组管理 (Groups)

3.1 创建小组

3.2 加入小组

3.3 获取我的小组列表

3.4 获取小组详情

3.5 更新小组信息

3.6 设置成员角色

3.7 踢出成员

3.8 退出小组

3.9 解散小组

4. 游戏库 (Games)

4.1 获取游戏列表

4.2 获取游戏详情

4.3 创建游戏

4.4 更新游戏信息

4.5 删除游戏

4.6 获取热门游戏

4.7 获取所有游戏标签

4.8 获取所有游戏平台

5. 预约管理 (Appointments)

5.1 创建预约

5.2 获取预约列表

5.3 获取我参与的预约

5.4 获取预约详情

5.5 加入预约

5.6 退出预约

5.7 更新预约

5.8 确认预约

5.9 完成预约

5.10 取消预约

6. 账目管理 (Ledgers)

6.1 创建账目

6.2 获取账目列表

6.3 获取账目详情

6.4 更新账目

6.5 删除账目

6.6 月度统计

6.7 层级统计

7. 排班助手 (Schedules)

7.1 创建排班

7.2 获取排班列表

7.3 查找共同空闲时间

7.4 获取排班详情

7.5 更新排班

7.6 删除排班

8. 系统接口 (System)

8.1 系统欢迎信息

8.2 健康检查

9. 黑名单管理 (Blacklist)

9.1 提交举报

9.2 查询黑名单列表

9.3 检查游戏ID

9.4 审核黑名单 (管理员)

10. 荣誉墙 (Honors)

10.1 创建荣誉记录

10.2 获取荣誉时间轴

11. 资产管理 (Assets)

11.1 创建资产 (管理员)

11.2 查询小组资产

11.3 借用资产

35 KiB

Raw Blame History