Claude Code前端开发实战：React+TypeScript七步高效交付

claude --version
# 预期输出: 1.0.x 或更高

pnpm create vite task-dashboard --template react-ts
cd task-dashboard
pnpm install

# Task Dashboard

## Tech Stack
- React 19 + TypeScript 5.6 (strict mode)
- Vite 6 for build tooling
- Tailwind CSS 4 for styling
- Zustand for client state
- TanStack Query v5 for server state
- React Router v7 for routing
- Vitest + React Testing Library for tests

## Project Structure
src/
├── components/     # 可复用UI组件（按功能分子目录）
│   ├── ui/        # 基础原子组件（Button, Input, Modal...）
│   ├── layout/    # 布局组件（Header, Sidebar, Footer...）
│   └── features/  # 业务功能组件（TaskList, TaskCard...）
├── hooks/         # 自定义Hooks
├── stores/        # Zustand stores
├── services/      # API调用层
├── types/         # TypeScript类型定义
├── utils/         # 工具函数
└── pages/         # 路由页面组件

## Code Conventions
- 组件用PascalCase命名，文件名用PascalCase.tsx
- Hooks用use前缀，文件名用camelCase.ts
- 优先使用named export，仅在页面组件用default export
- Props接口定义在组件文件内部，不单独建types文件（除非跨组件复用）
- 样式用Tailwind class，禁止内联style
- 所有组件必须包含TypeScript类型，禁止any

## Commands
- `pnpm dev` — 启动开发服务器
- `pnpm build` — 生产构建
- `pnpm test` — 运行测试
- `pnpm lint` — ESLint检查
- `pnpm type-check` — TypeScript类型检查

## Testing Rules
- 测试文件放在被测组件同级目录: Component.tsx → Component.test.tsx
- 用Vitest + React Testing Library
- 测试用户行为，不测试实现细节
- 每个组件至少覆盖: 渲染正确、用户交互、边界状态

claude

根据CLAUDE.md中的技术栈，安装所有需要的依赖包。包括:
Tailwind CSS 4, Zustand, TanStack Query v5, React Router v7, Vitest, React Testing Library, 以及它们的TypeScript类型定义。配置好tailwind和vitest。

✓ 安装 tailwindcss @tailwindcss/vite zustand @tanstack/react-query react-router
✓ 安装 -D vitest @testing-library/react @testing-library/jest-dom jsdom
✓ 配置 vite.config.ts 集成 Tailwind 和 Vitest
✓ 创建 src/index.css 引入 Tailwind
✓ 配置 tsconfig.json 的 types 字段包含 vitest/globals

帮我创建一套UI基础原子组件，放在 src/components/ui/ 目录下。

需要以下组件，每个组件遵循以下规范：
1. 完整的TypeScript Props类型定义
2. 支持forwardRef
3. 支持className合并（用clsx）
4. 包含variants（用class-variance-authority）
5. 同目录下有对应的.test.tsx测试文件

组件列表：
- Button: primary/secondary/danger/ghost四种variant，sm/md/lg三种size
- Input: 支持label, error, disabled状态
- Badge: 支持不同颜色主题
- Card: 支持header/body/footer分区
- Modal: 支持打开/关闭动画，点击外部关闭

// src/components/ui/Button.tsx
import { forwardRef } from 'react';
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/utils/cn';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: {
        primary: 'bg-blue-600 text-white hover:bg-blue-700',
        secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
        danger: 'bg-red-600 text-white hover:bg-red-700',
        ghost: 'hover:bg-gray-100 text-gray-700',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4 text-sm',
        lg: 'h-12 px-6 text-base',
      },
    },
    defaultVariants: {
      variant: 'primary',
      size: 'md',
    },
  }
);

interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {}

const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, ...props }, ref) => {
    return (
      <button
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    );
  }
);
Button.displayName = 'Button';

export { Button, buttonVariants };
export type { ButtonProps };

第一批: 生成 Button, Input, Badge（基础表单组件）
第二批: 生成 Card, Modal, Dialog（容器组件）
第三批: 生成 DataTable, Pagination（复合组件）

pnpm test src/components/ui/

graph TB
    subgraph Server["服务端状态层"]
        A[React Query / TanStack Query] --> B[缓存管理]
        A --> C[自动重新获取]
        A --> D[乐观更新]
        A --> E[轮询与分页]
    end

    subgraph Client["客户端状态层"]
        F[Zustand Store] --> G[UI状态]
        F --> H[用户偏好]
        F --> I[表单临时数据]
        F --> J[全局通知]
    end

    subgraph API["API调用层"]
        K[fetch封装] --> L[请求拦截]
        K --> M[响应处理]
        K --> N[错误统一处理]
    end

    Server --> API
    Client -.->|触发mutation| Server

创建 src/services/api.ts，实现以下功能：
1. 基于fetch的HTTP客户端封装
2. 自动添加Content-Type: application/json
3. 统一错误处理，抛出自定义ApiError
4. 请求/响应拦截器模式
5. 支持请求取消（AbortController）

然后创建 src/services/taskService.ts，实现Task的CRUD：
- getTasks(filters?): GET /api/tasks
- getTaskById(id): GET /api/tasks/:id
- createTask(data): POST /api/tasks
- updateTask(id, data): PATCH /api/tasks/:id
- deleteTask(id): DELETE /api/tasks/:id

Task类型定义在 src/types/task.ts:
interface Task {
  id: string;
  title: string;
  description?: string;
  status: 'todo' | 'in_progress' | 'done';
  priority: 'low' | 'medium' | 'high';
  assignee?: string;
  dueDate?: string;
  createdAt: string;
  updatedAt: string;
}

基于 taskService 创建 src/hooks/useTaskQueries.ts，使用 TanStack Query v5:

1. useTasks(filters?) - 查询任务列表，支持过滤参数
2. useTask(id) - 查询单个任务
3. useCreateTask() - 创建任务mutation，创建后自动刷新列表
4. useUpdateTask() - 更新任务mutation，乐观更新
5. useDeleteTask() - 删除任务mutation，删除后从缓存移除

要求：
- 所有query使用queryKey工厂模式
- createTask成功后使相关query失效
- updateTask使用乐观更新，失败时回滚
- deleteTask成功后从缓存移除该项
- 错误处理通过全局toast通知用户

// src/hooks/useTaskQueries.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import * as taskService from '@/services/taskService';
import type { Task, CreateTaskInput, UpdateTaskInput } from '@/types/task';

// Query Key 工厂 — 集中管理缓存键
export const taskKeys = {
  all: ['tasks'] as const,
  lists: () => [...taskKeys.all, 'list'] as const,
  list: (filters?: Record<string, unknown>) =>
    [...taskKeys.lists(), filters] as const,
  details: () => [...taskKeys.all, 'detail'] as const,
  detail: (id: string) => [...taskKeys.details(), id] as const,
};

export function useTasks(filters?: Record<string, unknown>) {
  return useQuery({
    queryKey: taskKeys.list(filters),
    queryFn: () => taskService.getTasks(filters),
  });
}

export function useTask(id: string) {
  return useQuery({
    queryKey: taskKeys.detail(id),
    queryFn: () => taskService.getTaskById(id),
    enabled: !!id,
  });
}

export function useCreateTask() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: CreateTaskInput) => taskService.createTask(data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: taskKeys.lists() });
    },
  });
}

export function useUpdateTask() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({ id, data }: { id: string; data: UpdateTaskInput }) =>
      taskService.updateTask(id, data),
    onMutate: async ({ id, data }) => {
      await queryClient.cancelQueries({ queryKey: taskKeys.detail(id) });
      const previousTask = queryClient.getQueryData<Task>(taskKeys.detail(id));
      queryClient.setQueryData(taskKeys.detail(id), (old: Task) => ({
        ...old,
        ...data,
      }));
      return { previousTask };
    },
    onError: (_err, { id }, context) => {
      queryClient.setQueryData(taskKeys.detail(id), context?.previousTask);
    },
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: taskKeys.lists() });
    },
  });
}

export function useDeleteTask() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (id: string) => taskService.deleteTask(id),
    onSuccess: (_data, deletedId) => {
      queryClient.removeQueries({ queryKey: taskKeys.detail(deletedId) });
      queryClient.invalidateQueries({ queryKey: taskKeys.lists() });
    },
  });
}

创建 src/stores/uiStore.ts，用Zustand管理：
1. sidebarOpen: boolean — 侧边栏展开/折叠
2. theme: 'light' | 'dark' — 主题切换
3. notifications: Notification[] — 全局通知队列
4. addNotification(message, type): 添加通知并3秒后自动移除
5. removeNotification(id): 手动移除通知

要求：
- 使用persist middleware持久化theme到localStorage
- 使用immer middleware支持不可变更新
- 导出独立的selector函数，避免不必要的re-render

// 错误：订阅整个store
const { sidebarOpen, theme } = useUIStore();

// 正确：只订阅需要的状态
const sidebarOpen = useUIStore((s) => s.sidebarOpen);
const theme = useUIStore((s) => s.theme);

使用React Router v7配置以下路由，创建 src/router.tsx：

路由结构：
/ → DashboardPage（任务统计面板）
/tasks → TaskListPage（任务列表，支持筛选排序）
/tasks/:id → TaskDetailPage（任务详情）
/tasks/new → TaskFormPage（创建新任务）
/settings → SettingsPage（用户设置）

要求：
- 使用createBrowserRouter + RouterProvider
- 实现Lazy Loading（React.lazy + Suspense）
- 添加Layout组件包裹所有页面（Header + Sidebar + Main）
- 添加404页面兜底
- 添加全局Loading Spinner

// src/router.tsx
import { createBrowserRouter, Navigate } from 'react-router';
import { lazy, Suspense } from 'react';
import { Layout } from '@/components/layout/Layout';
import { LoadingSpinner } from '@/components/ui/LoadingSpinner';

const Lazy = (Component: React.LazyExoticComponent<React.ComponentType>) => (
  <Suspense fallback={<LoadingSpinner />}>
    <Component />
  </Suspense>
);

export const router = createBrowserRouter([
  {
    element: <Layout />,
    children: [
      { index: true, element: Lazy(lazy(() => import('@/pages/DashboardPage'))) },
      { path: 'tasks', element: Lazy(lazy(() => import('@/pages/TaskListPage'))) },
      { path: 'tasks/:id', element: Lazy(lazy(() => import('@/pages/TaskDetailPage'))) },
      { path: 'tasks/new', element: Lazy(lazy(() => import('@/pages/TaskFormPage'))) },
      { path: 'settings', element: Lazy(lazy(() => import('@/pages/SettingsPage'))) },
      { path: '404', element: Lazy(lazy(() => import('@/pages/NotFoundPage'))) },
      { path: '*', element: <Navigate to="/404" replace /> },
    ],
  },
]);

创建 src/pages/TaskListPage.tsx，实现一个任务管理列表页面：

功能：
1. 顶部搜索栏（实时过滤任务标题）
2. 状态筛选Tab（全部/待办/进行中/已完成）
3. 优先级下拉筛选
4. 任务卡片网格布局（响应式：移动端1列，平板2列，桌面3列）
5. 每张任务卡片显示：标题、优先级Badge、负责人头像、截止日期
6. 卡片点击跳转到详情页
7. 右下角浮动"新建任务"按钮
8. 空状态展示（无任务时显示引导插图）
9. 加载状态展示骨架屏

使用已有的 useTasks hook 获取数据。
使用已有的 UI 组件（Button, Input, Badge, Card）。
样式使用Tailwind CSS。

在 src/index.css 中配置 Tailwind CSS v4 主题：

自定义设计令牌：
- 主色调: blue-600 (#2563EB)
- 成功色: green-500
- 警告色: amber-500
- 危险色: red-500
- 圆角: 默认8px, 大号12px
- 阴影: sm/md/lg三档
- 动画: 添加fade-in和slide-up两个自定义动画

字体：
- 中文: system-ui, -apple-system, "PingFang SC"
- 代码: "JetBrains Mono", monospace

/* src/index.css */
@import "tailwindcss";

@theme {
  --color-primary: #2563EB;
  --color-primary-hover: #1D4ED8;
  --color-success: #22C55E;
  --color-warning: #F59E0B;
  --color-danger: #EF4444;

  --radius-default: 8px;
  --radius-lg: 12px;

  --shadow-card: 0 1px 3px rgba(0, 0, 0, 0.1);
  --shadow-elevated: 0 4px 12px rgba(0, 0, 0, 0.1);

  --animate-fade-in: fade-in 0.2s ease-out;
  --animate-slide-up: slide-up 0.3s ease-out;

  --font-sans: system-ui, -apple-system, "PingFang SC", "Microsoft YaHei", sans-serif;
  --font-mono: "JetBrains Mono", "Fira Code", monospace;
}

@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

@keyframes slide-up {
  from { opacity: 0; transform: translateY(8px); }
  to { opacity: 1; transform: translateY(0); }
}

## Responsive Breakpoints
- sm: 640px (手机横屏)
- md: 768px (平板竖屏)
- lg: 1024px (平板横屏/小笔记本)
- xl: 1280px (桌面)
- 2xl: 1536px (大屏桌面)

策略: Mobile First，默认写移动端样式，用sm/md/lg/xl递增。

为 src/components/ui/Button.tsx 生成完整的测试文件 Button.test.tsx。

测试要求：
1. 渲染测试：正确渲染文本内容
2. Variant测试：四种variant都有正确的CSS类名
3. Size测试：三种size都有正确的CSS类名
4. 交互测试：点击事件正确触发
5. 禁用测试：disabled状态下不可点击
6. Ref转发测试：forwardRef正确工作
7. 类名合并测试：自定义className正确合并

使用 Vitest + React Testing Library。
不要使用已废弃的act()包装，用screen和userEvent。

// src/components/ui/Button.test.tsx
import { describe, it, expect, vi } from 'vitest';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Button } from './Button';

describe('Button', () => {
  it('renders children text', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument();
  });

  it.each([
    ['primary', 'bg-blue-600'],
    ['secondary', 'bg-gray-100'],
    ['danger', 'bg-red-600'],
    ['ghost', 'hover:bg-gray-100'],
  ] as const)('applies %s variant styles', (variant, expectedClass) => {
    render(<Button variant={variant}>{variant}</Button>);
    const button = screen.getByRole('button');
    expect(button.className).toContain(expectedClass);
  });

  it('calls onClick when clicked', async () => {
    const onClick = vi.fn();
    const user = userEvent.setup();
    render(<Button onClick={onClick}>Click</Button>);
    await user.click(screen.getByRole('button'));
    expect(onClick).toHaveBeenCalledOnce();
  });

  it('does not call onClick when disabled', async () => {
    const onClick = vi.fn();
    const user = userEvent.setup();
    render(<Button disabled onClick={onClick}>Disabled</Button>);
    await user.click(screen.getByRole('button'));
    expect(onClick).not.toHaveBeenCalled();
  });

  it('forwards ref to button element', () => {
    const ref = { current: null };
    render(<Button ref={ref}>Ref</Button>);
    expect(ref.current).toBeInstanceOf(HTMLButtonElement);
  });

  it('merges custom className', () => {
    render(<Button className="my-custom">Custom</Button>);
    expect(screen.getByRole('button').className).toContain('my-custom');
  });
});

为 src/hooks/useTaskQueries.ts 生成测试 useTaskQueries.test.ts。

要求：
1. Mock taskService的所有方法
2. 用 @tanstack/react-query 的 QueryClientWrapper 包裹
3. 测试 useTasks 成功获取数据
4. 测试 useCreateTask 成功后自动刷新列表
5. 测试 useUpdateTask 乐观更新和错误回滚
6. 测试 useDeleteTask 成功后移除缓存
7. 使用 waitFor 等待异步状态更新

pnpm test

运行 pnpm test，修复所有失败的测试。不要修改测试用例的期望值，修改实现代码使其通过测试。

function createQueryWrapper() {
  const queryClient = new QueryClient({
    defaultOptions: { queries: { retry: false } },
  });
  return function Wrapper({ children }: { children: React.ReactNode }) {
    return (
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    );
  };
}

优化 vite.config.ts 的生产构建配置：

1. 手动分包策略（vendor chunks）：
   - react/react-dom 打一个包
   - react-router 打一个包
   - tanstack-query 打一个包
   - zustand 打一个包
   - UI组件打一个包

2. 开启 gzip 压缩报告

3. 图片资源优化（小于4kb内联，大于4kb生成文件）

4. 配置路径别名 @/ 映射到 src/

5. 配置开发代理 /api → http://localhost:3001

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
import { resolve } from 'path';

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': resolve(__dirname, './src'),
    },
  },
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3001',
        changeOrigin: true,
      },
    },
  },
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'vendor-react': ['react', 'react-dom'],
          'vendor-router': ['react-router'],
          'vendor-query': ['@tanstack/react-query'],
          'vendor-state': ['zustand'],
        },
      },
    },
    reportCompressedSize: true,
  },
});

执行以下部署前检查并报告结果：
1. pnpm type-check — TypeScript类型检查，0错误
2. pnpm lint — ESLint检查，0警告
3. pnpm test — 全部测试通过
4. pnpm build — 构建成功
5. 分析构建产物大小，报告各chunk体积
6. 检查是否有未使用的依赖（depcheck）

配置部署到 Vercel:
1. 创建 vercel.json 配置SPA路由重写（所有路由→index.html）
2. 配置环境变量: VITE_API_BASE_URL
3. 输出构建命令和输出目录

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }],
  "buildCommand": "pnpm build",
  "outputDirectory": "dist",
  "env": {
    "VITE_API_BASE_URL": "@api-base-url"
  }
}

graph TB
    subgraph Browser["浏览器"]
        subgraph Router["React Router v7"]
            RP[RouterProvider] --> Dash[DashboardPage]
            RP --> TL[TaskListPage]
            RP --> TD[TaskDetailPage]
            RP --> TF[TaskFormPage]
            RP --> Set[SettingsPage]
        end

        subgraph State["状态管理"]
            RQ[TanStack Query<br/>服务端状态] --> Cache[缓存层]
            ZS[Zustand<br/>客户端状态] --> UI[UI状态]
        end

        subgraph Components["组件层"]
            UI_Comps[原子组件<br/>Button/Input/Badge] --> Feat_Comps[业务组件<br/>TaskCard/TaskList]
            Feat_Comps --> Pages[页面组件]
        end
    end

    subgraph Server["后端API"]
        API["/api/tasks<br/>CRUD Endpoints"]
    end

    Pages --> State
    State --> Services[API Service层]
    Services -->|fetch| Server

# Step 1 — 基础设施（5分钟）
"初始化项目，安装所有依赖，配置Tailwind、Vitest、路径别名"

# Step 2 — 类型与API层（10分钟）
"创建所有TypeScript类型定义和API Service层"

# Step 3 — 状态管理（10分钟）
"创建TanStack Query hooks和Zustand store"

# Step 4 — UI组件库（15分钟）
"生成所有原子组件，每个组件带完整测试"

# Step 5 — 布局组件（10分钟）
"生成Layout、Header、Sidebar布局组件"

# Step 6 — 业务组件（15分钟）
"生成TaskCard、TaskList、TaskForm、StatusFilter等业务组件"

# Step 7 — 页面组件（15分钟）
"生成所有页面组件并配置路由"

# Step 8 — 测试与优化（10分钟）
"运行全量测试，修复失败用例，分析构建产物大小"

# 安装shadcn CLI
pnpm dlx shadcn@latest init

# 在Claude Code中使用
"用shadcn/ui的DataTable组件实现任务列表，支持排序、筛选和分页"

1. 安装Figma MCP Server
2. 在Claude Code中输入: "根据Figma文件 xxx 的设计稿，生成TaskCard组件"
3. Claude Code会读取Figma的设计令牌、布局和样式，生成匹配的React组件

第一阶段: 只添加CLAUDE.md，让Claude Code理解项目现状
第二阶段: 让Claude Code为新功能编写代码（遵循现有模式）
第三阶段: 逐步让Claude Code重构旧代码（一次一个模块）
第四阶段: 引入新的工具链（Tailwind、Zustand等）

为 src/components/ui/ 下所有组件生成 Storybook stories 文件。
每个组件至少3个story: Default, WithVariants, EdgeCase。
使用CSF 3.0格式。

## Accessibility (Must Follow)
- 所有交互元素必须有aria-label
- 表单input必须关联label
- 颜色对比度至少4.5:1
- 键盘可操作（Tab/Enter/Escape）
- 使用role属性标注自定义组件

flowchart LR
    A[编写CLAUDE.md] --> B[项目初始化<br/>安装依赖]
    B --> C[类型定义<br/>API层]
    C --> D[状态管理<br/>Query+Store]
    D --> E[UI组件库<br/>原子组件]
    E --> F[布局+路由<br/>页面骨架]
    F --> G[业务组件<br/>功能页面]
    G --> H[测试+修复<br/>构建优化]
    H --> I[部署上线]

    style A fill:#2563EB,color:#fff
    style I fill:#22C55E,color:#fff