后端接口文档

基础信息

Base URL: http://38.12.23.48:8080/api
Content-Type: application/json
认证方式: Bearer Token (Authorization: Bearer {token})
超时时间: 10秒

通用响应格式

{
    "success": true,
    "message": "操作成功",
    "data": { ... }
}

1. 认证模块

1.1 用户登录

接口: POST /auth/login

描述: 用户登录接口，返回用户信息和认证Token

请求体:

{
    "username": "string",
    "password": "string"
}

响应体:

{
    "success": true,
    "message": "登录成功",
    "data": {
        "userId": 1,
        "username": "string",
        "email": "string",
        "studyAbility": 1,
        "currentLevel": 1,
        "experience": 0,
        "token": "string"
    }
}

调用示例:

NetworkManager.Instance.PostRequest<LoginResponse>("/auth/login", loginRequest, onSuccess, onError);

1.2 用户注册

接口: POST /auth/register

描述: 用户注册接口

请求体:

{
    "username": "string",
    "password": "string",
    "email": "string"
}

响应体:

{
    "success": true,
    "message": "注册成功",
    "data": {
        "userId": 1,
        "username": "string",
        "email": "string",
        "studyAbility": 1,
        "currentLevel": 1,
        "experience": 0,
        "token": "string"
    }
}

调用示例:

NetworkManager.Instance.PostRequest<RegisterResponse>("/auth/register", registerRequest, onSuccess, onError);

2. 游戏模块

2.1 保存游戏会话 (旧版)

接口: POST /game/session

描述: 保存单次游戏会话数据

请求体:

{
    "playTime": 120.5,
    "progress": 5,
    "difficulty": 1
}

响应体:

{
    "success": true,
    "message": "保存成功",
    "data": {
        "userId": 1,
        "playTime": 120.5,
        "progress": 5,
        "difficulty": 1,
        "sessionDate": "2024-01-01T12:00:00Z"
    }
}

调用示例:

NetworkManager.Instance.SaveGameSession(playTime, progress, difficulty, onSuccess, onError);

2.2 保存游戏结果 (新版)

接口: POST /game/result

描述: 保存完整的游戏结果数据，包含通关时长、房间数、答题统计等

请求体:

{
    "playTime": 180.5,
    "roomsCompleted": 10,
    "correctAnswers": 15,
    "wrongAnswers": 3,
    "difficulty": 2,
    "isCompleted": true,
    "goldCollected": 150
}

参数	类型	必填	说明
playTime	float	是	游戏时长(秒)
roomsCompleted	int	是	完成房间数
correctAnswers	int	是	正确答题数
wrongAnswers	int	是	错误答题数
difficulty	int	是	游戏难度等级
isCompleted	bool	是	是否通关
goldCollected	int	是	收集金币数

响应体:

{
    "success": true,
    "message": "保存成功",
    "data": {
        "userId": 1,
        "playTime": 180.5,
        "roomsCompleted": 10,
        "correctAnswers": 15,
        "wrongAnswers": 3,
        "difficulty": 2,
        "isCompleted": true,
        "goldCollected": 150,
        "createdAt": "2024-01-01T12:00:00Z"
    }
}

调用示例:

NetworkManager.Instance.SaveGameResult(resultRequest, onSuccess, onError);

2.3 获取难度配置

接口: GET /game/difficulty

描述: 获取难度等级配置信息

响应体:

{
    "success": true,
    "message": "获取成功",
    "data": [
        {
            "difficultyLevel": 1,
            "studyAbilityMin": 1,
            "studyAbilityMax": 3,
            "description": "简单难度"
        },
        {
            "difficultyLevel": 2,
            "studyAbilityMin": 4,
            "studyAbilityMax": 6,
            "description": "中等难度"
        },
        {
            "difficultyLevel": 3,
            "studyAbilityMin": 7,
            "studyAbilityMax": 10,
            "description": "困难难度"
        }
    ]
}

调用示例:

NetworkManager.Instance.GetDifficultyConfig(onSuccess, onError);

2.4 获取题库

接口: GET /game/questions?difficulty={difficulty}

描述: 根据难度获取题目列表

查询参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | difficulty | int | 是 | 难度等级 |

响应体:

{
    "success": true,
    "message": "获取成功",
    "data": [
        {
            "questionId": 1,
            "questionText": "1 + 1 = ?",
            "correctAnswer": 2,
            "wrongAnswers": [1, 3, 4],
            "difficulty": 1
        }
    ]
}

调用示例:

NetworkManager.Instance.GetQuestionsByDifficulty(difficulty, onSuccess, onError);

2.5 获取复习题库

接口: GET /game/review-questions?difficulty={difficulty}

描述: 根据难度获取复习题目列表，用于复习模式

认证: 需要Bearer Token

查询参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | difficulty | int | 是 | 难度等级 |

响应体:

{
    "success": true,
    "message": "获取成功",
    "data": [
        {
            "questionId": 1,
            "questionText": "1 + 1 = ?",
            "correctAnswer": 2,
            "wrongAnswers": [1, 3, 4],
            "difficulty": 1
        }
    ]
}

调用示例:

NetworkManager.Instance.GetReviewQuestions(difficulty, onSuccess, onError);

2.6 添加题目到复习题库

接口: POST /game/review-questions/add

描述: 将普通模式中做过的题目添加到用户的复习题库

认证: 需要Bearer Token

请求体:

{
    "questionId": 1
}

参数	类型	必填	说明
questionId	int	是	题目ID

响应体:

{
    "success": true,
    "message": "添加成功"
}

调用示例:

NetworkManager.Instance.AddQuestionToReview(questionId, onSuccess, onError);

3. 用户模块

3.1 更新学习力

接口: PUT /user/study-ability

描述: 更新玩家学习力等级

认证: 需要Bearer Token

请求体:

{
    "studyAbility": 5
}

响应体:

{
    "success": true,
    "message": "更新成功",
    "data": {
        "userId": 1,
        "studyAbility": 5,
        "currentLevel": 2,
        "experience": 100
    }
}

调用示例:

NetworkManager.Instance.UpdateStudyAbility(studyAbility, onSuccess, onError);

3.2 更新玩家等级

接口: PUT /user/level

描述: 更新玩家等级和经验值

认证: 需要Bearer Token

请求体:

{
    "currentLevel": 5,
    "experience": 50
}

参数	类型	必填	说明
currentLevel	int	是	当前等级(1-30)
experience	int	是	当前经验值

响应体:

{
    "success": true,
    "message": "更新成功",
    "data": {
        "userId": 1,
        "currentLevel": 5,
        "experience": 50,
        "maxHealth": 14,
        "attackPower": 1
    }
}

等级系统说明:

等级上限: 30级
每升1级: 最大血量 +1
每10级: 攻击力 +1 (即10级攻击力2，20级攻击力3，30级攻击力4)
升级所需经验: 100 × 当前等级

调用示例:

NetworkManager.Instance.UpdatePlayerLevel(currentLevel, experience, onSuccess, onError);

4. 成就模块

4.1 获取成就数据

接口: GET /achievements

描述: 获取当前用户的所有成就进度

认证: 需要Bearer Token

响应体:

{
    "success": true,
    "message": "获取成功",
    "data": [
        {
            "achievementId": "complete_10_rooms",
            "currentValue": 10,
            "isUnlocked": true,
            "unlockedAt": "2024-01-01T12:00:00Z"
        },
        {
            "achievementId": "collect_100_gold",
            "currentValue": 50,
            "isUnlocked": false,
            "unlockedAt": null
        }
    ]
}

调用示例:

NetworkManager.Instance.GetAchievements(onSuccess, onError);

4.2 同步成就数据

接口: POST /achievements/sync

描述: 同步玩家成就进度到服务器

认证: 需要Bearer Token

请求体:

{
    "achievements": [
        {
            "achievementId": "complete_10_rooms",
            "currentValue": 10,
            "isUnlocked": true
        },
        {
            "achievementId": "collect_100_gold",
            "currentValue": 50,
            "isUnlocked": false
        }
    ]
}

参数	类型	必填	说明
achievements	array	是	成就列表
achievements[].achievementId	string	是	成就ID
achievements[].currentValue	int	是	当前进度值
achievements[].isUnlocked	bool	是	是否已解锁

响应体:

{
    "success": true,
    "message": "同步成功",
    "data": [
        {
            "achievementId": "complete_10_rooms",
            "currentValue": 10,
            "isUnlocked": true,
            "unlockedAt": "2024-01-01T12:00:00Z"
        }
    ]
}

调用示例:

NetworkManager.Instance.SyncAchievements(request, onSuccess, onError);

5. 题目统计模块

5.1 上报题目统计

接口: POST /questions/stats

描述: 上报单道题目的答题情况

认证: 需要Bearer Token

请求体:

{
    "questionId": 1,
    "isCorrect": true,
    "difficulty": 1
}

参数	类型	必填	说明
questionId	int	是	题目ID
isCorrect	bool	是	是否答对
difficulty	int	是	题目难度

响应体:

{
    "success": true,
    "message": "上报成功",
    "data": {
        "questionId": 1,
        "totalAttempts": 100,
        "correctAttempts": 80,
        "correctRate": 0.8
    }
}

调用示例:

NetworkManager.Instance.ReportQuestionStats(questionId, isCorrect, difficulty, onSuccess, onError);

6. 数据模型定义

UserData - 用户数据

public class UserData
{
    public int userId;           // 用户ID
    public string username;      // 用户名
    public string email;         // 邮箱
    public int studyAbility;     // 学习力
    public int currentLevel;     // 当前等级
    public int experience;       // 经验值
    public string token;         // 认证Token
}

QuestionData - 题目数据

public class QuestionData
{
    public int questionId;       // 题目ID
    public string questionText;  // 题目文本
    public int correctAnswer;    // 正确答案
    public int[] wrongAnswers;   // 错误答案列表
    public int difficulty;       // 难度等级
}

AchievementSyncItem - 成就同步项

public class AchievementSyncItem
{
    public string achievementId; // 成就ID
    public int currentValue;     // 当前进度值
    public bool isUnlocked;      // 是否已解锁
}

AchievementSyncData - 成就数据

public class AchievementSyncData
{
    public string achievementId; // 成就ID
    public int currentValue;     // 当前进度值
    public bool isUnlocked;      // 是否已解锁
    public string unlockedAt;    // 解锁时间(ISO 8601格式)
}

GetAchievementsResponse - 获取成就响应

public class GetAchievementsResponse
{
    public bool success;             // 是否成功
    public string message;           // 消息
    public AchievementSyncData[] data; // 成就数据列表
}

7. 错误码说明

错误码	说明
200	成功
400	请求参数错误
401	未授权/Token无效
403	禁止访问
404	资源不存在
500	服务器内部错误

8. 调用流程

登录流程

调用 POST /auth/login 获取用户信息和Token
保存Token到 NetworkManager.SetAuthToken(token)
保存用户数据到 LoginManager

游戏流程

游戏开始时调用 GET /game/difficulty 获取难度配置
根据 studyAbility 选择合适难度
调用 GET /game/questions?difficulty={n} 获取题库
游戏结束时调用 POST /game/result 保存结果
调用 PUT /user/study-ability 更新学习力
调用 PUT /user/level 同步等级和经验
调用 POST /achievements/sync 同步成就

成就流程

登录后调用 GET /achievements 获取成就进度
游戏结束时调用 POST /achievements/sync 同步成就

文档生成时间: 2026年 版本: 1.3

API_Documentation.md 13 KB Pysyvä linkki Historia Raaka

后端接口文档

基础信息

通用响应格式

1. 认证模块

1.1 用户登录

1.2 用户注册

2. 游戏模块

2.1 保存游戏会话 (旧版)

2.2 保存游戏结果 (新版)

2.3 获取难度配置

2.4 获取题库

2.5 获取复习题库

2.6 添加题目到复习题库

3. 用户模块

3.1 更新学习力

3.2 更新玩家等级

4. 成就模块

4.1 获取成就数据

4.2 同步成就数据

5. 题目统计模块

5.1 上报题目统计

6. 数据模型定义

UserData - 用户数据

QuestionData - 题目数据

AchievementSyncItem - 成就同步项

AchievementSyncData - 成就数据

GetAchievementsResponse - 获取成就响应

7. 错误码说明

8. 调用流程

登录流程

游戏流程

成就流程

API_Documentation.md 13 KB

Pysyvä linkki Historia Raaka