# 专注训练模块需求分析

**版本**: V1.2
**更新时间**: 2026-04-15

---

## 一、需求清单概览

| 需求ID | 描述 | 优先级 | 状态 |
|--------|------|--------|------|
| FOCUS-001 | 舒尔特方格游戏 | P1 | ✅ 已实现 |
| FOCUS-002 | 1a2b猜数字游戏 | P1 | ✅ 已实现 |
| FOCUS-003 | 数独游戏 | P1 | ✅ 已实现 |
| FOCUS-004 | 专注力训练记录 | P1 | ⚠️ 部分实现 |
| FOCUS-005 | 训练数据分析 | P1 | ❌ 未实现 |
| FOCUS-006 | 训练成果展示 | P1 | ❌ 未实现 |
| FOCUS-007 | 训练提醒与激励 | P1 | ❌ 未实现 |
| FOCUS-008 | 训练积分奖励 | P1 | ⚠️ 部分实现 |

---

## 二、需求详细描述

### 2.1 舒尔特方格游戏（FOCUS-001）

#### FOCUS-001: 舒尔特方格游戏
- **描述**：经典的专注力训练游戏，玩家按顺序点击1-25的数字正方形
- **游戏规则**：
  - 5x5 网格，随机分布 1-25 数字
  - 按顺序点击，速度越快分数越高
  - 可选难度：简单(3x3)/中等(4x4)/困难(5x5)
- **现有字段**（基于 `MiniGame` 实体）：
  - `gameCode`：schulte
  - `gameName`：舒尔特方格
  - `defaultDuration`：默认时长
  - `defaultPoints`：默认积分
- **状态**：✅ 已实现

---

### 2.2 1a2b猜数字游戏（FOCUS-002）

#### FOCUS-002: 1a2b猜数字游戏
- **描述**：猜测指定位数的数字，A表示位置和数字都正确，B表示数字正确但位置错误
- **游戏规则**：
  - 4位不重复数字
  - 输入猜测后返回 "xAyB" 格式结果
  - 可选难度：3位数/4位数/5位数
- **现有字段**：
  - `gameCode`：1a2b
  - `gameName`：猜数字
  - `defaultDuration`：默认时长
  - `defaultPoints`：默认积分
- **状态**：✅ 已实现

---

### 2.3 数独游戏（FOCUS-003）

#### FOCUS-003: 数独游戏
- **描述**：经典数独填充游戏，每行每列每个3x3宫格填入1-9不重复数字
- **游戏规则**：
  - 9x9 宫格，部分数字预先填充
  - 玩家填充剩余空格
  - 可选难度：简单/中等/困难
- **现有字段**：
  - `gameCode`：sudoku
  - `gameName`：数独
  - `defaultDuration`：默认时长
  - `defaultPoints`：默认积分
- **状态**：✅ 已实现

---

### 2.4 专注力训练记录（FOCUS-004）

#### FOCUS-004: 专注力训练记录
- **描述**：记录每次训练的详细数据，包括时长、得分、排名等
- **记录字段**：
  - `childId`：训练的孩子
  - `gameCode`：游戏类型
  - `score`：得分
  - `duration`：用时（秒）
  - `level`：难度等级
  - `rank`：本次排名
  - `completedAt`：完成时间
- **存储方式**：可复用 `MediaRecord` 或新建 `GameRecord` 表
- **状态**：⚠️ 部分实现（现有后端记录得分和用时）

---

### 2.5 训练数据分析（FOCUS-005）

#### FOCUS-005: 训练数据分析
- **描述**：对训练记录进行数据分析，生成专注力报告
- **分析维度**：
  - 各游戏平均得分
  - 各游戏最佳成绩
  - 训练频率统计
  - 能力趋势分析
- **展示形式**：数据卡片 + 趋势图表

---

### 2.6 训练成果展示（FOCUS-006）

#### FOCUS-006: 训练成果展示
- **描述**：在个人主页或专门页面展示训练成果
- **展示内容**：
  - 累计训练次数
  - 获得积分总数
  - 最佳成绩榜单
  - 连续训练天数
- **展示位置**：
  - 个人主页训练入口
  - 专门的训练成果页面
  - 勋章墙（可关联）

---

### 2.7 训练提醒与激励（FOCUS-007）

#### FOCUS-007: 训练提醒与激励
- **描述**：通过系统消息或激励机制鼓励孩子坚持训练
- **提醒功能**：
  - 每日训练提醒
  - 连续训练激励
  - 里程碑达成庆祝
- **激励机制**：
  - 连续训练徽章
  - 积分加成
  - 排行榜激励

---

### 2.8 训练积分奖励（FOCUS-008）

#### FOCUS-008: 训练积分奖励
- **描述**：完成游戏后获得积分奖励，积分可累积使用
- **奖励规则**：
  - 基础积分：游戏默认积分
  - 表现加成：根据用时/正确率增加积分
  -连胜加成：连续完成游戏获得额外积分
- **积分用途**：
  - 可用于心愿兑换
  - 可与任务积分合并统计
- **状态**：⚠️ 部分实现（现有小游戏积分已接入）

---

## 三、现有小游戏数据模型

### 3.1 MiniGame 小游戏定义实体

```java
// 现有字段
private Long id;
private String gameCode;          // 游戏代码: schulte, 1a2b, sudoku
private String gameName;          // 游戏名称
private String description;       // 游戏描述
private String icon;              // 图标emoji
private Integer defaultDuration; // 默认时长(分钟)
private Integer defaultPoints;   // 默认奖励积分
private String gameUrl;           // 游戏H5页面URL
private Integer sortOrder;       // 排序
private Integer status;          // 状态: 0禁用 1启用
private Date createdAt;
private Date updatedAt;
```

### 3.2 游戏记录实体（建议新增）

```java
private Long id;
private Long childId;           // 孩子ID
private String gameCode;        // 游戏代码
private Integer score;           // 得分
private Integer duration;       // 用时（秒）
private String level;            // 难度：easy/medium/hard
private Integer rank;            // 本次排名
private Integer pointsEarned;    // 获得积分
private Date completedAt;        // 完成时间
private String deviceInfo;       // 设备信息
private Date createdAt;
```

---

## 四、API接口设计

### 4.1 游戏管理

| 方法 | 路径 | 功能 | 权限 |
|------|------|------|------|
| GET | /api/games | 获取游戏列表 | 公开 |
| GET | /api/games/{code} | 获取游戏详情 | 公开 |
| POST | /api/games | 创建游戏定义 | 管理员 |
| PUT | /api/games/{code} | 更新游戏配置 | 管理员 |

### 4.2 游戏记录

| 方法 | 路径 | 功能 | 权限 |
|------|------|------|------|
| POST | /api/games/record | 记录游戏成绩 | 孩子 |
| GET | /api/games/records/{childId} | 游戏记录列表 | 孩子/家长 |
| GET | /api/games/best/{childId}/{gameCode} | 最佳成绩 | 孩子/家长 |
| GET | /api/games/statistics/{childId} | 训练统计 | 孩子/家长 |

### 4.3 排行榜

| 方法 | 路径 | 功能 | 权限 |
|------|------|------|------|
| GET | /api/games/ranking/{gameCode} | 全服排行榜 | 公开 |
| GET | /api/games/ranking/family/{familyId} | 家庭排行榜 | 家长 |

---

## 五、前端页面设计

| 页面 | 路径 | 功能 |
|------|------|------|
| 游戏列表 | `/pages/games/index` | 展示可玩游戏 |
| 舒尔特方格 | `/pages/games/schulte` | 舒尔特方格游戏 |
| 猜数字 | `/pages/games/1a2b` | 1a2b猜数字游戏 |
| 数独 | `/pages/games/sudoku` | 数独游戏 |
| 训练记录 | `/pages/games/records` | 历史训练记录 |
| 训练统计 | `/pages/games/statistics` | 训练数据分析 |
| 排行榜 | `/pages/games/ranking` | 排行榜展示 |

---

## 六、待完善事项

| 功能 | 优先级 | 说明 |
|------|--------|------|
| 游戏记录存储 | P1 | 新增 game_record 表 |
| 训练数据分析 | P1 | 统计 API |
| 训练成果展示 | P1 | 前端页面 |
| 训练提醒 | P2 | 定时任务 |
| 激励机制 | P2 | 徽章/积分加成 |
| 排行榜功能 | P1 | 排行榜 API |
| 数据导出 | P2 | 训练报告导出 |

---

## 七、数据库设计建议

### 7.1 游戏记录表

```sql
CREATE TABLE game_record (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    child_id BIGINT NOT NULL,
    game_code VARCHAR(20) NOT NULL,
    score INT NOT NULL,
    duration INT NOT NULL COMMENT '用时（秒）',
    level VARCHAR(10) DEFAULT 'medium',
    rank INT DEFAULT 0,
    points_earned INT DEFAULT 0,
    completed_at DATETIME,
    device_info VARCHAR(255),
    created_at DATETIME,
    INDEX idx_child (child_id),
    INDEX idx_game (game_code),
    INDEX idx_completed (completed_at)
);
```

### 7.2 排行榜缓存表（可选）

```sql
CREATE TABLE game_ranking (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    game_code VARCHAR(20) NOT NULL,
    child_id BIGINT NOT NULL,
    best_score INT DEFAULT 0,
    best_duration INT DEFAULT 0,
    total_games INT DEFAULT 0,
    total_points INT DEFAULT 0,
    ranking INT DEFAULT 0,
    updated_at DATETIME,
    UNIQUE KEY uk_game_child (game_code, child_id)
);
```

---

## 八、现有代码参考

### 8.1 实体类位置
`zxyj-backend/src/main/java/com/zxyj/entity/MiniGame.java`

### 8.2 现有三款游戏
| 游戏 | gameCode | 状态 |
|------|----------|------|
| 舒尔特方格 | schulte | ✅ 已实现 |
| 猜数字 | 1a2b | ✅ 已实现 |
| 数独 | sudoku | ✅ 已实现 |

### 8.3 前端页面
- `zxyj-frontend/pages/games/` 目录下已有对应页面

### 8.4 待补充
- 游戏记录存储（需新增表）
- 排行榜逻辑（需完善）
- 训练数据分析（需开发）

---

## 九、后续开发建议

### 9.1 第一阶段：完善记录
1. 新增 game_record 表
2. 完善游戏记录 API
3. 训练记录页面

### 9.2 第二阶段：数据分析
1. 训练统计 API
2. 最佳成绩展示
3. 训练趋势图表

### 9.3 第三阶段：激励与社交
1. 排行榜功能
2. 训练提醒定时任务
3. 连续训练激励机制
4. 与勋章系统关联