From 05a79b529a527f3d24e2950cd7a7c76c0f76c0af Mon Sep 17 00:00:00 2001 From: ouyu <1986834078@qq.com> Date: Mon, 20 Apr 2026 20:25:58 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20README=20=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E4=BB=A5=E5=85=A8=E9=9D=A2=E4=BB=8B=E7=BB=8D=20GRE=20?= =?UTF-8?q?=E8=AF=8D=E6=B1=87=E5=AD=A6=E4=B9=A0=E5=BA=94=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 重构 README 文档结构，详细描述项目功能、技术栈、安装指南和使用说明 新增项目结构、数据结构和核心组件说明 完善部署说明和贡献指南 --- README.md | 409 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 399 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 36b0197..5250156 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,408 @@ GHBanner -# Run and deploy your AI Studio app +# GRE Vocabulary Builder - GRE 词汇学习应用 -This contains everything you need to run your app locally. +一个基于 **间隔重复系统 (Spaced Repetition System, SRS)** 的现代化 GRE 词汇学习应用，帮助考生高效记忆 GRE 核心词汇。 -View your app in AI Studio: https://ai.studio/apps/drive/1VlzJ43yikTZOm1ZmNSsXBZOP_kt5SHyR +## 目录 -## Run Locally +- [项目简介](#项目简介) +- [核心功能](#核心功能) +- [技术栈](#技术栈) +- [安装与运行](#安装与运行) +- [使用指南](#使用指南) +- [数据结构](#数据结构) +- [部署说明](#部署说明) +- [项目结构](#项目结构) -**Prerequisites:** Node.js +## 项目简介 +GRE Vocabulary Builder 是一个专为 GRE 考生设计的词汇学习工具。它采用科学的 **间隔重复学习法**，根据用户对单词的掌握程度智能安排复习计划，帮助用户在最短时间内高效记忆大量 GRE 核心词汇。 -1. Install dependencies: - `npm install` -2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key -3. Run the app: - `npm run dev` +该应用不仅提供基础的单词闪卡学习，还包含： +- 思维导图式的单词关系展示 +- 自定义单词列表功能 +- 智能分类和难度追踪 +- 数据持久化和备份 + +## 核心功能 + +### 📚 闪卡学习系统 + +- **单词卡片**：显示单词、词性、中文定义 +- **记忆辅助**： + - 词根词缀记忆法提示 + - 谐音/联想记忆技巧 + - 例句展示 + - 同义词、反义词列表 + - 派生词扩展 + - 易混淆词辨析 + +### 🔄 间隔重复系统 (SRS) + +- **8级复习间隔**：1天 → 3天 → 7天 → 14天 → 30天 → 60天 → 120天 → 240天 +- **智能调整**： + - 答对单词：SRS 等级提升，复习间隔延长 + - 答错单词：SRS 等级降低（降至约1/2），次日必须复习 +- **可自定义**：用户可以在设置中调整各等级的间隔天数 + +### 🧠 测验模式 + +- **随机测试**：对当前列表中的单词进行随机测验 +- **即时反馈**：答题后立即统计正确率 +- **进度追踪**：自动记录每次答题结果并更新 SRS 状态 + +### 🗺️ 词汇思维导图 + +- **主题分类**：按语义主题分组展示相关单词 +- **关系网络**： + - 同义词组 + - 反义词组 + - 易混淆词辨析 +- **主题示例**： + - 变化与稳定 + - 批评与赞扬 + - 清晰与模糊 + - 常见与新颖 + - 固执与顺从 + - 敌意与友好 + - 短暂与持久 + - 虚假与真实 + +### 📋 智能列表系统 + +#### 自动生成的列表 + +| 列表名称 | 说明 | +|---------|------| +| **Today's Review** | 今日需要复习的单词（基于 SRS 系统） | +| **My Favorites** | 用户标记为收藏的单词 | +| **Difficult Words** | 基于答题统计的难词列表（动态难度评分） | +| **Known Words** | 用户标记为"已掌握"的单词 | + +#### 自定义列表 + +- 创建任意数量的私人单词列表 +- 自由添加/移除单词 +- 适用于： + - 按特定主题整理单词 + - 临时冲刺复习 + - 错题整理 + +### 📅 复习日历 + +- **月度概览**：以日历形式展示未来的复习安排 +- **每日详情**：点击任意日期查看当天需要复习的单词列表 +- **视觉提示**：当天日期高亮显示，有复习任务的日期显示单词数量 + +### 💾 数据管理 + +- **本地存储**：所有学习进度自动保存到浏览器 localStorage +- **数据导出**：将进度导出为 JSON 文件（`gre_vocab_progress.json`） +- **数据导入**：从文件恢复学习进度 +- **跨会话记忆**：自动记住用户上次浏览的位置 + +## 技术栈 + +| 类别 | 技术 | +|------|------| +| **前端框架** | React 19.1.1 | +| **语言** | TypeScript 5.8.2 | +| **构建工具** | Vite 6.2.0 | +| **样式方案** | Tailwind CSS（内联类名） | +| **AI 集成** | @google/genai 1.16.0（Gemini API） | + +## 安装与运行 + +### 前置要求 + +- Node.js (建议 v18 或更高版本) +- npm 或 yarn + +### 本地安装 + +1. **克隆项目** + +```bash +git clone +cd GRE-Basewords-Learning +``` + +2. **安装依赖** + +```bash +npm install +``` + +3. **配置环境变量（可选）** + +项目支持 Google Gemini AI 集成（用于未来扩展功能）。如需使用，请创建 `.env.local` 文件： + +```bash +# .env.local +GEMINI_API_KEY=your_gemini_api_key_here +``` + +> 注意：当前版本的核心功能不需要 API Key，仅用于未来的 AI 增强功能。 + +4. **启动开发服务器** + +```bash +npm run dev +``` + +应用将在 `http://localhost:5173/` 启动（Vite 默认端口）。由于配置了 `--host 0.0.0.0`，也可以通过局域网 IP 访问。 + +### 生产构建 + +```bash +npm run build +``` + +构建产物将输出到 `dist/` 目录，部署路径前缀设为 `/GRE-Basewords-Learning/`（适配 GitHub Pages）。 + +### 预览生产构建 + +```bash +npm run preview +``` + +## 使用指南 + +### 基本学习流程 + +1. **选择单词列表** + - 从左侧边栏选择一个 Section 或智能列表 + - 或使用自定义列表 + +2. **闪卡学习** + - 查看单词和词性 + - 点击卡片中央的"Reveal"区域显示定义和详细信息 + - 再次点击隐藏定义，测试记忆 + +3. **进行测验** + - 点击卡片下方的 "Quiz Me" 按钮 + - 查看单词，回忆定义后点击 "Show Definition" + - 根据实际掌握情况选择 "I Knew It" 或 "Didn't Know" + - 测验完成后显示本次正确率 + +4. **管理单词状态** + - **收藏**：点击星标图标标记为收藏 + - **标记已掌握**：点击复选框标记为"已知"，将从常规学习列表中移除 + - **添加到列表**：通过顶部菜单将单词添加到自定义列表 + +### 高级功能 + +#### 查看思维导图 + +1. 点击卡片下方的 "Mind Map" 按钮 +2. 浏览按主题分类的单词网络 +3. 悬停在单词上查看简要定义 +4. 查看同义词、反义词、易混淆词辨析 + +#### 使用复习日历 + +1. 在边栏的 "Today's Review" 旁点击日历图标 +2. 切换月份查看不同时间的复习安排 +3. 点击有复习任务的日期查看具体单词列表 + +#### 自定义 SRS 间隔 + +1. 点击右上角设置图标 +2. 在 "SRS Intervals" 部分调整各等级的间隔天数 +3. 点击 "Reset to Default" 恢复默认设置 +4. 点击 "Save Changes" 保存 + +#### 数据备份与恢复 + +**导出数据：** +1. 打开设置 +2. 点击 "Export Data" 按钮 +3. 文件将自动下载（命名为 `gre_vocab_progress.json`） + +**导入数据：** +1. 打开设置 +2. 点击 "Import Data" 按钮 +3. 选择之前导出的 JSON 文件 +4. 导入成功后进度将被覆盖 + +## 数据结构 + +### 单词数据结构 (`Vocabulary`) + +```typescript +interface Vocabulary { + word: string; // 单词 + pos: string; // 词性 (如: adj., n., v.) + definition: string; // 中文定义 + examples?: string[]; // 例句 + notes?: string; // 记忆技巧/注释 + derivatives?: Derivative[]; // 派生词 + antonyms?: string[]; // 反义词 + synonyms?: string[]; // 同义词 + distinctions?: string[]; // 易混淆词辨析 +} +``` + +### 学习统计数据 (`WordStats`) + +```typescript +interface WordStats { + isFavorite: boolean; // 是否收藏 + correctCount: number; // 答对次数 + incorrectCount: number; // 答错次数 + srsLevel: number; // 当前 SRS 等级 (0-8) + nextReview: string | null; // 下次复习日期 (YYYY-MM-DD) + isKnown: boolean; // 是否已标记为掌握 + lastReviewed: string | null; // 最后复习日期 +} +``` + +### 默认 SRS 间隔 + +```typescript +const defaultSrsIntervals = { + 1: 1, // 等级1: 1天后复习 + 2: 3, // 等级2: 3天后复习 + 3: 7, // 等级3: 7天后复习 + 4: 14, // 等级4: 14天后复习 + 5: 30, // 等级5: 30天后复习 + 6: 60, // 等级6: 60天后复习 + 7: 120, // 等级7: 120天后复习 + 8: 240, // 等级8: 240天后复习 +}; +``` + +### 难度评分算法 + +```typescript +// 难词列表基于动态评分算法 +score = (incorrectCount * 5) - (correctCount * 2) + (daysSinceLastReview * 0.1) +``` + +- 答错惩罚：每次错误 +5 分 +- 答对奖励：每次正确 -2 分 +- 时间衰减：每多一天未复习 +0.1 分 + +## 部署说明 + +### GitHub Pages 部署 + +项目已配置 GitHub Actions 自动部署流程（`.github/workflows/deploy.yml`）。 + +**部署触发条件：** +- 推送到 `main` 分支时自动部署 +- 可手动从 Actions 页面触发 + +**部署步骤：** + +1. 确保项目推送到 GitHub 仓库 +2. 在仓库设置中启用 GitHub Pages： + - Source: `Deploy from a branch` + - Branch: `gh-pages` (由 Action 自动创建) +3. 等待 Action 执行完成 +4. 访问 `https://.github.io/GRE-Basewords-Learning/` + +### 手动部署到其他平台 + +1. 构建项目： +```bash +npm run build +``` + +2. 根据部署目标调整 `vite.config.ts` 中的 `base` 路径： +```typescript +// vite.config.ts +build: { + base: '/your-deploy-path/', // 修改为实际路径 +} +``` + +3. 将 `dist/` 目录的内容上传到服务器 + +## 项目结构 + +``` +GRE-Basewords-Learning/ +├── .github/ +│ └── workflows/ +│ └── deploy.yml # GitHub Pages 自动部署配置 +├── components/ +│ ├── AddToListPopover.tsx # 添加到列表的弹出层 +│ ├── AppHeader.tsx # 应用顶部导航栏 +│ ├── Badge.tsx # 标签组件（同义词/反义词） +│ ├── CardSection.tsx # 卡片内部分区组件 +│ ├── CreateListModal.tsx # 创建自定义列表模态框 +│ ├── MindMapModal.tsx # 词汇思维导图模态框 +│ ├── QuizModal.tsx # 测验模态框 +│ ├── ReviewCalendarModal.tsx # 复习日历模态框 +│ ├── SettingsModal.tsx # 设置模态框 +│ ├── Sidebar.tsx # 左侧边栏 +│ ├── VocabularyCard.tsx # 单词闪卡组件 +│ └── icons.tsx # 图标组件集合 +├── public/ +│ ├── list.json # 主词汇数据（多个 Section） +│ └── mindmap.json # 思维导图主题数据 +├── utils/ +│ └── srs.ts # SRS 间隔重复系统核心逻辑 +├── App.tsx # 主应用组件（状态管理核心） +├── index.html # HTML 入口 +├── index.tsx # React 入口 +├── package.json # 项目依赖和脚本 +├── tsconfig.json # TypeScript 配置 +├── types.ts # 全局类型定义 +└── vite.config.ts # Vite 构建配置 +``` + +## 核心组件说明 + +### App.tsx + +应用的核心状态管理组件，负责： +- 加载词汇数据和用户进度 +- 管理所有模态框状态 +- 处理 SRS 逻辑的更新 +- 数据导入导出功能 +- localStorage 数据持久化 + +### VocabularyCard.tsx + +单词闪卡组件，实现： +- 3D 翻转动画效果 +- 响应式字体大小（根据单词长度） +- 结构化展示单词详细信息 +- 支持键盘和鼠标操作 + +### QuizModal.tsx + +测验模态框，实现： +- 单词随机打乱 +- 分步答题流程 +- 答题结果即时更新 SRS 状态 +- 完成后统计正确率 + +### Sidebar.tsx + +左侧边栏导航，包含： +- 智能列表（今日复习、收藏、难词、已知词） +- 自定义列表管理 +- Section 列表 +- 数量徽章显示 + +### srs.ts + +间隔重复系统的核心算法： +- `handleCorrectAnswer()`：答对后的 SRS 升级逻辑 +- `handleIncorrectAnswer()`：答错后的 SRS 降级逻辑 +- `calculateDifficulty()`：难词动态评分算法 + +--- + +## 许可证 + +本项目采用 MIT 许可证，详见源代码文件。 + +## 贡献 + +欢迎提交 Issue 和 Pull Request！