diff --git a/docs/TypeWords Nuxt 4 迁移计划.md b/docs/TypeWords Nuxt 4 迁移计划.md new file mode 100644 index 00000000..7396d79c --- /dev/null +++ b/docs/TypeWords Nuxt 4 迁移计划.md @@ -0,0 +1,132 @@ +# TypeWords Nuxt 4 迁移计划 + +## 1. 需求文档 + +### 1.1 项目概述 + +TypeWords 是一个基于 Web 的打字练习应用,专注于语言学习(英语单词和文章)。它提供多种练习模式、词典管理和进度跟踪功能。目标是将现有的 Vue 3 SPA(单页应用)迁移到 **Nuxt 4** 应用,以充分利用最新的框架特性、提升性能、SEO 和开发体验。 + +### 1.2 核心功能 + +* **单词练习**: + * 学习模式:跟写、拼写、辨析、听音、听写。 + * 间隔重复:新词、复习、拼写、乱序。 + * 词典选择:CET-4、CET-6、雅思(IELTS)等。 + * 统计数据:花费时间、学习/复习单词数。 + +* **文章练习**: + * 打字练习:支持音频同步(LRC)。 + * 阅读模式。 + * 句子级练习。 + +* **用户系统**: + * 登录/注册。 + * VIP 会员状态。 + * 用户设置同步。 + +* **设置**: + * 快捷键自定义。 + * 主题切换。 + * 声音/音量控制。 + * 翻译引擎选择。 + +* **离线/本地能力**: + * PWA 支持(Service Worker)。 + * 本地数据存储(IndexedDB)。 + +### 1.3 非功能性需求 + +* **性能**: 流畅的打字体验,无延迟。 +* **兼容性**: 支持现代浏览器。 +* **离线优先**: 支持离线使用已下载的词典。 + +## 2. 技术规范 + +### 2.1 技术栈 + +| 组件 | 当前 (Vue 3) | 目标 (Nuxt 4) | +| :--- | :--- | :--- | +| **框架** | Vue 3.5 + Vite | **Nuxt 4.x** | +| **语言** | TypeScript | TypeScript | +| **状态管理** | Pinia | Pinia (Nuxt 模块) | +| **路由** | Vue Router (配置式) | Nuxt 基于文件的路由 | +| **UI/样式** | Sass, UnoCSS | Sass, UnoCSS (Nuxt 模块) | +| **图标** | Iconify (unplugin) | Nuxt Icon / Iconify | +| **HTTP** | Axios | $fetch / useFetch | +| **存储** | IndexedDB (idb-keyval) | IndexedDB (idb-keyval) | +| **工具库** | Lodash, Dayjs | Lodash, Dayjs | + +### 2.2 数据模型 + +* **单词 (Word)**: JSON 结构,包含拼写、音标、翻译、例句、短语、同义词和词根。 +* **文章 (Article)**: JSON 结构,包含标题、正文、音频链接、LRC 时间轴和问题。 +* **词典 (Dictionary)**: 元数据 + 单词/文章列表。 +* **用户 (User)**: 个人资料、设置、进度数据。 + +### 2.3 关键算法 + +* **打字引擎**: 处理输入匹配、错误高亮和 WPM(每分钟字数)计算。 +* **间隔重复**: 决定哪些单词需要复习的逻辑。 +* **音频同步**: 使用 LRC 数据将音频播放时间映射到文本位置。 + +## 3. 架构文档 + +### 3.1 目录结构映射 (采用 Nuxt 4 推荐结构) + +Nuxt 4 推荐将源码主要放置在 `app/` 目录下,以保持根目录整洁(也可继续使用根目录模式,视具体配置而定)。以下以标准结构为例: + +``` +src/ -> app/ (或根目录) + apis/ -> composables/api/ 或 utils/api/ + assets/ -> assets/ + components/ -> components/ + config/ -> app.config.ts / runtimeConfig + directives/ -> plugins/directives.ts + hooks/ -> composables/ + libs/ -> utils/ 或 server/ (如果需要 API 路由) + locales/ -> i18n/ + pages/ -> pages/ + stores/ -> stores/ + types/ -> types/ (或 utils/types) + utils/ -> utils/ + App.vue -> app.vue + main.ts -> plugins/ (初始化逻辑) + router.ts -> pages/ (文件路由) +public/ -> public/ +``` + +### 3.2 状态管理流 + +* **全局状态**: 保留 Pinia store (`user`, `setting`, `runtime`, `practice`)。 +* **水合 (Hydration)**: Nuxt 处理状态水合。注意 `localStorage`/`IndexedDB` 的客户端仅有性(使用 `ClientOnly` 或 `onMounted`)。 + +### 3.3 路由策略 + +* **当前**: `router.ts` 定义显式路由。 +* **目标**: `pages/` 目录结构。 + * `pages/words/index.vue` + * `pages/practice-words/[id].vue` + * `pages/articles/index.vue` + * `pages/user/login.vue` + * 等等。 + +## 4. 实施步骤 + +1. **初始化**: 创建一个新的 **Nuxt 4** 项目(使用 `nuxi init` 并选择最新版本)。 +2. **依赖安装**: 安装 Pinia, UnoCSS, Sass 和其他库的 Nuxt 兼容版本。 +3. **资源迁移**: 移动 `public/` 内容和 `assets/` 样式。 +4. **核心逻辑迁移**: + * 复制 `types/`。 + * 将 `utils/` 和 `hooks/` 转换为 `composables/`。 + * 设置 Pinia `stores/`。 +5. **组件迁移**: + * 移动 `components/`(利用自动导入)。 + * 修复导入路径。 +6. **页面迁移**: + * 在 `pages/` 中重建路由结构。 + * 移动页面组件,适配 Nuxt 页面元数据 (`definePageMeta`)。 +7. **插件/配置**: + * 注册自定义指令。 + * 配置 UnoCSS。 + * 处理 PWA/Service Worker(可能需要 `vite-pwa/nuxt`)。 +8. **验证**: 测试所有练习模式和数据加载。 diff --git a/docs/TypeWords 系统架构文档.md b/docs/TypeWords 系统架构文档.md new file mode 100644 index 00000000..f1cee980 --- /dev/null +++ b/docs/TypeWords 系统架构文档.md @@ -0,0 +1,84 @@ +# TypeWords 系统架构文档 + +## 1. 架构概览 + +本项目由 Vue 3 单页应用 (SPA) 迁移至 Nuxt 4 全栈框架。架构旨在提供高性能的客户端交互(打字体验)和优化的服务端渲染(SEO、首屏加载)。 + +### 1.1 技术栈对比 + +| 层级 | 原架构 (Vue 3) | 新架构 (Nuxt 4) | 说明 | +| :--- | :--- | :--- | :--- | +| **Runtime** | Browser Only | Node.js (Server) + Browser | 支持 SSR/SSG | +| **Framework** | Vue 3.5 + Vite | Nuxt 4.x | 约定优于配置 | +| **Language** | TypeScript | TypeScript | 强类型约束 | +| **State** | Pinia | Pinia (Nuxt Module) | 状态管理 | +| **Routing** | Vue Router (Manual) | Nuxt File System Routing | 自动路由生成 | +| **UI Framework** | UnoCSS + SCSS | UnoCSS (Nuxt Module) | 原子化 CSS | +| **HTTP Client** | Axios | $fetch / useFetch | Nuxt 内置 fetch | +| **Storage** | IndexedDB (idb-keyval) | IndexedDB (Client Only) | 本地大容量存储 | + +## 2. 目录结构设计 + +遵循 Nuxt 4 的最佳实践,采用 `app/` 目录结构以保持根目录整洁。 + +``` +nuxt-tw/ +├── app/ +│ ├── assets/ # 静态资源 (CSS, Images) +│ ├── components/ # Vue 组件 (自动导入) +│ │ ├── base/ # 基础 UI 组件 (Button, Input) +│ │ ├── business/ # 业务组件 (WordCard, TypingArea) +│ │ └── layout/ # 布局组件 (Header, Footer) +│ ├── composables/ # 组合式函数 (原 hooks + apis) +│ │ ├── api/ # API 接口封装 +│ │ └── usePractice.ts # 练习逻辑封装 +│ ├── layouts/ # 页面布局模板 +│ ├── middleware/ # 路由中间件 (Auth 守卫) +│ ├── pages/ # 页面路由 +│ ├── plugins/ # 插件 (Directives, 3rd-party libs) +│ ├── stores/ # Pinia 状态仓库 +│ ├── types/ # TypeScript 类型定义 +│ ├── utils/ # 工具函数 +│ └── app.vue # 应用入口 +├── public/ # 公共静态文件 (favicon, robots.txt) +├── server/ # (可选) 服务端 API 路由 +├── nuxt.config.ts # Nuxt 配置文件 +├── uno.config.ts # UnoCSS 配置文件 +└── package.json +``` + +## 3. 核心模块架构 + +### 3.1 状态管理 (State Management) +使用 Pinia 管理全局状态,主要 Store 模块: +* **UserStore**: 用户认证信息、Token、个人资料。 +* **SettingStore**: 应用配置(主题、快捷键、音效)。 +* **RuntimeStore**: 运行时临时状态(当前路由、加载状态)。 +* **PracticeStore**: 核心业务状态(当前单词列表、输入状态、统计数据)。 + +### 3.2 数据持久化 (Data Persistence) +* **IndexedDB**: 用于存储大型数据,如: + * 下载的词典文件 (JSON)。 + * 文章音频数据 (Blob)。 +* **LocalStorage**: 用于存储轻量配置,如: + * 用户 Token。 + * 用户偏好设置 (Settings)。 +* **SSR 注意事项**: IndexedDB 和 LocalStorage 仅在客户端可用。在 Nuxt 中需使用 `` 组件或在 `onMounted` 生命周期中访问,避免水合不匹配 (Hydration Mismatch)。 + +### 3.3 路由与导航 (Routing) +利用 Nuxt 的文件系统路由自动生成路由表: +* `pages/words/index.vue` -> `/words` (单词列表) +* `pages/practice-words/[id].vue` -> `/practice-words/:id` (单词练习) +* `pages/articles/index.vue` -> `/articles` (文章列表) +* `pages/user/login.vue` -> `/user/login` (登录) + +### 3.4 网络请求 (Networking) +封装 `useFetch` 或 `$fetch` 替代 Axios: +* 统一处理请求拦截(添加 Token)。 +* 统一处理响应拦截(错误提示、Token 过期跳转)。 +* 支持 SSR 期间的服务端数据预取。 + +## 4. 部署架构 +* **构建**: `nuxt build` 生成生产环境包。 +* **模式**: 推荐使用 **SSG (Static Site Generation)** 或 **Hybrid** 模式,因为主要内容(词典、练习)强依赖客户端交互,但首页和文章页可预渲染以提升 SEO。 +* **服务器**: Node.js 服务器或静态托管 (Vercel/Netlify/Nginx)。 diff --git a/docs/TypeWords 需求分析文档.md b/docs/TypeWords 需求分析文档.md new file mode 100644 index 00000000..5cacd809 --- /dev/null +++ b/docs/TypeWords 需求分析文档.md @@ -0,0 +1,102 @@ +# TypeWords 需求分析文档 + +## 1. 项目概述 +TypeWords 是一个专注于语言学习的 Web 打字练习应用。它结合了打字练习与英语/外语学习,提供单词记忆、文章阅读、听写练习等多种模式。核心理念是通过键盘输入强化记忆,同时提供丰富的词典资源和进度跟踪功能。 + +## 2. 用户角色 +* **游客**: 可以使用基础练习功能,但数据保存在本地,无法跨设备同步,部分高级功能(如VIP词典)受限。 +* **注册用户**: 可以同步学习进度、设置和收藏夹。 +* **VIP 用户**: 享有更多高级功能(如特定词典、无限发音等)。 + +## 3. 功能模块详解 + +### 3.1 单词练习 (Word Practice) +* **练习模式**: + * **跟写 (FollowWrite)**: 屏幕显示单词,用户照着输入。 + * **拼写 (Spell)**: 隐藏单词拼写,仅显示释义/发音,用户需拼写出单词。 + * **辨析 (Identify)**: 给出单词,选择正确的释义(或是反过来)。 + * **听音 (Listen)**: 播放单词发音,用户输入单词。 + * **听写 (Dictation)**: 连续播放一组单词,用户依次输入。 +* **练习范围**: + * **新词学习**: 系统推荐的新单词。 + * **复习**: 基于间隔重复算法(Spaced Repetition)复习旧单词。 + * **乱序练习**: 随机抽取单词练习。 + * **错词重练**: 针对历史错误单词进行强化练习。 +* **交互细节**: + * 支持快捷键(如 Ctrl+P 播放发音,Enter 收藏)。 + * 打字错误实时高亮。 + * 练习结束后显示统计数据(WPM、准确率、用时)。 + +### 3.2 文章练习 (Article Practice) +* **阅读/打字模式**: 用户可以对整篇文章进行打字练习。 +* **音频同步**: 支持 LRC 格式,实现音频播放与文本高亮同步。 +* **句式练习**: 将文章拆分为句子进行练习。 +* **辅助功能**: + * 点击单词查询释义。 + * 句子翻译对照。 + * 支持填空题和选择题(基于文章内容)。 + +### 3.3 词典管理 (Dictionary Management) +* **词典库**: 内置多种词典(CET-4/6, 雅思, 托福, 考研, 专四/八等)。 +* **自定义词典**: 支持用户导入词典数据。 +* **特殊词本**: + * **生词本 (Collect)**: 用户手动收藏的单词。 + * **错题本 (Wrong)**: 自动记录拼写错误的单词。 + * **熟词本 (Known)**: 用户标记为“已掌握”的单词,练习时会跳过。 + +### 3.4 用户系统 (User System) +* **账号管理**: 注册、登录(支持验证码)、找回密码。 +* **个人中心**: 查看学习天数、打卡记录、VIP 状态。 +* **数据同步**: 学习进度、偏好设置云端同步。 + +### 3.5 设置系统 (Settings) +* **界面偏好**: 主题切换(深色/浅色)、字体大小、界面布局。 +* **声音设置**: 音量调节、音效开关(打字音、错误音)。 +* **练习设置**: 每日学习量、每组单词数、自动发音设置。 +* **快捷键**: 全局快捷键自定义。 + +## 4. 数据实体 (Data Entities) + +### 4.1 单词 (Word) +```typescript +interface Word { + id: string; + word: string; // 拼写 + phonetic0: string; // 英式音标 + phonetic1: string; // 美式音标 + trans: { pos: string; cn: string }[]; // 释义列表 + sentences: { c: string; cn: string }[]; // 例句 + phrases: { c: string; cn: string }[]; // 短语 + synos: { pos: string; ws: string[] }[]; // 同义词 + relWords: { root: string; rels: ... }[]; // 词根/派生词 + etymology: { t: string; d: string }[]; // 词源 +} +``` + +### 4.2 文章 (Article) +```typescript +interface Article { + title: string; + text: string; + audioSrc: string; // 音频链接 + lrcPosition: number[][]; // LRC 时间轴 + questions: Question[]; // 配套习题 +} +``` + +### 4.3 词典 (Dict) +```typescript +interface Dict { + id: string; + name: string; + category: string; + words: Word[]; + lastLearnIndex: number; // 学习进度 +} +``` + +## 5. 非功能性需求 +* **性能**: 打字响应延迟需极低(<50ms),确保跟手感。 +* **离线能力**: 已下载的词典应支持离线使用(PWA + IndexedDB)。 +* **兼容性**: 适配主流桌面浏览器(Chrome, Edge, Firefox, Safari)。 +* **SEO**: 首页和公共资源页需对搜索引擎友好(Nuxt SSR)。 diff --git a/docs/更新后的详细执行计划.md b/docs/更新后的详细执行计划.md new file mode 100644 index 00000000..e145b9bd --- /dev/null +++ b/docs/更新后的详细执行计划.md @@ -0,0 +1,42 @@ +遵照您的指示,我将在迁移代码之前,先梳理并输出详细的需求文档和架构文档。 + +**更新后的详细执行计划:** + +### 第一阶段:文档编写 (Documentation) +1. **需求文档 (`documents/Requirement_Analysis.md`)**: + * 基于源码(`router.ts`, `types.ts` 等)深度解析现有功能。 + * 详细列出功能模块:单词练习(多种模式)、文章练习(音频同步)、词典管理(本地/在线)、用户系统(VIP/同步)、快捷键系统等。 + * 明确数据结构:Word, Article, Dict, User 等核心实体的定义。 +2. **架构文档 (`documents/System_Architecture.md`)**: + * **技术栈**: Vue 3 -> Nuxt 4, Pinia, UnoCSS, IndexedDB。 + * **目录结构**: 详细对比 `TypeWords` 和 `nuxt-tw` 的目录映射关系。 + * **数据流**: 描述前端与后端 (API)、本地存储 (IndexedDB) 的交互流程。 + * **路由设计**: 规划 Nuxt 的文件路由结构。 + +### 第二阶段:基础设施与依赖 (Infrastructure & Dependencies) +1. **清理与配置**: + * 移除 `nuxt-tw` 中的临时文件和 `@nuxt/ui` 及其 Tailwind 依赖。 + * 配置 `nuxt.config.ts`:移除 UI 模块,添加 `@unocss/nuxt`。 + * 创建 `uno.config.ts`。 +2. **依赖安装**: + * 安装核心依赖:`unocss`, `pinia`, `sass`, `idb-keyval`, `dayjs`, `lodash` 等。 + +### 第三阶段:核心逻辑迁移 (Core Logic) +1. **类型与工具**: 迁移 `types` 和 `utils/libs`。 +2. **状态管理**: 迁移 `stores` 到 Nuxt Pinia 模块。 +3. **Composables**: 重构 `hooks` 和 `apis` 为 Nuxt Composables。 + +### 第四阶段:资源与组件 (Assets & Components) +1. **静态资源**: 迁移 `assets` 和 `public`。 +2. **组件迁移**: 迁移并适配所有 Vue 组件。 + +### 第五阶段:页面与路由 (Pages & Routing) +1. **页面重构**: 将 Vue Router 配置转换为 `pages/` 目录结构。 +2. **元数据适配**: 使用 `definePageMeta` 和 `useHead`。 + +### 第六阶段:验证 (Verification) +1. **功能测试**: 验证核心业务流程(登录、练习、词典加载)。 +2. **样式检查**: 确保 UnoCSS 样式正确应用。 + +**确认执行?** +如果同意,我将首先生成两份文档,供您查阅和存档。