# xuexileyuan

**Repository Path**: cpfzym/xuexileyuan

## Basic Information

- **Project Name**: xuexileyuan
- **Description**: 专为**兰化二小一年四班**设计的多学科儿童学习乐园，包含拼音、语文、数学三大模块。

- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-02
- **Last Updated**: 2026-10-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 兰化二小学习乐园

专为**兰化二小一年四班**设计的多学科儿童学习乐园，一套代码三端运行：**Web / Windows（Electron）/ Android（Capacitor）**。

> 版本说明：项目目前处于开发阶段，版本号采用 `0.x.y` 语义（2026-10 由早期的 1.4.x 规整为 0.4.x），正式发布时再进入 1.0.0。

## 功能特色

### 拼音王国
- 23 个声母、24 个韵母、16 个整体认读音节
- 声调练习（四声走势动画 + 跟读评测）
- 声母韵母两拼法拼读、看图词语拼读
- 字母描红书写
- 5 款趣味游戏：拼音配对、声调听辨、看图识音、听音找字母、拼音打地鼠

### 语文乐园（人教版一年级）
- **看图识字**：269 个教材同步汉字，按课文分组，带 emoji 插图和描红
- **古诗词朗读**：12 首必背古诗，逐行拼音标注
- **课文朗读**：经典课文选段，标准语速 + 慢速跟读
- 游戏：汉字泡泡乐、古诗排排队

### 数学星球
- 0-100 数字认读、10 / 20 以内分级口算
- 比大小、找规律

### 通用功能
- 学科广场首页 + **年级选择**（一年级已开放，二至六年级内容预告中）
- **教学资源宝库**（`/resources`）：按 学科 → 单元 → 课时 整理 758 条资源，
  内置音频即点即播；视频课与电子教材跳转教育部「国家中小学智慧教育平台」官方入口在线学习
- 熊猫伙伴养成（自定义名字、喂竹子、换装饰）
- 星星 / 贴纸 / 徽章奖励系统、每日打卡、连续学习、惊喜宝箱
- 主题皮肤、背景音乐开关、护眼提醒、断网提示
- 家长中心（学习数据、薄弱环节、语音诊断、版本更新、版本记录）

## 界面预览

| 学科广场 | 拼音王国 |
|---|---|
| ![学科广场](docs/screenshots/plaza.png) | ![拼音王国](docs/screenshots/pinyin-home.png) |

| 字母认读 | 声韵拼读 |
|---|---|
| ![字母认读](docs/screenshots/letters.png) | ![声韵拼读](docs/screenshots/blend.png) |

| 趣味游戏 | 教学资源宝库 |
|---|---|
| ![趣味游戏](docs/screenshots/games.png) | ![教学资源宝库](docs/screenshots/resources.png) |

## 技术栈

| 领域 | 技术 |
|---|---|
| 前端 | Vue 3 + Vite 5 + Pinia + Vue Router |
| 桌面端 | Electron 44（electron-builder，portable 单文件） |
| 安卓端 | Capacitor 6 + WebView（Android Studio 工程在 `android/`） |
| 语音（教学内容） | **2377 个预生成 MP3**（`public/tts/`，约 14MB），拼音/口诀/汉字/课文 100% 覆盖 |
| 语音（动态文本） | Web Speech API → 安卓 sherpa-onnx 离线合成（vits 模型）→ 系统 TTS 三级兜底 |
| 语音识别 | 仅浏览器端启用 webkitSpeechRecognition；APK 内自动降级为亲子跟读模式 |
| 更新 | Gitee Release 整包更新 + Web/Electron 端 Service Worker 热更新 |
| 存储 | localStorage（学习进度纯本地保存） |

## 目录结构

```
pinyin/
├── src/
│   ├── subjects/      # 学科注册表（新增学科入口）
│   ├── views/         # 页面（pinyin/yuwen/shuxue 子目录 + games/）
│   ├── composables/   # useSpeech.js 语音链路等组合式函数
│   ├── stores/        # Pinia（progress.js 学习进度）
│   ├── data/          # 拼音、汉字等教学数据；data/resources/ 为资源中心目录清单
│   └── version.js     # 应用版本号 + 更新地址
├── electron/          # Electron 主进程 / preload
├── android/           # Capacitor 生成的 Android Studio 工程
├── public/tts/        # 预生成教学语音 MP3
├── public/resources/  # 资源中心可随包分发的本地媒体（按学科/类型分目录，附版权约定）
├── scripts/           # 构建、语音合成、热更新清单、打包瘦身等脚本
├── hotupdate/         # Web 热更新资源（由 dist 同步，随 git 发布）
├── update.json        # 三端统一更新清单
└── capacitor.config.json
```

## 开发

```bash
# 安装依赖
npm install

# 启动开发服务器（默认 http://127.0.0.1:5173，端口占用自动顺延）
npm run dev

# 构建 Web 版（产物在 dist/，并自动生成热更新清单）
npm run build
```

## 打包脚本

| 命令 | 产物 | 说明 |
|---|---|---|
| `npm run dev` | — | 本地开发服务器 |
| `npm run build` | `dist/` | Web 构建 + 生成 `dist/web-manifest.json` |
| `npm run electron:build` | `release-v{version}/lanhuaerxiao-{version}.exe` | Windows 便携版（免安装单文件） |
| `npm run cap:sync` | — | Web 构建并同步到 Android 工程 |
| `npm run cap:open` | — | 用 Android Studio 打开安卓工程 |
| `npm run apk:debug` | `releases/lanhuaerxiao-{ver}-{code}-debug.apk` | 安卓调试包 |
| `npm run apk:release` | `releases/lanhuaerxiao-{ver}-{code}-release.apk` | 安卓正式签名包 |

> 产物中的 `{version}` 取 `package.json` 的 version，`{code}` 取安卓 `versionCode`；
> 升版本后 `build.directories.output` 与 `win.artifactName` 也要一起改（见文末发版流程）。

### Windows 打包

- 目标为 **portable**：单个 exe，双击即用、无需安装，适合微信/U 盘分发
- 已内置瘦身钩子 [scripts/after-pack.cjs](scripts/after-pack.cjs)：
  - 语言包仅保留 `zh-CN` / `en-US`（Chromium 回退语言）
  - 删除 dxcompiler/dxil（WebGPU/DX12 编译器，2D 教学应用不用）
  - 保留 vk_swiftshader 软件渲染器（无独显/远程桌面兜底）
- `compression: maximum`，并排除 asar 内与 Vite 产物重复的 node_modules
- 清理后安装包约 **90MB**（Chromium 内核占约 75MB，属 Electron 应用正常水位）

### Android 打包

前置条件：JDK + Android SDK，`cap sync android` 可正常同步。

- **签名**：正式包读取 `android/keystore.properties`（含密钥库密码，**不入库、需本机自备并离线备份**）；缺失时只能打 debug 包
- **ONNX 模型**：`android/app/src/main/assets/vits-melo-tts-zh_en/`（约 182MB，**超过 Gitee 单文件限制，不入库**），换机器打包需重新下载放置
- `build.gradle` 已配置 `noCompress 'onnx', 'fst'`，防止 aapt 压缩模型导致 sherpa 引擎初始化失败
- 打完的 APK 由 `scripts/collect-apk.mjs` 汇总到 `releases/`
- 安卓**不支持 Service Worker 热更新**（Capacitor https scheme 限制），安卓端更新统一走「检测新版 APK → 下载安装」

### 教学语音包（TTS）

`public/tts/` 为预生成的核心教学语音，相关脚本：

| 脚本 | 作用 |
|---|---|
| `scripts/gen-tts.mjs` | 扫描教学数据生成待合成文本清单 |
| `scripts/synth-tts.py` | 调用本地 TTS 引擎批量合成 MP3 |
| `scripts/check-tts-coverage.mjs` | 校验语音文件覆盖率 |

运行时播放链：内置 MP3 → sherpa-onnx（仅 APK）→ 系统 TTS，播放失败自动降级并有超时保护。

### 教学资源中心与版权

资源中心页面：`src/views/ResourceView.vue`，路由 `/resources`（广场页有入口）；
目录清单：`src/data/resources/`（sources.js 登记来源与许可，三个学科文件分别组织单元/课时）。

资源分三类处理：

| 类型 | 处理方式 |
|---|---|
| 🔊 音频 | 复用自行合成的语音包，`speak()` 即点即播，离线可用 |
| 🎬 视频课 / 📖 电子教材 | 仅跳转官方平台**已核实入口**（见下），不抓取、不转存、不二次分发 |
| 🧩 练习 | 路由到 App 内对应学习页 |

官方入口（教育部主办，免费公开）：

- 课程教学：`https://www.zxx.edu.cn/syncClassroom/auto`
- 电子教材：`https://www.zxx.edu.cn/tchMaterial`

**版权红线**：人教社教材配套音视频、教材扫描页、从官方平台下载的视频一律禁止入库；
`public/resources/` 只接收自有录制或 CC0/CC-BY 授权媒体，且须在清单登记来源与许可
（详见 [public/resources/版权须知与目录约定.md](public/resources/%E7%89%88%E6%9D%83%E9%A1%BB%E7%9F%A5%E4%B8%8E%E7%9B%AE%E5%BD%95%E7%BA%A6%E5%AE%9A.md)）。

## 发版流程（版本号同步）

每次发版必须同步以下位置，缺一不可：

1. `src/version.js` 的 `APP_VERSION`（Web/安卓显示版本）
2. `package.json` 的 `version`、`build.directories.output`、`win.artifactName`
3. `android/app/build.gradle` 的 `versionCode`（**只增不减**）与 `versionName`
4. `update.json`：
   - 顶层字段 → Windows/Electron 整包更新
   - `android`（versionCode / versionName / apkUrl）→ 安卓整包更新
   - `web`（version / manifestPath / minNativeVersion）→ Web 热更新
5. Web/安卓改动需重新构建并把 `dist/` 内容同步到 `hotupdate/`（热更新清单排除 tts 目录）
6. 安装包上传 Gitee Release，**附件文件名必须与 update.json 中的 URL 完全一致**
7. 提交并推送 `update.json` 与 `hotupdate/`，客户端才能检测到更新

> Gitee 普通附件单文件限 100MB：瘦身后的 Windows exe（~90MB）可直接传；含模型的 APK（~208MB）需走网盘等其他渠道分发。

## 版本记录

### v0.5.0（2026-10-03，开发中）
- **新增教学资源宝库**：学科/单元/课时四级目录、758 条资源、关键词搜索
- 内置音频（声母韵母、生字、古诗课文标题等）即点即播
- 视频课/电子教材跳转国家中小学智慧教育平台官方入口，页面内展示版权声明与平台导航提示
- 新增 `public/resources/` 本地媒体目录与版权登记约定

### v0.4.9（2026-10-03）
- 首页新增年级选择（一年级开放，二至六年级锁定预告）
- 修复窄屏下熊猫问候气泡被遮挡；全局按钮行等宽统一；字母页分类标签一屏放下
- 修复设置孩子/熊猫名字后表扬语仍念"小朋友"，以及安卓中文输入法下修改信息保存失效
- Windows 安装包瘦身：108.7MB → 90.2MB（语言包/GPU 编译器裁剪 + maximum 压缩）
- 安卓端关闭不可用的 Service Worker 热更新，统一走 APK 整包更新
- 语音：2377 个预生成 MP3 + sherpa-onnx 离线模型兜底 + 播放超时保护

### 更早版本（归档）
- v1.1.0（2025-10-02）：新增语文乐园、数学星球、学科广场、熊猫自定义名字、主题皮肤
- v1.0.0（2025-09-28）：拼音字母/声调/拼读/词语、4 款游戏、熊猫养成、打卡奖励
- v1.2 ~ v1.4：多学科架构、Capacitor 安卓打包、Electron 自动更新、离线语音链路、手机端布局适配（版本号后规整为 0.4.x）

---

**By CrazyCheng · 程圣宸专用**