# 用户使用流程图 — 小游戏 > **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动 > > **分层说明**: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体 ```mermaid 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}]` | ## 数据实体关系 ```mermaid 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流程一致 |