进行中移动端
AI English Coach
AI 英语教练 —— AI 英语学习 App
基于 FastAPI + Flutter 的 AI 英语学习 App：AI 口语陪练、SM-2 单词复习、阅读助手、作文批改、CET 全题型训练与学习统计，语音支持本地 ASR 与 TTS。
角色 独立开发（项目规划 / 后端 / Flutter 前端 / 部署 / 测试与文档）
- Python
- FastAPI + Uvicorn
- SQLAlchemy 2（异步）
- Pydantic v2
- JWT（access + refresh）
- DeepSeek / OpenAI 兼容 LLM（对话 / 纠错 / 评分 / 分析）
- faster-whisper 本地 ASR（可切云端）
- Edge TTS（内存 + 磁盘缓存）
- 还有 12 项技术
概览
基于 FastAPI + Flutter 的 AI 英语学习 App（Android），覆盖 CET-4 / CET-6 备考与日常英语学习：AI 口语陪练（DeepSeek 对话 + 语法纠错 + SSE 流式）、单词学习（SM-2 间隔复习 + 多题型测验 + 生词本）、阅读助手、作文批改、学习统计与学习计划、语音（ASR / TTS / 发音评测）、CET 全题型专项训练与数据备份。
规模为 19 个后端路由模块、88 个接口、26 张表、31 个 Flutter 页面；后端已部署到云服务器，App 内可随时切换服务器地址。
问题
主流备考 App 多是「题库 + 背单词」，缺少能对话、能纠错、能给反馈的 AI 教练；市面 AI 口语产品价格高，且不针对四六级备考场景。
学习数据分散在多个 App：背单词一个、听力一个、作文一个，无法形成「计划 → 练习 → 统计 → 调整」的闭环。
语音能力往往依赖云端付费接口，成本与隐私都不可控。
目标
做一款能日常使用的 AI 英语教练 App：既覆盖 CET 全题型备考，也支持日常英语学习场景。
AI 能力可插拔、可本地化：LLM 可切换、语音转写支持本地 Whisper、语音合成走 Edge TTS。
工程可维护：后端 API 化并配文档（88 接口），移动端服务器地址可配置，前后端都有可运行的测试。
方案
后端把所有能力做成 API 化的 19 个路由模块，业务逻辑集中在 18 个 Service 层，出入参统一由 Pydantic 校验、异常由全局处理器统一返回。
AI 能力做成可替换的两条通道：LLM 走 OpenAI 兼容协议（DeepSeek / OpenAI 只改配置），语音转写支持本地 faster-whisper 与云端切换，TTS 用 Edge TTS 并加内存 / 磁盘缓存。
移动端把 API 地址做成三级优先级（App 内设置 > 编译期 --dart-define > assets 默认值）并提供连接测试，解决模拟器、真机与云服务器三种环境地址不同的问题。
架构
Flutter Android App（Provider 状态管理 / GoRouter 路由 / Dio HTTP）→ HTTP（JSON / SSE 流式 / multipart 音频上传）→ FastAPI 后端（:8002，API 基础路径 /api/v1）：19 个路由模块（auth / chat / vocabulary / reading / writing / stats / plan / profile / speech / cet_* / backup / reminder / server 等）→ 18 个 Service 业务层 + Pydantic schema 校验 → SQLAlchemy 2 异步 ORM（26 张表，SQLite 单文件数据库）；AI 服务层包含 DeepSeek / OpenAI（可切换）、faster-whisper（本地）与 Edge TTS（含磁盘缓存）；词库导入工具支持 CET4 / CET6 / 考研 / IELTS / TOEFL 约 2500 词。
AI 能力可插拔，语音优先本地化
- 背景
- 语音与对话全部依赖云端付费接口时，成本与隐私都不可控。
- 选择
- LLM 走 OpenAI 兼容协议可切换；ASR 支持本地 faster-whisper 与云端双通道；TTS 用 Edge TTS + 缓存
- 原因
- 把可替换的部分抽象出去，成本与隐私可以选择，换模型只改配置。
- 考虑过的方案
- 全部使用云端 AI 服务
- 对话用云端 LLM、语音转写用本地模型
为 AI 失败设计降级路径
- 背景
- AI 接口可能不可用，若直接报错会导致页面不可用。
- 选择
- AI 不可用时按用户弱项生成兜底建议，并把该场景写成测试用例
- 原因
- 功能不白屏比每次都拿到 AI 结果更重要。
API 地址三级优先级 + 连接测试
- 背景
- 模拟器、真机、云服务器三种场景访问后端的地址各不相同，写死任何一个都会让其它场景不可用。
- 选择
- App 内设置 > 编译期 --dart-define > assets/config 默认值，并提供连接测试页
- 原因
- 地址可以在运行时切换，排查连接问题也不必重新打包。
后端错误文案统一映射
- 背景
- 后端抛出的英文错误直接显示给用户不友好，而前端硬编码中文又难以维护。
- 选择
- 后端返回的英文错误经 server_messages 统一本地化（含变量占位），UI 文案收敛到 AppStrings
- 原因
- 文案只在一处维护，并补 4 个单测覆盖中英文与兜底分支。
技术栈
后端
- Python
- FastAPI + Uvicorn
- SQLAlchemy 2（异步）
- Pydantic v2
- JWT（access + refresh）
AI
- DeepSeek / OpenAI 兼容 LLM（对话 / 纠错 / 评分 / 分析）
- faster-whisper 本地 ASR（可切云端）
- Edge TTS（内存 + 磁盘缓存）
前端
- Flutter 3.38（Android，Material 3）
- Provider 状态管理
- GoRouter
- Dio
- fl_chart 图表
- shared_preferences / sqflite / flutter_secure_storage
- flutter_local_notifications
数据库
- SQLite（26 张表）
- 词库导入工具（CET4 / CET6 / 考研 / IELTS / TOEFL 约 2500 词）
DevOps 与基础设施
- Gradle + Kotlin DSL
- 一键打包脚本 build_apk.bat
- 云服务器后端部署
基础设施
- 云服务器部署（后端 API）
- release APK 构建
- 本地 Whisper 模型（体积受控，不进版本库）
技术亮点
AI 能力可插拔
LLM 走 OpenAI 兼容协议（DeepSeek / OpenAI 切换只改配置），ASR 支持本地 faster-whisper 与云端双通道，TTS 用 Edge TTS + 内存 / 磁盘缓存避免重复合成。
教育算法落地
SM-2 间隔复习调度学习节奏；CET 写作按 15 分制批改、口语模拟四维评分，结果都回流到统计与画像。
流式体验与统一错误处理
AI 对话走 SSE 流式输出；前端 Dio 拦截器统一处理 401 跳登录 / 500 提示 / 网络异常。
失败可降级
AI 不可用时按用户弱项生成兜底建议（测试专门覆盖 ai fail fallback 场景），功能不白屏。
移动端工程化
API 地址三级优先级（App 内设置 > 编译期 --dart-define > assets/config 默认值）并支持连接测试；Gradle + Kotlin DSL 一键出 release APK。
文案与错误治理
所有 UI 文案收敛到 AppStrings，后端返回的英文错误经 server_messages 统一本地化（含变量占位），前端不再硬编码中文。
难点与取舍
语音链路打通
- 问题
- 本地 Whisper 模型与语音文件体积大，直接入库会拖垮仓库；TTS 每次实时合成也有额外延迟。
- 做法
- 部署本地 Whisper 并控制模型体积（模型与语音文件用 gitignore 排除），TTS 加缓存避免重复合成，发音评测用「识别文本对比 + AI 建议」实现。
- 结果
- 语音能力可用且成本可控。
AI 依赖不可靠
- 问题
- AI 接口失败会让相关页面不可用。
- 做法
- 为 AI 调用设计降级路径（AI 失败时按弱项返回兜底目标），并把该场景写成测试用例。
- 结果
- 接口挂掉也不会导致页面不可用。
学习数据一致性
- 问题
- 学习计时、统计口径与备份恢复涉及多处数据。
- 做法
- 学习计时在前后台切换时自动暂停；统计按周 / 月 / 日历多口径聚合；一键备份 / 恢复覆盖全部学习数据。
- 结果
- 统计数据与备份保持一致。
移动端连接环境复杂
- 问题
- 模拟器、真机、云服务器三种场景的 API 地址各不相同。
- 做法
- 三级优先级的地址解析 + App 内连接测试 + 服务器设置页。
- 结果
- 切换环境不需要重新打包。
后端错误文案本地化
- 问题
- 后端抛出的英文错误要显示成中文。
- 做法
- 用 server_messages 统一映射（含带变量的模板），并补 4 个单测覆盖中英文与兜底分支。
- 结果
- 错误提示统一为中文，且分支有测试覆盖。
接口规模膨胀后的可维护性
- 问题
- 88 个接口 / 26 张表下，如果业务逻辑散在路由里会难以维护。
- 做法
- 用 Service 层承载业务、Pydantic 统一出入参、全局异常处理器统一错误响应。
- 结果
- 路由保持轻薄，业务逻辑集中可测。
权衡取舍
语音能力实现方式
选了 本地 Whisper + Edge TTS + 缓存，而不是 全部依赖云端语音接口 —— 成本与隐私更可控，也减少对外部服务的强依赖。
代价：需要控制模型与语音文件体积（用 gitignore 排除，不进仓库与安装包）。
AI 不可用时的行为
选了 按弱项返回兜底建议，而不是 直接提示失败 —— 学习类应用的核心页面不应因为外部接口波动而不可用。
代价：需要额外维护兜底逻辑并为其补测试。
数据存储方案
选了 SQLite 单文件数据库，而不是 引入独立数据库服务 —— 单用户学习类应用的写入量与并发都很低。
代价：多实例水平扩展受限，需要随规模变化再评估。
结果
规模：后端 19 个路由模块、88 个接口、26 张表（17 个模型文件、18 个 Service）；Flutter 31 个页面。
后端测试：冒烟脚本 8/8 全部通过（本次实测运行，覆盖画像、目标、AI 建议、缓存、计划调整与 AI 失败降级）。
前端测试：flutter test 12 个用例全部通过（本次实测：服务端文案本地化 4 个 + 组件 / 流程 8 个）；flutter analyze 0 error / 0 warning（134 条 info 级 lint 建议）。
构建：release APK 构建成功（app-release.apk 57.5 MB，BUILD_EXIT=0）。
部署：后端已上线云服务器并在线（在线 API 文档 https://english.myiskg.com/docs ，健康检查 https://english.myiskg.com/health 返回 healthy；线上 OpenAPI 暴露 80 条路径 / 90 个操作），App 内可随时切换服务器地址。自 2026-09-24 起启用 HTTPS。
词库：内置 CET4 / CET6 / 考研 / IELTS / TOEFL 约 2500 词导入工具。
收获
AI 相关功能必须显式设计失败路径：把「AI 不可用」当成正常分支处理并写进测试，页面才不会因为外部接口波动而不可用。
移动端的环境差异要在一开始就抽象掉：模拟器、真机与服务器三种地址用优先级解析处理，比后期逐个改配置可靠。
文案与错误消息应该集中维护：统一收敛到 AppStrings / server_messages 之后，本地化与改动都不再依赖搜索替换。
截图
登录页（真机运行截图） 
服务器设置：API 地址与连接测试 
在线 API 文档（按模块分组的 88 个接口） 
首页仪表盘 
个人中心 
单词学习（SM-2 间隔复习）