cfc/docs/backup/root/focus-requirements.md

专注训练模块需求分析

版本: 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 小游戏定义实体

// 现有字段
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 游戏记录实体（建议新增）

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 游戏记录表

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 排行榜缓存表（可选）

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 实体类位置

cfc-backend/src/main/java/com/etotem/cfc/entity/MiniGame.java

8.2 现有三款游戏

游戏	gameCode	状态
舒尔特方格	schulte	✅ 已实现
猜数字	1a2b	✅ 已实现
数独	sudoku	✅ 已实现

8.3 前端页面

• cfc-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. 与勋章系统关联