From 933d71c99d791d0f73082e6f75aa832a0fec4625 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BC=A0=E5=BE=B7=E8=BE=89?= <zdh@bowong.ai>
Date: Mon, 30 Jun 2025 09:29:58 +0800
Subject: [PATCH] fix

---
 .cursorrules | 148 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 148 insertions(+)
 create mode 100644 .cursorrules

diff --git a/.cursorrules b/.cursorrules
new file mode 100644
index 0000000..e3ed1e3
--- /dev/null
+++ b/.cursorrules
@@ -0,0 +1,148 @@
+# 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 变量进行主题定制，支持暗色模式 
\ No newline at end of file