# 前端开发规则 ## 技术栈 - 使用 React 18、TypeScript 和 Vite。 - UI 组件库使用 shadcn/ui。 - 样式使用 Tailwind CSS；新增样式优先使用 Tailwind 工具类和主题变量。 - 图标使用 Lucide React，禁止手写重复的图标 SVG。 - 优先使用项目现有依赖；引入新依赖前说明必要性和影响。 ## 项目结构（不可变） 前端源码必须遵循以下目录结构： ```text src/ ├── assets/ # 静态资源 ├── components/ # 可复用 UI 组件 ├── constants/ # 业务常量、枚举 ├── hooks/ # 自定义 Hook ├── http/ # 请求封装 ├── interfaces/ # 类型声明（model、api） ├── routes/ # 路由页面 ├── stores/ # 全局状态，按业务拆分 ├── utils/ # 工具函数 └── 根级入口文件 ``` 结构约束： - 常量必须放在 `constants/`，状态必须放在 `stores/`，接口类型必须放在 `interfaces/`。 - `interfaces/` 下按业务模块组织类型；每个模块至少包含 `model.ts` 和 `api.ts`。 - 可复用组件放在 `components/`；仅供单个路由使用的组件放在 `routes//components/`。 - 路由页面必须放在 `routes/` 下；每个路由模块包含 `Page`、`Loader` 和 `index.module.scss`。 - 新增文件前先确认其职责与目录匹配，不得为了方便将业务代码放入根级入口文件。 ## 组件规范 ### 组件结构 - 组件必须放在 `src/components/` 或对应路由的 `components/` 目录下，每个组件使用独立目录。 - 组件目录至少包含 `index.tsx` 和 `index.module.scss`。 - 组件样式必须使用 SCSS Modules，禁止新增全局样式。 - Props 必须定义明确的 TypeScript 接口，禁止使用隐式或无类型 Props。 - 使用 `classnames` 管理动态 class；不要通过字符串拼接维护复杂 class 列表。 ### 组件层级 - 页面级组件：仅单页使用时，放在 `routes//components/`。 - 通用组件：跨页面复用时，放在 `src/components/`。 - 单个文件建议不超过 400 行；超过后应根据职责拆分为更小的组件或工具模块。 ## 编码规范 ### TypeScript - 所有前端源码必须使用 TypeScript，禁止新增 JavaScript 文件。 - 禁止使用 `any`；确有必要时必须说明理由并添加代码注释。 - 接口和类型使用 PascalCase 命名；组件 Props 必须定义清晰、完整的接口。 ### 命名 | 类型 | 规则 | 示例 | | ------------ | ---------- | ---------------------- | | 文件夹、路由 | kebab-case | `user-profile` | | 变量、函数 | camelCase | `userList`、`onSubmit` | | 常量 | UPPER_CASE | `API_TIMEOUT` | | 接口、类 | PascalCase | `UserInfo` | | React 组件 | PascalCase | `UserProfile` | | 自定义 Hook | `use` 开头 | `useUserStore` | ### 业务函数 - 事件处理函数使用 `onXxx` 命名，例如 `onSubmit`。 - 组件或业务内部处理函数使用 `handleXxx` 命名，例如 `handleDelete`。 ## 文档规范 ### 注释规范 - 必要注释统一使用 JSDoc（`/** ... */`）格式。 - 注释重点解释设计原因、业务约束和非显而易见的取舍，不要重复代码本身表达的内容。 - 文件头、函数或方法、复杂逻辑块和类型定义应根据需要补充说明。 - 注释必须使用中文；代码标识符仍使用英文命名。 ## 路由规范（不可变） ### 路由结构 - 路由目录必须位于 `src/routes/` 下，每个页面使用独立目录，目录名使用 kebab-case。 - 每个页面目录必须包含 `Page.tsx`、`Loader.tsx` 和 `index.module.scss`。 - `Loader.tsx` 只负责懒加载对应的 `Page.tsx`，不得嵌套 `Routes` 或 `Route`。 ### 路由与菜单 - 路由配置必须全局集中管理，禁止在多个文件中重复维护同一套路由。 - 同一个页面只能在一处使用 `lazy` 引入；菜单、面包屑等导航数据引用统一的路由配置。 ## 状态管理规范（不可变） ### 基础规范 - 必须使用项目约定的状态库（例如 Zustand）管理全局状态。 - 所有 store 必须放在 `src/stores/` 下，禁止在 `src/` 的其他目录中存放 store。 ### Store 组织 - 按业务模块划分 store，每个业务模块使用独立文件。 - 每个 store 对外暴露对应的 `useXxxStore` Hook。 - Store 只负责数据和业务行为，不得耦合 UI 组件、页面结构或展示逻辑。 - 需要持久化时使用 `persist` 等状态库中间件，并明确持久化字段范围。 ## 代码组织 - 组件使用 PascalCase 命名，变量、函数和文件中的普通标识使用 camelCase。 - 保持组件职责单一；页面、可复用组件、请求服务和类型定义分开组织。 - 避免在 `App.tsx` 或单个组件中堆积所有业务逻辑。 - 为组件 props、接口请求和响应定义明确的 TypeScript 类型，避免使用 `any`。 - 复用逻辑优先提取为自定义 Hook 或独立工具函数。 ## API 调用 - API 路径遵循根目录 `AGENTS.md` 中的版本和响应规范。 - 请求地址、认证信息和环境差异通过 `.env.example` 中定义的 Vite 环境变量配置。 - 不在源码中硬编码密码、令牌或生产环境地址。 - 统一处理加载、成功、空数据和错误状态。 ## 样式与交互 - 优先复用现有样式和设计约定，避免为单个页面重复定义相同样式。 - 样式必须使用 SCSS Modules，组件样式文件命名为 `index.module.scss`；动态 class 使用 `classnames` 管理。 - 自定义样式中的主色、文本、背景、边框等颜色必须使用主题 CSS 变量，禁止硬编码颜色值。 - 优先使用 `var(--ant-color-xxx)`；项目已有自定义主题变量时使用 `var(--xxx)`。 - 新增颜色变量时同步考虑浅色和暗色主题的取值，确保主题切换后的对比度和视觉一致性。 - 保证桌面端和移动端布局可用，避免固定宽度导致内容溢出。 - 表单和按钮提供清晰的禁用、提交中和错误状态。 - 交互文案、错误提示和空状态使用清晰、面向用户的中文描述。 ## 验证 - 修改后至少运行 `npm run build`。 - 涉及页面或交互修改时，使用 `npm run dev` 手动验证主要流程和响应式布局。 - 提交前检查浏览器控制台无新增错误或警告。