wip

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. **验证**: 测试所有练习模式和数据加载。

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 中需使用 `<ClientOnly>` 组件或在 `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)。

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）。

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 样式正确应用。
+
+**确认执行？**
+如果同意，我将首先生成两份文档，供您查阅和存档。