# 自然拼读训练工具 - 系统设计文档

> 子项目 1：英语学习闭环系统 - 自然拼读训练 MVP
> 日期：2026-05-23
> 状态：设计阶段

---

## 1. 项目概述

### 1.1 背景

为6岁女宝定制的英语学习工具，基于已有的牛津自然拼读(Oxford Phonics World 1-5)、牛津树(Stage 1-14)、剑桥英语真题(Starters/Movers/Flyers)、小猪佩奇剧本等学习资料，构建一套完整的学习闭环系统。

本文档聚焦第一个子项目：**自然拼读训练工具**。

### 1.2 目标用户画像

- 6岁女宝，约300常见词汇量（生活名词+高频词）
- 拼读 Level 1-5 约60%已教过，但掌握不熟练
- 痛点：拼读规则没内化，不能举一反三（apple vs take 分不清用哪个规则）
- 高频词混淆：人称代词(i/me/we/us)、时态(go/went)、单复数
- 字母偶尔混淆：b/p/d/q，大小写混写
- 已认识的单词能认读，但对拼读缺乏举一反三能力

### 1.3 成功标准

- 孩子能独立在 iPad 上完成每日学习任务（AI引导，减少家长参与）
- 通过系统化训练，建立自然拼读习惯，为后续默写打基础
- 家长能在 PC 端查看进度、定制任务、管理课程
- 课程体系松耦合，支持后续替换/自定义/分享

---

## 2. 技术选型

| 层级 | 技术 | 理由 |
|------|------|------|
| 前端框架 | React 18 + TypeScript | 移动端路径(React Native)、社区生态大、Framer Motion动画 |
| 构建工具 | Vite 5 | 快速HMR、React官方推荐 |
| 移动端UI | Ant Design Mobile | 触控友好、儿童大按钮适配 |
| 动画 | Framer Motion | 儿童交互动画、拖拽、手势 |
| 状态管理 | Zustand | 轻量、TS友好、无boilerplate |
| 路由 | React Router v6 | 标准选择 |
| 后端 | Python FastAPI | 轻量、AI/语音生态好、开发快 |
| 数据库 | SQLite (MVP) / MySQL (后续) | 本机部署简单，后续可迁移 |
| ORM | SQLAlchemy | Python标准ORM |
| TTS | edge-tts | 免费、质量好、批量生成 |
| PDF处理 | PyMuPDF (fitz) | PDF→图片、文字提取 |
| 音视频 | ffmpeg | 剪辑、格式转换 |
| 离线 | PWA + Service Worker + IndexedDB | 课程包下载后离线可用 |
| 部署 | Docker + Nginx (NAS) | 静态CDN + API反代 |

### 跨平台升级路径

- Web (当前) → Tauri 桌面端（React 直接支持）
- Web → React Native 移动端（逻辑复用70%+）
- 后续可考虑 Flutter 重写移动端UI层

---

## 3. 系统架构

### 3.1 三层数据架构

```
┌───────────────────────────────────────────────┐
│  📚 内容层 (Content) — 标准化学习原子单元       │
│  Word / Phoneme / PhonicsRule / Media          │
│  → 与任何课程体系无关，纯粹的英语学习素材       │
├───────────────────────────────────────────────┤
│  📋 课程层 (Course) — 组织和编排内容            │
│  Course → Unit → Lesson → LessonItem          │
│  → 可插拔：牛津/剑桥/自定义/按主题/按难度       │
├───────────────────────────────────────────────┤
│  📊 进度层 (Progress) — 用户学习状态            │
│  CourseEnroll → LessonRecord → ContentMastery  │
│  → 跨课程聚合掌握度，不绑定某个体系             │
└───────────────────────────────────────────────┘
```

### 3.2 部署架构

```
本机 192.168.11.157（核心服务 + 开发）
├── FastAPI (:8000) — 用户/课程/进度/任务调度/AI调用
├── 数据库 (SQLite/MySQL)
├── 预处理工具链 (Python脚本)
│   PDF→图片 / TTS生成 / 拼读拆分 / 视频剪辑
└── 前端开发环境 (Vite dev server :5173)

NAS 192.168.11.94（静态CDN）
├── Nginx (:80) — 统一入口
│   /          → /www/ (前端构建产物)
│   /assets/*  → /assets/ (音频/图片/视频/闪卡)
│   /api/*     → proxy_pass http://192.168.11.157:8000
│   /packages/* → /packages/ (课程包下载)
└── 存储卷: /www + /assets + /packages

客户端 (iPad / PC)
├── 访问: http://192.168.11.94
├── PWA离线: 课程包下载后离线可用
└── 联网同步: 进度上报 + AI功能
```

### 3.3 在线/离线策略

**离线可用（课程包下载后）：**
- 课程内容浏览（文字+图片+音频）
- 拼读学习（预处理好的拆分+音频）
- 测验练习（题目+答案都在本地）
- 学习进度记录（IndexedDB，联网后同步）

**需要联网：**
- AI 语音识别（跟读判断）
- AI 辅助引导（实时对话式引导）
- 进度同步到服务器
- 课程包下载/更新
- 家长远程查看进度

---

## 4. 数据模型

### 4.1 内容层（标准化学习原子，与课程体系无关）

```typescript
// 音素 — 发音的最小单位
interface Phoneme {
  id: string
  symbol: string              // IPA 符号，如 "ʃ"
  common_spellings: string[]  // 常见拼写方式，如 ["sh"]
  audio: string               // 音素发音音频路径
  video?: string              // 口型示范视频（可选）
  description: string         // 助记描述，如 "像让别人安静的声音"
}

// 单词 — 最基础的学习单元
interface Word {
  id: string
  word: string                // 如 "ship"
  ipa: string                 // 国际音标 "/ʃɪp/"
  meaning: string             // 中文释义
  pos: string                 // 词性 noun/verb/adj...
  phonics_breakdown: [{       // 自然拼读拆分
    letters: string           // 字母(组合)，如 "sh"
    phoneme: string           // 对应音素符号
    audio: string             // 该音素发音音频
  }]
  audio: {
    en: string                // 英文整词发音
    cn: string                // 中文释义发音
  }
  image?: string              // 配图
  tags: string[]              // 灵活标签，如 ["CVC","short-vowel","level1"]
}

// 拼读规则 — 字母(组合)到发音的映射规则
interface PhonicsRule {
  id: string
  pattern: string             // 字母/字母组合，如 "sh", "a_e"
  phoneme_id: string          // 引用 Phoneme
  position: "initial" | "medial" | "final" | "any"
  rule_description: string    // 规则说明
  examples: string[]          // 引用 Word ID 列表
  confusables: string[]       // 易混淆项，如 ["s","ch"]
  difficulty: number          // 1-5
}

// 媒体资源
interface Media {
  id: string
  type: "video" | "audio" | "image" | "flashcard" | "pdf"
  url: string
  title: string
  duration?: number           // 秒（音视频）
  source?: string             // 来源标识
  tags: string[]
}
```

### 4.2 课程层（可插拔的课程编排）

```typescript
// 课程 — 一套完整的学习体系
interface Course {
  id: string
  name: string                // 如 "牛津自然拼读 Level 1"
  type: string                // "oxford_phonics"|"oxford_reading_tree"|"cambridge_yle"|"custom"
  description: string
  cover_image?: string
  difficulty: number          // 1-5
  created_by: string          // "system" | user_id
  is_public: boolean          // 是否公开供其他用户导入
  units: Unit[]
}

// 单元 — 课程内的章节/主题
interface Unit {
  id: string
  course_id: string
  order: number
  title: string               // 如 "Unit 3: Short Vowels - a"
  theme?: string              // 主题标签
  lessons: Lesson[]
}

// 课时 — 单次学习的最小编排单位
interface Lesson {
  id: string
  unit_id: string
  order: number
  title: string
  type: "learn" | "practice" | "review" | "quiz" | "mixed"
  estimated_minutes: number
  items: LessonItem[]
}

// 课时内容项 — 引用内容层的原子单元
interface LessonItem {
  order: number
  content_type: "word" | "phonics_rule" | "media" | "quiz"
  content_id: string          // 引用内容层ID
  activity: "listen" | "watch" | "read" | "spell" | "choose" | "compare"
  config?: {                  // 活动配置
    show_breakdown?: boolean
    auto_play_audio?: boolean
    confusable_options?: string[]
    shuffle_letters?: boolean
  }
}
```

### 4.3 进度层（跨课程掌握度追踪）

```typescript
// 用户课程注册
interface UserCourseEnroll {
  user_id: string
  course_id: string
  enrolled_at: string         // ISO datetime
  current_unit_id: string
  current_lesson_id: string
  status: "active" | "paused" | "completed"
}

// 课时完成记录
interface LessonRecord {
  id: string
  user_id: string
  lesson_id: string
  course_id: string
  started_at: string
  completed_at: string
  score: number
  items_detail: [{
    item_id: string
    correct: boolean
    attempts: number
    time_spent: number        // 秒
  }]
}

// 内容掌握度 — 跨课程聚合
interface ContentMastery {
  user_id: string
  content_type: "word" | "phonics_rule" | "phoneme"
  content_id: string
  mastery: number             // 0-100 综合掌握度
  correct_streak: number
  total_attempts: number
  last_practice: string
  next_review: string         // SM-2 算法计算
  notes: string[]             // 易错点备注
}

// 每日任务
interface DailyTask {
  id: string
  user_id: string
  date: string
  source_course_id?: string   // 可选关联课程
  review_items: string[]      // ContentMastery IDs
  new_items: string[]         // LessonItem IDs
  free_explore: boolean
  parent_override?: object    // 家长定制覆盖
  status: "pending" | "in_progress" | "completed"
}
```

### 4.4 课程包格式（导入/导出/分享）

```
course-package.zip
├── manifest.json       // 课程元数据、版本、依赖声明
├── content/            // Word/PhonicsRule/Phoneme JSON
│   ├── words.json
│   ├── phonemes.json
│   └── rules.json
├── assets/             // 音频/图片（或URL引用清单）
│   ├── audio/
│   └── images/
├── curriculum/         // Course/Unit/Lesson 编排
│   └── course.json
└── README.md           // 课程说明
```

导入逻辑：内容层去重合并（同一个 word 不重复创建），课程层直接导入，资源按需下载。

### 4.5 内容引用索引（跨课程关联）

```typescript
// 单词/句子在课程中的出现记录 — 用于"融会贯通"跳转
interface ContentReference {
  id: string
  content_type: "word" | "sentence" | "phonics_rule"
  content_id: string              // 引用的 Word/Sentence/Rule ID
  course_id: string               // 出现在哪个课程
  unit_id: string
  lesson_id: string
  context_type: "text" | "image" | "audio" | "video"  // 出现的形式
  context_snippet: string         // 上下文片段，如 "The ship sailed away."
  page?: number                   // 教材页码（PDF来源时）
  timestamp?: number              // 音视频中的时间点（秒）
  highlight_range?: [number, number]  // 在句子中的字符位置
}

// 句子 — 单词的语境载体
interface Sentence {
  id: string
  text: string                    // 英文原句 "The cat sat on the mat."
  translation: string             // 中文翻译
  audio?: string                  // 整句发音
  words: [{                       // 句中单词引用
    word_id: string               // 引用 Word
    position: [number, number]    // 在句子中的起止位置
    form: string                  // 原文形态（如 "sat" 对应 word "sit"）
    grammar_note?: string         // 语法备注，如 "past tense of sit"
  }]
  source: {                       // 来源
    course_id?: string
    lesson_id?: string
    book_title?: string           // 如 "Peppa Pig S01E03"
    page?: number
  }
  tags: string[]                  // 如 ["past-tense","CVC","oxford-tree-stage3"]
}
```

**使用场景：**

1. **学单词时关联跳转** — 学 "ship" 时，查询 ContentReference 找到它出现在哪些课程/绘本/句子中，展示"这个词还出现在《The Snowman》第3页"，点击可跳转回顾
2. **句子中学语法** — "The cat sat on the mat" 中 sat 标注为 sit 的过去式，帮助孩子理解时态
3. **绘本→单词反向索引** — 读绘本时，点击任意单词可查看它的拼读拆分、其他出现位置
4. **复习时提供语境** — 复习单词不只是孤立闪卡，还能展示它在真实句子/故事中的用法

**索引构建时机：**
- 课程导入时自动扫描 Lesson 内容，建立 Word → ContentReference 映射
- 绘本/剧本导入时，NLP 分词后自动关联已有 Word
- 手动标注：家长在管理端可手动添加引用关系

---

## 5. 功能模块设计

### 5.1 MVP 功能模块

#### 5.1.1 拼读学习模块

**核心交互流程（以学习 "sh" 为例）：**

1. **展示规则卡片** — 大字展示 "sh"，自动播放音素 /ʃ/ 发音，配合口型动画提示
2. **示例单词拆解** — 展示 "ship"，逐个高亮字母组合并播放对应音素：sh→/ʃ/ → i→/ɪ/ → p→/p/，最后整词发音
3. **多个示例强化** — 依次展示 shop, fish, shell，强化 "sh" 在不同位置的识别
4. **AI引导语音** — TTS播放引导语："很好！sh 发 /ʃ/ 的音，像让别人安静的声音"

**设计原则：**
- 听+看为主，孩子被动接收阶段
- 每个规则配 3-5 个示例单词
- 字母组合作为整体高亮（sh 不拆开）
- 自动播放，孩子只需点"下一个"

#### 5.1.2 拼读测验模块

**题型1：听音选字母组合**
- 播放音素发音 → 4个大按钮选项（如 sh/ch/th/s）
- 选对 → 绿色✓ + 鼓励动画
- 选错 → 红色✗ + 正确答案高亮 + 重新播放音频

**题型2：乱序字母拼写**
- 播放单词发音 + 展示图片
- 展示打乱的字母块（字母组合作为整体，如 [i] [sh] [f]）
- 孩子点击排列顺序 → f-i-sh
- 正确后自动播放拆解发音

**题型3：易混淆项对比**
- 展示两个单词（如 cap vs cape），播放其中一个
- 问"你听到的是哪个？"
- 答对后展示规则提示（如"末尾有 e 时，a 读长音 /eɪ/"）

**设计原则：**
- 点选为主，避免全键盘输入
- 字母组合保持整体，降低难度
- 即时反馈 + 错误后重复强化
- 针对孩子实际痛点设计混淆项

#### 5.1.3 每日任务模块

**任务结构（15-20分钟）：**
1. 复习环节（3-5个已学规则/单词，快速闪卡式）
2. 新规则学习（1-2个新规则，完整学习流程）
3. 练习巩固（针对新学内容的简单练习）
4. 小测验（混合新旧内容，5-8题）
5. 奖励反馈（星星/徽章/进度条）

**任务生成逻辑：**
- 复习项：从 ContentMastery 中选 mastery < 80 且 next_review <= today 的内容
- 新学项：按课程编排顺序取下一个未学 Lesson
- 家长可覆盖：追加/替换/跳过某些内容

#### 5.1.4 进度仪表盘（家长端）

**功能：**
- 每日/周/月学习时长统计图表
- 各课程进度概览（百分比+当前位置）
- 薄弱点热力图（哪些规则/单词错误率高）
- 生词本管理（查看/删除/手动添加）
- 任务定制界面（拖拽调整、追加内容）

### 5.2 V2 功能模块（后续迭代）

#### 5.2.1 间隔复习（SM-2）
- 基于遗忘曲线自动调度复习时间
- 生词/易错项自动加入复习队列
- 闪卡式快速复习界面

#### 5.2.2 语音跟读
- Web Speech API 语音识别
- 单词/音素跟读 + 发音准确度反馈
- 可选功能，非核心依赖

#### 5.2.3 课程制作工具
- 向导式课程创建（选内容→编排→预览→发布）
- 批量导入单词（Excel/CSV/文本）
- AI自动生成拼读拆分+音标（可人工校对）
- TTS批量生成音频
- PDF教材→图片提取
- 视频/音频片段剪辑
- 课程包导出/发布/分享

---

## 6. 数据预处理 Pipeline

### 6.1 流程概览

```
素材导入 → 内容解析 → AI增强 → 人工校对 → 资源生成 → 课程编排 → 发布部署
```

### 6.2 各步骤详情

**Step 1: 素材导入**
- 输入：单词列表(txt/csv/excel)、PDF教材、音视频文件
- 支持指定本地路径或上传

**Step 2: 内容解析**
- PDF → 图片：PyMuPDF (fitz)，dpi=150
- 视频 → 片段：ffmpeg 按时间戳切割
- 文本 → 结构化：解析为 Word 列表

**Step 3: AI增强**
- 单词 → 音标(IPA)：规则引擎 + LLM 兜底
- 单词 → 拼读拆分：基于音素规则库自动拆分
- 中文释义生成：LLM 生成适合儿童理解的释义
- 易混淆项标注：基于发音相似度自动关联

**Step 4: 人工校对**
- 管理端展示 AI 生成结果
- 家长可修正拆分/释义/标注
- 支持批量确认和逐条编辑

**Step 5: 资源生成**
- TTS音频：edge-tts 批量生成（英文 en-US-AriaNeural，中文 zh-CN-XiaoxiaoNeural）
- 音素音频：从已有音频库匹配或单独生成
- 单词图片：AI生成 / 手动上传 / 从教材提取

**Step 6: 课程编排**
- 将内容组织为 Course → Unit → Lesson 结构
- 设定每个 LessonItem 的活动类型
- 向导式或手动编排

**Step 7: 发布部署**
- 静态资源 rsync 到 NAS /assets
- 课程数据写入数据库
- 可选：打包为课程包(.zip)供下载/分享

---

## 7. 设计原则总结

### 7.1 松耦合原则
- 内容层与课程体系完全解耦，同一个 Word 可被任意课程引用
- 更换/删除课程体系不影响内容层数据
- 版权隔离：删除课程编排即可，通用内容不受影响

### 7.2 课程生态设计方向
- 系统预置主流课程（牛津拼读/剑桥等），推荐用户优先使用
- 用户可自定义课程（按主题/难度/复习需求）
- 用户可发布课程供其他用户导入使用
- 后续可考虑版权授权合作

### 7.3 离线优先
- 课程内容预处理为静态资源，支持打包下载
- 离线状态下核心学习功能完全可用
- AI/语音识别等云服务功能为增强项，非核心依赖

### 7.4 渐进式开发
- MVP 先跑通核心学习+测验流程
- 后端按需加入（初期可纯前端+静态JSON验证交互）
- 功能逐步迭代：学习→测验→复习→语音→课程工具

### 7.5 儿童交互设计
- 大按钮、大字体、高对比度
- 触控优先（iPad），避免精细操作
- 即时反馈（动画+音效+鼓励语）
- AI语音引导，减少文字阅读依赖
- 字母组合保持整体，降低认知负担

---

## 8. 现有资源映射

| 资源 | 路径 | 用途 |
|------|------|------|
| 牛津自然拼读教材 | E:\牛津自然拼读课件+课程\01 电子教材\ | Level 1-5 PDF+音频+视频+闪卡 |
| 牛津自然拼读视频 | 同上 1.books_notebooks_audio-video\{1-5}\ | 每个字母/组合的教学视频 |
| 牛津拼读闪卡 | 同上 5.flash-cards\ | Letter Cards + Student Cards |
| 牛津树绘本 | E:\牛津树\牛津树1-14阶段PDF+音频\ | 阅读材料（后续模块） |
| 剑桥真题 | E:\真题{Stage} {N}\ | Starters/Movers/Flyers 测试 |
| 小猪佩奇剧本 | E:\小猪佩奇剧本台词\ | 听力/阅读拓展材料 |
| 已有工具代码 | D:\codes\MyProjects\easy-study\251228-words\ | 单词游戏+拼读数据+TTS工具 |
| 已有拼读数据 | 同上 phonics-data.json | 13691行音素+单词拆分数据 |

---

## 9. MVP 范围定义

### 包含
- [ ] 拼读学习模块（规则展示+单词拆解+音频播放）
- [ ] 拼读测验模块（3种题型）
- [ ] 每日任务模块（自动生成+家长可调）
- [ ] 家长进度仪表盘（基础统计）
- [ ] 预处理工具（牛津拼读 Level 1-2 内容导入）
- [ ] 部署（本机FastAPI + NAS Nginx）
- [ ] PWA 基础离线支持

### 不包含（V2+）
- 语音跟读/识别
- 间隔复习(SM-2)完整实现
- 课程制作向导
- 课程包分享/社区
- 外网访问/内网穿透
- React Native 移动端
- 绘本阅读模块
- 剑桥真题模块