35 KiB
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)
- 2. 用户管理 (Users)
- 3. 小组管理 (Groups)
- 4. 游戏库 (Games)
- 5. 预约管理 (Appointments)
- 6. 账目管理 (Ledgers)
- 7. 排班助手 (Schedules)
- 8. 系统接口 (System)
- 9. 黑名单管理 (Blacklist)
- 10. 荣誉墙 (Honors)
- 11. 资产管理 (Assets)
- 12. 积分系统 (Points)
- 13. 竞猜系统 (Bets)
🔐 认证说明
获取 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个字符 |
| 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://..."
}
参数说明:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 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个接口）