diff --git a/README.md b/README.md index 8b07fefac36472a20488dfb1648328255fad03ef..51639fdfe8ef223e41509590144a745f426480bc 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,171 @@ -# English Vocab · 英语单词学习单页应用 +# English Vocab · 英语单词学习应用 -基于 **React 19 + TypeScript + Vite + Tailwind CSS v4 + ShadCN UI** 的英语单词学习单页应用(SPA)。当前仓库为「页面跳转骨架」阶段,仅完成: +基于 **React 19 + TypeScript + Vite + Tailwind CSS v4 + ShadCN UI** 的英语单词学习单页应用(SPA),配套 **Express + Prisma** 后端服务。 -- 完整项目目录与配置 -- 全局路由(React Router v7) -- 顶部导航栏 + 4 个核心页面(我的 / 错题本 / 单词库 / 练习) -- Tailwind v4 + ShadCN 主题变量与基础 `Button` 组件 -- localStorage 预留(业务阶段再接入) +## 功能特性 + +- **用户认证**:注册/登录,JWT 令牌鉴权 +- **单词库管理**:内置 CET-4、CET-6、考研英语等词库,支持自定义词库创建 +- **多种练习模式**:看英选义、看义选英、听写、拼写等 +- **错题本**:自动归集练习中的错误单词,支持针对性复习 +- **学习统计**:记录练习次数、正确率、学习进度等数据 + +## 技术栈 + +| 层面 | 技术 | +|------|------| +| 前端框架 | React 19 + TypeScript | +| 构建工具 | Vite | +| 样式方案 | Tailwind CSS v4 + ShadCN UI | +| 路由 | React Router v7 | +| 状态管理 | React Context + useReducer | +| 后端 | Express.js | +| 数据库 | Prisma + SQLite | +| 认证 | JWT | ## 目录结构 ``` -xiaozuxiangmu/ -├── components.json # ShadCN CLI 配置 ├── index.html # Vite 入口 HTML ├── package.json -├── tsconfig.json / tsconfig.app.json / tsconfig.node.json ├── vite.config.ts -└── src/ - ├── main.tsx # React 入口,挂载 BrowserRouter - ├── App.tsx # 集中式路由表 - ├── index.css # Tailwind v4 + ShadCN 主题变量 +├── tsconfig.json +├── server/ # 后端服务 +│ ├── prisma/ +│ │ └── schema.prisma # Prisma 数据模型 +│ └── src/ +│ ├── index.ts # Express 入口 +│ ├── lib/ +│ │ ├── auth.ts # JWT 认证中间件 +│ │ └── prisma.ts # Prisma 客户端 +│ └── routes/ +│ ├── auth.ts # 注册/登录 +│ ├── words.ts # 单词 CRUD +│ ├── libraries.ts # 词库管理 +│ ├── practice.ts # 练习记录 +│ ├── attempts.ts # 练习历史 +│ ├── wrongWords.ts# 错题管理 +│ └── stats.ts # 统计数据 +└── src/ # 前端源码 + ├── main.tsx # React 入口 + ├── App.tsx # 路由配置 + ├── index.css # Tailwind + ShadCN 主题 ├── components/ + │ ├── auth/ + │ │ └── ProtectedRoute.tsx │ ├── layout/ - │ │ ├── AppLayout.tsx # 全局布局(顶栏 + Outlet + 底栏) - │ │ └── NavBar.tsx # 顶部导航栏(NavLink 高亮) + │ │ ├── AppLayout.tsx + │ │ ├── NavBar.tsx + │ │ └── BottomNav.tsx + │ ├── practice/ + │ │ ├── PracticeQuiz.tsx + │ │ └── PracticeResult.tsx │ ├── shared/ - │ │ └── PageHeader.tsx # 各页面统一标题区 + │ │ ├── PageHeader.tsx + │ │ ├── LibraryCard.tsx + │ │ ├── CreateLibraryDialog.tsx + │ │ ├── StatCard.tsx + │ │ ├── EmptyState.tsx + │ │ └── NativeSelect.tsx │ └── ui/ - │ └── button.tsx # ShadCN Button(最小可用版) - ├── constants/ - │ └── nav.ts # 导航项配置 + │ ├── button.tsx + │ ├── card.tsx + │ ├── badge.tsx + │ ├── radio-group.tsx + │ ├── slider.tsx + │ └── skeleton.tsx + ├── contexts/ + │ └── AuthContext.tsx # 认证状态管理 ├── lib/ - │ └── utils.ts # cn() 工具 + │ ├── api.ts # API 请求封装 + │ ├── utils.ts # 工具函数 + │ ├── storage.ts # localStorage 封装 + │ ├── quiz.ts # 题目生成逻辑 + │ └── stats.ts # 统计计算 ├── pages/ - │ ├── Mine.tsx # /mine - │ ├── WrongBook.tsx # /wrong-book - │ ├── WordLibrary.tsx # /word-library - │ └── Practice.tsx # /practice(默认首页) + │ ├── Login.tsx + │ ├── Register.tsx + │ ├── Practice.tsx + │ ├── WordLibrary.tsx + │ ├── WrongBook.tsx + │ └── Mine.tsx └── types/ - └── vocab.ts # 单词/错题类型定义 + └── vocab.ts # 类型定义 ``` ## 路由 -| 路径 | 页面 | -| ---------------- | -------- | -| `/practice` | 练习 | -| `/word-library` | 单词库 | -| `/wrong-book` | 错题本 | -| `/mine` | 我的 | -| `/` 与 `*` | 重定向到 `/practice` | +| 路径 | 页面 | 说明 | +|------|------|------| +| `/login` | 登录 | 登录表单 | +| `/register` | 注册 | 注册表单 | +| `/practice` | 练习 | 选择词库和练习模式 | +| `/word-library` | 单词库 | 词库浏览与管理 | +| `/wrong-book` | 错题本 | 错题复习 | +| `/mine` | 我的 | 个人中心与统计 | +| `/` | 重定向 | 默认跳转到 `/practice` | ## 本地运行 +### 前端 + ```bash -# 1. 安装依赖 +# 安装依赖 npm install -# 2. 启动开发服务器(默认 http://localhost:5173) +# 启动开发服务器(默认 http://localhost:5173) npm run dev -# 3. 类型检查 + 生产构建 +# 类型检查 + 生产构建 npm run build -# 4. 本地预览构建产物 +# 预览构建产物 npm run preview ``` -## 下一步(业务实现阶段) +### 后端 + +```bash +cd server + +# 安装依赖 +npm install + +# 数据库迁移 +npx prisma migrate dev + +# 启动服务(默认 http://localhost:3000) +npm run dev +``` + +## 内置词库 + +应用预置了以下词库,注册后自动加载: + +- **CET-4** - 大学英语四级词汇 +- **CET-6** - 大学英语六级词汇 +- **考研英语** - 考研英语核心词汇 +- **IELTS** - 雅思词汇 +- **TOEFL** - 托福词汇 + +## 练习模式 + +| 模式 | 说明 | +|------|------| +| 看英选义 | 显示英文单词,选择中文含义 | +| 看义选英 | 显示中文含义,选择英文单词 | +| 听写 | 播放单词发音,输入英文拼写 | +| 拼写 | 根据中文提示拼写英文单词 | + +## 数据模型 + +- **User** - 用户 +- **Library** - 单词库 +- **Word** - 单词 +- **PracticeAttempt** - 练习记录 +- **WrongWord** - 错题记录 +- **UserProgress** - 学习进度 + +## 许可证 -- 在 `src/lib/` 下新增 `storage.ts`,封装 `localStorage` 读写与版本迁移 -- 使用 `useReducer` / Zustand 维护全局学习状态 -- 接入更多 ShadCN 组件:`npx shadcn@latest add card input dialog tabs ...` -- 实现练习题型(看英选义、看义选英、听写、拼写等) -- 接入错题自动归集与复习计划(基于简单 SM-2 间隔重复即可) +MIT License \ No newline at end of file