微型商城（Mini Mall）—— 详细模块开发

5.5 商品模块开发

本节目标：完成商品的增删查改全流程，学会用 Skill 加速开发

演示的 Claude Code 功能：自定义 Skill 实战、/review、官方 Skill

5.5.1 开发思路

商品模块是最核心的模块，包含：

后端 API        前端页面
──────────      ──────────
GET /api/products    →  首页商品列表（搜索 + 分类筛选 + 分页）
GET /api/products/[id] →  商品详情页
GET /api/categories   →  顶部导航的分类标签

（管理员接口稍后在 6.8 节实现）

5.5.2 用 Prompt 驱动开发

在 Claude Code 对话中输入：

请实现商品模块的公开 API：
1. GET /api/products — 商品列表，支持 search（模糊搜索）、category（按slug筛选）、page（分页，每页9条）
2. GET /api/products/[id] — 商品详情，包含关联的分类信息
3. GET /api/categories — 分类列表，包含每个分类下的商品数量

然后实现前端页面：
1. 首页 — 商品网格展示 + 搜索框 + 分类标签切换 + 分页
2. 商品详情页 — 大图 + 名称/价格/描述/库存 + "加入购物车"按钮

要求：
- 用 Server Component 做数据获取
- 用 TailwindCSS 做样式
- UI 文案用中文
- 参考 CLAUDE.md 中的项目规范

AI 会：

1. 读取 CLAUDE.md 了解项目规范
2. 读取 Prisma schema 了解数据模型
3. 按照你的要求生成代码
4. 告诉你每个文件的用途

5.5.3 代码审查：用 /review 检查质量

每个模块开发完后，用 /review 让 AI 做一次代码审查：

/review

AI 会检查：

• 代码是否符合项目规范
• 有没有潜在的性能问题（如 N+1 查询）
• 错误处理是否完善
• 类型定义是否正确

提示：/review 类似于让一个高级工程师帮你 Code Review。它可能不会发现所有问题，但能帮你揪出大部分低级错误。

5.5.4 你学到了什么

概念	说明
Server Component	Next.js 默认的服务端组件，可以直接访问数据库
分页实现	skip + take 实现数据库级分页
关联查询	Prisma 的 include 语法加载关联数据
/review	让 AI 审查代码质量

---

5.6 用户认证模块

本节目标：实现注册登录系统，理解认证的基本原理

演示的 Claude Code 功能：/security-review、多模型切换

5.6.1 认证基础：Cookie + Session

我们用最简单也最透明的认证方案——Cookie Session：

注册：用户填邮箱+密码 → bcrypt 哈希密码 → 存入数据库
登录：验证邮箱+密码 → 生成 session token → 写入 Cookie
鉴权：每次请求读取 Cookie → 解析出用户 ID → 判断权限

提示： 为什么不直接用 next-auth？ next-auth 很强大，但它是"黑盒"——你不知道内部怎么工作的。对于教学来说，自己实现一个简易的认证系统，能看到每一步的细节，更容易理解认证的本质。学会原理后，再用 next-auth 也不迟。

5.6.2 实现认证系统

在 Claude Code 中输入：

请实现一个简易的用户认证系统：

1. 创建 src/lib/auth.ts，包含以下函数：
   - hashPassword(password) — 用 bcryptjs 哈希密码
   - verifyPassword(password, hash) — 验证密码
   - setSession(userId, role) — 把用户信息写入 httpOnly Cookie
   - getSession() — 从 Cookie 读取当前用户信息
   - getCurrentUser() — 获取当前用户的完整信息
   - clearSession() — 清除 Cookie（退出登录）

2. 实现 API：
   - POST /api/auth/register — 注册（验证邮箱唯一性，密码至少6位）
   - POST /api/auth/login — 登录（验证密码，写入session）
   - GET /api/auth/me — 获取当前用户
   - POST /api/auth/logout — 退出登录

3. 实现前端页面：
   - /login — 登录表单
   - /register — 注册表单

要求：
- 密码用 bcryptjs 哈希存储，绝不能存明文
- 登录失败时不要暴露"用户不存在"和"密码错误"的区别（防止撞库攻击）
- Session Cookie 设置 httpOnly + sameSite + secure（生产环境）

5.6.3 安全审查：用 /security-review 检查

认证模块涉及用户数据安全。让 AI 做一次安全检查：

/security-review

AI 会检查：

• 密码是否正确哈希存储（绝对不能明文）
• 有没有 SQL 注入风险（Prisma 已经帮我们预防了）
• Session Cookie 的安全属性是否正确
• 错误信息是否泄露了系统内部信息

注意：/security-review 是一个参考性检查，不能替代专业的安全审计。但它能帮你发现大部分常见的安全问题，是上线前的重要一步。

5.6.4 多模型切换实战

在这个项目中，你可以体验多模型切换的实际收益：

任务	推荐模型	理由
写用户认证逻辑	Claude Opus	安全相关，要确保万无一失
写登录页面 UI	Claude Haiku	简单表单，Haiku 足够且更快更便宜
日常功能开发	Claude Sonnet	速度和质量的最佳平衡

切换模型只需一条命令：

/model opus     ← 切换到 Opus，处理复杂逻辑
/model sonnet   ← 切回 Sonnet，日常开发
/model haiku    ← 切换到 Haiku，快速轻量任务

提示： 省钱技巧：每天开发结束时，用 /cost 查看当天的 API 费用。如果发现账单太高，下次更多用 Haiku 处理简单任务。

5.6.5 你学到了什么

概念	说明
bcrypt	密码哈希算法，即使数据库泄露，密码也无法被还原
Cookie Session	最简单的认证方案，Cookie 里存标识，服务端验证
httpOnly Cookie	JavaScript 无法读取，防止 XSS 攻击偷取 Cookie
/security-review	AI 辅助的安全检查
/model 切换	按任务复杂度选择不同级别的模型

---

5.7 购物车 + 订单模块

本节目标：实现电商的核心交易流程

演示的 Claude Code 功能：Task 任务列表、复杂业务逻辑处理

5.7.1 用 Task 管理复杂模块

购物车和订单模块涉及多个子任务。告诉 AI：

请创建任务列表，跟踪购物车和订单模块的开发进度。

AI 会帮你拆分成：

□ 购物车 API（GET、POST、PUT、DELETE）
□ 购物车页面（展示、修改数量、删除、提交订单）
□ 订单 API（GET 列表、GET 详情、POST 下单）
□ 订单页面（列表页、详情页）
□ 订单状态机（PENDING → PAID → SHIPPED → COMPLETED）

每完成一项，AI 会自动标记为完成，你随时知道进度。

5.7.2 实现购物车

在 Claude Code 中输入：

请实现购物车功能：

API：
- GET /api/cart — 获取当前用户的购物车（需登录）
- POST /api/cart — 加入购物车（productId + quantity）
  - 如果购物车已有该商品，增加数量
  - 检查库存，库存不足返回错误
- PUT /api/cart/[id] — 修改数量
- DELETE /api/cart/[id] — 删除某项

前端页面 /cart：
- 列表展示购物车商品（图片、名称、单价、数量、小计）
- 每项可以 + / - 调整数量，或删除
- 底部显示总价，"提交订单"按钮
- 未登录时跳转到登录页

5.7.3 实现订单和"模拟支付"

请实现订单功能：

API：
- POST /api/orders — 从购物车创建订单
  - 在数据库事务中：创建订单 → 扣减库存 → 清空购物车
  - 如果库存不足，返回具体哪个商品缺货
- GET /api/orders — 我的订单列表
- GET /api/orders/[id] — 订单详情
- PUT /api/orders/[id] — 模拟支付（PENDING → PAID）

前端页面：
- /orders — 订单列表（订单号、金额、状态标签、时间）
- /orders/[id] — 订单详情（商品明细、合计、状态、模拟支付按钮）

订单状态流转：
PENDING（待付款）→ PAID（已支付）→ SHIPPED（已发货）→ COMPLETED（已完成）
                                               CANCELLED（已取消）← 可从任意状态取消

5.7.4 核心业务逻辑解析

为什么下单要用数据库事务？

下单涉及三个操作：创建订单 + 扣减库存 + 清空购物车。这三个操作必须要么全做，要么全不做。如果创建了订单但库存扣减失败了——用户付了钱但库存没减，后续会超卖。

Prisma 的事务写法：

const order = await prisma.$transaction(async (tx) => {
  // 1. 创建订单
  const newOrder = await tx.order.create({ data: { ... } });
  // 2. 扣减库存
  await tx.product.update({ where: { id }, data: { stock: { decrement: qty } } });
  // 3. 清空购物车
  await tx.cartItem.deleteMany({ where: { userId } });
  return newOrder;
});
// 如果任何一步失败，前面已执行的操作会自动回滚

为什么订单明细要存 productName 和 price？

历史订单不应该受后续商品修改影响。如果一个月后商品改名或涨价，你的历史订单不应该跟着变。所以下单时把商品名和价格"快照"到 OrderItem 表里。

5.7.5 你学到了什么

概念	说明
数据库事务	保证多个操作要么全成功要么全失败
库存扣减时机	下单时扣减，防止超卖
数据快照	历史数据不应该受后续修改影响
Task 管理	复杂模块拆成小任务，逐个跟踪

---

5.8 后台管理模块

本节目标：用 Skill 快速生成后台 CRUD，实现管理功能

演示的 Claude Code 功能：自定义 Skill 的复用、权限校验

5.8.1 使用自定义 Skill 加速开发

还记得 6.4 节创建的 api-crud-generator Skill 吗？现在它派上用场了：

请用 api-crud-generator Skill 为后台管理生成以下模块：

1. 商品管理 /admin/products
   - API: GET/POST /api/admin/products
   - API: PUT/DELETE /api/admin/products/[id]
   - 页面：表格列表 + 新增/编辑表单

2. 订单管理 /admin/orders
   - API: GET /api/admin/orders（所有订单列表）
   - API: PUT /api/admin/orders/[id]（更新订单状态）
   - 页面：表格列表 + 状态流转按钮

3. 分类管理 /admin/categories
   - API: GET/POST /api/admin/categories
   - API: DELETE /api/admin/categories/[id]
   - 页面：列表 + 新增表单

所有后台页面需要验证当前用户是否为 ADMIN 角色。

提示：这就是 Skill 的价值——如果没有 api-crud-generator，你需要为三个模块分别写几乎相同的 Prompt。有了 Skill，一句话就搞定了。

5.8.2 权限校验

后台页面通过 Server Component 做权限校验：

// src/app/admin/page.tsx
import { getCurrentUser } from "@/lib/auth";
import { redirect } from "next/navigation";

export default async function AdminPage() {
  const user = await getCurrentUser();
  if (!user || user.role !== "ADMIN") {
   redirect("/login");  // 非管理员直接跳转
  }
  // ... 页面内容
}

注意：服务端校验是必须的。不能只在客户端隐藏按钮——用户可以通过浏览器开发者工具直接调用 API。所以 API Route 里也要做权限检查（本项目简化处理，实际生产环境每个管理 API 都应该做）。

5.8.3 更新导航栏

后台模块完成后，更新 Navbar 组件：

• 未登录时：显示"登录"按钮
• 登录后：显示用户名 + 购物车 + 我的订单
• 管理员：额外显示"后台管理"入口
• 点击"退出"：清除 Cookie，回到首页

AI 能根据会话状态动态展示导航菜单，提升用户体验。

5.8.4 你学到了什么

概念	说明
Skill 复用	一次创建，在多个模块中反复使用
权限校验	服务端检查用户角色，不能只靠前端
redirect	Next.js 的服务端跳转方法

---

5.9 上线前审查 + 项目复盘

本节目标：用 /review 和 /security-review 做最终检查，回顾完整项目

演示的 Claude Code 功能：/review、/security-review、Git 工作流

5.9.1 全量安全审查

所有功能完成后，做一次完整的安全检查：

/security-review

AI 会从多个维度检查：

维度	检查内容
认证安全	密码正确哈希？Session 安全？
数据安全	API 是否暴露了不该暴露的字段？
输入验证	是否有未验证的用户输入？
权限控制	管理接口是否正确保护？

注意：AI 的安全审查不能替代专业安全审计。如果是真的上线的项目，还需要做渗透测试、依赖漏洞扫描等。

5.9.2 最终代码审查

/review

AI 会给出代码质量报告，包括：

• 代码风格是否一致
• 有没有未使用的变量/导入
• 有没有潜在的运行时错误
• 改进建议

5.9.3 Git 工作流回顾

看看我们一路走来的提交历史：

git log --oneline

理想情况下，你应该看到类似这样的提交历史：

a1b2c3d feat: 后台管理模块（商品/订单/分类 CRUD）
d4e5f6g feat: 购物车 + 订单模块
g7h8i9j feat: 用户认证模块（注册/登录/Session）
j0k1l2m feat: 商品模块（API + 前端页面）
m3n4o5p feat: 数据库模型 + 种子数据
p6q7r8s chore: 项目初始化

每个功能一个 commit，提交信息清晰明了。这就是良好的 Git 实践。

提示：用 AI 开发时，养成一个习惯——在让 AI 做大改动之前，先 git add . && git commit。这样即使 AI 改坏了，你也能随时回到上一个正确的版本。这是无数 AI 编程老手的血泪经验。

5.9.4 项目运行指南

# 1. 进入项目
cd mini-mall

# 2. 安装依赖
npm install

# 3. 初始化数据库
npx prisma migrate dev
npx prisma db seed

# 4. 启动开发服务器
npm run dev

# 5. 浏览器打开 http://localhost:3000

测试账号：

• 管理员：admin@minimall.com / admin123
• 用户：user@example.com / user123

5.9.5 完整用户流程测试

1. 打开首页 → 看到 12 个商品，按分类筛选，搜索
2. 点击商品 → 查看详情
3. 注册新账号 → 登录
4. 加入购物车 → 修改数量 → 删除某项
5. 提交订单 → 查看订单列表 → 点击"模拟支付"
6. 退出 → 管理员登录 → 访问 /admin
7. 后台添加商品 → 编辑商品 → 管理订单状态

5.9.6 你学到了什么

概念	说明
/security-review	AI 辅助的安全检查，上线前必做
/review	AI 代码审查，保证质量
Git 提交规范	每个功能一个 commit，清晰可追溯
完整的项目交付	从架构设计到最终审查的完整闭环

---

5.10 项目总结：13 项 Claude Code 功能清单

#	功能	你在本项目中哪里用过	什么时候再用
1	/plan	6.1 项目启动	任何新项目/新功能开始前
2	CLAUDE.md	6.2 环境搭建	每个项目都要有
3	Task 任务列表	6.7 购物车开发	多步骤复杂任务
4	自定义 Skill	6.4 创建 + 6.8 复用	重复性工作封装
5	官方 Skill	文档提到 frontend-design	需要专业能力时
6	Hook 配置	6.3 配置	项目初始化时配置一次
7	Memory	6.3 配置	偏好和约定记录
8	/review	6.5 + 6.9	每个模块完成后
9	/security-review	6.6 + 6.9	认证模块 + 上线前
10	多模型切换	6.6.4 讨论	复杂逻辑用 Opus，UI 用 Haiku
11	权限模式	6.3.2 讨论	根据信任程度调整
12	Git 工作流	6.9.3 回顾	全程
13	.env 管理	6.2	存储密钥和配置

---

5.11 token使用情况

此demo项目一共消费4.31元，缓存命中率较高。