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

Doc/PRODUCT-PRD.md

@@ -0,0 +1,336 @@
+# 开口英语（暂定名）首版产品 PRD
+
+> 版本：0.2｜2026-09-12  
+> 使用方式：个人自用、手机优先，支持 iPhone、Android 与 Mac 的中文英语学习工具  
+> 学习目标：按可用时间练习，逐步把英语用在生活中，追求稳定听懂、稳定被听懂；不承诺固定周数达标。
+
+## 1. 产品概述
+
+### 1.1 要解决的问题
+
+零基础成人通常不是缺资料，而是缺少三件事：知道自己该从哪里开始、每天有一条明确的学习路径，以及有机会把输入转成开口和写作。传统资料站提供大量音频、文章和语法说明，但用户容易收藏后放弃，也难获得个人化纠错。
+
+本产品提供按能力分级的短课。每节课围绕一个生活任务，完成“听懂—模仿—开口—阅读—写出—复习”闭环。AI 仅在用户实际输出后进行简短、可执行的反馈。
+
+发音目标是清楚、可理解、可完成任务，而非模仿特定地区口音；听力目标是理解当前阶段场景中的主要意思与关键细节，并能在没听清时继续沟通。
+
+每日内容生成、词句掌握判定、阶段出口任务与通向 B1/B2 的内容扩展，统一以 [学习引擎规格](LEARNING-ENGINE-SPEC.md) 为准。
+
+M1 范围、内容数据和异常验收以 [开发与验收约定](M1-IMPLEMENTATION-CONTRACT.md) 为准；A0 可执行门槛见 [A0 阶段标准](A0-STAGE-STANDARD.md)。下文 A1 场景是后续方向，不属于 M1。
+
+### 1.2 当前目标
+
+- M1 先建立自我介绍、简单问候和 A0 信息交流能力；掌握后再进入购物/点餐等 A1 内容，不以 4 周或固定课数解锁。
+- 让你在每个阶段通过核心课、变式任务和补救练习，逐步建立开口习惯；不以固定总课数作为目标。
+- 让每次练习结束时都能明确知道自己会说什么、下一步练什么。
+
+### 1.3 当前不做
+
+- 不以雅思、托福、四六级等考试提分为目标。
+- 不在首版提供高阶新闻阅读、商务谈判或开放社交社区。
+- 不把整套教材或外部网站内容直接搬入应用。
+- 不做登录注册、付费、消息推送、排行榜、多人协作、增长分析或上线运营。
+- 当前支持 iPhone、Android 与 Mac；Web、多人共享和自动跨设备同步不在 M1 范围。
+
+客户端、数据同步和 AI 调用的实现边界见 [技术架构](TECHNICAL-ARCHITECTURE.md)。
+
+## 2. 用户与使用场景
+
+| 用户 | 现状 | 需求 |
+|---|---|---|
+| 零基础职场成人 | 认识少量单词，羞于开口 | 从最简单且有用的句子开始，得到耐心纠错 |
+| 有基础但遗忘的成人 | 学过语法，听说困难 | 快速定位起点，恢复日常对话能力 |
+| 旅行/生活需求者 | 有明确近期出行或生活任务 | 在出发前完成点餐、问路、入住等演练 |
+
+首版默认用户为第一类。界面语言、解释和纠错均为简体中文；英语内容保持真实、自然、短小。
+
+## 3. 能力等级与升级规则
+
+| 等级 | 名称 | 核心能力 | 进入条件 |
+|---|---|---|---|
+| A0 | 起步 | 认识常用字母/声音，能说极短句 | 新用户默认起点或测评结果 |
+| A1 | 生存 | 用简单句完成固定生活互动 | A0 通过且 A1 内容就绪；M1 显示待提供 |
+| A2 | 日常 | 描述日常、计划与简单经历 | 首版仅显示“即将推出” |
+
+### 3.1 入门测评
+
+测评控制在约 3 分钟，共 3 项：
+
+1. 1 题听句选义；
+2. 1 题朗读 `Hello. My name is ...`，可跳过；
+3. 1 题回答 `What is your name?`，可用文字或录音。
+
+结果只给出建议起点和原因，不给“失败”标签。用户可随时选择“从更简单内容开始”。语音题不作为硬性分级依据，避免麦克风环境造成误判。
+
+### 3.2 阶段升级
+
+阶段升级不由完成课数决定。A0 必须达到固定核心词句门槛并通过两次不同题组的听说读写评估；初次见面对话仅是其中一部分。可提前评估但不得未通过就跳级。A1→A2 的旅行日模拟是后续方向，须先补齐 A1 标准才能启用。完整规则见 [学习引擎规格](LEARNING-ENGINE-SPEC.md)。
+
+## 4. 学习体验与信息架构
+
+### 4.1 主导航
+
+| 页面 | 用户要做什么 | 关键内容 |
+|---|---|---|
+| 首页 | 知道今天学什么 | 一张“今日任务”卡、到期复习、上次未完成课程 |
+| 学习 | 完成一节新课 | 情境、词句、听说读写任务 |
+| 对话 | 在安全的情境中开口交流 | 场景卡、语音/文字对话、对话总结 |
+| 复习 | 巩固个人薄弱点 | 忘记的词、说错的句、听错的音频 |
+| 我的 | 看得见进步 | 当前等级、掌握句型、练习记录、目标设置 |
+
+课程、阅读和对话中的英文均可点词或点短语查看当前语境下的中文意思、音频、短例句，并手动加入复习；短语优先于单词。查词卡不是独立主导航，关闭后回到原步骤。
+
+首页只突出一个主要按钮：`开始今天的 20 分钟学习`。对话场景由“对话”页管理；不设置独立的“场景”主导航，避免选择过载。
+
+### 4.2 新用户流程
+
+```text
+选择目标（生活 / 旅行 / 工作起步）
+    → 选择每日时间（10 / 20 / 30 分钟）
+    → 可选入门测评
+    → 得到起点与第一节课
+    → 完成一次开口练习
+    → 建立明日复习计划
+```
+
+### 4.3 每日学习循环
+
+```text
+到期复习与补救（按时间选任务）
+    → 教学段：预热 → 带帮助练习 → 受控对话 → 独立尝试
+    → 完成页：会说什么、明天复习什么
+```
+
+10 分钟模式按复习/补救 3 分钟、教学/续学 6 分钟、总结 1 分钟安排；20 分钟为 5+14+1，30 分钟为 8+20+2。教学额度包含预热、听说读写、课程内对话和独立尝试，不能再次加时。剩余时间不足时保存下一步骤，未完成技能留待续学。积压时减少新内容，规则见学习引擎。
+
+### 4.4 每日内容选择
+
+每日任务按预算从“到期复习、未完成课/主线新课、错误修复、短对话”选择，缺少到期项或错误项时不硬凑。AI 不能随机决定能力主线，只能生成通过校验的变式。具体优先级见 [学习引擎规格](LEARNING-ENGINE-SPEC.md)。
+
+每个包含新语言的教学段在听力前先提供 1–3 分钟“今天先认识”的词汇预热：只展示本段会用到的 3–6 个词或词块（不超过该段预算），逐项播放英文、显示当前句义中文与一个短例句，再完成一次轻量匹配/听辨。用户可跳过或回看；预热不是掌握测试，不能因看过词卡就增加掌握度或自动完成课程。
+
+## 5. 单课内容模板
+
+每个教学分段只解决一个明确任务，最多 8 个新词汇项、2 个主动产出句型、2 个新增理解用词块；不要求凑足新词。A0 每段约 10–15 分钟，数字/字母/星期等种子主题可拆段或分多天。对话额外新词另限每轮 1 个、整段 2 个，评估为 0。下表点餐是后续 A1 模板示例，M1 使用自我介绍等 A0 内容。
+
+| 步骤 | 形式 | 示例：在咖啡店点单 |
+|---|---|---|
+| 课前预热 | 词块卡 + 音频 + 轻量匹配 | `coffee`、`tea`、`I'd like ...` |
+| 情境导入 | 图片 + 10 秒音频 | 顾客走进咖啡店 |
+| 听懂 | 选择/点词 | 听 `What would you like?`，选择正确含义 |
+| 词句应用 | 把预热词放进句子，必要时回看 | 用 tea 替换 coffee，不重复整套释义卡 |
+| 跟读 | 逐句录音 | 跟读 `I'd like a coffee, please.` |
+| 阅读 | 4–6 句短对话 | 店员与顾客的订单对话 |
+| 输出 | 角色扮演 | AI 问：`What would you like?`，用户回答 |
+| 写作 | 改写/自由输入 | 将 coffee 改成自己的饮品 |
+| 独立尝试 | 撤掉句框、翻译和答案，换任务值 | 看新饮品图独立表达；可复用对话最后一轮 |
+| 结课 | 能力回顾 | “你现在能礼貌地点一杯饮料。” |
+
+### 5.1 固定的反馈格式
+
+写作和已确认的口语转写反馈均遵循以下顺序，首版一次最多指出一个问题；无错误时只给可选替换，不强行纠错：
+
+1. 先肯定已表达清楚的部分；
+2. 给出用户原句；
+3. 给出“正确版”；
+4. 有必要时给“更自然版”；
+5. 用不超过两句中文解释；
+6. 给一个替换词的小练习。
+
+示例：
+
+```text
+你说清楚了想喝咖啡，很好。
+你的句子：I want a coffee.
+更礼貌的说法：I'd like a coffee, please.
+在点餐时，I'd like... 比 I want... 更自然、礼貌。
+现在试试：I'd like a tea, please.
+```
+
+## 6. 初始主题库（持续扩展）
+
+下列主题是首轮内容，不是阶段总课数或升级门槛。用户是否进入下一阶段由出口任务、词句掌握和真实对话表现决定；未达标时，系统围绕薄弱点继续提供同阶段的变式练习与新情境。
+
+### A0：起步（1–10）
+
+| 编号 | 主题 | 课后能做什么 |
+|---:|---|---|
+| 1 | 你好，我是… | 打招呼并介绍姓名 |
+| 2 | 字母与拼写姓名 | 拼读自己的名字 |
+| 3 | 你好吗？ | 问候并简单回应 |
+| 4 | 数字与电话号码 | 分段学习 0–10 和虚拟三位号码片段 |
+| 5 | 这是什么？ | 说出常见物品名称 |
+| 6 | 我来自… | 介绍国家/城市 |
+| 7 | 我的家人 | 介绍一位家人 |
+| 8 | 今天星期几？ | 分段学习七天与 1–12 整点，不教日历日期 |
+| 9 | 我喜欢… | 表达一项喜好 |
+| 10 | A0 小对话 | 完成 45 秒自我介绍 |
+
+### A1：生存英语（11–30）
+
+| 编号 | 主题 | 课后能做什么 |
+|---:|---|---|
+| 11 | 在咖啡店点单 | 点饮料并表达礼貌需求 |
+| 12 | 在餐厅点餐 | 点餐、询问推荐 |
+| 13 | 结账与价格 | 询价、付款、确认金额 |
+| 14 | 买衣服 | 询问尺码、颜色、试穿 |
+| 15 | 超市购物 | 找商品、说数量 |
+| 16 | 问路 | 询问地点与方向 |
+| 17 | 打车 | 告知目的地并确认路线 |
+| 18 | 公交与地铁 | 买票、问站点、确认下车 |
+| 19 | 入住酒店 | 办理入住、说明预订信息 |
+| 20 | 酒店里的问题 | 要毛巾、报告房间问题 |
+| 21 | 在机场 | 办理值机、问登机口 |
+| 22 | 看病不舒服 | 说明简单症状、听懂基本建议 |
+| 23 | 预约时间 | 约见面、改时间 |
+| 24 | 打电话留言 | 留下姓名、号码和简短信息 |
+| 25 | 认识新朋友 | 询问职业、兴趣和居住地 |
+| 26 | 介绍日常生活 | 说作息和常做的事 |
+| 27 | 今天的天气 | 谈天气与穿衣建议 |
+| 28 | 周末计划 | 说将要做的事 |
+| 29 | 请求帮助 | 礼貌求助、感谢与回应 |
+| 30 | A1 生活挑战 | 完成 3 分钟多场景模拟 |
+
+## 7. 功能需求与验收标准
+
+### 7.1 分级与推荐
+
+- 系统根据测评、已完成课程和复习表现推荐下一课。
+- 用户可自主切换到低一级课程；切换不丢失原有进度。
+- 首页展示推荐原因，例如“你已掌握自我介绍，下一步练习数字”。
+
+验收：用户完成首课后，再次打开首页时能在一个主按钮内进入下一步，且无需浏览课程目录。
+
+### 7.2 听力与阅读
+
+- 音频支持正常/慢速播放、逐句重复及中英字幕切换。
+- A0 教学模式可显示中文辅助；独立听力题默认隐藏字幕和翻译，查看后仅记辅助练习。正式评估按 A0 标准限制提示。
+- 阅读题以理解意思和情境为主，避免孤立翻译题。
+- 教学中的英文词和词块可点开查词：显示当前句义、中文释义、播放、慢放和已学例句，可手动加入复习。动态释义未审核时须标明，不自动计入核心词汇。
+
+验收：用户在不离开课程或对话的情况下，可打开并关闭一个词/短语的查词卡；点 `from` 能看到“来自；从……”及 `I'm from Hong Kong.`。课程中查词不影响完成；独立练习和评估中先提示切换为练习，不能把查词后的正确答案算独立能力。
+
+验收：每课至少有 1 个听力理解任务、1 段不超过 6 句的可点击文本。
+
+### 7.3 口语
+
+- 用户可跟读、重录，并查看原音频和自己的录音。
+- 系统反馈已确认表达中的任务信息，提供示范与回听；不能仅凭 ASR 文字诊断发音或保证真人可理解度，不输出发音分数。
+- 角色扮演有明确身份、目标与 3–5 轮上限；用户卡住时可以查看提示。
+
+验收：每课至少一次录音输出和一次情境回答；用户即使识别失败也能看文字示范后继续完成课程。
+
+### 7.4 写作与 AI 纠错
+
+- A0 以排序、替换词和填空为主；从第 6 课起加入 1 句自由写作。
+- 第 5 课由排序过渡到看图写完整句；第 6–9 课逐步撤掉句框，第 10 课独立写姓名、地点、喜好并复练物品/时间句。前期填空不能作为完整句写作证据；具体任务见课程包。
+- AI 不因标点、大小写等小问题掩盖用户表达成功；先处理影响理解的问题。
+- AI 不编造用户未学过的复杂表达，建议要符合当前等级。
+
+验收：在线完成判定的自由写作有简短中文反馈与重写机会；正确表达不强行修改。断网或判定不确定时保存待反馈，不伪造判定，也不修改掌握度。
+
+### 7.5 复习
+
+- 按稳定词句 ID 与薄弱技能形成复习项；同一词句的不同题目合并证据，不重复生成核心项。技术失败不进入错题队列。
+- 四个复习检查点以各词句首次完成正式教学为起点，正常在第 1、3、7、14 天出现，不等待整课完成；预热和查词不触发此日程。
+- 复习按时间预算选任务，区分任务数与覆盖词句数；一题只为有直接证据的目标记账。最早到期项和近期错项轮流安排，积压时暂停推荐新段，用户可自主继续。
+- 单次遗忘先标记需复核并次日换题，保留掌握历史；复核失败才诊断降级，检查点最多退回一个，不统一重走四次。
+
+验收：用户在课程中写错句型后，次日首页的复习中能看到该句型的简短变式题。
+
+### 7.6 AI 对话练习
+
+AI 对话区分以下模式，不能将受控场景误做成无限聊天：
+
+| 类型 | 目的 | 典型时长 | 例子 |
+|---|---|---:|---|
+| 课程角色扮演（M1） | 巩固本课 1–2 个句型 | 通常 3–5 轮 | 介绍姓名和来自哪里 |
+| 独立受控场景（M1） | 在明确任务中复练已学内容 | 通常 3–5 轮 | 第一次见面、介绍物品 |
+| 自由主题对话（M2） | 更开放地迁移已学内容 | 后续定义 | 聊日常、旅行计划 |
+
+“对话”页提供场景卡片而非空白聊天框。用户选择场景、身份和难度后开始；系统在开场前用中文说明目标，例如“你是顾客。请点一杯自己喜欢的饮料，并询问价格。”
+
+每次对话应遵循以下流程：
+
+```text
+选择场景与难度
+    → 选择文字或语音输入
+    → AI 用当前等级范围内的英文开场
+    → 用户回答；可查看一个提示或重新说
+    → AI 自然回应并推进任务
+    → 达成目标或到达轮数上限（M1 最多 5 个用户回答轮）
+    → 对话总结、纠错与个人复习卡
+```
+
+#### 对话能力要求
+
+- 默认以语音优先；用户可随时切换文字输入，避免嘈杂环境阻断学习。
+- AI 在对话进行时优先理解和回应，不逐句打断纠错。只有表达无法理解、用户主动请求或当前关键句型错误时，才给一句简短提示。
+- 结束后给出三部分总结：`你完成了什么`、`一个最值得改进的表达`、`下次可尝试的新句子`。
+- 回复的词汇、句长和语速受当前等级约束；A0–A1 每轮只包含一个问题或任务。
+- 每个场景都有可衡量的完成条件，例如点餐场景须说出饮品、数量/规格（如适用）并完成确认。
+- 用户可使用“提示”“慢一点”“翻译”“重说”四个求助按钮；求助不会终止练习，但按规则标记辅助证据。
+- 用户可点 AI 消息中的词或短语查询，不离开当前会话；查词后 AI 不重复开场或丢失已回答的信息。
+
+#### 首批对话场景
+
+| 等级 | 场景 | 用户目标 | 完成条件 |
+|---|---|---|---|
+| A0 | 初次见面 | 介绍姓名与来自哪里 | 至少完成姓名、城市两项信息 |
+| A0 | 认识新同学 | 问候并问对方姓名 | 完成一问一答 |
+| A1 | 咖啡店 | 点饮料 | 说出饮品并礼貌确认订单 |
+| A1 | 餐厅 | 点餐与询问推荐 | 至少提出一项需求和一个问题 |
+| A1 | 问路 | 找到车站 | 问地点并复述关键方向 |
+| A1 | 酒店入住 | 办理入住 | 说明姓名、预订与入住需求 |
+| A1 | 约时间 | 与朋友约见 | 提出时间并达成确认 |
+| A1 | 小病不适 | 向药店工作人员说明症状 | 说明一个症状并回答一个追问 |
+
+#### 对话安全与质量边界
+
+- AI 的角色、目标和可使用的语言范围由场景配置控制；不得让模型自由偏离到高难度、攻击性或不适龄的话题。
+- AI 不假装真人，不提供医疗、法律、金融等高风险判断；看病场景仅训练语言表达，并提示用户寻求专业帮助。
+- 用户语音及转写须征得明确授权，提供删除入口，并避免将录音用于未说明的训练目的。
+- 低置信度的语音识别结果要允许用户编辑文字后再发送，不能直接判错。
+
+验收：A0 用户从进入场景到完成一次 3 轮语音/文字对话不超过 5 分钟；结束页必须产生至少 1 条可复习的个人化内容，且用户能一键再次练习同一场景。
+
+## 8. 内容规范
+
+- 所有对话先由英语母语编辑或高质量审核流程校验自然度。
+- 每个新词必须至少在听力、阅读和口语中的两个环节出现。
+- 同一课只引入一个主要语法点，解释限制为 80 字中文以内，并用对话例句说明。
+- 发音提示用可听示范与简短动作说明，音标可选展开；不使用汉字谐音作为标准，不仅凭转写诊断音素。
+- 语速、口音和文化背景保持多样，但 A0 优先清晰、慢速、标准化语音。
+
+## 9. 数据与进度
+
+为每位用户记录：当前等级、目标、课程完成状态、词汇/句型掌握度、听力正确率、常见写作错误、口语尝试次数和复习到期时间。进度页避免只显示“学了多少词”，应显示可完成的任务，例如“你已能用英语点餐”。
+
+## 10. 个人使用验收清单
+
+不追踪留存、活跃或增长数据。每周只用以下问题检查工具是否真的有帮助：
+
+- 我能否在不看中文提示时完成本周的 AI 情境对话？
+- 我是否能重说上周的关键句，并替换其中一个词？
+- 系统给出的纠错是否少而清楚，且我知道下一次该怎么说？
+- 学习记录是否准确保存了已完成的课程和需要复习的句子？
+
+## 11. 版本路线图
+
+### M1：A0 个人学习闭环
+
+完成 10 节 A0 种子课及必要分段、听说读写、基础 AI 写作反馈、受控对话、每日变式/补救、复习、掌握证据、进度及四技能出口评估；包含服务配置、离线降级和中断恢复。课程总量不限，未掌握持续同阶段补练。通过 A0 后若 A1 内容未就绪，显示待提供。完整范围与验收见《开发与验收约定》。
+
+### M2：完整个人学习路径
+
+在 M1 闭环基础上新增 A1 能力地图、核心清单、种子主题及出口评估，扩展生活场景与自由主题对话；可增加加密导出/导入。M1 已有的复习、纠错、场景页和进度不重复列为 M2 首次交付。
+
+### M3：个性化与 A2
+
+加入更细的能力诊断、学习计划调整、旅行/工作目标路径，以及 A2 课程。在你完成 A1 路径并确认现有内容和反馈确实满足个人学习需要后再启动。
+
+## 12. 版权与内容来源
+
+BBC Learning English、学习资源合集和新概念英语可用于研究信息架构、学习方法或作为外链推荐。不得未经授权抓取、复制、改编或在应用内重新分发它们的文本、音频、视频和练习。
+
+首版课程、对话、插画与音频使用原创或许可覆盖当前用途的素材；纳入应用时即记录来源、许可范围和署名要求，不以未来上线为前提。