一个围绕 小鹤双拼 打造的网页练习项目，覆盖单字、词组、文章训练，以及统计分析、历史追踪、云同步与正式后端支撑。
小鹤双拼打字练习：单字 / 词组 / 文章、实时统计、错字分析、邮箱登录同步。
flypy-typing 是一个面向小鹤双拼用户的练习平台，当前采用 React 19 + TypeScript + Vite 构建前端，并已接入 FastAPI 正式后端骨架 作为云同步与内容服务基础设施。
它既可以作为纯前端练习工具独立运行，也可以在联调正式后端后提供完整的账号同步体验，包括邮箱验证码登录、设置同步、练习记录同步、错字本同步，以及云端文章拉取。
适合人群：
- 想系统熟悉小鹤双拼键位和编码规则的新手
- 想提升速度、准确率和稳定性的进阶用户
- 想通过错字统计和专项练习做针对性提升的用户
- 希望继续扩展内容服务、认证体系和后台能力的开发者
单字练习：适合记忆编码、熟悉按键和提升基础准确率词组练习：覆盖更接近日常输入的节奏与联想文章练习：用于长文本连续输入、节奏控制和稳定性训练
- 支持
随机、顺序、困难字等常规出题方式 - 支持
专项声母、专项韵母等针对性训练 - 支持
60s / 180s / 300s限时练习，适合做速度冲刺与稳定性测试 - 支持多音字上下文判定与提示越界修复后的更稳定训练逻辑
- 实时展示速度、准确率、进度、连击等核心指标
- 支持键位图高亮，帮助建立音节到键位的映射
- 集成音效反馈与音量调节，强化输入节奏感
- 结果面板提供速度等级、完成反馈和练习总结
- 持久化保存练习记录与高频错字数据
- 历史面板支持近期趋势查看，便于观察速度与准确率变化
- 错字统计可反向支持后续专项训练和复盘
- 支持拼音显示、字号、音量、深色模式等界面与输入偏好设置
- 支持统一的设置弹窗与历史弹窗交互行为，减少操作割裂感
- 支持邮箱验证码登录
- 支持云端设置同步
- 支持练习记录同步
- 支持错字本同步
- 支持云端文章列表拉取，后端不可用时自动回退到本地预设文章
以下内容基于最近一批关键提交整理，反映当前主线能力而不是完整变更日志。
feat: 初始化 FastAPI 正式后端骨架- 项目新增
backend/目录，作为正式业务后台入口 - 后端已预置认证、练习数据、内容题库、管理 API、AI 预留等模块骨架
- 本地联调方式已从旧 Node 原型路线转向 FastAPI + Docker Compose 方案
feat: 接入前端云同步基础设施- 前端新增 API 客户端、认证状态、云文章状态等基础模块
- 设置、练习记录、错字本可以与后端进行同步
- 云端文章列表可在应用启动后自动加载
feat: 新增登录同步入口与认证弹窗- 顶部导航加入登录同步入口
- 新增认证弹窗，支持邮箱验证码登录
- 登录后可自动拉取个人信息与云端配置
fix: 统一历史与设置弹窗交互行为- 历史记录与设置面板的打开、关闭与覆盖关系更一致
- 便于后续继续扩展更多弹窗型功能而不引入交互冲突
chore: 移除旧 Node 原型后端- README 和开发说明应以正式后端方案为准
- 当前仓库的主要后端入口是
backend/，不是旧原型服务
当前仓库已补充多张界面截图，下面按使用场景展示核心界面。
- 展示完整主工作区，包括顶部入口、键位图、练习区和底部统计栏
- 适合快速理解应用的整体布局与默认操作路径
- 更聚焦输入训练区域，便于观察当前题目、输入反馈与界面层次
- 可直观看到练习模式切换后主区域的展示效果
- 展示练习参数、显示偏好、音效音量、深色模式等配置入口
- 适合让用户预先了解可调节项，而不是进入页面后再逐个试探
- 展示历史练习记录、趋势变化和错字复盘相关内容
- 体现项目不仅关注即时输入，也支持长期训练追踪
- 展示邮箱验证码登录入口和云同步相关交互
- 对应当前仓库已接入的正式后端联调能力
KeyboardMap：帮助建立小鹤双拼编码与键位之间的映射TypingArea：承载单字、词组、文章三类核心训练内容StatsBar：在练习进行中持续反馈速度、准确率、进度和连击SettingsPanel：集中管理训练模式、显示偏好和音效配置HistoryPanel：用于训练后的趋势复盘和错字分析AuthPanel：负责邮箱登录、云同步入口与账号联动体验
适合本地体验输入练习、界面与大部分本地功能。
- 安装依赖
npm install- 启动开发服务器
npm run dev- 构建生产版本
npm run build- 本地预览构建结果
npm run preview- 执行代码检查
npm run lint适合验证邮箱登录、云同步、云端文章和正式接口。
- 安装前端依赖
npm install- 安装后端依赖
npm run backend:install- 启动后端依赖服务
npm run backend:compose- 执行数据库迁移
npm run backend:migrate- 启动 FastAPI 开发服务
npm run backend:dev- 启动前端开发服务器
npm run dev后端补充说明见 backend/README.md。
- 打开页面后选择练习模式：单字、词组或文章。
- 根据目标调整练习参数，例如出题方式、数量、限时模式、音效和显示选项。
- 直接键盘输入即可开始练习，实时查看速度、准确率、进度和连击。
- 练习结束后查看结果面板，并结合历史记录与错字统计做复盘。
- 如需跨设备同步，可点击右上角登录入口，通过邮箱验证码登录云端账号。
| 命令 | 说明 |
|---|---|
npm run dev |
启动 Vite 开发服务器 |
npm run build |
先执行 TypeScript 构建，再输出生产包 |
npm run preview |
本地预览生产构建结果 |
npm run lint |
执行 ESLint 检查 |
| 命令 | 说明 |
|---|---|
npm run backend:install |
安装 backend/ Python 依赖 |
npm run backend:compose |
通过 Docker Compose 启动后端依赖服务 |
npm run backend:migrate |
执行 Alembic 数据库迁移 |
npm run backend:dev |
启动 FastAPI 开发服务 |
- 环境变量模板位于
backend/.env.example - 详细启动说明位于 backend/README.md
- Swagger 文档默认地址为
http://localhost:8000/docs - OpenAPI 描述默认地址为
http://localhost:8000/openapi.json - 邮箱验证码发送依赖 SMTP 配置，未配置时无法完成真实邮件登录链路
flypy-typing/
├─ backend/ # FastAPI 正式后端（认证 / 内容 / 练习 / 管理 / AI 预留）
├─ docs/ # 文档与预览资源
├─ public/ # 前端静态资源
├─ server/ # 其他服务端实验目录，非当前主线后端入口
├─ src/
│ ├─ api/ # 前端 API 客户端与云同步请求
│ ├─ components/
│ │ ├─ Auth/ # 登录与认证弹窗
│ │ ├─ KeyboardMap/ # 键位图
│ │ ├─ Layout/ # 顶部布局与入口操作
│ │ ├─ Settings/ # 设置面板
│ │ ├─ Stats/ # 统计、结果、历史面板
│ │ └─ TypingArea/ # 单字 / 词组 / 文章练习区
│ ├─ data/ # 静态字典与小鹤映射
│ ├─ stores/ # Zustand 状态（输入、设置、历史、认证、文章）
│ ├─ utils/ # 拼音处理、输入校验、音效等工具
│ ├─ App.tsx # 应用主入口
│ └─ main.tsx # 渲染入口
├─ package.json
├─ README.en.md
└─ README.md
- React 19
- TypeScript 5
- Vite 7
- Zustand 5
- Tailwind CSS 4
- pinyin-pro
- FastAPI
- SQLAlchemy / Alembic
- PostgreSQL
- Redis
- Celery
- Docker Compose
| 键名 | 说明 |
|---|---|
flypy-settings |
本地练习设置与展示偏好 |
flypy-history |
本地练习历史与错字统计 |
flypy-auth |
本地登录态与云端用户会话 |
- 未登录时，应用以本地模式运行
- 登录后，前端会尝试拉取用户信息、云端设置并同步本地记录
- 设置变更会在短暂延迟后自动保存到云端
- 后端不可用时，云同步失败会提示用户，云文章列表回退到本地预设数据
- 正式后端说明：backend/README.md
- AI 模块实现讲解：docs/ai-module-implementation-guide.md
- 题库与编码映射：
src/data/flypy.ts - 小鹤双拼官网：https://flypy.cc/
- Rime 输入法：https://rime.im/
本项目采用 MIT License 开源。