Instruction file imported from longlian-online/longlian-oa-frontend (.cursor/rules/project-rules.mdc). Copyright stays with the author.

description: longlian-oa开发规范 globs: **/*.{ts,tsx} alwaysApply: true

项目开发规范

你是一位资深的前端技术专家，精通所有的前端技术和代码架构设计模式等。团队主要使用 TypeScript、React、shadcn/ui 和 Tailwind CSS 作为主要的技术栈。

文件和目录命名规范

• 组件目录: PascalCase，如 Loading、UserInfoPopover
• 页面文件: camelCase，如 index.tsx、dashboard.tsx、[id].tsx
• 工具/Hook 文件: camelCase，如 formatDate.ts、useUserInfo.ts
• 类型文件: camelCase，如 api.ts、user.ts

components/
├── Loading/
│   └── index.tsx
└── MarkdownEditor/
    ├── index.tsx
    ├── Toolbar.tsx       # 子组件 PascalCase
    └── Preview.tsx

pages/
├── index.tsx             # → /
├── login.tsx             # → /login
└── dashboard/
    ├── index.tsx         # → /dashboard
    └── [id].tsx          # → /dashboard/:id

命名规范

• 组件: PascalCase，如 UserCard
• 组件 Props 类型: [Name]Props，如 UserCardProps
• 函数/变量: camelCase，如 handleClick、isLoading
• 常量: SNAKE_CASE，如 MAX_COUNT、API_BASE_URL
• 枚举: PascalCase + Enum 后缀，如 ButtonEnum，每项加 JSDoc 中文注释
• 事件处理: handle 前缀，如 handleSubmit
• 回调 Props: on 前缀，如 onSubmit、onChange
• 自定义 Hook: use 前缀，放 hooks/ 目录

TypeScript 规范

• 禁止使用 any，所有参数、返回值、Props 必须有明确类型
• 对象类型用 interface，联合类型/工具类型用 type

interface UserCardProps {
  name: string;
  avatar?: string;
  onSelect?: (id: string) => void;
}

React 规范

• 只用函数组件 + Hooks，禁止类组件
• 合理使用 React.memo、useMemo、useCallback 做性能优化

样式规范

• 只用 Tailwind CSS utility class，不写独立 CSS 文件，不用内联 style
• 动态/复合 class 用 cn() 处理，不做字符串拼接

import { cn } from "@/lib/utils";

<button
  className={cn(
    "px-4 py-2 rounded-md font-medium",
    disabled && "opacity-50 cursor-not-allowed",
    className
  )}
/>

shadcn/ui 规范

• 优先使用 shadcn/ui 组件，保持 UI 风格一致
• 通过 vp dlx shadcn@latest add <component> 安装，组件落地 src/components/ui/
• 不直接修改 src/components/ui/ 原始文件，二次封装放 src/components/

UI 设计规范

• 涉及界面设计、视觉优化、交互体验时，使用 Impeccable skill 辅助
• 避免平庸的默认审美，追求有设计感的 UI

导入规范

• 使用 @/ 绝对路径，禁止相对路径跨层级引用
• 导入顺序：第三方库 → 内部模块 → 类型

import { useState } from "react";
import { Button } from "@/components/ui/button";
import { formatDate } from "@/utils/formatDate";
import type { UserInfo } from "@/types/user";

组件设计原则

• 单一职责，单文件不超过 500 行（最多 1000 行）
• 复杂组件拆分子组件，Props 必需项在前、可选项在后