cfc/docs/flows/minigame-flow.md

用户使用流程图 — 小游戏

端口说明: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动

分层说明: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体

flowchart TD
    %% ============ 颜色定义 ============
    classDef page fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef api fill:#fff3e0,stroke:#f57c00,stroke-width:1px
    classDef service fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
    classDef data fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
    classDef external fill:#fce4ec,stroke:#d32f2f,stroke-width:1px,stroke-dasharray:3 2
    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,stroke-dasharray:5 3

    %% ============ 角色 ============
    A0(("👶 孩子")):::actor
    B0(("🖥 管理员")):::actor

    %% ================================================================
    %% 阶段一：游戏浏览与选择
    %% ================================================================
    subgraph 阶段一[阶段一：游戏浏览与选择]
        direction TB

        P1["🏠 小程序：游戏列表页"]:::page
        P1 -->|"进入页面"| A1["🔗 POST /api/mini-game/list"]:::api
        A1 -->|"无参数"| S1["⚙️ MiniGameService.getEnabledGames()"]:::service
        S1 -->|"启用的游戏列表"| D1["📦 mini_games 表（status=1）"]:::data

        D1 -->|"返回游戏列表"| P2["🏠 选择游戏"]:::page
        P2 -->|"点击游戏"| P2a["🏠 游戏详情页"]:::page
        P2a -->|"gameCode"| A2["🔗 POST /api/mini-game/{gameCode}"]:::api
        A2 -->|"gameCode"| S2["⚙️ MiniGameService.getGameByCode()"]:::service
        S2 -->|"单个游戏信息"| D1
    end

    %% ================================================================
    %% 阶段二：游戏执行
    %% ================================================================
    subgraph 阶段二[阶段二：游戏执行]
        D1 -->|"选中的游戏"| G1{"游戏类型"}:::page

        G1 -->|"舒尔特方格 / 猜数字 / 数独"| G2["🏠 标准游戏页"]:::page
        G2 -->|"完成: childId, gameCode, completionTime, score"| A3["🔗 POST /api/mini-game/complete"]:::api
        A3 -->|"childId, gameCode, 用时, 得分"| S3["⚙️ MiniGameService.completeGame()"]:::service
        S3 -->|"计算积分"| S3a["⚙️ MiniGameService.calculatePoints()"]:::service
        S3a -->|"更新余额"| D_FAM["📦 family_members 表（totalPoints）"]:::data
        S3a -->|"积分流水"| D_PT["📦 points_log 表"]:::data
        S3a -->|"持久化记录"| S3b["⚙️ GameRecordService.saveRecord()"]:::service
        S3b -->|"写入游戏记录"| D_GR["📦 game_records 表"]:::data

        G1 -->|"智慧数学"| G3["🏠 智慧数学页"]:::page
        G3 -->|"开始: childId, age"| A4["🔗 POST /api/wisdom/math/start"]:::api
        A4 -->|"childId, age"| S4["⚙️ WisdomMathService.startSession()"]:::service
        S4 -->|"计算推荐题目"| D_MCL["📦 math_child_level 表（查询/创建）"]:::data
        S4 -->|"题目列表, 关卡信息"| G3

        G3 -->|"验证: expression, userAnswer"| A5["🔗 POST /api/wisdom/math/verify"]:::api
        A5 -->|"表达式, 用户答案"| S5["⚙️ WisdomMathService.verifyAnswer()"]:::service
        S5 -->|"正确/错误, 解析"| D_MATH["📦 MathQuizLog（写入）"]:::data

        G3 -->|"完成: level, correctCount, totalAttempts, totalTimeMs"| A6["🔗 POST /api/wisdom/math/complete"]:::api
        A6 -->|"关卡, 正确数, 总尝试, 总耗时"| S6["⚙️ WisdomMathService.completeSession()"]:::service
        S6 -->|"更新等级进度"| D_MCL
    end

    %% ================================================================
    %% 阶段三：游戏记录与统计
    %% ================================================================
    subgraph 阶段三[阶段三：游戏记录与统计]
        D_GR -->|"数据已保存"| P3["🏠 游戏记录页"]:::page
        P3 -->|"查看历史"| A7["🔗 POST /api/game/history"]:::api
        A7 -->|"childId, gameCode, page, size"| S7["⚙️ GameRecordService.getHistory()"]:::service
        S7 -->|"分页历史记录"| D_GR

        P3 -->|"查看最佳"| A8["🔗 POST /api/game/best"]:::api
        A8 -->|"childId"| S8["⚙️ GameRecordService.getBestScores()"]:::service
        S8 -->|"各游戏最佳成绩"| D_GR

        P3 -->|"查看统计"| A9["🔗 POST /api/game/stats"]:::api
        A9 -->|"childId"| S9["⚙️ GameRecordService.getStats()"]:::service
        S9 -->|"总次数, 总积分, 连续天数"| D_GR

        P3 -->|"查看排行榜"| A10["🔗 POST /api/game/leaderboard"]:::api
        A10 -->|"gameCode, limit"| S10["⚙️ GameRecordService.getLeaderboard()"]:::service
        S10 -->|"排名列表"| D_GR
    end

    %% ================================================================
    %% 阶段四：管理端维护
    %% ================================================================
    subgraph 阶段四[阶段四：管理端维护]
        P4["🏠 管理后台：游戏管理页"]:::page
        P4 -->|"加载所有游戏"| A11["🔗 POST /api/mini-game/all"]:::api
        A11 -->|"无参数"| S11["⚙️ MiniGameService.getAllGames()"]:::service
        S11 -->|"全部游戏列表（含禁用）"| D1

        P4 -->|"启用/禁用游戏"| P4a["🏠 确认状态变更"]:::page
        P4a -->|"id, status"| A12["🔗 POST /api/mini-game/{id}/status"]:::api
        A12 -->|"游戏ID, 目标状态"| S12["⚙️ MiniGameService.updateGameStatus()"]:::service
        S12 -->|"更新状态字段"| D1
    end

    %% ================================================================
    %% 角色关联
    %% ================================================================
    A0 -.- P1
    A0 -.- P2
    A0 -.- G2
    A0 -.- G3
    A0 -.- P3
    B0 -.- P4

端点明细

标准小游戏

端点	说明	端口	请求数据	响应数据
POST /api/mini-game/list	获取启用的游戏列表	📱小程序	—	MiniGame[]（游戏编码, 名称, 图标, 排序）
POST /api/mini-game/{gameCode}	获取游戏详情	📱小程序	path: gameCode	MiniGame
POST /api/mini-game/complete	完成任务并发放积分	📱小程序	{childId, gameCode, completionTime, score}	{pointsEarned, newBalance, gameName}
POST /api/mini-game/all	获取全部游戏（管理端）	🖥管理后台	—	MiniGame[]（含禁用状态）
POST /api/mini-game/{id}/status	更新游戏启用状态	🖥管理后台	path: id, param: status	boolean

智慧数学

端点	说明	端口	请求数据	响应数据
POST /api/wisdom/math/start	开始智慧数学新会话	📱小程序	{childId, age}	{level, levelName, questions[], sessionId}
POST /api/wisdom/math/verify	验证单题答案	📱小程序	{childId, expression, userAnswer}	{correct, correctAnswer, explanation}
POST /api/wisdom/math/complete	完成智慧数学关卡	📱小程序	{childId, level, targetN, correctCount, totalAttempts, totalTimeMs, expressions}	{levelUp, newLevel, stats}

游戏记录

端点	说明	端口	请求数据	响应数据
POST /api/game/record	保存游戏记录	📱小程序	{childId, gameCode, score, completionTime, difficulty, pointsEarned}	{saved}
POST /api/game/history	获取游戏历史	📱小程序	{childId, gameCode, page, size}	{records[], total, page, size}
POST /api/game/best	获取最佳成绩	📱小程序	{childId}	[{gameCode, bestScore, bestTime, playCount}]
POST /api/game/stats	获取统计概览	📱小程序	{childId}	{totalGames, totalPoints, streakDays, byGame[]}
POST /api/game/leaderboard	获取排行榜	📱小程序	{gameCode, limit}	[{rank, childName, score, completionTime}]

数据实体关系

erDiagram
    MiniGame ||--o{ GameRecord : "一个游戏多个记录"
    FamilyMember ||--o{ GameRecord : "一个孩子多个记录"
    FamilyMember ||--o{ PointsLog : "积分流水"
    MathChildLevel ||--o{ MathQuizLog : "一个关卡多次答题"

    MiniGame {
        Long id PK
        string gameCode "schulte / 1a2b / sudoku"
        string gameName
        string description
        string icon
        int defaultDuration
        int defaultPoints
        int sortOrder
        int status "0禁用 1启用"
    }

    GameRecord {
        Long id PK
        Long childId FK
        string gameCode
        int score
        int completionTime
        string difficulty
        int pointsEarned
    }

    MathChildLevel {
        Long id PK
        Long childId FK
        int level "1-4"
        int correctStreak
    }

    MathQuizLog {
        Long id PK
        Long childId FK
        string expression
        string userAnswer
        bool correct
    }

完整性分析

#	维度	评估	说明
1	流程完整性	✅ 完整	覆盖游戏浏览→执行（3种标准游戏+智慧数学）→记录统计→管理维护4个阶段，路径完整
2	异常路径	⚠️ 部分覆盖	游戏不存在/孩子不存在等业务异常在Service层throw RuntimeException，由全局异常处理器捕获；游戏中答错题继续、完成时积分保底逻辑已覆盖
3	端点覆盖	✅ 完整	13个端点全部映射到流程图中，与MiniGameController、WisdomMathController、GameRecordController实际代码一致
4	角色覆盖	✅ 完整	孩子（玩游戏、查看记录）和管理员（管理端启停游戏）两种角色已覆盖；智慧数学无独立管理入口
5	数据实体	✅ 完整	mini_games、game_records、family_members（积分）、points_log、math_child_level、math_quiz_log 6个实体均在图中映射
6	一致性	✅ 与代码一致	所有端点路径与实际Controller中的@PostMapping匹配；积分计算逻辑（calculatePoints中的保底/加成规则）与completeGame流程一致