200 lines
14 KiB
Markdown
200 lines
14 KiB
Markdown
# 三十六计小课堂
|
||
|
||
一款面向低龄儿童（4-8 岁）的闯关式学习《三十六计》应用。不教历史故事，而是把每一条计策翻译成**现代生活场景**，让孩子在校园、家庭、公园等熟悉的情境中学会"遇到问题怎么想、怎么做"。
|
||
|
||
## 功能特性
|
||
|
||
- **分支情境闯关**：36 计 × 每计 1-3 个现代情境，每个情境是一棵决策树——环境场景、人物、道具构成每个决策的要素，不同选择走向不同分支、产生不同结果，多条路线都能拿到最佳结果；每步即时反馈"智慧点评"，**每个选择都解释好处/坏处（对比点评）**，结算页展示整局选择路线回顾；**通关 = 到达最佳终局，完美 = 走完所有分支，完美才解锁下一关**；未通关走错路线扣教训分
|
||
- **多样互动**：闯关不止选项点击——道具选择、步骤排序、动作过关（跳跃/攀爬/躲避/奔跑，一套组件配置驱动）、拖拽放置、接取收集、找线索、连线配对共 8 类互动形态按年龄适配；操作型互动成功/失败同样走向对应决策分支，教育逻辑不受互动形式影响
|
||
- **计策学堂**：每章开头先认识计策——卡通图文讲解名称、拼音、释义与"什么时候用它"，再进情境践行，构成认知 → 践行 → 反思完整学习闭环
|
||
- **智慧总结**：每章闯关完成后一道反思题"哪个说法总结了这条计策"，把直觉选择转成语言认知，答对奖励积分
|
||
- **生活践行**：家长中心下发生活小任务（把游戏里的计谋用到真实生活），孩子完成、家长确认后奖励积分，知行合一
|
||
- **成长守护**：单次会话一关（5-10 分钟）、每日学习限额与休息提醒由家长端设置；等级称号（小学徒→小军师→大将军）见证成长
|
||
- **年龄分级**：4-6 岁启蒙版（全量拼音 + 朗读）与 6-8 岁进阶版（拼音辅助可关），按注册年龄段自动过滤内容
|
||
- **闯关地图**：三十六计按六套分组（胜战计/敌战计/攻战计/混战计/并战计/败战计），依次解锁
|
||
- **游戏化激励**：星星评分、完美标记（钻石）、计策卡收集（集齐 36 张成大成就）、徽章成就、每日签到、积分
|
||
- **奖品兑换**：积分兑换虚拟奖品（即时到账）与实物奖品（家长确认 + 兑换码）
|
||
- **家长陪伴**：家长账号注册登录，下挂多个孩子档案（年龄/进度独立）；家长中心查看学习报告、确认实物奖品
|
||
- **再玩一次**：已通关情境随时可重玩，补完剩余分支看不同结果（不计分无压力），多路线价值由"完美"机制天然覆盖
|
||
- **章末温故**：每章完美通关后自动回顾之前 2-3 个已学计谋的关卡（选项打乱），完成解锁下一章并奖励积分，防遗忘
|
||
- **多端覆盖**：一套 uni-app 代码发布 Android / iOS / 平板 / 微信小程序 / H5
|
||
- **管理后台**：计策、情境关卡、决策节点、奖品、徽章内容运营，家长/孩子与兑换管理
|
||
|
||
## 技术架构
|
||
|
||
```
|
||
┌─────────────┐ ┌──────────────┐
|
||
│ ui-src/ │ │ admin-src/ │
|
||
│ uni-app │ │ Vue3 + EP │
|
||
│ 五端前台 │ │ 管理后台 │
|
||
└──────┬──────┘ └──────┬───────┘
|
||
│ HTTP / JSON │
|
||
└────────┬────────┘
|
||
┌────────▼────────┐
|
||
│ Go + GoFrame │
|
||
│ 后端服务 │
|
||
└────────┬────────┘
|
||
┌────────▼────────┐
|
||
│ SQLite (data/) │ ← 种子数据启动初始化，后台可迭代
|
||
└─────────────────┘
|
||
```
|
||
|
||
- **后端**：Go + GoFrame（分层与代码规范遵循 CLAUDE.md）
|
||
- **前端前台**：uni-app (Vue 3)，一套代码五端，生产产物由后端托管（H5 端）或独立打包发布
|
||
- **前端后台**：Vue 3 + Element Plus 独立 Web 工程，产物由后端托管
|
||
- **数据库**：SQLite 单文件，运行时数据在 `data/`，上传文件在 `workspace/`，均不提交 git
|
||
- **部署**：Docker Compose 单机，前后端一体单端口，数据目录挂载持久化
|
||
- **目录结构**：后端业务代码在 `biz/`（分层职责见 CLAUDE.md），前端前台 `ui-src/`（uni-app）、后台 `admin-src/`（Web）
|
||
|
||
## 数据流
|
||
|
||
前端调用 HTTP API（JSON）→ controller 接收参数 → service 执行业务（判分、积分、兑换）→ dao 访问 SQLite；内容型数据（计策/关卡/元素/奖品）读接口走缓存，后台修改后失效；返回值组装后回前端。种子数据在服务启动时自动初始化，后台运营可直接迭代。
|
||
|
||
## 功能模块
|
||
|
||
### 前台（多端）
|
||
|
||
| 模块 | 说明 |
|
||
|---|---|
|
||
| 家长中心 | 家长注册/登录（微信 openid 或手机号）、孩子档案管理（含每日学习限额）、学习报告、实物奖品确认、生活任务确认 |
|
||
| 计策学堂 | 每章开头的认知环节：图文/动画讲解计策名称、拼音、释义、使用时机 |
|
||
| 关卡地图 | 36 计按六套分组展示，星星进度、解锁状态、计策卡图标 |
|
||
| 情境闯关 | 每关一棵决策树：环境场景 + 人物冲突 + 道具行为构成决策要素，入口 → 多样互动（选择/排序/动作过关-跳跃攀爬躲避奔跑/拖拽/找线索，按年龄适配）→ 多路线通往不同终局；通关=到达最佳终局，完美=走完全部分支解锁下一关；未通关走错扣教训分。已实现：选项选择 + 触控互动（道具选择/步骤排序/拖拽放置/找线索/连线配对，互动入口节点模型，成功进决策树/失败进失败终局）+ 对比点评（每个选项好处/坏处）+ 结算路线回顾 + 场景插画/角色立绘/道具图标视觉呈现；呈现为三幕小剧场：开场演出（旁白朗读+字幕逐字淡入+角色入场+道具飞入，可跳过）→ 决策演出（普通节点为动作卡——图标/拼音/听读/按压动画，config 互动节点为触控互动，选择后分支演出过渡再弹对比点评）→ 结局演出（成功彩带/失败鼓励语） |
|
||
| 章末温故 | 每章完美后自动出现：随机抽 2-3 个已学计谋关卡重温（选项打乱），完成解锁下一章 + 奖励积分 |
|
||
| 智慧总结 | 每章完成后的反思题（"哪个说法总结了这条计策"），答对 +5 分 |
|
||
| 生活践行 | 章完美后下发的真实生活小任务（家长引导完成并确认，得积分） |
|
||
| 成长等级 | 按完美关卡数升级的称号体系（小学徒→小军师→大将军） |
|
||
| 计策卡 | 通关计策单元解锁对应卡片，集卡图鉴 |
|
||
| 积分 | 闯关得分、每日签到，积分流水明细 |
|
||
| 徽章 | 成就徽章（集卡、连续学习、通关数、复习、探索等），自动解锁 |
|
||
| 奖品 | 积分兑换虚拟/实物奖品，兑换记录与状态 |
|
||
| 朗读拼音 | 拼音随内容一次性标注入库（逐字对齐 JSON，`common/pinyin.go` + 多音字词表），朗读音频优先播文件、无文件时浏览器语音降级朗读（H5），低龄档（4-6）全量开启；TTS 文件生成留后续接入 |
|
||
| 视觉素材生成 | 场景插画/角色立绘/道具图标/计策卡图标由 `cmd/genasset/` 离线生成管线调用本机 oMLX（Qwen3.5-9B）生成 SVG 并转 PNG，打包入客户端随五端发布；未生成素材按 emoji 映射兜底 |
|
||
|
||
### 后台（Web）
|
||
|
||
| 模块 | 说明 |
|
||
|---|---|
|
||
| 内容管理 | 计策、情境关卡、决策节点（含互动形态配置）与分支选项 CRUD（含音频/图片资源上传） |
|
||
| 元素库管理 | 场景/人物/道具元素 CRUD 与素材上传 |
|
||
| 奖品管理 | 奖品定义、积分价格、库存 |
|
||
| 徽章管理 | 徽章定义与解锁条件 |
|
||
| 用户管理 | 家长/孩子列表、孩子进度与积分查看 |
|
||
| 兑换管理 | 兑换记录、实物发货/确认、兑换码生成 |
|
||
| 生活任务管理 | 生活践行任务配置（关联计策、任务文案、奖励积分） |
|
||
| 数据统计 | 节点卡点分析：各节点/选项选择分布、失败终局到达率，按关卡聚合 |
|
||
|
||
## 数据表清单
|
||
|
||
| 表 | 职责 |
|
||
|---|---|
|
||
| parent | 家长账号：微信 openid、手机号、昵称 |
|
||
| child | 孩子档案：所属家长、昵称、年龄段、积分余额、每日学习限额（学习主体，进度/积分/兑换均按孩子） |
|
||
| strategy | 计策：名称、拼音、释义、分组、图标、解锁前置、学堂内容、总结问题 |
|
||
| level | 情境关卡：所属计策、情境主题、年龄段、排序、内容版本号 |
|
||
| element | 元素库：场景（环境）/ 人物 / 道具，决策树的结构性骨架（关卡关联场景、节点关联人物、选项关联道具） |
|
||
| scene_node | 情境节点：决策节点（含互动形态）/ 终局节点（含最佳/良好/失败评级）、关联人物 |
|
||
| node_option | 分支选项：行为文本、使用道具、指向的下一节点、即时点评 |
|
||
| user_progress | 闯关进度：孩子 × 关卡、星星、完美标记、得分、通关时内容版本 |
|
||
| chapter_review | 章末温故记录：孩子 × 章节、复习关卡快照、完成状态 |
|
||
| user_route_log | 决策路径流水：孩子每步选择记录，支撑学习报告与内容优化 |
|
||
| user_collection | 计策卡收集：孩子 × 计策 |
|
||
| badge | 徽章定义与解锁条件 |
|
||
| user_badge | 孩子已获徽章 |
|
||
| point_log | 积分流水：变动、原因类型、余额快照 |
|
||
| life_task | 生活践行任务：关联计策、任务描述、家长引导语、确认奖励积分 |
|
||
| life_task_log | 生活任务完成记录：孩子 × 任务、家长确认状态 |
|
||
| prize | 奖品：积分价格、库存、类型（虚拟/实物） |
|
||
| redemption | 兑换记录：孩子 × 奖品、状态流转、兑换码 |
|
||
| admin_user | 后台管理员账号 |
|
||
|
||
## API 清单
|
||
|
||
### 前台（`/api/` 前缀，家长账号体系）
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| POST /api/parent/register | POST | 家长注册（微信 openid 或手机号） |
|
||
| POST /api/parent/login | POST | 家长登录 |
|
||
| POST /api/parent/child/create | POST | 创建孩子档案（昵称、年龄段） |
|
||
| POST /api/parent/child/update | POST | 更新孩子资料（昵称、头像、年龄段、每日学习限额） |
|
||
| GET /api/parent/child/list | GET | 孩子档案列表（含各孩子积分余额） |
|
||
| GET /api/parent/report | GET | 学习报告（按孩子：通关数、星星、近期活动） |
|
||
|
||
### 内容与闯关
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| GET /api/strategy/list | GET | 关卡地图：计策列表 + 进度/解锁状态 |
|
||
| GET /api/strategy/detail | GET | 计策详情（含学堂内容、总结问题）+ 关卡列表 |
|
||
| GET /api/level/detail | GET | 关卡入口节点、情境信息与元素（环境/人物/道具，含素材地址） |
|
||
| POST /api/level/choose | POST | 提交当前节点 + 所选选项（操作型互动提交成功/失败出口），返回下一节点；到达终局时结算（未通关结算积分/教训分，已通关不计分只记完成度） |
|
||
| POST /api/review/start | POST | 开始章末温故：随机抽 2-3 个已学计谋关卡返回 |
|
||
| POST /api/review/complete | POST | 温故完成：校验后解锁下一章 + 发放奖励积分 |
|
||
| POST /api/summary/submit | POST | 智慧总结答题（strategy_id + 选项），答对 +5 分（每章一次） |
|
||
| GET /api/task/list | GET | 生活任务列表（含状态：已下发/待确认/已确认） |
|
||
| POST /api/task/confirm | POST | 家长确认生活任务完成（child_id + task_id + 可选照片），发放积分 |
|
||
| GET /api/collection/list | GET | 已收集计策卡 |
|
||
|
||
### 积分与奖励
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| GET /api/points/info | GET | 积分余额 |
|
||
| GET /api/points/log | GET | 积分流水 |
|
||
| POST /api/signin | POST | 每日签到 |
|
||
| GET /api/badge/list | GET | 徽章列表与已获状态 |
|
||
| GET /api/prize/list | GET | 可兑换奖品 |
|
||
| POST /api/prize/redeem | POST | 积分兑换奖品 |
|
||
| GET /api/redemption/list | GET | 我的兑换记录 |
|
||
|
||
### 后台（`/api/admin/` 前缀，管理员鉴权）
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| POST /api/admin/login | POST | 管理员登录 |
|
||
| GET/POST /api/admin/strategy/… | GET/POST | 计策 CRUD |
|
||
| GET/POST /api/admin/level/… | GET/POST | 关卡 CRUD |
|
||
| GET/POST /api/admin/node/… | GET/POST | 情境节点（决策/终局）CRUD |
|
||
| GET/POST /api/admin/option/… | GET/POST | 分支选项 CRUD |
|
||
| GET/POST /api/admin/element/… | GET/POST | 元素库（场景/人物/道具）CRUD |
|
||
| GET/POST /api/admin/task/… | GET/POST | 生活任务 CRUD |
|
||
| GET /api/admin/stats/level | GET | 节点卡点统计（选择分布、失败率） |
|
||
| GET/POST /api/admin/prize/… | GET/POST | 奖品 CRUD |
|
||
| GET/POST /api/admin/badge/… | GET/POST | 徽章 CRUD |
|
||
| GET /api/admin/user/list | GET | 用户列表 |
|
||
| GET /api/admin/redemption/list | GET | 兑换记录 |
|
||
| POST /api/admin/redemption/ship | POST | 实物发货/确认 |
|
||
|
||
## 使用说明
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 后端（Go 1.22+）
|
||
go run main.go
|
||
|
||
# 前台（ui-src/，uni-app）
|
||
cd ui-src && npm install && npm run dev:h5 # H5 调试
|
||
npm run dev:mp-weixin # 微信小程序调试
|
||
|
||
# 后台（admin-src/）
|
||
cd admin-src && npm install && npm run dev # vite 代理到后端
|
||
```
|
||
|
||
后端启动时自动初始化数据库与种子数据（36 计内容、题目、奖品、徽章）。
|
||
|
||
### Docker 部署
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
- 单端口对外，前端产物（H5 + 后台）由后端托管
|
||
- `data/`、`workspace/` 挂载持久化，容器重建不丢数据
|
||
- App / 小程序端独立打包发布（见技术设计.md）
|
||
|
||
### 数据备份
|
||
|
||
文件型存储：备份 = 打包 `data/`（小而关键）+ `workspace/`（大而可重建）两个目录。
|