feat: complete kouyu_english app codebase, A0 specifications and .gitignore

2026-09-15 15:58:33 +08:00
parent b8072673d8
commit 37c86f7ecb
136 changed files with 19042 additions and 0 deletions
@@ -0,0 +1,159 @@
+# 技术架构：Flutter 手机优先、支持 Mac 的个人学习工具
+
+> 当前目标：iPhone、Android 手机与 Mac；个人自用；无需发布、登录或自建服务器。  
+> 原则：手机优先、本地优先；每台设备都可以独立完成全部学习功能。
+
+本文技术方向不代表已验证实现。M1 的范围、内容结构、证据实体及异常行为以 [开发与验收约定](M1-IMPLEMENTATION-CONTRACT.md) 为准；课程总量不限，阶段核心清单固定版本。
+
+## 1. 推荐技术路线
+
+使用 **Flutter / Dart** 构建 iPhone、Android 与 macOS 客户端，共享课程、学习引擎和对话状态代码；布局以手机为第一优先级，Mac 只是更宽的阅读和练习界面。
+
+| 层级 | 方案 | 用途 |
+|---|---|---|
+| 客户端 | Flutter / Dart | iPhone、Android 优先界面，macOS 适配 |
+| 状态管理 | Riverpod 或同类单向状态方案 | 课程步骤、录音状态、对话状态、复习队列 |
+| 本地数据 | SQLite（Drift） | 证据、掌握、复习、会话、评估、进度和临时词条分表保存；旧版完整快照只作迁移/恢复回退，正常写入不再生成快照 |
+| 课程内容 | 内置 JSON | A0 课程、场景、词句、词条释义、练习规则 |
+| 录音与播放 | Flutter 跨平台音频插件 + 原生适配 | 录音、回放、慢速播放、音频缓存 |
+| AI 对话 | 云端模型 API 或本地模型 | 受控情境对话、纠错、每日变式 |
+| 语音转写 | 云端转写或各平台原生语音能力 | 将用户英语录音变成可确认文字 |
+| 英文朗读 | 跨平台 TTS 或云端语音合成 | 播放 AI 的英语回复和标准示范音 |
+| 密钥保存 | 平台安全存储 | iOS Keychain、Android Keystore、macOS Keychain |
+
+## 2. 手机优先原则
+
+- 单手操作：录音、重说、提示等核心按钮位于手机屏幕下方。
+- 一屏一个任务：课程和对话不要求用户滚动查找下一步。
+- 断网可继续内置课程、本地判题、学习记录、已有音频和模板复习；AI 动态生成、在线对话/反馈及云端语音需网络。原生 STT/TTS 离线可用性须逐设备探测；缺音频的听力题与开放答案反馈留待补做。
+- 声音可选：公共场合可切换为文字输入与静音阅读，不应阻止完成练习。
+- Mac 复用：Mac 端展示同一课程和本机进度，可更适合阅读、输入和查看历史，不重新设计一套学习流程。
+
+## 3. 是否需要后台
+
+不需要自行部署远程后台。
+
+```text
+iPhone / Android / Mac App
+├─ 本地课程 JSON
+├─ 本地学习数据库
+├─ 本地录音与音频缓存
+└─ 通过可切换的 AI 提供商调用对话 / 转写 / 语音服务
+```
+
+### 3.1 跨设备同步
+
+M1 不做自动跨设备同步。每台设备保存自己的学习记录，但都内置相同课程并可独立使用。
+
+如需在手机开始后在 Mac 继续，可在后续版本增加“加密导出/导入学习进度”。导出的内容包括：
+
+- 当前课程和步骤；
+- 词句掌握状态与复习到期时间；
+- 对话文字摘要、错误项与重说句；
+- 偏好设置；
+- 不包含原始录音。
+
+原始录音默认只保留在产生它的设备，以节省空间并减少隐私暴露。若以后必须自动同步，可选择用户自有的云盘同步或小型后台代理；这不属于 M1。
+
+### 3.2 AI 提供商配置与网络请求
+
+个人自用时，模型服务密钥或兼容代理 Token 可分别保存在 iPhone、Android 和 Mac 的安全存储中，由客户端直接调用选定的 AI 服务。不要把密钥写进课程 JSON、源代码或可分享的配置文件。
+
+这只适用于你自己的设备和开发构建。若未来发布给他人使用，必须改为通过后台代理请求，以保护密钥、控制成本和处理滥用。
+
+客户端只依赖统一的 `AIProvider` 接口，而不将课程逻辑写死到单一服务商：
+
+```text
+AIProvider
+├─ GeminiProvider
+├─ OpenAIProvider
+└─ OpenAICompatibleProvider
+```
+
+每个提供商配置包含：提供商类型、模型名、接口地址、Token 和能力开关（文字对话、转写、语音）。设置页只显示当前选中的提供商；切换提供商不影响本地课程、掌握状态和复习队列。
+
+### 3.3 OpenAI 兼容反代（CLIProxyAPI）
+
+CLIProxyAPI 可作为 `OpenAICompatibleProvider` 的可选接口地址，用于文字情境对话、课程变式、纠错与结构化返回。它不是 M1 的唯一依赖；不可用时可切换到 Gemini API 或 OpenAI API。
+
+使用前必须满足：
+
+- 手机和 Mac 都能访问该地址。手机中的 `localhost` 指向手机本身，不能访问 Mac 上运行的反代；需使用可访问的局域网地址或有效 HTTPS 地址。
+- 反代须通过 App 的地址/鉴权、选定模型短文本及结构化返回测试；流式可选，可用非流式降级。测试成功仅证明当前文字能力，不证明语音或全部兼容能力。
+- 反代 Token 仅保存在平台安全存储；不得使用网页 Cookie、账号密码或 OAuth 会话作为 App 凭据。
+- 如果反代基于消费者订阅的登录态或令牌，使用前须自行确认授权方式与相关服务条款。
+
+反代先只承担文字 AI。转写优先设备原生能力，朗读优先设备 TTS；设备权限、英语语言包与实际可用性验证通过后才能运行对应语音流程。文字降级允许继续学习，但不能代替口语/听力达标。
+
+## 4. M1 数据模型
+
+下图仅为概览。实现必须补充 StageDefinition、AbilityNode、Task/Asset、AttemptEvidence、StudySession、StageAssessment 与 ProviderConfiguration，字段和事务约束见《开发与验收约定》第 3 节。掌握度应能从有版本的分技能证据重算，AI 不直接写入升级状态。
+
+```text
+Course
+  └─ Lesson
+      ├─ vocabulary / patterns
+      ├─ listening / reading / writing tasks
+      └─ dialogue scenario and completion rules
+
+LexiconEntry
+  ├─ word or phrase, contextual Chinese meaning and example
+  ├─ audio reference and approval/source status
+  └─ related ability / vocabulary / pattern IDs
+
+LearnerProfile
+  ├─ current level and current lesson
+  ├─ daily study duration
+  └─ preferences (voice, subtitles, speed)
+
+MasteryItem
+  ├─ word or sentence pattern
+  ├─ state: new / recognize / recall / use / master
+  ├─ success and failure history
+  └─ next review date
+
+SavedWord
+  ├─ lexicon entry and saved time
+  └─ optional low-priority review state
+
+ConversationSession
+  ├─ scenario, turns and task progress
+  ├─ transcript summary
+  ├─ one improvement sentence
+  └─ review item
+```
+
+## 5. M1 的 AI 提供商与模型组合
+
+ChatGPT 与 Gemini 的消费者订阅可用于手动编写课程、检查内容和测试提示词，但不能直接作为 Flutter App 的自动调用额度。App 需要配置各自的开发者 API Key；订阅与 API 计费/额度分开处理。
+
+文字 AIProvider、SpeechRecognizer、SpeechSynthesizer 分别抽象；选择文字代理不意味着其也支持语音。M1 手动选择一个文字提供商，不同时调用多家或自动切换付费服务。下表为候选配置，模型名、额度及价格未在本次文档修订中联网验证，使用时以账号实际能力和连接测试为准，不把免费额度作为运行保证。
+
+| 能力 | M1 默认方案 | 可切换方案 | 说明 |
+|---|---|---|---|
+| 情境对话、课程变式、纠错、结构化 JSON | Gemini API 免费层（先用于个人原型） | OpenAI API 的 GPT-5 mini | 两者均须各自 API Key；先用已有 Google 账号可访问的免费额度验证流程，额度或质量不够时切换 OpenAI |
+| 兼容反代文字对话 | 不默认启用 | CLIProxyAPI 的 OpenAI 兼容地址 | 在设置中手动填写 Base URL、Token 和模型名；只在接口能力与授权边界明确时启用 |
+| 英语语音转写 | 设备原生语音识别 | OpenAI API 的 GPT-4o mini Transcribe | 先避免增加 API 成本；低可信度时必须允许确认、修改或重说 |
+| 英文朗读 | 设备 TTS | 云端语音合成 | M1 优先本机朗读，减少成本并支持基础离线使用 |
+| 实时全双工语音 | 暂不使用 | 后续单独评估 | 当前采用 3–5 轮的轮流对话，实时打断不是 M1 需求 |
+
+每次 AI 对话都应传入当前等级、场景、允许词句、用户已回答内容和任务完成条件；不要用模型决定课程顺序。模型用量主要来自对话和反馈，因此应限制为 3–5 轮短对话，并缓存已生成的课程音频和练习变式。
+
+官方参考：[OpenAI API Key 快速开始](https://developers.openai.com/api/docs/quickstart)、[GPT-5 mini](https://developers.openai.com/api/docs/models/gpt-5-mini)、[OpenAI API 定价](https://developers.openai.com/api/docs/pricing)、[Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key)、[Gemini API 计费](https://ai.google.dev/gemini-api/docs/billing)。
+
+## 6. M1 实现顺序
+
+1. 完成一课听说读写、本地证据与恢复流程。
+2. 加入文字 AI 对话、结构校验、反馈与本地降级。
+3. 加入 TTS、录音、语音转写与确认；分别记录听说读写证据。
+4. 完成每日推荐、复习、变式生成、A0 出口评估与全部种子内容审校。
+5. 完成 iPhone、Android 真机及 macOS 同流程验证，覆盖《开发与验收约定》的异常测试。加密导出/导入留到 M2。
+
+## 7. 当前不做
+
+- 自建后端、账号、公开用户数据库；
+- Web、多人共享、社交匹配与自动跨设备同步；
+- 支付、订阅、通知、运营分析；
+- 云端长期保存原始录音；
+- 实时全双工电话式 AI 通话。
+- 加密导出/导入、个性化音素诊断；前者留到 M2，后者须另行验证。