Skip to content
BranchesTags

Repository files navigation

Next.js 16 React 19 TypeScript 5 TailwindCSS v4 Prisma 6 shadcn/ui v4 License MIT

WordForge — AI-Powered English Vocabulary Learning

WordForge（词锻） is an intelligent English vocabulary learning platform that combines spaced repetition (SM-2 algorithm), AI-generated reading comprehension, and gamification to help learners systematically master English vocabulary from CET-4 through TOEFL levels.

词锻（WordForge）是一个智能英语词汇学习平台，融合间隔重复（SM-2 算法）、AI 生成阅读理解和游戏化机制，帮助学习者系统掌握从四级到托福的英语词汇。

✨ Features · 功能特性

📚 Vocabulary Learning · 词汇学习

  • Spaced Repetition (SM-2) — Adaptive flashcard system with 3D flip animation. Rate your recall quality on a 4-point scale; the algorithm schedules the optimal next review.
  • Multi-Level Word Pools — Select one or more difficulty levels to study simultaneously (CET-4 / CET-6 / Postgraduate / IELTS / TOEFL).
  • Daily Word Goal — Customize how many new words to learn per day (1–50).
  • Keyboard Shortcuts — Full keyboard control: Space flip, 1-4 rate, ←→ navigate, P pronounce, F favorite.
  • Today's Re-Review — Re-review all words learned today independently of the SM-2 schedule.
  • 22,760 Words — Complete CET-4, CET-6, and Postgraduate vocabulary with phonetics, translations, and example sentences.

间隔重复（SM-2） — 3D 翻转闪卡，四档评分，自适应复习间隔。
多级词库 — 可同时选择多个难度级别学习（四/六级/考研/雅思/托福）。
每日目标 — 自定义每天新学单词数量（1–50）。
全键盘操作 — Space 翻转、1-4 评分、方向键导航、P 发音、F 收藏。
今日重学 — 独立于 SM-2 排期，随时复习当天学过的单词。
22,760 词汇 — 完整的四六级+考研词汇，含音标、释义、例句。

🤖 AI Reading Generation · AI 阅读生成

  • AI-Crafted Articles — LLM generates exam-level reading passages that naturally incorporate your recently learned vocabulary.
  • Multi-Provider Support — OpenAI (GPT-4o), DeepSeek (deepseek-chat), and Anthropic (Claude). Configure per-user API keys in Settings.
  • 8 Topic Preferences — AI, Education, Environment, Psychology, Digital Life, Future Trends, Science, Society.
  • 5 Difficulty Levels — Passage complexity adapts from CET-4 through TOEFL.
  • 4 Question Types — Main Idea, Detail, Inference, and Vocabulary questions with detailed explanations.
  • Chinese Translation — Every generated article includes a full Chinese translation, toggleable after completion.
  • Smart Retry — Wrong answers can be retried; correct answers auto-advance.

AI 生成文章 — 大模型生成考试级阅读短文，自然融入你近期所学的词汇。
多厂商支持 — OpenAI（GPT-4o）、DeepSeek（deepseek-chat）、Anthropic（Claude），支持每个用户自己配置 API Key。
8 种主题偏好 — 人工智能、教育、环境、心理学、数字生活、未来趋势、科学、社会。
5 个难度级别 — 段落复杂度从四级到托福自适应。
4 种题型 — 主旨大意、细节理解、推理判断、词汇理解，均含解析。
中文翻译 — 每篇文章附带中文翻译，答题完成后可展开查看。

🎮 Gamification · 游戏化

  • XP & Levels — Earn XP for learning new words, reviewing, and answering reading questions. Level up formula: floor(√(totalXP / 100)) + 1.
  • Streaks — Consecutive daily study streaks with max streak tracking.
  • Achievements — 5 categories (STREAK, MILESTONE, ACCURACY, SPEED, SPECIAL) with XP rewards.
  • Daily Stats — Per-day tracking of words learned, words reviewed, readings done, accuracy, XP, and study minutes.

经验与等级 — 学习新词、复习、答题均可获得经验值。升级公式：floor(√(总经验 / 100)) + 1。
连续打卡 — 追踪每日连续学习天数与最长纪录。
成就系统 — 5 大类成就，解锁可获得额外经验奖励。

📊 Analytics · 数据分析

  • Activity Heatmap — GitHub-style 365-day contribution graph showing study activity.
  • 30-Day Trends — Interactive line/bar charts (Recharts) for daily XP, words learned, readings, and study time.
  • Weekly/Monthly Reports — Aggregated stats summaries.

活动热力图 — GitHub 风格的全年 365 天学习活跃度可视化。
30 天趋势图 — 交互式折线/柱状图，展示每日经验、单词、阅读、学习时长。
周报/月报 — 汇总统计摘要。

🛠 Admin Panel · 管理面板

  • Platform statistics dashboard (total users, words, readings, XP, accuracy).
  • Word CRUD management with single and bulk JSON import.
  • Admin role gated via middleware.

平台概览 — 总用户数、总词汇量、阅读数、经验值、正确率等统计仪表盘。
词汇管理 — 支持单个增删改查和批量 JSON 导入。

🎨 UI/UX

  • Dark Mode — Full light/dark theme support via next-themes.
  • Responsive — Desktop sidebar + mobile bottom navigation.
  • Chinese Localization — Full Chinese interface for Chinese-speaking learners.
  • Toast Notifications — Real-time feedback for all user actions.

暗色模式 — 完整支持明暗主题切换。
响应式 — 桌面端侧边栏 + 移动端底部导航。
中文界面 — 面向中文用户的完整中文本地化。

🏗 Tech Stack · 技术栈

Layer Technology
Framework Next.js 16 (App Router, Turbopack)
Language TypeScript 5 (strict)
UI React 19, TailwindCSS v4, shadcn/ui v4, Framer Motion
Database MySQL 8.4 + Prisma 6
State Zustand (client) + TanStack Query (server)
Auth Custom JWT (bcryptjs + jsonwebtoken)
AI OpenAI SDK + Anthropic SDK, multi-provider factory + Zod validation
Charts Recharts v3
Forms react-hook-form + Zod
Deploy Vercel / Docker (standalone output)

🚀 Quick Start · 快速开始

Prerequisites · 环境要求

  • Node.js 22+
  • MySQL 8.x
  • API key for at least one AI provider (OpenAI / DeepSeek / Anthropic)

Local Development · 本地开发

# 1. Clone & install dependencies
git clone https://github.com/your-username/wordforge.git
cd wordforge
npm install

# 2. Setup environment variables
cp .env.example .env
# Edit .env — fill in:
#   DATABASE_URL (MySQL connection string)
#   JWT_SECRET (random string, min 32 chars)
#   At least one AI provider API key

# 3. Initialize database
npx prisma migrate dev --name init
npx prisma db seed

# 4. Start dev server (Turbopack)
npm run dev

Open http://localhost:3000 and register an account.

Docker Deployment · Docker 部署

# Set required environment variables
export OPENAI_API_KEY="sk-your-key"
export JWT_SECRET="your-secure-random-string"

# Start full stack (MySQL + App)
docker compose up -d

The app will be available at http://localhost:3000. Database migrations run automatically on container start.

Vercel Deployment · Vercel 部署

Deploy with Vercel

  1. Fork this repository
  2. Connect to Vercel
  3. Set environment variables in Vercel dashboard
  4. Set Build Command: npx prisma generate && next build
  5. Set Output Directory: .next
  6. Deploy

Note: You need a MySQL instance accessible from Vercel (e.g., PlanetScale, Aiven, or a self-hosted MySQL server).

🔧 Environment Variables · 环境变量

Variable Description · 说明 Default · 默认值
DATABASE_URL MySQL connection string · MySQL 连接字符串 mysql://root:password@localhost:3306/english_ai_learning
JWT_SECRET JWT signing secret (min 32 chars) · JWT 密钥 (required)
JWT_EXPIRES_IN Token expiration · Token 过期时间 7d
OPENAI_API_KEY OpenAI API key · OpenAI API 密钥 (optional)
OPENAI_MODEL OpenAI model · OpenAI 模型 gpt-4o
DEEPSEEK_API_KEY DeepSeek API key · DeepSeek API 密钥 (optional)
DEEPSEEK_MODEL DeepSeek model · DeepSeek 模型 deepseek-chat
ANTHROPIC_API_KEY Anthropic API key · Anthropic API 密钥 (optional)
ANTHROPIC_MODEL Anthropic model · Anthropic 模型 claude-sonnet-4-20250514
DEFAULT_AI_PROVIDER Default AI provider · 默认 AI 厂商 openai
NEXT_PUBLIC_APP_URL Public app URL · 公开访问地址 http://localhost:3000

Users can also configure their own AI provider keys and models per-account via Settings → AI Configuration, which takes priority over the global environment variables.

用户还可以在设置 → AI 配置中为每个账户单独配置 AI 厂商和密钥，优先级高于全局环境变量。

📦 Project Structure · 项目结构

wordforge/
├── prisma/
│   ├── schema.prisma          # 12 models, 6 enums
│   ├── migrations/            # Database migrations
│   └── seed.ts                # Seed data (users, words, achievements)
├── src/
│   ├── app/
│   │   ├── (auth)/            # Login / Register (centered layout)
│   │   ├── (dashboard)/       # Main app pages (sidebar + header layout)
│   │   │   ├── dashboard/     # Home dashboard
│   │   │   ├── learn/         # New word learning session
│   │   │   ├── review/        # Spaced repetition review
│   │   │   ├── words/         # Word library + detail page
│   │   │   ├── favorites/     # Favorited words
│   │   │   ├── reading/       # AI reading articles + generation
│   │   │   ├── achievements/  # Achievement gallery
│   │   │   ├── analytics/     # Learning analytics dashboard
│   │   │   ├── profile/       # User profile + settings
│   │   │   └── admin/         # Admin panel + word management
│   │   └── api/               # 25+ API route handlers
│   ├── components/
│   │   ├── ui/                # shadcn/ui primitives (27 components)
│   │   ├── layout/            # AppSidebar, AppHeader, MobileNav
│   │   ├── words/             # Flashcard, ActionPanel, WordListSidebar
│   │   ├── reading/           # ArticleReader, QuestionPanel, ReadingResults
│   │   ├── analytics/         # LearningHeatmap, TrendsChart
│   │   ├── gamification/      # AchievementBadge, XPAnimation
│   │   └── common/            # ErrorBoundary, Spinner, EmptyState
│   ├── features/              # Domain logic (services)
│   │   ├── auth/              # Authentication, registration
│   │   ├── learning/          # SM-2 algorithm, session management
│   │   ├── reading/           # Article management, answer grading
│   │   └── gamification/      # XP calculator, streak, achievements
│   ├── services/
│   │   ├── ai/                # Multi-provider AI factory
│   │   │   └── providers/     # OpenAI, DeepSeek, Anthropic implementations
│   │   └── db/                # Prisma client singleton
│   ├── store/                 # Zustand stores (auth, learning)
│   ├── prompts/               # LLM prompt templates (level-aware)
│   ├── hooks/                 # Custom React hooks (useKeyboard, etc.)
│   ├── lib/                   # Utilities (api-client, middleware, rate-limit)
│   └── types/                 # TypeScript type definitions
├── docker-compose.yml         # Docker Compose (MySQL + App)
├── Dockerfile                 # Multi-stage production build
├── vercel.json                # Vercel deployment config
└── next.config.ts             # Next.js configuration (standalone output)

🧠 SM-2 Spaced Repetition Algorithm

This project implements the standard SM-2 algorithm (SuperMemo 2):

Parameter Description
Quality 4-point scale: EASY=5, GOOD=4, HARD=3, AGAIN=1
Ease Factor Starts at 2.5, adjusted by EF' = EF + (0.1 - (5 - q) * (0.08 + (5 - q) * 0.02))
Interval 0 reps → 1 day, 1 rep → 3 days, then interval * easeFactor
Status Interval ≥ 30 → MASTERED, 0 reps → LEARNING, else → REVIEWING

本项目实现了标准的 SM-2 算法。质量分四档，难度系数从 2.5 起步动态调整，间隔从 1 天逐步增长至 30 天以上即视为"已掌握"。

🔐 API Overview · API 概览

Group · 分组 Endpoints
Auth · 认证 POST /api/auth/register POST /api/auth/login POST /api/auth/logout
User · 用户 GET /api/user/me GET /api/user/stats PUT /api/user/settings GET/POST /api/user/ai-config PUT/DELETE /api/user/ai-config/[id]
Words · 词汇 GET /api/words GET /api/words/[id] PATCH /api/words/[id]/favorite GET /api/words/favorites
Learning · 学习 GET /api/learning/session GET /api/learning/review GET /api/learning/today POST /api/learning/progress
Reading · 阅读 GET /api/reading POST /api/reading/generate GET/DELETE /api/reading/[id] POST /api/reading/answer
Achievements · 成就 GET /api/achievements POST /api/achievements/check
Analytics · 分析 GET /api/analytics/trends GET /api/analytics/heatmap GET /api/analytics/report
Admin · 管理 GET /api/admin/stats POST /api/admin/words PUT/DELETE /api/admin/words/[id]

All routes under /api/words/* and /api/learning/* require authentication. Admin routes additionally require the ADMIN role.

所有 /api/words/* 和 /api/learning/* 路径需要登录认证。管理接口额外需要 ADMIN 角色。

🗃 Default Accounts · 默认账号

After running npx prisma db seed:

Role · 角色 Email Password · 密码
Admin · 管理员 admin@wordforge.com admin123
Demo · 演示 demo@wordforge.com demo123

📝 License

MIT

🙏 Acknowledgements · 鸣谢

Built with ❤️ for English learners everywhere · 为每一位英语学习者打造

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

8 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages