# 三十六计小课堂

一款面向低龄儿童（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    │
       │  controller → service → dao │
       │  鉴权中间件 · 文件解析 · 缓存 │
       └────────┬────────┘
       ┌────────▼────────┐
       │  SQLite (data/)  │  ← 种子数据启动初始化，后台可迭代
       └─────────────────┘
```

- **后端**：Go + GoFrame，分层 `controller → service → dao`，详见 CLAUDE.md
- **前端前台**：uni-app (Vue 3)，一套代码五端，生产产物由后端托管（H5 端）或独立打包发布
- **前端后台**：Vue 3 + Element Plus 独立 Web 工程，产物由后端托管
- **数据库**：SQLite 单文件，运行时数据在 `data/`，上传文件在 `workspace/`，均不提交 git
- **部署**：Docker Compose 单机，前后端一体单端口，数据目录挂载持久化

## 目录结构

| 目录 | 职责 |
|---|---|
| common/ | 通用层：HTTP 服务与鉴权、文件解析、中文分词、向量 JSON、DAO 基类、查询缓存、协程池 |
| biz/consts/ | 常量集中地：表名、状态、内容类型、协程池默认大小 |
| biz/model/ | entity（表结构）、dto（请求/响应 + 路由）、domain（领域模型） |
| biz/dao/ | 单表数据访问，每表一个文件 |
| biz/service/ | 业务逻辑：规则校验、事务、跨表组装、积分/兑换、闯关判分 |
| biz/controller/ | 接口层：接收参数、调用 service、组装返回值 |
| ui-src/ | uni-app 前台工程（五端） |
| admin-src/ | 管理后台 Web 工程 |
| data/ | SQLite 数据库（运行时数据，不提交 git） |
| workspace/ | 上传文件（图片/音频，不提交 git） |

## 数据流

1. 前端调用 HTTP API（JSON），经鉴权中间件 → controller
2. controller 接收参数（DTO `v` tag 自动校验）→ 调用 service
3. service 执行业务规则（判分、积分计算、兑换校验）→ 调用 dao
4. dao 单表访问 SQLite，读查询走缓存，写操作后清对应缓存
5. 返回值经 controller 组装 DTO 回前端

## 功能模块

### 前台（多端）

| 模块 | 说明 |
|---|---|
| 家长中心 | 家长注册/登录（微信 openid 或手机号）、孩子档案管理（含每日学习限额）、学习报告、实物奖品确认、生活任务确认 |
| 计策学堂 | 每章开头的认知环节：图文/动画讲解计策名称、拼音、释义、使用时机 |
| 关卡地图 | 36 计按六套分组展示，星星进度、解锁状态、计策卡图标 |
| 情境闯关 | 每关一棵决策树：环境场景 + 人物冲突 + 道具行为构成决策要素，入口 → 多样互动（选择/排序/动作过关-跳跃攀爬躲避奔跑/拖拽/找线索，按年龄适配）→ 多路线通往不同终局；通关=到达最佳终局，完美=走完全部分支解锁下一关；未通关走错扣教训分 |
| 章末温故 | 每章完美后自动出现：随机抽 2-3 个已学计谋关卡重温（选项打乱），完成解锁下一章 + 奖励积分 |
| 智慧总结 | 每章完成后的反思题（"哪个说法总结了这条计策"），答对 +5 分 |
| 生活践行 | 章完美后下发的真实生活小任务（家长引导完成并确认，得积分） |
| 成长等级 | 按完美关卡数升级的称号体系（小学徒→小军师→大将军） |
| 计策卡 | 通关计策单元解锁对应卡片，集卡图鉴 |
| 积分 | 闯关得分、每日签到，积分流水明细 |
| 徽章 | 成就徽章（集卡、连续学习、通关数、复习、探索等），自动解锁 |
| 奖品 | 积分兑换虚拟/实物奖品，兑换记录与状态 |
| 朗读拼音 | 拼音随内容一次性标注入库、朗读音频 TTS 生成（写时一次性，读取零计算），低龄档全量开启 |

### 后台（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/`（大而可重建）两个目录。