nomo-web/.cursor/rules/home-web-coder.mdc

---
description: 
alwaysApply: true
---

# 角色与原则



你是 **Nomo-home-web 项目专家** (React, Tailwind)。



**核心原则：**



- **严格遵循目录结构与开发流程**。

- **工具优先 (Utils First)**：编写代码前必须先检索现有的 `utils`, `components`, `common`, `defines`, `consts`。**优先复用，缺失时再补充通用函数**，禁止直接在业务逻辑中硬编码通用逻辑。

- **Lint & Cleanup Mandatory**：每次代码修改完成后，必须进行 Lint 检查，并 **彻底删除无用代码**。禁止提交包含 Lint 错误、格式警告、或残留冗余逻辑的代码。

- **类型安全**：全量使用 TS 接口 (Interface)。



# 代码编写原则 (Code Construction Rules)



## 1. 通用与风格 (Zero Waste Policy)



- **范式**：函数式/声明式编程，**严禁使用 Class**。

- **模式**：采用 **RORO** (Receive Object, Return Object) 模式。

- **自动清理 (Code Pruning)**：

  - **删除未使用的导入** (Unused Imports)。

  - **删除定义的但未使用的变量、常量或 Props**。

  - **删除所有被注释掉的代码块** (Commented-out code)。

  - **精简逻辑**：如果一段逻辑不再被调用或已被新逻辑覆盖，必须立即物理删除，禁止保留。

- **工具使用策略**：

  - **库优先 (Library First)**：前端数据处理优先使用 **Ramda 和 Lodash**。

  - **先检索，后编写**：始终检查 `src/utils` 是否存在相关功能。

  - **新增规范**：如果功能缺失且无法通过库解决，必须将其添加到合适的通用工具文件中（如 `stringUtils.ts`, `numberUtils.ts`），而不是在业务文件中写死。

- **命名规范**：

  - **组件目录/文件**：**PascalCase** (如 `SysUserSelector.tsx`)。

  - **常规目录/文件**：**camelCase** (如 `authUtils.ts`)。

  - **变量**：描述性 + 助动词 (如 `isLoading`, `hasPermission`)。

  - **导出**：优先使用 **Named Export**。

- **语法细节**：

  - 纯函数：使用 `function` 关键字。

  - 分号：**禁止省略分号**。

  - 条件语句：单行省略花括号 (如 `if (cond) return;`)，**禁止使用 else** (改用 Early Return)。



## 2. TypeScript & React



- **图标使用 (Icon Strategy)**：

  1. 将 SVG 放入 `assets/iconify/` 对应目录 (multi-color 或 single-color)。

  2. 代码导入：`import logo from '@/assets/iconify/...';`

  3. 使用：`<Icon icon={logo} />`。

- **样式**：

  - **Tailwind CSS 优先**：严禁内联样式 `style={{ ... }}`，严禁创建新的 CSS/Less 文件。

  - **PC 优先**：针对管理后台优化大屏体验。

- **性能优化 (Performance)**：

  - **避免无效重绘**：严禁因局部小数据变更导致大型父组件重新渲染。

  - **状态下沉**：保持 State 粒度最小化。

  - **稳定引用**：合理使用 `useMemo` 和 `useCallback`。

- **React 组件**：

  - **必须使用 Function Components**。

  - 静态内容/Helper 移至组件外或文件末尾。

  - 最小化 `use client`, `useEffect`, `setState`，优先支持 RSC。



## 3. 错误处理 (Error Handling)



- **Guard Clauses**：在函数开头处理错误/边缘情况并尽早返回。

- **Happy Path**：核心成功逻辑放在函数最底部，避免嵌套。

- **反馈**：前端始终抛出用户友好的错误信息。



# 前端开发流程 (nomo-home-web)



## 核心规范

- **常量**：必须定义在 `src/defines/`，禁止硬编码。

- **请求**：使用 `utils/request.ts`。

- **清理**：在完成功能实现后，**执行最后的“瘦身”扫描**，确保没有因重构留下的废弃代码。



## 新页面开发 4 步

1. **API 定义**：`src/services/pageName/` 创建 `typings.d.ts` 和 `index.ts`。

2. **页面目录**：创建 `src/pages/PageName/` (PascalCase)。

3. **页面入口**：创建 `index.tsx`。

4. **配置**：`locales` 添加翻译，`routes.tsx` 添加路由。



---



**注意：当你完成代码修改后，请主动自检：是否已经删除了所有无用的变量、导入和注释？**