# ptx

**Repository Path**: pcxadmin/ptx

## Basic Information

- **Project Name**: ptx
- **Description**: 核心能力

语文智能听写、英语智能听写、小学数学专项习题练习

技术栈

微信原生小程序、微信云开发（云函数+云数据库）、百度语音合成API
- **Primary Language**: 微信
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小学学习助手小程序\-需求详细设计文档

# 1 文档概述

## 1\.1 项目基本信息

|项目项|详细说明|
|---|---|
|项目名称|小学学习助手小程序|
|项目类型|微信原生小程序（微信云开发）|
|目标用户|小学1\-6年级学生、学生家长|
|核心能力|语文智能听写、英语智能听写、小学数学专项习题练习|
|技术栈|微信原生小程序、微信云开发（云函数\+云数据库）、百度语音合成API|

## 1\.2 文档目的

本文档为小学学习助手小程序详细需求设计文档，用于明确项目整体架构、各模块功能细节、数据结构、业务逻辑、交互规则、性能及安全规范，为开发、测试、迭代提供统一标准依据，可直接用于项目开发落地与交付归档。

## 1\.3 适用范围

适用于本小程序前端页面、工具方法、云函数、云数据库的开发、测试、验收及后续版本迭代工作。

# 2 系统整体架构

本项目采用「小程序前端\+微信云开发后端」的轻量化架构，分为页面展示层、工具公共层、云函数服务层、云数据库存储层四层结构，整体轻量化、低耦合，支持离线缓存、在线同步能力。

```Plain Text
┌─────────────────────────────────────────────────────────────┐
│                        小程序端                             │
├─────────────────────────────────────────────────────────────┤
│  页面层  │ 首页 | 语文听写 | 英语听写 | 数学习题 | 设置     │
│          │ 语文播报 | 英语播报                              │
├─────────────────────────────────────────────────────────────┤
│  工具层  │ storage.js | cloud.js | baiduSpeech.js          │
│          │ pinyin.js | pinyin-pro.js                        │
├─────────────────────────────────────────────────────────────┤
│                        云开发端                             │
├─────────────────────────────────────────────────────────────┤
│  云函数  │ initUserConfig | getUserConfig | updateUserConfig│
│          │ getChineseDict | getEnglishDict | getMathQuestion│
│          │ addCustomDict | getCustomDict | deleteCustomDict │
│          │ getBaiduToken                                   │
├─────────────────────────────────────────────────────────────┤
│  数据库  │ user_config | chinese_dict | english_dict        │
│          │ math_question | custom_dict                      │
└─────────────────────────────────────────────────────────────┘
```

# 3 核心功能模块详细设计

## 3\.1 首页模块

**页面路径**：pages/index/index

**功能概述**：小程序主入口页面，展示核心功能入口，加载并展示用户基础配置，做年级权限拦截。

### 3\.1\.1 页面结构与交互

|页面区域|展示内容|交互逻辑|
|---|---|---|
|顶部标题区|小学学习助手、1\-6年级报听写\&数学习题副标题|静态展示，无交互|
|功能卡片区|语文听写、英语听写、数学习题三大功能卡片|点击对应卡片跳转对应功能页面|
|底部导航区|语文听写、英语听写、数学习题导航入口|点击切换对应功能页面|

### 3\.1\.2 核心业务逻辑

- 页面加载优先读取本地用户配置，无本地配置则调用云函数初始化默认配置；

- 权限拦截：用户年级小于3年级时，点击英语听写入口弹出提示「英语从3年级开始学习」，禁止进入；

- 页面每次显示（onShow）都会刷新最新用户配置，保证数据同步。

## 3\.2 语文听写模块

### 3\.2\.1 语文听写选择页

**页面路径**：pages/chinese\-dictation/index

**功能概述**：按年级、单元、内容类型筛选语文听写素材，支持自定义添加、删除听写内容，批量选择听写素材。

#### 3\.2\.1\.1 数据结构

|字段名|字段类型|字段说明|
|---|---|---|
|unit\_id|String|单元唯一标识|
|unit\_name|String|单元名称|
|content\_type|String|内容类型：生字/词语/句子/诗词|
|content|String|听写原文内容|
|pinyin|String|内容对应拼音|
|author|String|诗词作者（非诗词类型为空）|
|is\_custom|Boolean|是否为用户自定义内容|

#### 3\.2\.1\.2 页面交互与核心功能

- **类型筛选**：点击生字、词语、句子、诗词标签，实时筛选对应类型素材；

- **单元折叠**：支持单元列表展开/收起，优化长列表展示；

- **批量操作**：一键全选、一键清空所有选中素材；

- **自定义内容**：弹窗添加自定义听写内容，输入汉字自动生成拼音，支持删除已添加的自定义内容；

- **数据合并展示**：系统默认素材\+用户自定义素材合并展示，自定义内容统一展示在对应单元末尾。

#### 3\.2\.1\.3 数据加载策略

优先读取本地缓存语文听写数据，本地无数据则调用云函数拉取云端数据并缓存至本地；同时加载用户自定义云端数据，与系统数据合并渲染。

### 3\.2\.2 语文播报页

**页面路径**：pages/dictation\-play/index

**功能概述**：对选中的语文听写素材进行智能语音播报，支持自定义播放次数、间隔时间，支持暂停、跳过、显隐内容。

#### 3\.2\.2\.1 核心状态变量

|变量名|变量类型|变量说明|
|---|---|---|
|items|Array|待播报听写内容列表|
|currentIndex|Number|当前播报素材索引|
|currentPlayCount|Number|当前素材已播放次数|
|playCount|Number|单素材播放总次数（默认3次）|
|intervalTime|Number|素材播报间隔时间（单位：秒，默认3秒）|
|isPlaying|Boolean|是否处于播放状态|
|showContent|Boolean|是否展示听写原文内容|
|\_isProcessing|Boolean|播放防重锁，防止多次触发播放结束事件|

#### 3\.2\.2\.2 核心播放功能

- 自动播放：页面加载完成后自动开启语音播报；

- 循环播报：单条素材可自定义播放次数，默认3次；

- 间隔等待：单条素材播报完成后，等待自定义间隔时间再切换下一条；

- 基础操作：支持暂停、继续、跳过下一题、显示/隐藏原文；

- 参数自定义：可实时调整播放次数、播报间隔时长。

#### 3\.2\.2\.3 音频播放兼容策略

- 基于微信原生音频上下文 wx\.createInnerAudioContext 实现播放；

- 通过 onCanplay 回调触发播放，兼容iOS、Android双端；

- 新增 onTimeUpdate 兜底逻辑，解决安卓端 onEnded 失效问题；

- 通过 \_isProcessing 状态锁，杜绝播放结束事件重复触发。

## 3\.3 英语听写模块

### 3\.3\.1 英语听写选择页

**页面路径**：pages/english\-dictation/index

**功能概述**：仅对3\-6年级开放，筛选英语单词、句子听写素材，支持自定义内容增删、批量选择。

#### 3\.3\.1\.1 数据结构

|字段名|字段类型|字段说明|
|---|---|---|
|unit\_id|String|单元唯一标识|
|unit\_name|String|单元名称|
|content\_type|String|内容类型：单词/句子|
|english|String|英文原文|
|translate|String|中文翻译|
|is\_custom|Boolean|是否为用户自定义内容|

#### 3\.3\.1\.2 核心功能

页面交互、筛选逻辑、批量操作、自定义内容、数据加载策略与语文听写选择页完全一致，仅素材类型与字段不同。

### 3\.3\.2 英语播报页

**页面路径**：pages/english\-play/index

**功能概述**：实现英文\+中文翻译分层播报，适配英语听写学习场景。

#### 3\.3\.2\.1 差异化播报逻辑

- 首次播放：播报英文原文 \+ 对应中文翻译；

- 二次及后续播放：仅播报英文原文，不重复播报翻译；

- 新增状态变量 \_pendingTranslate 控制翻译播报时序；

- 其余暂停、跳过、间隔设置、内容显隐功能与语文播报一致。

#### 3\.3\.2\.2 语音合成规则

- 英文内容调用百度语音接口，语种参数 lang=en；

- 中文翻译调用百度语音接口，语种参数 lang=zh。

## 3\.4 数学习题模块

**页面路径**：pages/math\-question/index

**功能概述**：按年级、题型随机生成小学数学题目，支持在线答题、答案核对、正确率统计。

### 3\.4\.1 数据结构

|字段名|字段类型|字段说明|
|---|---|---|
|q\_type|String|题目类型：口算/竖式/应用题/填空|
|question|String|题目内容|
|answer|String|标准答案|
|grade|Number|对应年级|
|volume|String|册数：上册/下册|

### 3\.4\.2 核心功能

- 题型筛选：支持口算、竖式、应用题、填空题型切换；

- 数量自定义：可设置单次答题题目数量，默认10道；

- 随机出题：从对应年级册数题库中随机抽取题目；

- 答题交互：支持手动输入答案、左右滑动切换题目；

- 结果校验：支持一键显示答案、提交核对答案；

- 数据统计：答题完成后展示正确数、错误数、整体正确率。

## 3\.5 设置模块

**页面路径**：pages/settings/index

**功能概述**：用户个人学习配置管理，支持年级、册数、播报参数自定义，配置本地\+云端双向同步。

### 3\.5\.1 配置项参数

|配置项|字段类型|默认值|说明|
|---|---|---|---|
|grade|Number|1|学习年级（1\-6）|
|volume|String|上册|课本册数（上册/下册）|
|speech\_speed|Number|5|语音播报语速（1\-10档）|
|interval\_time|Number|3|播报间隔时间（秒）|
|play\_count|Number|3|单内容播放次数|

### 3\.5\.2 配置同步策略

- 保存配置时，同步写入本地存储与云端用户配置表；

- 云端通过用户 openid 唯一标识用户配置，无记录则新建，有记录则更新；

- 支持一键重置为系统默认配置。

# 4 公共工具模块设计

## 4\.1 本地存储工具 storage\.js

统一封装小程序本地缓存读写、删除方法，管理所有业务缓存数据，实现数据本地持久化。

### 4\.1\.1 核心缓存Key

|缓存Key|缓存内容说明|
|---|---|
|user\_config|用户个性化配置|
|chinese\_dict\_\{grade\}\_\{volume\}|对应年级册数语文听写素材|
|english\_dict\_\{grade\}\_\{volume\}|对应年级册数英语听写素材|
|math\_question\_\{grade\}\_\{volume\}|对应年级册数数学习题库|
|user\_custom\_dict|用户自定义听写内容|
|baidu\_token、baidu\_token\_expire|百度语音Token及过期时间|

### 4\.1\.2 核心方法

通用方法：get\(\)、set\(\)、remove\(\)；同时封装各业务专属的配置读写、素材缓存读写方法。

## 4\.2 云函数封装工具 cloud\.js

统一封装所有云函数调用逻辑，规范入参、出参，简化页面调用逻辑。

### 4\.2\.1 云函数清单

|云函数名|功能说明|核心入参|
|---|---|---|
|initUserConfig|初始化用户默认配置|无|
|getUserConfig|获取用户云端配置|无|
|updateUserConfig|更新用户配置|grade、volume、speech\_speed、interval\_time、play\_count|
|getChineseDict|获取语文听写素材|grade、volume、unit\_id、content\_type|
|getEnglishDict|获取英语听写素材|grade、volume、unit\_id、content\_type|
|getMathQuestion|获取数学习题|grade、volume、q\_type、count|
|addCustomDict|新增自定义听写内容|subject、grade、volume、content、pinyin、translate等|
|getCustomDict|查询自定义内容|subject、grade、volume|
|deleteCustomDict|删除自定义内容|id|
|getBaiduToken|获取百度语音授权Token|无|

## 4\.3 百度语音工具 baiduSpeech\.js

封装百度语音合成API，实现Token缓存、语音URL生成，统一管控语音播报参数。

### 4\.3\.1 核心能力

- Token管理：优先读取本地缓存，过期自动重新获取，有效期29天；

- 语音生成：根据文本、语速、语种生成可播放的语音URL；

- 参数统一配置：固定音调、音量、音色、音频格式参数。

## 4\.4 拼音转换工具 pinyin\.js / pinyin\-pro\.js

提供汉字转拼音能力，用于用户自定义语文内容时，自动匹配生成对应拼音，无需手动输入。

# 5 云函数核心逻辑设计

## 5\.1 initUserConfig

根据用户openid查询配置，无配置则创建默认用户配置数据，默认参数：1年级、上册、语速5、播放间隔3秒、单次播放3次。

## 5\.2 updateUserConfig

基于用户唯一openid做数据更新：存在对应用户记录则增量更新，无记录则新增完整配置数据，保证单用户唯一配置。

## 5\.3 getBaiduToken

服务端调用百度官方接口获取语音合成access\_token，密钥存放于云函数端，不对外暴露，返回Token及过期时间。

# 6 数据流转流程

## 6\.1 用户配置数据流

用户修改配置 → 本地storage缓存保存 → 调用云函数同步至云端user\_config表 → 下次启动优先读取本地缓存，无缓存则拉取云端数据。

## 6\.2 听写素材数据流

云端字典表数据 → 云函数拉取数据 → 本地缓存持久化 → 页面加载读取本地缓存 → 用户选择素材 → 语音工具生成音频URL → 小程序音频组件播放。

## 6\.3 自定义内容数据流

用户新增自定义内容 → 云函数提交至custom\_dict表 → 本地缓存更新 → 页面加载合并系统素材\+用户自定义素材渲染展示 → 支持删除自定义云端数据。

# 7 页面路由清单

|页面路由|页面名称|功能说明|
|---|---|---|
|/pages/index/index|首页|小程序主入口，功能导航|
|/pages/chinese\-dictation/index|语文听写选择页|筛选、选择语文听写素材|
|/pages/dictation\-play/index|语文播报页|语文素材语音播报|
|/pages/english\-dictation/index|英语听写选择页|筛选、选择英语听写素材|
|/pages/english\-play/index|英语播报页|英语素材分层语音播报|
|/pages/math\-question/index|数学习题页|数学刷题、答案校验、统计|
|/pages/settings/index|设置页|用户个性化配置管理|

# 8 数据库详细设计

## 8\.1 user\_config 用户配置表

|字段名|字段类型|字段说明|
|---|---|---|
|\_id|String|记录唯一ID|
|openid|String|用户微信唯一标识（唯一索引）|
|grade|Number|用户选择年级|
|volume|String|册数|
|speech\_speed|Number|播报语速|
|interval\_time|Number|播报间隔时间|
|play\_count|Number|单内容播放次数|
|create\_time|Number|记录创建时间戳|
|update\_time|Number|记录更新时间戳|

## 8\.2 chinese\_dict 语文听写表

|字段名|字段类型|字段说明|
|---|---|---|
|\_id|String|记录唯一ID|
|grade|Number|对应年级|
|volume|String|册数|
|unit\_id|Number|单元ID|
|unit\_name|String|单元名称|
|content\_type|String|内容类型|
|content|String|听写内容|
|pinyin|String|对应拼音|
|author|String|诗词作者|

## 8\.3 english\_dict 英语听写表

|字段名|字段类型|字段说明|
|---|---|---|
|\_id|String|记录唯一ID|
|grade|Number|对应年级|
|volume|String|册数|
|unit\_id|Number|单元ID|
|unit\_name|String|单元名称|
|content\_type|String|内容类型|
|english|String|英文内容|
|translate|String|中文翻译|

## 8\.4 math\_question 数学习题库

|字段名|字段类型|字段说明|
|---|---|---|
|\_id|String|记录唯一ID|
|grade|Number|对应年级|
|volume|String|册数|
|q\_type|String|题目类型|
|question|String|题目内容|
|answer|String|标准答案|

## 8\.5 custom\_dict 自定义内容表

|字段名|字段类型|字段说明|
|---|---|---|
|\_id|String|记录唯一ID|
|openid|String|用户唯一标识，数据隔离|
|subject|String|科目：语文/英语|
|grade|Number|年级|
|volume|String|册数|
|unit\_id|Number|单元ID|
|unit\_name|String|单元名称|
|content\_type|String|内容类型|
|content|String|语文内容/英文内容|
|pinyin|String|拼音（语文专用）|
|translate|String|中文翻译（英语专用）|
|create\_time|Number|创建时间戳|

# 9 项目约束与开发规范

## 9\.1 开发技术约束

- WXML 不使用ES6\+语法，保证兼容性；

- WXSS 样式类名统一使用英文命名，规范统一；

- 禁用async/await，异步逻辑统一使用Promise