# 后端接口文档

## 基础信息

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

---

## 通用响应格式

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

---

## 1. 认证模块

### 1.1 用户登录

**接口**: `POST /auth/login`

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

**请求体**:
```json
{
    "username": "string",
    "password": "string"
}
```

**响应体**:
```json
{
    "success": true,
    "message": "登录成功",
    "data": {
        "userId": 1,
        "username": "string",
        "email": "string",
        "studyAbility": 1,
        "currentLevel": 1,
        "experience": 0,
        "token": "string"
    }
}
```

**调用示例**:
```csharp
NetworkManager.Instance.PostRequest<LoginResponse>("/auth/login", loginRequest, onSuccess, onError);
```

---

### 1.2 用户注册

**接口**: `POST /auth/register`

**描述**: 用户注册接口

**请求体**:
```json
{
    "username": "string",
    "password": "string",
    "email": "string"
}
```

**响应体**:
```json
{
    "success": true,
    "message": "注册成功",
    "data": {
        "userId": 1,
        "username": "string",
        "email": "string",
        "studyAbility": 1,
        "currentLevel": 1,
        "experience": 0,
        "token": "string"
    }
}
```

**调用示例**:
```csharp
NetworkManager.Instance.PostRequest<RegisterResponse>("/auth/register", registerRequest, onSuccess, onError);
```

---

## 2. 游戏模块

### 2.1 保存游戏会话 (旧版)

**接口**: `POST /game/session`

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

**请求体**:
```json
{
    "playTime": 120.5,
    "progress": 5,
    "difficulty": 1
}
```

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

**调用示例**:
```csharp
NetworkManager.Instance.SaveGameSession(playTime, progress, difficulty, onSuccess, onError);
```

---

### 2.2 保存游戏结果 (新版)

**接口**: `POST /game/result`

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

**请求体**:
```json
{
    "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 | 是 | 收集金币数 |

**响应体**:
```json
{
    "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"
    }
}
```

**调用示例**:
```csharp
NetworkManager.Instance.SaveGameResult(resultRequest, onSuccess, onError);
```

---

### 2.3 获取难度配置

**接口**: `GET /game/difficulty`

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

**响应体**:
```json
{
    "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": "困难难度"
        }
    ]
}
```

**调用示例**:
```csharp
NetworkManager.Instance.GetDifficultyConfig(onSuccess, onError);
```

---

### 2.4 获取题库

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

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

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

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

**调用示例**:
```csharp
NetworkManager.Instance.GetQuestionsByDifficulty(difficulty, onSuccess, onError);
```

---

### 2.5 获取复习题库

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

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

**认证**: 需要Bearer Token

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

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

**调用示例**:
```csharp
NetworkManager.Instance.GetReviewQuestions(difficulty, onSuccess, onError);
```

---

### 2.6 添加题目到复习题库

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

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

**认证**: 需要Bearer Token

**请求体**:
```json
{
    "questionId": 1
}
```

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

**响应体**:
```json
{
    "success": true,
    "message": "添加成功"
}
```

**调用示例**:
```csharp
NetworkManager.Instance.AddQuestionToReview(questionId, onSuccess, onError);
```

---

## 3. 用户模块

### 3.1 更新学习力

**接口**: `PUT /user/study-ability`

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

**认证**: 需要Bearer Token

**请求体**:
```json
{
    "studyAbility": 5
}
```

**响应体**:
```json
{
    "success": true,
    "message": "更新成功",
    "data": {
        "userId": 1,
        "studyAbility": 5,
        "currentLevel": 2,
        "experience": 100
    }
}
```

**调用示例**:
```csharp
NetworkManager.Instance.UpdateStudyAbility(studyAbility, onSuccess, onError);
```

---

### 3.2 更新玩家等级

**接口**: `PUT /user/level`

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

**认证**: 需要Bearer Token

**请求体**:
```json
{
    "currentLevel": 5,
    "experience": 50
}
```

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

**响应体**:
```json
{
    "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 × 当前等级

**调用示例**:
```csharp
NetworkManager.Instance.UpdatePlayerLevel(currentLevel, experience, onSuccess, onError);
```

---

## 4. 成就模块

### 4.1 获取成就数据

**接口**: `GET /achievements`

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

**认证**: 需要Bearer Token

**响应体**:
```json
{
    "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
        }
    ]
}
```

**调用示例**:
```csharp
NetworkManager.Instance.GetAchievements(onSuccess, onError);
```

---

### 4.2 同步成就数据

**接口**: `POST /achievements/sync`

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

**认证**: 需要Bearer Token

**请求体**:
```json
{
    "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 | 是 | 是否已解锁 |

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

**调用示例**:
```csharp
NetworkManager.Instance.SyncAchievements(request, onSuccess, onError);
```

---

## 5. 题目统计模块

### 5.1 上报题目统计

**接口**: `POST /questions/stats`

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

**认证**: 需要Bearer Token

**请求体**:
```json
{
    "questionId": 1,
    "isCorrect": true,
    "difficulty": 1
}
```

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

**响应体**:
```json
{
    "success": true,
    "message": "上报成功",
    "data": {
        "questionId": 1,
        "totalAttempts": 100,
        "correctAttempts": 80,
        "correctRate": 0.8
    }
}
```

**调用示例**:
```csharp
NetworkManager.Instance.ReportQuestionStats(questionId, isCorrect, difficulty, onSuccess, onError);
```

---

## 6. 数据模型定义

### UserData - 用户数据
```csharp
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 - 题目数据
```csharp
public class QuestionData
{
    public int questionId;       // 题目ID
    public string questionText;  // 题目文本
    public int correctAnswer;    // 正确答案
    public int[] wrongAnswers;   // 错误答案列表
    public int difficulty;       // 难度等级
}
```

### AchievementSyncItem - 成就同步项
```csharp
public class AchievementSyncItem
{
    public string achievementId; // 成就ID
    public int currentValue;     // 当前进度值
    public bool isUnlocked;      // 是否已解锁
}
```

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

### GetAchievementsResponse - 获取成就响应
```csharp
public class GetAchievementsResponse
{
    public bool success;             // 是否成功
    public string message;           // 消息
    public AchievementSyncData[] data; // 成就数据列表
}
```

---

## 7. 错误码说明

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

---

## 8. 调用流程

### 登录流程
1. 调用 `POST /auth/login` 获取用户信息和Token
2. 保存Token到 `NetworkManager.SetAuthToken(token)`
3. 保存用户数据到 `LoginManager`

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

### 成就流程
1. 登录后调用 `GET /achievements` 获取成就进度
2. 游戏结束时调用 `POST /achievements/sync` 同步成就

---

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