congsh/gamegroup_fe
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8a43cc00959316da1bdfffe736a94d6d881216e0
gamegroup_fe/doc/api/API文档.md

1858 lines
35 KiB
Markdown
Raw Normal View History

feat: 初始化项目脚手架
2026-01-28 14:35:43 +08:00
# 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)
Reference in New Issue Copy Permalink