# API 接口文档

## 基础信息

- **Base URL**: `http://localhost: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"
    }
}
```

---

### 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"
    }
}
```

---

## 2. 游戏模块

### 2.1 保存游戏结果

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

**描述**: 保存完整的游戏结果数据

**认证**: 需要Bearer Token

**请求体**:
```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"
    }
}
```

---

### 2.2 获取难度配置

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

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

**响应体**:
```json
{
    "success": true,
    "message": "获取成功",
    "data": [
        {
            "difficultyLevel": 1,
            "studyAbilityMin": 1,
            "studyAbilityMax": 33,
            "description": "简单难度"
        },
        {
            "difficultyLevel": 2,
            "studyAbilityMin": 34,
            "studyAbilityMax": 66,
            "description": "中等难度"
        },
        {
            "difficultyLevel": 3,
            "studyAbilityMin": 67,
            "studyAbilityMax": 100,
            "description": "困难难度"
        }
    ]
}
```

---

### 2.3 获取题库

**接口**: `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
        }
    ]
}
```

---

## 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
    }
}
```

---

### 3.2 更新玩家等级

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

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

**认证**: 需要Bearer Token

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

**响应体**:
```json
{
    "success": true,
    "message": "更新成功",
    "data": {
        "userId": 1,
        "currentLevel": 5,
        "experience": 50,
        "maxHealth": 14,
        "attackPower": 1
    }
}
```

---

## 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"
        }
    ]
}
```

---

### 4.2 同步成就数据

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

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

**认证**: 需要Bearer Token

**请求体**:
```json
{
    "achievements": [
        {
            "achievementId": "complete_10_rooms",
            "currentValue": 10,
            "isUnlocked": true
        }
    ]
}
```

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

---

## 5. 管理模块

### 5.1 管理员登录

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

**描述**: 管理员登录接口

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

**响应体**:
```json
{
    "success": true,
    "message": "登录成功",
    "data": {
        "token": "string"
    }
}
```

---

### 5.2 获取用户列表

**接口**: `GET /admin/users`

**描述**: 获取所有用户列表

**认证**: 需要管理员Bearer Token

**响应体**:
```json
{
    "success": true,
    "message": "获取成功",
    "data": [
        {
            "userId": 1,
            "username": "player1",
            "email": "player1@example.com",
            "studyAbility": 5,
            "currentLevel": 3,
            "experience": 50,
            "status": "NORMAL",
            "createdAt": "2024-01-01T12:00:00Z"
        }
    ]
}
```

---

### 5.3 题目管理

**接口列表**:
- `GET /admin/questions` - 获取题目列表
- `POST /admin/questions` - 添加题目
- `PUT /admin/questions/{id}` - 更新题目
- `DELETE /admin/questions/{id}` - 删除题目

---

## 6. 健康检查

**接口**: `GET /health`

**描述**: 服务健康检查

**响应体**:
```json
{
    "success": true,
    "message": "服务正常"
}
```

---

## 7. 错误码说明

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