# 🎈 数学乐园 · 四年级

给孩子做的**在线数学学习系统**：知识库 + 练习引擎 + 错题本，纯静态网页、无需服务器、数据归你自己。

- **知识库**：按四年级核心专题组织的知识点卡片（概念 / 例题 / 易错点），可标记"已掌握"
- **练习引擎**：口算、竖式（三位数×两位数、除数是两位数的除法）、应用题，自动出题、自动批改、即时讲解；除法竖式可看逐位试商过程
- **错题本**：答错自动收录，可标记错因（计算粗心 / 看错题 / 概念不清），支持"再做一遍"练到对为止

---

## 一、本地运行

不需要装任何东西（系统自带 Python 即可）：

```bash
cd 学习   # 本项目目录
python3 -m http.server 8000
```

浏览器打开 <http://localhost:8000> 即可使用。

> ⚠️ 不要用「双击 index.html」的方式打开（浏览器安全限制下部分功能不可用），请用上面的 http 服务。

## 二、部署到网上（手机/平板也能用）

系统是纯静态页面，可免费部署到任意静态托管平台，数据存在各设备浏览器里。

### Cloudflare Pages（最快，不用命令行）

1. 项目根目录有现成的 **`math-site.zip`**（已打包好）
2. 注册/登录 <https://dash.cloudflare.com> → **Workers & Pages** → **Create** → **Pages** → **Upload assets**
3. 拖入 `math-site.zip` → 部署，约 1 分钟后得到 `https://xxx.pages.dev` 网址

详细图文步骤见 **[DEPLOY.md](DEPLOY.md)**。

### GitHub Pages

```bash
cd 学习
git init
git add -A
git commit -m "数学乐园 v1"
# 在 GitHub 新建一个仓库，然后：
git remote add origin https://github.com/<你的用户名>/<仓库名>.git
git branch -M main
git push -u origin main
```

然后在仓库页面 **Settings → Pages → Build and deployment → Source** 选 `Deploy from a branch`，分支选 `main`，目录选 `/ (root)`，保存后等 1-2 分钟，就能通过 `https://<你的用户名>.github.io/<仓库名>/` 访问。

### Cloudflare Pages / Vercel / Netlify

直接拖拽上传整个项目文件夹，或连接 GitHub 仓库即可，都是免费档。

## 三、多设备数据同步

数据存在**各设备自己的浏览器**里。跨设备同步方法：

1. 在设备 A 点右上角 **「⬇️ 导出数据」**，得到一个 `.json` 文件
2. 把文件发到设备 B（微信文件传输助手等）
3. 在设备 B 点 **「⬆️ 导入数据」**，选择该文件

导入会**覆盖**该设备原有数据，操作前建议先导出备份。

## 四、自定义知识库与题库

所有内容都在 **`js/data.js`** 一个文件里，按教材版本、单元顺序随意改：

- `units`：知识库单元与知识点（`title` 标题、`body` 概念、`examples` 例题、`warnings` 易错点）
- `problems`：人工精选应用题（`question` 题干、`answer` 数字答案、`unit` 单位、`solution` 解析、`level` 1=基础 / 2=提高、`check` 自动校验表达式）
- `templates`：应用题题型模板（自动生成无限变体）——`gen` 生成随机参数、`pattern` 题干占位、`answer` 算答案、`check` 校验表达式。练习时按模板随机出题，数字/场景每次不同

改完刷新页面即生效，无需改任何其他代码。

## 五、测试

```bash
# 核心逻辑单元测试（出题答案正确性、判题逻辑、题库数据完整性）
node tests/core.test.js

# 界面冒烟测试（模拟浏览器跑完整做题流程）
npm install jsdom --no-save   # 需要先装 jsdom
node tests/smoke.js
```

## 六、项目结构

```
index.html        页面入口
css/style.css     样式
js/core.js        出题与判题核心逻辑（纯函数，可测试）
js/store.js       本地数据层（localStorage + 导入导出）
js/data.js        知识库数据 + 应用题题库
js/app.js         界面渲染与交互
tests/            单元测试 + 冒烟测试
```

---

*提示：页面底部「使用说明」链接的就是本文件。*