# 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 ``` ### 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 ``` **请求体**: ```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 ``` **路径参数**: | 参数 | 类型 | 说明 | |------|------|------| | 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 ``` **路径参数**: | 参数 | 类型 | 说明 | |------|------|------| | 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 ``` **请求体**: ```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 ``` **查询参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | 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 ``` **查询参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | status | string | 否 | 状态筛选 | | page | number | 否 | 页码 | | limit | number | 否 | 每页数量 | **成功响应**: 同获取预约列表 ### 5.4 获取预约详情 **接口**: `GET /api/appointments/:id` **认证**: 需要JWT认证 **描述**: 获取指定预约的详细信息 **请求头**: ``` Authorization: Bearer ``` **路径参数**: | 参数 | 类型 | 说明 | |------|------|------| | id | string | 预约ID | **成功响应**: 同创建预约 ### 5.5 加入预约 **接口**: `POST /api/appointments/join` **认证**: 需要JWT认证 **描述**: 加入指定预约 **请求头**: ``` Authorization: Bearer ``` **请求体**: ```json { "appointmentId": "appointment-uuid" } ``` **成功响应**: 返回更新后的预约详情 **错误响应**: - 30002: 预约已满 - 30004: 已加入预约 - 20007: 不在该小组中 ### 5.6 退出预约 **接口**: `DELETE /api/appointments/:id/leave` **认证**: 需要JWT认证 **描述**: 退出指定预约（创建者不能退出） **请求头**: ``` Authorization: Bearer ``` **路径参数**: | 参数 | 类型 | 说明 | |------|------|------| | id | string | 预约ID | **成功响应**: ```json { "code": 0, "message": "success", "data": { "message": "已退出预约" } } ``` ### 5.7 更新预约 **接口**: `PUT /api/appointments/:id` **认证**: 需要JWT认证 **描述**: 更新预约信息（需要创建者或小组管理员权限） **请求头**: ``` Authorization: Bearer ``` **路径参数**: | 参数 | 类型 | 说明 | |------|------|------| | 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 ``` **路径参数**: | 参数 | 类型 | 说明 | |------|------|------| | id | string | 预约ID | **成功响应**: 返回更新后的预约详情 ### 5.9 完成预约 **接口**: `PUT /api/appointments/:id/complete` **认证**: 需要JWT认证 **描述**: 标记预约为已完成（需要创建者或小组管理员权限） **请求头**: ``` Authorization: Bearer ``` **路径参数**: | 参数 | 类型 | 说明 | |------|------|------| | id | string | 预约ID | **成功响应**: 返回更新后的预约详情 ### 5.10 取消预约 **接口**: `DELETE /api/appointments/:id` **认证**: 需要JWT认证 **描述**: 取消预约（需要创建者或小组管理员权限） **请求头**: ``` Authorization: Bearer ``` **路径参数**: | 参数 | 类型 | 说明 | |------|------|------| | 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)