从零到一，借助 Claude Code 等 AI 编程工具，快速构建一个包含后台管理系统 + H5 移动端应用的英语单词学习平台。
📌 项目概览
Danci（单词）是一个全栈英语单词学习平台，包含两个子项目：
| 子项目 | 定位 | 技术栈 |
|---|---|---|
danci-admin |
🖥️ 后台管理系统 | Next.js 16 + React 19 + shadcn/ui |
nextjs-typescript-starter |
📱 H5 移动端应用 | Next.js 14 + NextAuth + Drizzle ORM |
两个项目共享同一个 Supabase 云端 PostgreSQL 数据库，通过 ORM 实现数据层的统一管理。
🏗️ 技术架构
┌─────────────────────────────────────────────────────────┐
│ 用户层 │
│ ┌──────────────────┐ ┌──────────────────────────┐ │
│ │ danci-admin │ │ H5 移动端应用 │ │
│ │ 后台管理系统 │ │ (nextjs-typescript- │ │
│ │ (Next.js 16) │ │ starter) │ │
│ └────────┬─────────┘ └────────────┬─────────────┘ │
│ │ │ │
│ ┌────────▼───────────────────────────▼─────────────┐ │
│ │ API Routes / Server Actions │ │
│ └────────────────────────┬──────────────────────────┘ │
│ │ │
│ ┌────────────────────────▼──────────────────────────┐ │
│ │ Drizzle ORM (对象关系映射) │ │
│ │ Schema → SQL 映射，告别手写 SQL │ │
│ └────────────────────────┬──────────────────────────┘ │
│ │ │
│ ┌────────────────────────▼──────────────────────────┐ │
│ │ Supabase (云端 PostgreSQL 数据库) │ │
│ │ BaaS --- Backend as a Service │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘🔑 核心技术选型
- ⚡ Next.js --- React 全栈框架，支持 SSR/SSG，SEO 友好
- 🎨 shadcn/ui --- 高度可定制的 UI 组件库，搭配 Tailwind CSS
- 🔐 NextAuth.js --- 身份认证解决方案，支持邮箱密码登录
- 🗄️ Drizzle ORM --- 类型安全的 ORM，Schema 即表结构
- ☁️ Supabase --- 云端 BaaS 平台，零运维成本
📊 数据库设计
项目采用 关系型数据库（PostgreSQL），通过 Drizzle ORM 管理表结构。
核心数据表
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ users │ │ books │ │ words │
│ 用户表 │ │ 单词书表 │ │ 单词表 │
├──────────────┤ ├──────────────┤ ├──────────────────┤
│ id (PK) │ │ id (PK) │ │ id (PK) │
│ email │ │ book_id │ │ wordRank │
│ password_hash│ │ title │ │ headWord │
│ created_at │ │ word_count │ │ content (JSON) │
│ updated_at │ │ cover_url │ │ bookId │
└──────┬───────┘ │ tags │ └──────────────────┘
│ └──────┬───────┘
│ │
│ ┌───────────────▼────────────────┐
└────► user_progress │
│ 学习进度表 │
├─────────────────────────────────┤
│ id (PK) │
│ user_id (FK → users) │
│ book_id (FK → books) │
│ last_word_rank (上次学到第几个) │
│ learned_words (已学单词数) │
│ total_words (总单词数) │
│ is_active (是否当前学习中) │
└─────────────────────────────────┘💡 设计亮点
- 外键级联删除（CASCADE）：删除用户时，自动清理其学习进度，避免数据残留
- 唯一约束 ：每个用户每本书只有一条进度记录，通过
upsert实现更新或插入 - 活跃标记 ：
is_active字段标记当前正在学习的单词书，首页"最近学习"功能的核心
🖥️ 后台管理系统（danci-admin）
后台管理系统面向运营管理员，负责单词书和管理员的维护。
功能模块
📁 danci-admin/app/
├── (dashboard)/
│ ├── books/page.tsx 📚 单词书管理（CRUD）
│ └── admin-users/page.tsx 👥 管理员管理
├── api/
│ ├── auth/ 🔐 认证接口
│ │ ├── signin/route.ts ➜ 登录
│ │ ├── signup/route.ts ➜ 注册
│ │ └── signout/route.ts ➜ 登出
│ ├── books/route.ts 📚 单词书 API
│ └── admin-users/route.ts 👥 管理员 API
├── signin/page.tsx 🔑 登录页
└── signup/page.tsx 📝 注册页🎨 UI 组件库选型
选用 shadcn/ui 作为组件库，原因如下：
| 对比维度 | Element UI / Ant Design | shadcn/ui ✅ |
|---|---|---|
| 定制性 | 较低，覆盖样式复杂 | 极高，源码级定制 |
| 样式方案 | CSS-in-JS / Less | Tailwind CSS |
| AI 友好 | 一般 | ✅ 语义化，AI 易理解 |
| 按需加载 | 需配置 | ✅ 天然支持 |
| 体积 | 较大 | 极小 |
📱 H5 移动端应用
H5 应用面向终端用户，提供沉浸式的单词学习体验。
页面结构
📁 nextjs-typescript-starter/app/
├── page.tsx 🏠 首页（单词书列表 + 最近学习）
├── learn/[bookId]/page.tsx 📖 学习页面（单词卡片）
├── word/[bookId]/[wordId]/
│ ├── page.tsx 📝 单词详情页
│ └── pronunciation.tsx 🔊 发音组件
├── mine/page.tsx 👤 我的页面（学习进度）
├── login/page.tsx 🔑 登录页
└── register/page.tsx 📝 注册页🔄 核心学习流程
用户打开首页
│
├── 未登录 → 点击单词书 → 弹出登录弹窗
│
└── 已登录 → 点击单词书 → 进入学习页面
│
▼
┌──────────────────────┐
│ 获取学习进度 │
│ (user_progress 表) │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 定位到上次学到的单词 │
│ last_word_rank + 1 │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 展示单词卡片 │
│ · 单词原文 │
│ · 音标（英/美） │
│ · 释义 │
│ · 例句 │
└──────────┬───────────┘
│
┌──────────▼───────────┐
│ 用户操作 │
│ · 上一个 / 下一个 │
│ · 点击查看详情 │
│ · 点击🔊播放发音 │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 更新学习进度 │
│ POST /api/progress │
└──────────────────────┘🔊 单词发音功能
集成有道英语发音接口，支持英式和美式发音切换：
https://dict.youdao.com/dictvoice?audio={word}&type={1|2}
type=1 → 英式发音 🇬🇧
type=2 → 美式发音 🇺🇸🧹 数据清洗实战
项目中一个关键环节是将 GitHub 上的开源单词数据导入数据库。
数据清洗流程
GitHub 下载 ZIP
│
▼
解压得到 JSON 文件（178KB）
│
├── ❌ 直接让 AI 处理 178KB JSON？
│ 上下文窗口限制，Token 开销巨大
│
└── ✅ 让 AI 生成清洗脚本，本地运行
│
▼
scripts/json2csv.mjs
(仅消耗 ~1000 Token)
│
▼
CSV / SQL 格式 → 导入 Supabase💡 AI 编程最佳实践
不要把大段数据丢给 AI 处理，而是让 AI 生成处理数据的脚本。
这是本项目的重要经验：
- 上下文管理：AI 的上下文窗口有限，大文件会撑爆 Token
- 脚本化思维：让 AI 写脚本，脚本在本地运行，效率更高
- 可复用性：脚本可以反复执行，不依赖 AI 会话
🤖 AI 辅助开发实践
本项目全程使用 Claude Code 进行 AI 辅助开发，以下是总结的最佳实践。
📋 Prompt 工程要点
✅ 好的 Prompt 习惯：
┌─────────────────────────────────────────────────┐
│ 1. 上下文准确且清晰 │
│ → 把数据表结构、技术架构写入 AGENTS.md │
│ │
│ 2. 规则和规范明确 │
│ → 表单字段、业务场景、功能描述要详细 │
│ → 不能让 LLM 去"猜" │
│ │
│ 3. 颗粒度适中 │
│ → 大任务拆分为小步骤 │
│ → 每次只做一件事，验证通过再继续 │
│ │
│ 4. 让 AI 做擅长的事 │
│ → 生成代码、写脚本 → AI 做 │
│ → 运行脚本、验证结果 → 人工确认 │
└─────────────────────────────────────────────────┘🔄 Git 提交规范
项目采用 Conventional Commits（约定式提交） 规范：
| 前缀 | 用途 | 示例 |
|---|---|---|
feat |
新增功能 | feat: 完成单词发音功能 |
fix |
修复 Bug | fix: 修复登录表单 UI 割裂 |
docs |
文档变更 | docs: 更新 README |
refactor |
代码重构 | refactor: 重构学习进度逻辑 |
style |
样式变更 | style: 调整卡片间距 |
chore |
构建/工具 | chore: 更新 pnpm lock 文件 |
📁 项目目录结构总览
danci/
├── 📄 README.md # 项目说明文档
├── 📄 LICENSE # 开源许可证
├── 📄 .gitignore # Git 忽略配置
│
├── 📁 danci-admin/ # 🖥️ 后台管理系统
│ ├── app/ # Next.js App Router
│ ├── db/ # 数据库 Schema (Drizzle)
│ ├── scripts/ # 数据库脚本
│ ├── components/ # UI 组件 (shadcn/ui)
│ └── .env # 环境变量
│
└── 📁 nextjs-typescript-starter/ # 📱 H5 移动端应用
├── app/ # Next.js App Router
│ ├── api/ # API 路由
│ ├── learn/ # 学习页面
│ ├── word/ # 单词详情
│ └── mine/ # 个人中心
├── db/ # 数据库 Schema (Drizzle)
├── docs/ # 技术设计文档
└── .env # 环境变量🚀 快速启动
环境要求
- Node.js >= 18
- pnpm (推荐) 或 npm
- Supabase 账号
启动步骤
bash
# 1. 克隆项目
git clone <repo-url>
cd danci
# 2. 启动后台管理系统
cd danci-admin
cp .env.example .env # 配置环境变量
pnpm install
pnpm dev # 访问 http://localhost:3000
# 3. 启动 H5 应用
cd ../nextjs-typescript-starter
cp .env.example .env # 配置环境变量
pnpm install
pnpm dev # 访问 http://localhost:3001环境变量配置
env
# Supabase 数据库连接
DATABASE_URL=postgresql://...
# NextAuth 认证
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key🎯 总结与展望
✅ 已完成功能
- 🖥️ 后台管理系统 --- 单词书管理、管理员管理
- 🔐 用户认证 --- 注册、登录、会话管理
- 📚 单词书浏览 --- 首页列表展示
- 📖 单词学习 --- 卡片式学习，支持翻页
- 📊 学习进度 --- 自动保存，断点续学
- 🔊 单词发音 --- 英式/美式发音切换
- 📱 移动端适配 --- H5 响应式布局
🔮 未来规划
- 🧠 艾宾浩斯遗忘曲线 --- 智能复习提醒
- 📈 学习统计 --- 每日学习数据可视化
- 🏆 学习打卡 --- 连续学习激励机制
- 📱 多端扩展 --- React Native / Flutter 客户端
- 🤖 AI 智能推荐 --- 基于学习数据的个性化推荐
💡 本项目的核心理念 ：善用 AI 编程工具，将精力集中在业务逻辑和产品设计上，而非重复性的代码编写。AI 不是替代开发者，而是让开发者更高效。