🎯 Danci —— 用 AI 驱动开发一个全栈英语单词学习平台Danci 是一个 AI 驱动的全栈英语单词学习平台，

从零到一，借助 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 账号

启动步骤

# 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

环境变量配置

# Supabase 数据库连接
DATABASE_URL=postgresql://...

# NextAuth 认证
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key

🎯 总结与展望

✅ 已完成功能

🖥️ 后台管理系统 — 单词书管理、管理员管理
🔐 用户认证 — 注册、登录、会话管理
📚 单词书浏览 — 首页列表展示
📖 单词学习 — 卡片式学习，支持翻页
📊 学习进度 — 自动保存，断点续学
🔊 单词发音 — 英式/美式发音切换
📱 移动端适配 — H5 响应式布局

🔮 未来规划

🧠 艾宾浩斯遗忘曲线 — 智能复习提醒
📈 学习统计 — 每日学习数据可视化
🏆 学习打卡 — 连续学习激励机制
📱 多端扩展 — React Native / Flutter 客户端
🤖 AI 智能推荐 — 基于学习数据的个性化推荐

💡 本项目的核心理念：善用 AI 编程工具，将精力集中在业务逻辑和产品设计上，而非重复性的代码编写。AI 不是替代开发者，而是让开发者更高效。