cfc/docs/plans/2026-04-17-minigame-as-task-type-design.md

在线小游戏作为任务类型的设计方案

1. 需求背景

当前项目中：

• MiniGame系统：独立的小游戏模块（舒尔特方格、猜数字1a2b、数独），通过MiniGameController/MiniGameService管理，完成时调用积分计算
• Task系统：独立的任务模块，通过TaskController/TaskService管理，任务完成时计算积分
• 共同点：都使用PointsLog记录积分变动，更新孩子的totalPoints

需求：将在线小游戏作为任务分类的一种形式（"小游戏类"），统一到任务系统中管理

2. 选定方案

方案B-2：task_type类型区分

设计点	选择
字段添加	新增minigameCode字段
category值	小游戏类
积分计算	使用MiniGame规则（现有MiniGameService逻辑）

3. 数据库设计

3.1 Tasks表变更

-- 添加minigameCode字段
ALTER TABLE tasks ADD COLUMN minigame_code VARCHAR(50) DEFAULT NULL COMMENT '小游戏代码: schulte/1a2b/sudoku';

-- 添加索引
CREATE INDEX idx_tasks_minigame ON tasks(minigame_code) WHERE minigame_code IS NOT NULL;

3.2 字段说明

字段	类型	说明
category	String	'小游戏类'
minigameCode	String	小游戏代码，category='小游戏类'时必填
points	Integer	基准积分，为空时使用MiniGame.defaultPoints
status	String	pending/completed/canceled
completedAt	Date	完成时间

4. API设计

4.1 创建小游戏任务

POST /api/tasks
{
  "title": "完成舒尔特方格",
  "category": "小游戏类",
  "minigameCode": "schulte",
  "childId": 2,
  "deadline": "2026-04-20T18:00:00",
  "points": 5,  // 可选，为空时使用MiniGame.defaultPoints
  "needReview": 0
}

4.2 获取小游戏列表（创建任务时选择）

POST /api/mini-game/list

4.3 完成小游戏任务

POST /api/tasks/{id}/complete
{
  "childId": 2,
  "completionTime": 45,  // 完成时间（秒）
  "score": 80  // 得分，可选
}

5. 业务流程

5.1 创建流程

家长选择"小游戏类" ↓
可选小游戏列表（舒尔特方格/猜数字/数独） ↓
选择具体小游戏 ↓
设置任务名称、截止时间 ↓
保存任务（category='小游戏类'，minigameCode='schulte'）

5.2 完成流程

孩子完成任务 ↓
校验任务存在且属于该孩子 ↓
判断category='小游戏类' ↓
调用MiniGameService.completeGame()计算积分 ↓
更新任务状态为completed ↓
记录PointsLog（类型: earn） ↓
更新孩子总积分

6. 核心代码变更

6.1 Task实体（Task.java）

// 新增字段
private String minigameCode;  // 小游戏代码: schulte/1a2b/sudoku

6.2 TaskService变更

// createTask方法中增加校验
if ("小游戏类".equals(category) && minigameCode == null) {
    throw new BusinessException("小游戏类任务必须选择具体游戏");
}

// completeTask方法中小游戏任务处理
if ("小游戏类".equals(task.getCategory())) {
    // 调用MiniGameService计算积分
    Map<String, Object> result = miniGameService.completeGame(
        childId, 
        task.getMinigameCode(), 
        completionTime, 
        score
    );
    pointsEarned = (Integer) result.get("pointsEarned");
}

6.3 TaskController增加小游戏任务相关接口

// 获取可选择的小游戏列表（创建任务时使用）
@PostMapping("/minigame-options")
public Result<List<MiniGame>> getMinigameOptions()

7. 前端变更

7.1 创建任务页面

• category选择器增加"小游戏类"选项
• 选择"小游戏类"后，弹出小游戏选择列表
• 选择具体游戏后自动填充任务名称

7.2 小游戏页面

• 任务列表中的小游戏任务，点击进入小游戏页面
• 完成小游戏后自动调用任务完成接口

8. 测试用例

用例ID	描述	预期结果
MINITASK-001	家长创建小游戏任务	任务创建成功，category='小游戏类'
MINITASK-002	孩子完成小游戏任务	积分按MiniGame规则计算
MINITASK-003	小游戏任务记录到任务历史	历史中可查询
MINITASK-004	积分记录到PointsLog	积分流水正确

9. 实施计划

序号	任务	预估工作量
1	数据库迁移脚本	0.5h
2	Task实体添加字段	0.5h
3	TaskService逻辑变更	2h
4	TaskController API变更	1h
5	前端创建任务页面	2h
6	前端任务列表/详情页	1h
7	测试验证	1h

总计: 约8小时

10. 待确认事项

• 方案选择
• 字段添加方式
• category值确定
• 积分计算方式
• 启动实施？

---

设计日期: 2026-04-17 设计人: Sisyphus 状态: 待用户确认后启动实施