从零搭建单词管理系统：Next.js + Supabase + Drizzle ORM 全栈实战

从零搭建单词管理系统：Next.js + Supabase + Drizzle ORM 全栈实战

学了 Next.js 文件路由，学了 SDD 规范驱动开发，但总觉得缺一个完整的全栈项目把知识串起来？本文以一个"单词后台管理系统 + H5 应用"为真实需求，完整拆解从数据清洗、云端数据库、ORM 映射、UI 组件库到 Conventional Commits 的全链路工程实践。Supabase 做 BaaS 云数据库，Drizzle ORM 做对象关系映射，shadcn/ui 做组件层，Next.js 做全栈骨架------四个工具各司其职，拼出一个 AI 友好的现代全栈架构。建议收藏后动手实践。

---

一、项目概述：为什么做单词管理系统？

1.1 应用形式

项目名称：words（单词后台管理系统 + H5 应用）

  两种应用形态：
  ┌──────────────────────────────────────────────────┐
  │                                                  │
  │  ① 后台管理系统（Admin Dashboard）               │
  │  → 单词书管理：创建、删除、修改、查询             │
  │  → 管理员管理：超级管理员 + 普通管理员            │
  │  → 交给小编管理员使用                             │
  │                                                  │
  │  ② H5 应用（面向终端用户）                        │
  │  → 用户在手机上背单词                            │
  │  → 从单词书中获取单词列表                        │
  │                                                  │
  │  ③ 多端开发                                       │
  │  → 后台 + H5 共享同一套数据                      │
  │  → Next.js 全栈搞定两端                          │
  └──────────────────────────────────────────────────┘

1.2 路由设计

后台管理系统路由：

  /                     → 注册超级管理员页面 → 登录
  /                     → 登录页 → 单词书管理

  路由流程：
  ┌─────────────┐     ┌──────────────┐     ┌──────────────┐
  │  访问 /     │ ──→ │  注册超管页面  │ ──→ │   登录页面    │
  └─────────────┘     └──────────────┘     └──────────────┘
                                                   │
                                                   ▼
                                           ┌──────────────┐
                                           │  单词书管理   │
                                           │  （主面板）   │
                                           └──────────────┘
                                                   │
                                    ┌──────────────┼──────────────┐
                                    ▼              ▼              ▼
                              ┌──────────┐  ┌──────────┐  ┌──────────┐
                              │ 单词书CRUD│  │ 管理员管理│  │  H5 应用 │
                              └──────────┘  └──────────┘  └──────────┘

1.3 项目亮点

┌──────────────────────────────────────────────────────────┐
│                    项目四大亮点                           │
│                                                          │
│  ① 数据清洗                                              │
│  → GitHub 高星单词资料库作为数据源                        │
│  → 数据清洗：选择、格式化、审核                           │
│  → 确保数据质量后再导入数据库                             │
│                                                          │
│  ② Supabase 云端 BaaS 数据库                             │
│  → 关系型数据库（类 PostgreSQL）                         │
│  → 同时支持向量数据库                                    │
│  → Backend as a Service，部署成本几乎为零                 │
│                                                          │
│  ③ ORM 对象关系映射                                      │
│  → 不用写 SQL，不用做数据库底层处理                       │
│  → 对象操作：todo.save() 自动翻译成 INSERT INTO           │
│  → 对象和数据库里的一行记录一一对应                       │
│                                                          │
│  ④ shadcn/ui 组件库                                      │
│  → 80% 前端组件业务趋同，不重复造轮子                    │
│  → 定制性极强，配合 Tailwind CSS                         │
│  → 语义化、AI 友好、按需加载                             │
└──────────────────────────────────────────────────────────┘

---

二、Supabase：云端 BaaS 数据库

2.1 什么是 BaaS？

BaaS = Backend as a Service（后端即服务）

  传统开发：
  → 自己搭数据库服务器
  → 自己写后端 API
  → 自己部署、运维、备份
  → 成本高、周期长

  BaaS 模式：
  → 数据库在云端，开箱即用
  → 自动提供 RESTful API
  → 自动提供认证、存储、实时订阅
  → 部署成本几乎为零

  ┌──────────────────────────────────────────────┐
  │  Supabase 提供的能力                           │
  │  ├── PostgreSQL 关系型数据库                  │
  │  ├── 向量数据库（pgvector）                   │
  │  ├── 认证服务（Auth）                         │
  │  ├── 文件存储（Storage）                      │
  │  ├── 实时订阅（Realtime）                     │
  │  └── 自动生成 RESTful API                     │
  └──────────────────────────────────────────────┘

2.2 为什么选 Supabase？

Supabase 的核心优势：

  ① 性能
  → 基于 PostgreSQL，工业级关系型数据库
  → 支持复杂查询、事务、索引
  → 性能不输自建数据库

  ② 安全
  → 行级安全策略（Row Level Security）
  → 内置认证系统（JWT、OAuth）
  → 数据权限细粒度控制

  ③ 可扩展性
  → 支持向量数据库（pgvector 扩展）
  → 可以做 AI 语义搜索、RAG
  → 云端弹性扩容

  ④ 部署成本
  → 免费额度足够个人项目
  → 不用自己买服务器
  → 不用自己运维
  → 几乎为零的部署成本

  ⑤ AI 友好
  → 标准 PostgreSQL，AI 非常熟悉
  → 有完善的 SDK 和文档
  → AI 可以直接生成操作代码

2.3 Supabase 在项目中的角色

┌──────────────────────────────────────────────────────────┐
│              Supabase 在架构中的位置                      │
│                                                          │
│  ┌──────────────────────────────────────────────┐        │
│  │  Next.js 全栈应用                             │        │
│  │  ├── 前端页面（App Router）                   │        │
│  │  ├── API 路由（Route Handlers）              │        │
│  │  └── Server Components（服务端渲染）         │        │
│  └──────────────────┬───────────────────────────┘        │
│                     │                                    │
│                     │  Drizzle ORM（对象关系映射）        │
│                     │  → db/index.ts 连接数据库           │
│                     │  → db/schema.ts 定义表结构          │
│                     │  → 对象操作翻译成 SQL               │
│                     │                                    │
│  ┌──────────────────▼───────────────────────────┐        │
│  │  Supabase（云端 BaaS）                        │        │
│  │  ├── PostgreSQL 关系型数据库                  │        │
│  │  ├── words 表（单词数据）                    │        │
│  │  ├── books 表（单词书）                      │        │
│  │  ├── admins 表（管理员）                     │        │
│  │  └── pgvector（向量数据库扩展）              │        │
│  └──────────────────────────────────────────────┘        │
└──────────────────────────────────────────────────────────┘

---

三、Drizzle ORM：对象关系映射

3.1 什么是 ORM？

ORM = Object-Relational Mapping（对象关系映射）

  核心思想：
  → 数据库里的一行记录 = 代码里的一个对象
  → 操作对象 = 操作数据库
  → ORM 负责翻译：对象操作 → SQL 语句

  没有 ORM 时：
  → 手写 SQL：INSERT INTO words (word, meaning) VALUES ('hello', '你好')
  → 手动处理参数绑定、结果映射
  → SQL 注入风险
  → 不同数据库方言不同，切换困难

  有 ORM 后：
  → const word = await db.insert(words).values({ word: 'hello', meaning: '你好' })
  → ORM 自动翻译成 SQL
  → 自动参数绑定，防 SQL 注入
  → 切换数据库只需改配置

  面向对象编程的体现：
  → Next.js 层：面向对象编程 Object 高级
  → 不同国家的人 → User 对象
  → user.save() → ORM 翻译 → SQL INSERT INTO
  → ORM 映射 = 翻译层

3.2 为什么选 Drizzle？

Drizzle ORM 的特点：

  ① 轻量级
  → 零依赖，体积小
  → 不像 Prisma 那样需要额外的引擎进程
  → 直接跑在 Node.js / Edge Runtime 上

  ② TypeScript 原生
  → 完整的类型推导
  → schema 定义即类型
  → 查询结果自动推导类型

  ③ SQL-like API
  → API 设计接近 SQL 语法
  → db.select().from(users).where(eq(users.id, 1))
  → 学习曲线低，SQL 基础即可上手

  ④ 无需建表，建 Schema 即可
  → 不用在数据库里手动建表
  → 在代码里定义 Schema
  → Schema 映射的就是数据表
  → migrate 自动迁移

  ⑤ AI 友好
  → 类型完整 → AI 知道字段名和类型
  → API 语义化 → AI 容易生成正确代码
  → 不需要猜 SQL → 减少幻觉

3.3 Drizzle 项目结构

db/
├── index.ts          # 数据库配置
│   → 连接 Supabase 并返回 db 操作句柄
│   → 读取 .env 中的 DATABASE_URL
│   → 创建 Drizzle 实例
│
└── schema.ts         # 对象定义数据库表结构
    → words 表：单词数据
    → books 表：单词书
    → admins 表：管理员
    → 每个表用对象定义，映射到数据库

// db/index.ts
import { drizzle } from 'drizzle-orm/node-postgres';
import { Pool } from 'pg';
import * as schema from './schema';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

export const db = drizzle(pool, { schema });

// db/schema.ts
import { pgTable, serial, varchar, text, timestamp } from 'drizzle-orm';

export const words = pgTable('words', {
  id: serial('id').primaryKey(),
  word: varchar('word', { length: 255 }).notNull(),
  phonetic: varchar('phonetic', { length: 255 }),
  meaning: text('meaning').notNull(),
  bookId: serial('book_id').references(() => books.id),
  createdAt: timestamp('created_at').defaultNow(),
});

export const books = pgTable('books', {
  id: serial('id').primaryKey(),
  title: varchar('title', { length: 255 }).notNull(),
  description: text('description'),
  createdAt: timestamp('created_at').defaultNow(),
});

export const admins = pgTable('admins', {
  id: serial('id').primaryKey(),
  username: varchar('username', { length: 255 }).notNull().unique(),
  password: varchar('password', { length: 255 }).notNull(),
  role: varchar('role', { length: 50 }).default('admin'),
  createdAt: timestamp('created_at').defaultNow(),
});

3.4 Drizzle 配套脚本

Drizzle 有一系列包和命令：

  ┌──────────────────────────────────────────────────────────┐
│              Drizzle 四大核心命令                         │
│                                                          │
│  ① generate（生成迁移文件）                               │
│  → 当 schema.ts 有变更时（加表、改字段、加索引）          │
│  → 生成一个新的 SQL 迁移文件                              │
│  → 多一个 schema 文件记录变更                             │
│  → npx drizzle-kit generate                              │
│                                                          │
│  ② migrate（数据库迁移）                                 │
│  → 执行迁移文件，将变更应用到数据库                       │
│  → 新表创建、字段修改等生效                               │
│  → npx drizzle-kit migrate                               │
│                                                          │
│  ③ push（数据库推送）                                    │
│  → 直接将 schema 推送到数据库                             │
│  → 跳过迁移文件，适合开发阶段快速迭代                     │
│  → npx drizzle-kit push                                  │
│                                                          │
│  ④ studio（数据库可视化工具）                            │
│  → 启动一个 Web 界面查看数据库                           │
│  → 类似 phpMyAdmin / DBeaver                             │
│  → 可视化查看表结构、数据                                 │
│  → npx drizzle-kit studio                                │
└──────────────────────────────────────────────────────────┘

开发流程：

  ① 在 schema.ts 定义/修改表结构
     │
     ▼
  ② npx drizzle-kit generate
     → 生成迁移文件（SQL）
     │
     ▼
  ③ npx drizzle-kit migrate
     → 迁移应用到 Supabase
     │
     ▼
  ④ npx drizzle-kit studio
     → 可视化查看数据
     → 验证表结构是否正确
     │
     ▼
  ⑤ 在代码中用 ORM 操作数据库
     → db.select().from(words)
     → db.insert(words).values(...)

---

四、shadcn/ui：定制性极强的组件库

4.1 为什么用组件库？

80% 前端组件业务趋同

  任何后台管理系统都有：
  → 表格（Table）
  → 表单（Form）
  → 按钮（Button）
  → 对话框（Dialog）
  → 下拉菜单（Dropdown）
  → 通知提示（Toast）
  → 标签页（Tabs）
  → 面包屑（Breadcrumb）

  不用组件库 → 重复造轮子 → 浪费时间
  用组件库 → 聚焦业务逻辑 → 效率提升

4.2 组件库对比

┌──────────────────────────────────────────────────────────┐
│              组件库对比                                   │
│                                                          │
│           Element UI    ANT Design    shadcn/ui          │
│  ─────────────────────────────────────────                │
│  来源       Vue 生态      React 生态    React + Tailwind  │
│  定制性     中等          中等          极高              │
│  代码位置   npm 包        npm 包        复制到项目中      │
│  可修改     封装黑盒       封装黑盒      源码在项目里      │
│  样式       SCSS/Less     Less          Tailwind CSS     │
│  AI 友好    中            中            极高             │
│  按需加载   需配置         需配置        天然按需          │
│  适合       Vue 项目       中后台        Next.js 全栈     │
└──────────────────────────────────────────────────────────┘

4.3 shadcn/ui 的独特之处

shadcn/ui 不是传统 npm 包，而是"复制粘贴"组件库

  传统组件库（Ant Design）：
  → npm install antd
  → import { Button } from 'antd'
  → 组件代码在 node_modules 里（黑盒）
  → 想改样式？覆盖 CSS / 用 !important
  → 想改逻辑？基本不可能

  shadcn/ui：
  → npx shadcn-ui add button
  → 组件代码复制到 components/ui/ 目录下
  → 组件源码在你的项目里
  → 想改样式？直接改源码
  → 想改逻辑？直接改源码
  → 完全可控，定制性极强

  ┌──────────────────────────────────────────────┐
  │  components/ui/                               │
  │  ├── button.tsx          # 按钮组件源码       │
  │  ├── dialog.tsx          # 对话框组件源码     │
  │  ├── input.tsx           # 输入框组件源码     │
  │  ├── table.tsx           # 表格组件源码       │
  │  ├── dropdown-menu.tsx   # 下拉菜单组件源码   │
  │  └── ...                                     │
  │  → 所有源码可见、可改                        │
  └──────────────────────────────────────────────┘

  配合 Tailwind CSS：
  → 原子类名，自带语义
  → AI 友好："写一个红色按钮" → bg-red-500
  → 按需加载：只用到的组件才复制进来
  → 没有冗余代码

4.4 shadcn/ui 对 AI 的价值

为什么 AI 特别喜欢 shadcn/ui？

  ① 源码可见
  → AI 可以读取 components/ui/ 下的组件源码
  → 知道组件的 props、样式、逻辑
  → 生成代码时引用准确

  ② Tailwind 语义化
  → 类名本身就是语义描述
  → AI 理解 "flex items-center gap-2" 的含义
  → 生成样式准确率高

  ③ 无黑盒
  → 不需要猜组件内部实现
  → 不需要翻文档查 API
  → AI 直接看源码就能理解

  ④ 按需加载
  → 只有用到的组件才存在
  → AI 的上下文干净，没有噪音
  → 生成更准确

---

五、数据清洗与导入：从 GitHub 到数据库

5.1 数据来源

数据源：GitHub 高星单词资料库

  GitHub 上有高质量的单词数据（高星仓库）
  → 下载 ZIP
  → 解压得到 JSON 文件（178KB）
  → 包含单词、音标、释义等字段

  但不能直接导入数据库：
  → JSON 格式 ≠ 数据库格式
  → 数据可能有脏数据
  → 字段可能不匹配
  → 需要数据清洗

5.2 数据清洗三步

┌──────────────────────────────────────────────────────────┐
│                  数据清洗三步法                           │
│                                                          │
│  第一步：选择                                             │
│  → 从原始数据中选择需要的字段                             │
│  → word（单词）、phonetic（音标）、meaning（释义）       │
│  → 去掉不需要的字段                                      │
│                                                          │
│  第二步：格式化                                           │
│  → 统一字段名和数据类型                                   │
│  → 空值处理（null → 默认值）                             │
│  → 字符串去除首尾空格                                    │
│  → 音标格式统一                                          │
│                                                          │
│  第三步：审核                                             │
│  → 检查是否有重复单词                                    │
│  → 检查释义是否完整                                      │
│  → 检查音标是否正确                                      │
│  → 确保数据质量                                          │
└──────────────────────────────────────────────────────────┘

5.3 JSON 转 CSV 的 AI 协作

数据导入的挑战：

  JSON 文件 178KB
  → 直接喂给 AI 让转换 → 178KB 的 Token 消耗巨大
  → 而且可能超出上下文限制

  两种方案：

  方案一：让 AI 直接转换（不推荐）
  → 把 JSON 内容粘贴给 AI
  → "帮我把这个 JSON 转成 CSV"
  → Token 消耗：~178KB
  → 成本高，效率低

  方案二：让 AI 写转换脚本（推荐）
  → 只给 AI 看 JSON 的字段结构（几百 Token）
  → "写一段 JSON 转 CSV 的脚本"
  → AI 生成脚本代码（~1000 Token）
  → 本地运行脚本，完成转换
  → Token 消耗：~1000
  → 成本低，效率高，可复用

  ┌──────────────────────────────────────────────────┐
  │  AI 协作最佳实践                                  │
  │                                                  │
  │  不要把大量数据喂给 AI 处理                       │
  │  让 AI 写处理数据的脚本                           │
  │  本地运行脚本处理数据                             │
  │  → Token 消耗从 178KB 降到 1KB                   │
  │  → 效率提升 178 倍                               │
  │  → 脚本可复用、可迭代                             │
  └──────────────────────────────────────────────────┘

// json-to-csv.mjs（AI 生成的转换脚本示例）
import { readFileSync, writeFileSync } from 'fs';

const data = JSON.parse(readFileSync('./words.json', 'utf-8'));

const csv = data
  .map(item => `${item.word},${item.phonetic || ''},${item.meaning}`)
  .join('\n');

writeFileSync('./words.csv', `word,phonetic,meaning\n${csv}`);
console.log(`转换完成：${data.length} 条记录`);

5.4 数据导入流程

完整数据导入流程：

  GitHub 高星仓库
    │
    ▼
  下载 ZIP → 解压
    │
    ▼
  words.json（178KB 原始数据）
    │
    ▼
  数据清洗（选择、格式化、审核）
    │
    ▼
  AI 写转换脚本（~1000 Token）
    │
    ▼
  本地运行脚本 → words.csv
    │
    ▼
  导入 Supabase 数据库
    → 直接导入 CSV（Supabase Dashboard 支持）
    → 或用 Drizzle 脚本批量插入
    │
    ▼
  words 表（正式数据）

---

六、Conventional Commits：约定式提交

6.1 为什么需要提交规范？

没有规范的 Git 提交信息：

  git commit -m "update"
  git commit -m "fix bug"
  git commit -m "改了一些东西"
  git commit -m "。。。"

  问题：
  → 看不出改了什么
  → 看不出是功能还是修复
  → 无法自动生成 CHANGELOG
  → 无法自动判断版本号该升多少
  → 团队协作混乱

有规范的提交信息：

  git commit -m "feat: 新增单词书管理 CRUD"
  git commit -m "fix: 修复单词导入重复问题"
  git commit -m "docs: 更新 API 文档"

  优势：
  → 一眼看出改动类型和内容
  → 可自动生成 CHANGELOG
  → 可自动判断版本号
  → Coding Agent 内置的 Git 提交天然遵循此规范

6.2 七大提交类型

Conventional Commits 规范：

  ┌──────────────────────────────────────────────────────────┐
│              七大提交类型                                  │
│                                                          │
│  feat     → 新增功能                                     │
│  → feat: 新增单词书管理 CRUD                              │
│  → feat: 添加 H5 单词列表页                               │
│                                                          │
│  fix      → 修复 bug                                    │
│  → fix: 修复单词导入重复问题                              │
│  → fix: 修复登录跳转异常                                  │
│                                                          │
│  docs     → 文档变更                                     │
│  → docs: 更新 README                                     │
│  → docs: 添加 API 文档                                   │
│                                                          │
│  refactor → 代码重构                                    │
│  → refactor: 重构数据库连接逻辑                           │
│  → refactor: 提取公共组件                                 │
│                                                          │
│  style    → 样式变更                                     │
│  → style: 调整按钮间距                                   │
│  → style: 统一颜色变量                                    │
│                                                          │
│  test     → 测试变更                                     │
│  → test: 添加单词导入测试                                 │
│  → test: 添加 API 单元测试                                │
│                                                          │
│  chore    → 构建工具变更                                 │
│  → chore: 更新依赖版本                                    │
│  → chore: 配置 ESLint                                    │
└──────────────────────────────────────────────────────────┘

  格式：<type>(scope): <description>
  → type：提交类型
  → scope：影响范围（可选）
  → description：简短描述

  Coding Agent 内置的 Git 提交：
  → Claude Code / Codex / Trae 自动遵循此规范
  → AI 生成的 commit message 天然符合 Conventional Commits
  → 不需要人手动规范

---

七、全栈架构全景

7.1 架构图

┌──────────────────────────────────────────────────────────┐
│                  全栈架构全景图                           │
│                                                          │
│  ┌──────────────────────────────────────────────┐        │
│  │  前端层（Next.js App Router）                  │        │
│  │  ├── shadcn/ui 组件（components/ui/）         │        │
│  │  ├── Tailwind CSS（原子类样式）               │        │
│  │  ├── 后台管理页面（/app/admin/）               │        │
│  │  └── H5 应用页面（/app/h5/）                   │        │
│  └──────────────────┬───────────────────────────┘        │
│                     │                                    │
│                     │  Server Components / Route Handlers│
│                     │  → 服务端渲染 + API 路由            │
│                     │                                    │
│  ┌──────────────────▼───────────────────────────┐        │
│  │  ORM 层（Drizzle）                             │        │
│  │  ├── db/index.ts（数据库连接）                 │        │
│  │  ├── db/schema.ts（表结构定义）                │        │
│  │  → 对象操作翻译成 SQL                          │        │
│  │  → 类型安全，防 SQL 注入                       │        │
│  └──────────────────┬───────────────────────────┘        │
│                     │                                    │
│                     │  DATABASE_URL（.env）              │
│                     │  → 环境变量连接云端数据库           │
│                     │                                    │
│  ┌──────────────────▼───────────────────────────┐        │
│  │  数据层（Supabase BaaS）                      │        │
│  │  ├── PostgreSQL 关系型数据库                  │        │
│  │  │   ├── words 表（单词数据）                 │        │
│  │  │   ├── books 表（单词书）                   │        │
│  │  │   └── admins 表（管理员）                  │        │
│  │  ├── pgvector（向量数据库扩展）              │        │
│  │  ├── Auth（认证服务）                        │        │
│  │  └── Storage（文件存储）                     │        │
│  └──────────────────────────────────────────────┘        │
│                                                          │
│  工程规范：                                               │
│  ├── Conventional Commits（约定式提交）                  │
│  ├── SDD 文档驱动开发                                    │
│  └── Git 版本控制（三级回退策略）                        │
└──────────────────────────────────────────────────────────┘

7.2 数据流示例

场景：管理员在后台创建一本新的单词书

  管理员填写表单
    │
    ▼
  shadcn/ui Form 组件（前端）
    → 表单验证
    → 用户输入：书名、描述
    │
    ▼
  Next.js Route Handler（API 层）
    → POST /api/books
    → 接收请求体
    │
    ▼
  Drizzle ORM（数据层）
    → db.insert(books).values({ title, description })
    → ORM 翻译成 SQL：INSERT INTO books (title, description) VALUES (...)
    │
    ▼
  Supabase（数据库层）
    → 执行 SQL
    → 插入成功，返回新记录
    │
    ▼
  响应链路
    → Supabase 返回数据
    → Drizzle 包装成对象
    → Route Handler 返回 JSON
    → 前端更新 UI
    → Toast 提示"创建成功"

---

八、技术选型决策表

8.1 选型理由

技术选择	替代方案	选择理由
Next.js	Vite + React	全栈统一、AI 友好约定、SSR 开箱即用
Supabase	自建 PostgreSQL + Node.js	BaaS 零运维、免费额度、支持向量数据库
Drizzle	Prisma / 原生 SQL	轻量零依赖、TypeScript 原生、SQL-like API
shadcn/ui	Ant Design / Element UI	源码可改、Tailwind 语义化、AI 友好
Tailwind CSS	SCSS / styled-components	原子类名、语义化、AI 理解力强
Conventional Commits	自由格式	Coding Agent 内置、可生成 CHANGELOG

8.2 AI 协作要点

AI 协作最佳实践：

  ① 不要把大量数据喂给 AI
  → 178KB JSON → 让 AI 写转换脚本（~1000 Token）
  → 本地运行脚本处理数据
  → Token 效率提升 178 倍

  ② 用约定减少 AI 猜测
  → Next.js 约定：文件位置、命名规则
  → Drizzle 约定：schema 即表结构
  → shadcn/ui 约定：组件在 components/ui/
  → 约定越多 → AI 猜得越少 → 准确率越高

  ③ SDD 文档 + 框架约定 = 双重上下文
  → SDD 文档：做什么（需求、架构、任务）
  → 框架约定：怎么做（文件位置、命名、API）
  → 两者结合 → AI 上下文完整

  ④ Git 作为安全网
  → 每次让 AI 生成前先 commit
  → 生成后验收 → 通过就 commit
  → 不通过就回退
  → Conventional Commits 自动规范提交信息

---

九、总结

9.1 知识体系图

Next.js + Supabase + Drizzle 全栈实战
│
├── 项目概述
│   ├── 应用形式：后台管理 + H5 应用 + 多端开发
│   ├── 路由设计：/ → 注册超管 → 登录 → 单词书管理
│   └── 四大亮点：数据清洗 / Supabase / ORM / shadcn
│
├── Supabase（BaaS 云数据库）
│   ├── BaaS = Backend as a Service
│   ├── PostgreSQL 关系型 + pgvector 向量数据库
│   ├── 性能、安全、可扩展、零部署成本
│   └── Auth + Storage + Realtime + RESTful API
│
├── Drizzle ORM（对象关系映射）
│   ├── ORM = Object-Relational Mapping
│   ├── 对象 → SQL 自动翻译
│   ├── 项目结构：db/index.ts + db/schema.ts
│   ├── 四大命令：generate / migrate / push / studio
│   └── 轻量、TS 原生、SQL-like API
│
├── shadcn/ui（组件库）
│   ├── 80% 组件业务趋同，不重复造轮子
│   ├── 不是 npm 包，是复制源码到项目
│   ├── 源码在 components/ui/ 下，完全可控
│   ├── 配合 Tailwind CSS，语义化 AI 友好
│   └── 对比 Element UI / Ant Design
│
├── 数据清洗与导入
│   ├── 数据源：GitHub 高星单词仓库
│   ├── 清洗三步：选择 → 格式化 → 审核
│   ├── AI 协作：让 AI 写脚本而非处理数据
│   │   → 178KB Token → 1KB Token（效率 178 倍）
│   └── 导入流程：JSON → CSV → Supabase
│
├── Conventional Commits（约定式提交）
│   ├── 七大类型：feat / fix / docs / refactor / style / test / chore
│   ├── 格式：<type>(scope): <description>
│   └── Coding Agent 内置 Git 提交天然遵循
│
├── 全栈架构
│   ├── 前端层：Next.js + shadcn/ui + Tailwind
│   ├── ORM 层：Drizzle（schema 即表结构）
│   ├── 数据层：Supabase（PostgreSQL + pgvector）
│   └── 工程规范：SDD + Conventional Commits + Git
│
└── AI 协作要点
    ├── 不喂大数据，让 AI 写脚本
    ├── 用约定减少 AI 猜测
    ├── SDD 文档 + 框架约定 = 双重上下文
    └── Git 三级回退作为安全网

9.2 一句话总结

这个单词管理系统展示了一套 AI 时代全栈架构的标准范式：Next.js 做全栈骨架（约定驱动 AI 编码），Supabase 做 BaaS 云数据库（零运维部署），Drizzle ORM 做对象关系映射（不用写 SQL），shadcn/ui 做组件层（源码可控 + Tailwind 语义化）。四个工具各司其职，配合 SDD 文档和 Conventional Commits 规范，让 AI Coding Agent 的上下文 Buff 拉满，代码生成准确率指数级提升。核心洞察：不要把大量数据喂给 AI 处理------让 AI 写处理数据的脚本，Token 效率提升 178 倍。

---

如果这篇文章对你有帮助，欢迎点赞 和收藏！