# Cursor Rules for Outfit Web Project

## 项目概述
这是一个基于 React 19 + TypeScript + Vite + Tailwind CSS 的前端项目，使用 shadcn/ui 组件库，包含自动生成的 API 客户端。

## 技术栈
- **前端框架**: React 19
- **语言**: TypeScript
- **构建工具**: Vite
- **样式**: Tailwind CSS 4.x
- **UI 组件库**: shadcn/ui (基于 Radix UI)
- **图标库**: Lucide React
- **工具库**: class-variance-authority, clsx, tailwind-merge
- **HTTP 客户端**: Axios
- **API 生成**: openapi-typescript-codegen

## 代码规范

### TypeScript 规范
- 使用严格的 TypeScript 配置
- 优先使用类型推断，但为公共 API 和复杂对象显式定义类型
- 使用 `interface` 定义对象类型，使用 `type` 定义联合类型和工具类型
- 避免使用 `any`，优先使用 `unknown` 或具体类型
- 使用泛型提高代码复用性

### React 组件规范
- 使用函数组件和 React Hooks
- 组件名使用 PascalCase
- 文件名与组件名保持一致
- 使用 TypeScript 为 props 定义接口
- 优先使用 `useState` 和 `useEffect` 等内置 Hooks
- 自定义 Hooks 以 `use` 开头

### shadcn/ui 组件库规范
- 使用 shadcn/ui 作为主要 UI 组件库
- 组件配置使用 "new-york" 风格
- 组件放在 `src/components/ui/` 目录
- 使用 `@/components/ui` 别名导入 UI 组件
- 使用 `@/lib/utils` 导入工具函数
- 图标使用 Lucide React 库
- 遵循 shadcn/ui 的设计原则和可访问性标准
- 组件引入、升级、修复请统一使用 `npx shadcn@latest add [component]`，确保与 Tailwind v4、React 19 兼容
- 组件样式、主题、变量配置统一在 `components.json` 和 `tailwind.config.ts`/`tailwind.config.js` 中管理，Tailwind v4 下 `config` 字段应留空，主题色用 `baseColor`，如 `neutral`、`zinc` 等
- 推荐开启 `cssVariables: true`，用 CSS 变量做主题定制，支持暗色模式
- 组件样式冲突时可用 `prefix` 字段（如 `tw-`）隔离 Tailwind 工具类
- 组件样式入口通过 `tailwind.css`/`globals.css` 引入
- 组件变体、条件样式统一用 `class-variance-authority`、`clsx`、`tailwind-merge` 组合
- 推荐使用 `cn()` 工具函数（`clsx`+`tailwind-merge`）合并类名，避免冲突
- 组件开发/迁移时优先用函数组件，类型用 `React.ComponentProps<typeof X>` 推断，避免 `forwardRef`，如需 `ref` 用 `data-slot` 辅助样式
- 组件升级/迁移时注意 Tailwind v4 新特性（如 `size-*` 替换 `w-* h-*`）
- 组件主题色、动画、变量扩展统一用 `cssVars` 和 `theme.extend`，如需自定义色彩/动画，参考官方 registry item 配置
- 组件可访问性（a11y）严格遵循 shadcn/ui 官方标准，确保键盘可用、aria 属性齐全、对比度达标
- 组件 peerDependencies 必须支持 React 19，升级依赖时如遇 npm ERESOLVE，优先用 `--force` 或 `--legacy-peer-deps` 解决
- 组件升级后如有 breaking change，需同步更新相关用法和文档

### 样式规范
- 使用 Tailwind CSS 类名
- 使用 `clsx` 和 `tailwind-merge` 进行条件样式组合
- 使用 `class-variance-authority` 创建变体组件
- 避免内联样式，优先使用 Tailwind 类名
- 响应式设计使用 Tailwind 的断点前缀
- 使用 CSS 变量进行主题定制（baseColor: neutral）

### 文件组织
- 组件放在 `src/components/` 目录
- UI 组件放在 `src/components/ui/` 目录
- 页面组件放在 `src/pages/` 目录
- 工具函数放在 `src/lib/` 目录
- 自定义 Hooks 放在 `src/hooks/` 目录
- API 相关代码在 `src/api/` 目录（自动生成）
- 类型定义放在 `src/types/` 目录

### 导入规范
- 使用绝对路径导入（`@/` 别名）
- 按以下顺序组织导入：
  1. React 相关
  2. 第三方库
  3. shadcn/ui 组件
  4. 内部组件/工具
  5. 类型定义
  6. 样式文件

### API 使用规范
- 使用自动生成的 API 客户端
- 在组件中使用 `useApi` Hook 进行 API 调用
- 处理加载状态和错误状态
- 使用 TypeScript 类型确保类型安全

### 命名规范
- 变量和函数使用 camelCase
- 常量使用 UPPER_SNAKE_CASE
- 组件使用 PascalCase
- 文件使用 kebab-case 或 PascalCase（组件文件）
- 类型和接口使用 PascalCase

### 代码质量
- 使用 ESLint 进行代码检查
- 遵循 React Hooks 规则
- 避免不必要的重新渲染
- 使用 React.memo 优化性能
- 正确处理副作用和清理

### 开发工作流
- 使用 `npm run dev` 启动开发服务器
- 使用 `npm run build` 构建生产版本
- 使用 `npm run generate-api` 重新生成 API 客户端
- 使用 `npm run lint` 检查代码质量
- 使用 `npx shadcn@latest add [component]` 添加新组件

## 最佳实践

### shadcn/ui 使用最佳实践
- 优先使用 shadcn/ui 提供的组件，避免重复造轮子
- 使用 `cn()` 工具函数组合类名
- 遵循 shadcn/ui 的可访问性标准
- 使用 `class-variance-authority` 创建组件变体
- 保持组件的可组合性和可扩展性

### 状态管理
- 对于简单状态，使用 `useState`
- 对于复杂状态，考虑使用 `useReducer`
- 避免过度使用全局状态

### 性能优化
- 使用 React.memo 包装纯组件
- 使用 useCallback 和 useMemo 优化回调函数和计算值
- 懒加载路由和组件
- 优化图片和资源加载

### 错误处理
- 使用 Error Boundaries 捕获组件错误
- 为 API 调用添加适当的错误处理
- 提供用户友好的错误信息

### 可访问性
- 使用语义化的 HTML 标签
- 添加适当的 ARIA 属性
- 确保键盘导航支持
- 提供足够的颜色对比度
- 遵循 shadcn/ui 的可访问性指南

## 注意事项
- API 客户端是自动生成的，不要手动修改
- 使用 Tailwind CSS 4.x 的新特性
- 遵循 React 19 的最佳实践
- 保持代码简洁和可维护性
- shadcn/ui 组件是可定制的，可以根据需要修改
- 使用 CSS 变量进行主题定制，支持暗色模式