本项目站内源代码下载地址

技术栈：Next.js 16 + React 19 + TypeScript + Tailwind CSS v4 + shadcn/ui + Zustand + Framer Motion
目标平台：Web（PWA/移动端优先）

---

1. 项目概述

1.1 项目定位

本项目是一款面向考研（研究生入学考试）英语备考的词汇闪卡学习工具，采用移动端优先的交互设计，支持：

• 闪卡记忆：3D翻转卡片展示单词、音标、释义、真题例句与记忆锚点
• 单词列表：分类浏览、搜索、收藏、掌握/熟悉标记
• 测验模式：四选一选择题，自动从同分类中生成干扰项
• 学习统计：今日进度、总体掌握率、分类进度、每日目标设定

1.2 核心特性

特性	说明
词汇覆盖	约 5500+ 考研大纲词汇，分核心词、阅读高频、完形高频、写作加分、基础词五大类
多分类标签	每个单词可属于多个分类（如核心词同时标记为阅读/写作）
数据去重	14 个数据源按优先级合并，保留最详细的词条信息
本地持久化	学习进度、收藏、测验成绩通过 localStorage 持久化
每日目标	支持 20/30/50/80/100 词每日学习目标，自动跨天重置
交互动画	卡片翻转、页面切换、进度条动画均采用 Framer Motion

---

2. 系统架构

2.1 整体架构图

2.2 技术栈明细

层级	技术选型	版本	用途
框架	Next.js	16.1.1	React 全栈框架，App Router
运行时	React	19.0.0	UI 库
语言	TypeScript	5.x	类型安全
样式	Tailwind CSS	4.x	原子化 CSS
UI 组件	shadcn/ui	latest	Radix UI 封装组件库
状态管理	Zustand	5.0.6	轻量级全局状态
动画	Framer Motion	12.23.2	交互动画
图标	Lucide React	0.525.0	矢量图标
构建	Bun	1.3.4	包管理与运行时
ORM	Prisma	6.11.1	数据库模型（当前未深度使用）
数据库	SQLite	-	本地数据库（当前未深度使用）

---

3. 目录结构

考研词汇练习/
├── src/
│   ├── app/
│   │   ├── api/route.ts          # API 路由（占位）
│   │   ├── globals.css           # Tailwind 主题与 CSS 变量
│   │   ├── layout.tsx            # 根布局（字体、Metadata）
│   │   └── page.tsx              # 主页面（单页应用，含所有 Tab）
│   ├── components/ui/            # shadcn/ui 组件（~50 个）
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── input.tsx
│   │   ├── progress.tsx
│   │   ├── badge.tsx
│   │   ├── scroll-area.tsx
│   │   ├── separator.tsx
│   │   └── ...
│   ├── data/                     # 词汇数据源（14 个文件）
│   │   ├── vocabulary.ts         # 核心词汇（最详细，40+ 词，含例句）
│   │   ├── vocab-core-ae.ts      # 核心词 A-E
│   │   ├── vocab-core-fn.ts      # 核心词 F-N
│   │   ├── vocab-core-oz.ts      # 核心词 O-Z
│   │   ├── vocab-core-expanded.ts
│   │   ├── vocab-ac.ts           # A-C 补充词
│   │   ├── vocab-dh.ts           # D-H 补充词
│   │   ├── vocab-io.ts           # I-O 补充词
│   │   ├── vocab-ps.ts           # P-S 补充词
│   │   ├── vocab-tz.ts           # T-Z 补充词
│   │   ├── vocab-extra.ts
│   │   ├── vocab-supplement-al.ts
│   │   ├── vocab-supplement-mz.ts
│   │   ├── vocab-rcw.ts
│   │   ├── vocab-final-supplement.ts
│   │   └── index.ts              # 数据聚合与去重逻辑
│   ├── store/
│   │   └── vocab-store.ts        # Zustand 全局状态
│   └── hooks/
│       ├── use-mobile.ts         # 移动端检测
│       └── use-toast.ts          # Toast 通知
├── prisma/
│   └── schema.prisma             # 数据库模型（User, Post）
├── public/
│   ├── logo.svg
│   └── robots.txt
├── scripts/
│   └── gen-vocab.js              # 词汇生成脚本
├── .zscripts/                    # 自定义脚本（build/dev/start）
├── next.config.ts                # Next.js 配置（standalone 输出）
├── components.json               # shadcn/ui 配置
├── package.json
├── bun.lock
└── Caddyfile                     # Caddy 反向代理配置

---

4. 数据模型设计

4.1 词汇数据模型

4.2 词汇字段说明

字段	类型	说明
id	string	唯一标识，格式 w{序号}
word	string	英文单词
phonetic	string	音标（IPA）
coreMeaning	string	核心中文释义
exampleEn	string	真题例句（英文）
exampleCn	string	真题例句（中文翻译）
memoryTip	string	记忆提示/锚点
category	enum	主分类：core/reading/cloze/writing/basic
categories	string[]	自动分配的多个分类标签
tags	string[]	词性标签：动词/名词/形容词/高频/搭配 等
frequency	number	考频等级 1-5
mastery	number	掌握等级 0-2（当前未使用）

4.3 状态管理模型（Zustand Store）

4.4 数据持久化流程

---

5. 页面与组件设计

5.1 页面结构

本项目采用**单页应用（SPA）**模式，所有功能集中在 page.tsx 中，通过底部 Tab Bar 切换视图。

5.2 底部导航栏

Tab	图标	标签	功能
home	Home	首页	学习概览、今日推荐、分类入口
words	BookOpen	单词	闪卡/列表模式切换
quiz	Brain	测验	四选一选择题测验
profile	User	我的	学习统计、进度、设置

5.3 首页（HomeTab）

核心交互：

• 点击分类卡片 → 切换到单词 Tab 并进入闪卡模式
• 点击收藏按钮 → 切换单词收藏状态
• 进度条动画 → Framer Motion animate={{ width }}

5.4 闪卡模式（FlashcardTab）

3D 翻转实现：

5.5 列表模式（WordListTab）

性能优化：

• 分页加载：初始显示 50 词，点击"加载更多"增量加载
• useMemo 缓存过滤结果
• ScrollArea 优化长列表滚动性能

5.6 测验模式（QuizMode）

干扰项生成算法：

1. 从当前分类中随机选取 3 个不同单词
2. 与正确答案一起随机排序
3. 每轮测验重新生成（通过 quizKey 触发 useMemo 重新计算）

5.7 个人中心（ProfileTab）

---

6. 数据流设计

6.1 词汇数据流

6.2 状态数据流

---

7. 核心算法与逻辑

7.1 数据去重与合并

优先级规则：

1. vocabulary.ts（最详细，含例句和记忆提示）
2. vocab-core-*.ts（核心词扩展）
3. vocab-ac.ts ~ vocab-tz.ts（按字母分区）
4. vocab-supplement*.ts（补充词汇）

7.2 自动分类分配算法

基于单词的 category、frequency、tags 自动分配多分类标签：

条件	分配分类
core + freq >= 5	reading, writing
core + freq >= 4 + 动词/名词/高频	reading
core + 标签含 易混/辨析/多义/用法	cloze
core + 标签含 搭配/写作/虚拟语气	writing
core + freq >= 4 + 形容词	reading, writing
basic + freq >= 4	reading
reading + freq >= 4	writing
writing	reading
cloze + freq >= 4	reading

7.3 测验干扰项生成

---

8. 样式与主题设计

8.1 色彩系统

用途	颜色值	说明
主色（微信绿）	#07C160	品牌主色，用于按钮、进度条、选中状态
主色深	#06AD56	渐变深色端
主色浅	#E8F8EE	背景、浅色卡片
核心词	#F59E0B	琥珀色
阅读高频	#8B5CF6	紫色
完形高频	#EC4899	粉色
写作加分	#06B6D4	青色
基础词	#6B7280	灰色

8.2 布局规范

• 最大宽度：max-w-lg mx-auto（移动端优先，桌面端居中）
• 底部安全区：pb-[max(0.25rem,env(safe-area-inset-bottom))]
• 卡片圆角：rounded-2xl / rounded-xl
• 按钮圆角：rounded-full
• 间距系统：基于 Tailwind 默认间距

---

9. 构建与部署

9.1 构建配置

// next.config.ts
const nextConfig: NextConfig = {
  output: "standalone",      // 独立输出，适合容器化部署
  typescript: {
    ignoreBuildErrors: true, // 忽略 TS 错误（快速构建）
  },
  reactStrictMode: false,
};

9.2 构建流程

9.3 部署方式

方式	说明
Standalone	输出独立 Node.js 应用，无需依赖 node_modules
Caddy	通过 Caddyfile 配置反向代理
Docker	可基于 node:alpine 或 oven/bun 镜像构建

---

10. 待优化与扩展点

10.1 当前局限性

1. API 未使用：src/app/api/route.ts 仅为占位，Prisma/SQLite 未深度集成
2. 无后端同步：学习进度仅保存在 localStorage，无法跨设备同步
3. 无用户系统：next-auth 已安装但未配置，无登录/注册功能
4. 数据体积大：所有词汇数据打包在 JS 中，首屏加载较重
5. 无服务端渲染：page.tsx 标记 "use client"，丧失 SSR 优势

10.2 建议扩展方向

方向	实现思路
后端 API	将词汇数据迁移到数据库，通过 API 分页获取
用户系统	配置 next-auth，支持 OAuth 登录，同步学习进度
数据懒加载	按分类/字母分区动态导入词汇数据
复习算法	引入艾宾浩斯遗忘曲线，智能推荐复习单词
语音播放	集成 Web Speech API 或第三方 TTS 服务
暗黑模式	利用 next-themes 实现主题切换（已安装）
国际化	利用 next-intl 支持多语言（已安装）

---

11. 附录

11.1 词汇数据统计

数据文件	行数	说明
vocabulary.ts	1704	核心词汇（最详细）
vocab-io.ts	1067	I-O 分区词汇
vocab-ps.ts	853	P-S 分区词汇
vocab-dh.ts	735	D-H 分区词汇
vocab-ac.ts	720	A-C 分区词汇
vocab-tz.ts	725	T-Z 分区词汇
vocab-rcw.ts	623	额外补充
vocab-supplement-al.ts	535	A-L 补充
vocab-core-ae.ts	376	核心词 A-E
vocab-core-fn.ts	365	核心词 F-N
vocab-core-oz.ts	405	核心词 O-Z
vocab-core-expanded.ts	328	核心词扩展
vocab-extra.ts	400	额外词汇
vocab-supplement-mz.ts	286	M-Z 补充
vocab-final-supplement.ts	93	最终补充
总计	~9387 行	~5500+ 去重词汇

11.2 依赖版本锁定

关键生产依赖版本：

• next: ^16.1.1
• react: ^19.0.0
• tailwindcss: ^4
• zustand: ^5.0.6
• framer-motion: ^12.23.2
• @prisma/client: ^6.11.1