Claude Code前端全栈实战：Next.js项目从零交付

node -v        # v22.x
claude --version  # 确认CLI已安装

mkdir my-saas-app && cd my-saas-app
claude

请帮我初始化一个Next.js 15项目，要求：
- App Router（不用Pages Router）
- TypeScript严格模式
- Tailwind CSS v4
- 使用pnpm作为包管理器
- 包含ESLint和Prettier配置

pnpm create next-app@latest . --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"

# 项目概览

SaaS任务管理应用，技术栈：Next.js 15 + App Router + TypeScript + Tailwind CSS v4 + Prisma + NextAuth.js v5

## 技术约定

- 路由：App Router，所有页面在 `src/app/` 下
- 组件：函数组件 + Hooks，禁止class组件
- 样式：Tailwind CSS，禁止内联style属性，禁止CSS Modules
- 状态管理：React Context + useReducer，不引入Redux
- 数据获取：Server Components优先，客户端用SWR
- 表单：React Hook Form + Zod验证
- 数据库：Prisma ORM，schema文件在 `prisma/schema.prisma`
- 认证：NextAuth.js v5，Auth.js适配器

## 文件结构约定

## 编码规范

- 组件文件名使用PascalCase：`TaskCard.tsx`
- 工具函数文件名使用camelCase：`formatDate.ts`
- 每个组件必须有TypeScript props类型定义
- Server Component不加'use client'指令
- Client Component必须以'use client'开头
- API路由返回类型化的JSON响应
- 数据库查询必须用Prisma，禁止原始SQL

## 测试要求

- 单元测试：Vitest + React Testing Library
- E2E测试：Playwright
- 测试文件放在对应组件同目录的 `__tests__/` 下

## 禁止事项

- 不要安装新的状态管理库（zustand、jotai等）
- 不要使用axios，用原生fetch
- 不要创建CSS文件，只用Tailwind类
- 不要修改 prisma/schema.prisma 除非明确要求

# 全局偏好

- 默认使用中文回复
- 代码注释用英文
- 不要自动 git commit
- 优先编辑现有文件而非创建新文件
- 修改代码后主动运行测试验证

请设计Prisma schema，包含以下模型：
- User：用户，含email、name、avatar
- Project：项目，属于User，含title、description、color
- Task：任务，属于Project，含title、description、status（TODO/IN_PROGRESS/DONE）、priority（LOW/MEDIUM/HIGH）、dueDate
- 支持软删除（deletedAt字段）

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        String    @id @default(cuid())
  email     String    @unique
  name      String?
  avatar    String?
  projects  Project[]
  createdAt DateTime  @default(now())
  updatedAt DateTime  @updatedAt
  deletedAt DateTime?
}

model Project {
  id          String    @id @default(cuid())
  title       String
  description String?
  color       String    @default("#3B82F6")
  userId      String
  user        User      @relation(fields: [userId], references: [id], onDelete: Cascade)
  tasks       Task[]
  createdAt   DateTime  @default(now())
  updatedAt   DateTime  @updatedAt
  deletedAt   DateTime?
}

model Task {
  id          String    @id @default(cuid())
  title       String
  description String?
  status      Status    @default(TODO)
  priority    Priority  @default(MEDIUM)
  dueDate     DateTime?
  projectId   String
  project     Project   @relation(fields: [projectId], references: [id], onDelete: Cascade)
  createdAt   DateTime  @default(now())
  updatedAt   DateTime  @updatedAt
  deletedAt   DateTime?
}

enum Status {
  TODO
  IN_PROGRESS
  DONE
}

enum Priority {
  LOW
  MEDIUM
  HIGH
}

在 src/actions/ 下创建以下Server Actions：
1. task-actions.ts - 任务的CRUD操作
2. project-actions.ts - 项目的CRUD操作
要求：每个action都有Zod输入验证，使用revalidatePath刷新缓存，统一错误处理

'use server'

import { revalidatePath } from 'next/cache'
import { prisma } from '@/lib/db'
import { z } from 'zod'

const createTaskSchema = z.object({
  title: z.string().min(1, '标题不能为空').max(100),
  description: z.string().max(500).optional(),
  priority: z.enum(['LOW', 'MEDIUM', 'HIGH']).default('MEDIUM'),
  dueDate: z.string().datetime().optional(),
  projectId: z.string().cuid(),
})

export async function createTask(formData: FormData) {
  const raw = {
    title: formData.get('title'),
    description: formData.get('description'),
    priority: formData.get('priority'),
    dueDate: formData.get('dueDate'),
    projectId: formData.get('projectId'),
  }

  const validated = createTaskSchema.safeParse(raw)
  if (!validated.success) {
    return { error: validated.error.flatten().fieldErrors }
  }

  try {
    const task = await prisma.task.create({
      data: validated.data,
    })
    revalidatePath(`/projects/${validated.data.projectId}`)
    return { data: task }
  } catch (error) {
    return { error: '创建任务失败，请稍后重试' }
  }
}

export async function updateTaskStatus(taskId: string, status: 'TODO' | 'IN_PROGRESS' | 'DONE') {
  try {
    const task = await prisma.task.update({
      where: { id: taskId },
      data: { status },
    })
    revalidatePath(`/projects/${task.projectId}`)
    return { data: task }
  } catch {
    return { error: '更新状态失败' }
  }
}

export async function deleteTask(taskId: string) {
  try {
    const task = await prisma.task.update({
      where: { id: taskId },
      data: { deletedAt: new Date() },
    })
    revalidatePath(`/projects/${task.projectId}`)
    return { success: true }
  } catch {
    return { error: '删除任务失败' }
  }
}

请创建任务看板视图，包含以下组件：
1. TaskBoard - 看板容器，三列布局（TODO/IN_PROGRESS/DONE）
2. TaskColumn - 单列，显示状态标题和任务计数
3. TaskCard - 任务卡片，显示标题、优先级标签、截止日期
4. TaskForm - 新建/编辑任务的弹窗表单

要求：
- TaskBoard是Server Component，获取初始数据
- TaskCard和TaskForm是Client Component（需要交互）
- 优先级用颜色区分：HIGH红色、MEDIUM黄色、LOW绿色
- 使用Tailwind实现响应式布局（移动端单列，桌面端三列）

src/components/features/
├── TaskBoard.tsx       # Server Component
├── TaskColumn.tsx      # Client Component
├── TaskCard.tsx        # Client Component
└── TaskForm.tsx        # Client Component

# 第1轮：基础框架
先完成项目页面的列表视图，显示所有项目卡片，点击进入项目详情

# 第2轮：核心交互
给任务卡片添加拖拽排序功能（使用 @dnd-kit/core），支持跨列拖动改变状态

# 第3轮：表单优化
TaskForm添加富文本编辑器（Tiptap），支持Markdown预览

# 第4轮：实时更新
用Server-Sent Events实现任务状态的实时推送

pnpm build    # 确保编译通过
pnpm lint     # 检查代码规范

参考 @src/components/features/TaskCard.tsx 的设计风格，
创建一个 ProjectCard 组件，显示项目名称、任务数量、进度百分比

页面报错 "Hydration failed because the server rendered HTML didn't match the client"。
请检查 @src/app/projects/[id]/page.tsx 中可能导致hydration mismatch的原因并修复。

为 @src/components/features/TaskCard.tsx 编写Vitest单元测试，覆盖：
1. 正确渲染标题和优先级标签
2. 高优先级显示红色标签
3. 点击卡片触发onClick回调
4. 截止日期已过时显示警告样式

// src/components/features/__tests__/TaskCard.test.tsx
import { describe, it, expect, vi } from 'vitest'
import { render, screen, fireEvent } from '@testing-library/react'
import { TaskCard } from '../TaskCard'

const mockTask = {
  id: 'clx123',
  title: '完成用户认证',
  description: '实现JWT登录流程',
  status: 'TODO' as const,
  priority: 'HIGH' as const,
  dueDate: new Date('2026-06-01'),
  projectId: 'proj123',
  createdAt: new Date(),
  updatedAt: new Date(),
  deletedAt: null,
}

describe('TaskCard', () => {
  it('renders title and priority badge', () => {
    render(<TaskCard task={mockTask} onClick={vi.fn()} />)
    expect(screen.getByText('完成用户认证')).toBeInTheDocument()
    expect(screen.getByText('HIGH')).toBeInTheDocument()
  })

  it('shows red badge for high priority', () => {
    render(<TaskCard task={mockTask} onClick={vi.fn()} />)
    const badge = screen.getByText('HIGH')
    expect(badge.className).toContain('bg-red')
  })

  it('calls onClick when clicked', () => {
    const handleClick = vi.fn()
    render(<TaskCard task={mockTask} onClick={handleClick} />)
    fireEvent.click(screen.getByRole('article'))
    expect(handleClick).toHaveBeenCalledWith(mockTask.id)
  })

  it('shows warning for overdue tasks', () => {
    const overdueTask = {
      ...mockTask,
      dueDate: new Date('2025-01-01'),
    }
    render(<TaskCard task={overdueTask} onClick={vi.fn()} />)
    expect(screen.getByText('已逾期')).toBeInTheDocument()
  })
})

pnpm test

pnpm tsc --noEmit

---
name: frontend-component
description: 创建标准化的React组件，包含TypeScript类型、Tailwind样式和单元测试骨架
---

## 使用场景
当需要创建新的React组件时使用此skill。

## 组件模板

创建组件时遵循以下结构：

1. 文件位置：根据组件类型放在对应目录
   - UI基础组件 → `src/components/ui/`
   - 业务组件 → `src/components/features/`

2. 组件模板：
   ```typescript
   import { type FC } from 'react'

   interface [ComponentName]Props {
     // props定义
   }

   export const [ComponentName]: FC<[ComponentName]Props> = ({ /* props */ }) => {
     return (
       <div className="/* Tailwind classes */">
         {/* 内容 */}
       </div>
     )
   }
   ```

3. 必须包含：
   - TypeScript props接口定义
   - FC类型标注
   - 命名导出（非默认导出）
   - 如需客户端交互，文件顶部加 `'use client'`

4. 同步创建测试文件：`__tests__/[ComponentName].test.tsx`

请进入plan mode，我需要实现以下功能：
"任务评论系统——用户可以在任务下方添加评论，支持@提及、Markdown格式、文件附件"

/compact 保留当前任务需求和最近的代码变更

# 不好 - 让Claude Code自己找文件
请修复登录页面的样式问题

# 好 - 精确指定文件
请修复 @src/app/(auth)/login/page.tsx 中登录表单的响应式布局问题

# 完成任务看板后
exit  # 退出当前会话

# 开始新功能时重新启动
claude  # 新会话，上下文干净

flowchart TD
    A[项目初始化] --> B[编写CLAUDE.md]
    B --> C[数据库Schema设计]
    C --> D[Server Actions开发]
    D --> E[UI组件开发]
    E --> F[页面路由组装]
    F --> G[测试与验证]
    G --> H{构建通过?}
    H -->|是| I[部署准备]
    H -->|否| J[修复错误]
    J --> G
    I --> K[生产环境上线]

    style A fill:#3B82F6,color:#fff
    style B fill:#3B82F6,color:#fff
    style I fill:#10B981,color:#fff
    style K fill:#10B981,color:#fff

创建 /projects 页面，展示当前用户的所有项目。
使用Server Component获取数据，每个项目显示为卡片。
如果用户没有项目，显示空状态引导。

创建 /projects/[id] 页面，展示项目下的任务看板。
参考 @src/components/features/TaskBoard.tsx 的组件。
页面顶部显示项目信息，下方是三列看板。

给 TaskCard 添加快捷操作：
1. 点击复选框直接标记为DONE
2. 右键菜单显示编辑/删除选项
3. 拖拽到其他列改变状态

TaskForm增加以下功能：
1. 日期选择器（截止日期）
2. 优先级下拉选择
3. 项目选择器（创建任务时选择归属项目）
4. 表单提交后自动关闭并刷新列表

为本次新增的所有功能编写测试：
1. 项目列表页渲染测试
2. 任务CRUD操作的集成测试
3. 拖拽功能的E2E测试
然后运行 pnpm build 确认一切正常。

my-saas-app/
├── .claude/
│   ├── CLAUDE.md              # 项目AI配置
│   └── skills/
│       └── frontend-component.md  # 自定义Skill
├── prisma/
│   └── schema.prisma          # 数据模型
├── src/
│   ├── app/
│   │   ├── layout.tsx         # 根布局
│   │   ├── page.tsx           # 首页
│   │   ├── (auth)/
│   │   │   ├── login/page.tsx
│   │   │   └── register/page.tsx
│   │   ├── projects/
│   │   │   ├── page.tsx       # 项目列表
│   │   │   └── [id]/
│   │   │       └── page.tsx   # 项目详情+看板
│   │   └── api/auth/[...nextauth]/route.ts
│   ├── components/
│   │   ├── ui/
│   │   │   ├── Button.tsx
│   │   │   ├── Input.tsx
│   │   │   └── Modal.tsx
│   │   └── features/
│   │       ├── ProjectCard.tsx
│   │       ├── TaskBoard.tsx
│   │       ├── TaskColumn.tsx
│   │       ├── TaskCard.tsx
│   │       └── TaskForm.tsx
│   ├── actions/
│   │   ├── task-actions.ts
│   │   └── project-actions.ts
│   ├── lib/
│   │   ├── db.ts
│   │   ├── auth.ts
│   │   └── utils.ts
│   └── types/
│       └── index.ts
├── CLAUDE.md                  # 根目录配置（可选）
├── package.json
├── tailwind.config.ts
└── tsconfig.json

// src/lib/utils.ts
import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

请对本项目进行前端性能审计，包括：
1. 分析 bundle size，找出过大的依赖
2. 检查是否有不必要的客户端组件
3. 确认图片使用了 next/image 优化
4. 检查是否有缺失的 loading.tsx（Suspense边界）
5. 验证 Server Components 正确使用

请执行以下部署前检查：
1. pnpm build 是否通过（零错误零警告）
2. pnpm lint 是否通过
3. pnpm test 是否全部通过
4. 环境变量是否都有 .env.example 文档
5. 是否有 console.log 残留
6. 是否有 TODO/FIXME 注释未处理