Skip to content

1. 项目概述

LexiScribe 是一个面向个人英语学习的轻量级 Web 应用，核心功能是英语句子的间隔重复复习系统。用户保存自己喜欢的英语句子，系统根据用户每次复习的表现自动安排下一次复习时间。

技术架构

  • 前端：Vue 3 + TypeScript + Vite + Tailwind CSS

  • 后端：Cloudflare Workers（Hono 框架）

  • 数据库：Cloudflare D1（SQLite）

  • 存储：Cloudflare R2（音频/视频文件）

  • 部署：Cloudflare Pages（前端）+ Cloudflare Workers（后端）

  • 认证：JWT + HttpOnly Cookie

  • 邮件服务：Resend（验证码邮件）

2. 已完成功能 ✅

2.1 用户认证

  • ✅ 用户注册（邮箱 + 密码，密码加密存储）

  • ✅ 邮箱验证（发送 6 位验证码，有效期 10 分钟）

  • ✅ 用户登录（JWT + HttpOnly Cookie）

  • ✅ 退出登录（清除 Cookie）

  • ✅ 未验证邮箱可登录但功能受限

  • ✅ 已登录用户禁止访问登录/注册页面（路由守卫）

2.2 句子管理

  • ✅ 添加句子（英文 + 中文 + 音标 + 备注 + 来源）

  • ✅ 编辑句子（所有字段可编辑）

  • ✅ 删除句子（级联删除关联的复习记录）

  • ✅ 句子库列表（支持搜索、排序）

  • ✅ 分页加载

2.3 复习系统（间隔重复）

  • ✅ 今日复习队列（自动筛选需要复习的句子）

  • ✅ 复习卡片（显示句子，点击显示答案）

  • ✅ 四级评价（Again / Hard / Good / Easy）

  • ✅ 间隔重复算法（动态计算下一次复习时间）

  • ✅ 状态管理（NEW → LEARNING → REVIEW → MATURE）

2.4 媒体文件（音频/视频）

  • ✅ 上传媒体文件（支持 mp3/mp4/wav/webm 等格式）

  • ✅ R2 存储（文件保存到 Cloudflare R2）

  • ✅ 播放媒体（直接通过 Worker 代理流式播放）

  • ✅ 删除媒体（同时删除 R2 文件和数据库记录）

  • ✅ 文件类型/大小验证

  • ✅ 原始文件名保留

2.5 个人中心（Profile）

  • ✅ 个人信息展示（邮箱、昵称）

  • ✅ 修改昵称

  • ✅ 修改密码（需验证当前密码）

  • ✅ 通知设置（每日提醒、邮件通知、声音提醒）

  • ✅ 邀请系统（生成专属邀请链接、统计邀请数据）

  • ✅ 积分系统（积分、等级、流水记录）

2.6 小组功能

  • ✅ 创建小组（名称、描述、公开/私密）

  • ✅ 加入小组（通过邀请码）

  • ✅ 小组列表（查看所有已加入的小组）

  • ✅ 小组详情（基本信息、成员列表）

  • ✅ 生成小组邀请链接

  • ✅ 权限控制（创建者/成员）

2.7 统计与积分

  • ✅ Dashboard 统计（今日复习数、总句子数）

  • ✅ 积分系统（每日登录 +1，邀请注册 +10，邮箱验证 +5）

  • ✅ 等级系统（青铜 → 白银 → 黄金 → 钻石 → 传奇）

  • ✅ 积分流水记录

  • ✅ 积分排行榜

2.8 邀请系统

  • ✅ 生成专属邀请链接（每个用户唯一）

  • ✅ 邀请追踪（点击链接记录 IP 和设备信息）

  • ✅ 邀请统计（总邀请数、已注册数、已认证数）

  • ✅ 邀请记录列表（邮箱/IP、状态、时间）

  • ✅ 邀请注册奖励（邀请人 +10 积分）

  • ✅ 防刷机制（同一 IP 只记录一次点击）

2.9 UI/UX

  • ✅ 深色/浅色模式切换

  • ✅ 响应式设计（手机/平板/桌面）

  • ✅ 自定义组件类（btn-primary、btn-secondary、card 等）

  • ✅ 加载状态（骨架屏、按钮 loading）

  • ✅ 空状态提示

  • ✅ 自定义 Confirm 弹窗（替代原生 confirm）

  • ✅ 统一的时间格式化（北京时间）

  • ✅ 文本截断（truncate、line-clamp）

  • ✅ 404 页面

  • ✅ 欢迎弹窗（首次登录）

2.10 PWA

  • ✅ Service Worker 注册

  • ✅ Manifest 配置（应用名称、图标、主题色）

  • ✅ 离线缓存（静态资源）

  • ✅ 可安装到桌面（Android/iOS）

  • ⚠️ 跨域 API 不缓存（前后端不同域名）

2.11 开发工具

  • ✅ 合并启动命令（npm run dev 同时启动前后端）

  • ✅ 代码模块化拆分（routes、services、types、constants）

3. 未完成/待开发功能 🚧

3.1 小组功能（待完善）

  • ⬜ 分享句子到小组

  • ⬜ 小组动态（成员加入、分享句子等）

  • ⬜ 小组排行榜

  • ⬜ 小组句子点赞

  • ⬜ 退出小组

  • ⬜ 小组设置（修改名称、描述、转移群主等）

3.2 邀请系统（待完善）

  • ⬜ 邀请页面 UI 优化（积分+等级展示）

  • ⬜ 邀请海报生成

  • ⬜ 邀请排行榜

3.3 通知系统

  • ⬜ 浏览器桌面通知（Notification API）

  • ⬜ 每日复习邮件提醒（Cron Trigger）

  • ⬜ 站内通知中心

3.4 学习统计

  • ⬜ 连续学习天数（Streak）

  • ⬜ 学习趋势图表（周/月）

  • ⬜ 掌握程度分布

  • ⬜ 每日复习完成率

3.5 数据管理

  • ⬜ 数据导出（JSON/CSV/Markdown）

  • ⬜ 数据导入（从 CSV 或 Anki）

  • ⬜ 数据备份

3.6 AI 辅助

  • ⬜ 自动生成中文翻译

  • ⬜ 自动生成音标（已实现通过词典 API）

  • ⬜ 语法分析

  • ⬜ 例句推荐

3.7 浏览器扩展

  • ⬜ 右键选中文字添加到 LexiScribe

  • ⬜ 快速添加弹窗

3.8 其他

  • ⬜ 标签系统（给句子打标签）

  • ⬜ 句子收藏/星标

  • ⬜ 复习历史查看

  • ⬜ 句子分享（图片卡片）

  • ⬜ 键盘快捷键（复习时 1-4 快速评分）

4. 技术栈与框架

前端

技术 版本 用途
Vue 3 3.5+ 前端框架
TypeScript 5.x 类型安全
Vite 5.x 构建工具
Tailwind CSS 3.x CSS 框架
Vue Router 4.x 路由管理
Wavesurfer.js 7.x 音频波形可视化
html2canvas 1.x 截图生成
vite-plugin-pwa 0.x PWA 支持
NProgress 0.x 顶部进度条

后端

技术 用途
Cloudflare Workers 后端运行环境
Hono Web 框架
D1 Database 主数据库
R2 Storage 文件存储
JWT 身份认证
Zod 参数验证
Resend 邮件服务

数据库表结构

表名 用途
users 用户信息（邮箱、密码、验证状态）
sentences 句子内容（英文、中文、音标等）
reviews 复习记录（状态、间隔、评价）
user_points 用户积分和等级
points_log 积分流水
invitations 邀请链接和统计
invitation_records 邀请记录（点击、注册）
groups 小组信息
group_members 小组成员
group_sentences 小组句子
group_activities 小组动态
notification_preferences 用户通知偏好

5. 关键注意事项

5.1 环境变量（Secrets）

变量名 用途 类型
JWT_SECRET JWT 签名密钥 Secret
RESEND_API_KEY Resend 邮件 API Secret
EMAIL_FROM 发件邮箱 Secret
FRONTEND_URL 前端地址 Variable
JWT_EXPIRES_IN Token 过期分钟数 Variable
MAX_FILE_SIZE 最大文件大小 Variable

5.2 域名架构

  • 前端：https://lexiscribe.cdragon.win

  • 后端 API：https://lexiscribe.cdragon.win/api/*（自定义域名）或 https://backend.xxx.workers.dev

  • 注意：前后端不同域名，PWA 只缓存前端静态资源，不缓存 API

5.3 数据库时间

  • D1 使用 UTC 时间

  • 前端显示时需要 +8 小时 转为北京时间

  • 使用 formatBeijingTime 工具函数统一处理

5.4 文件上传限制

  • 支持格式：mp3, wav, ogg, mp4, webm, mov

  • 默认大小限制：10MB

  • 通过环境变量 MAX_FILE_SIZE 可调整

5.5 Cloudflare 免费额度

资源 免费额度 项目使用量 结论
Workers 请求 10万次/天 < 500次/天 ✅ 充裕
D1 读取 500万行/月 < 5万行/月 ✅ 充裕
D1 写入 10万行/月 < 1万行/月 ✅ 充裕
R2 存储 10GB < 100MB ✅ 充裕

5.6 时区处理

  • 问题：CURRENT_TIMESTAMP 存储的是 UTC 时间

  • 解决：前端统一使用 formatBeijingTime 工具函数转换

  • 工具函数位置：frontend/src/utils/time.ts

5.7 跨域配置

  • 后端已配置 CORS，允许自定义域名和 localhost

  • credentials: true 支持携带 Cookie

  • maxAge: 86400 缓存预检请求 24 小时

5.8 路由守卫

  • 所有需要登录的页面：meta: { requiresAuth: true }

  • 登录/注册/验证页面：meta: { guestOnly: true }

  • 已登录用户访问 guestOnly 页面自动跳转首页

5.9 代码模块结构

text

backend/src/ ├── index.ts # 入口文件 ├── auth.ts # 认证函数 ├── types/ # 类型定义 │ └── index.ts ├── services/ # 服务类 │ └── PointsService.ts └── routes/ # 路由模块 ├── auth.ts ├── user.ts ├── sentences.ts ├── reviews.ts ├── media.ts ├── invitations.ts ├── points.ts ├── stats.ts └── groups.ts

6. 快速启动

bash

克隆项目

cd E:\AAA\CCode\english-review

启动开发环境（前后端同时启动）

npm run dev

或者分别启动

cd backend && wrangler dev --local cd frontend && npm run dev

部署后端

cd backend && wrangler deploy

部署前端

cd frontend && npm run build && wrangler pages deploy dist

7. 项目状态

维度 状态
MVP 功能 ✅ 完成
核心功能 ✅ 稳定
小组功能 ⚠️ 基础完成，部分待完善
PWA ✅ 完成
UI/UX ✅ 完整
文档 ⚠️ 本文档
生产环境 ✅ 已部署

总结：LexiScribe 的核心功能（句子管理 + 间隔复习 + 认证系统）已经稳定运行，小组功能基础版已完成，积分和邀请系统也已上线。后续主要工作是完善小组功能、添加学习统计、AI 辅助和浏览器扩展。