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

## 1. 需求背景

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

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

## 2. 选定方案

### 方案B-2：task_type类型区分

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

## 3. 数据库设计

### 3.1 Tasks表变更

```sql
-- 添加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）

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

### 6.2 TaskService变更

```java
// 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增加小游戏任务相关接口

```java
// 获取可选择的小游戏列表（创建任务时使用）
@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. 待确认事项

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

---

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