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

---
description: 
alwaysApply: true
---

# Nomo-home-web 项目专家指令集

## 角色与原则

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

**核心原则：**

- **严格遵循目录结构与开发流程**。
- **工具优先 (Utils First)**：编写代码前必须先检索现有的 `utils`, `components`, `common`, `defines`, `consts`。**优先复用，缺失时再补充通用函数**，禁止直接在业务逻辑中硬编码通用逻辑。
- **Lint & Cleanup Mandatory**：每次代码修改完成后，必须进行 Lint 检查，并 **彻底删除无用代码**。禁止提交包含 Lint 错误、格式警告、或残留冗余逻辑的代码。
- **类型安全**：全量使用 TS 接口 (Interface)。
- **全量国际化 (i18n Mandatory)**：**禁止在页面或组件中硬编码任何文本内容**。所有展示给用户的字符串必须通过多语言方案实现，统一在 `locales` 中定义并使用翻译 Hook 调用。

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

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

- **范式**：函数式/声明式编程，**严禁使用 Class**。
- **模式**：采用 **RORO** (Receive Object, Return Object) 模式。
- **自动清理 (Code Pruning)**：
  - **删除未使用的导入** (Unused Imports)。
  - **删除定义的但未使用的变量、常量或 Props**。
  - **删除所有被注释掉的代码块** (Commented-out code)。
  - **精简逻辑**：如果一段逻辑不再被调用或已被新逻辑覆盖，必须立即物理删除。

- **工具使用策略**：
  - **React 优先**：优先使用 React 原生 Hooks 和工具（如 `useId`, `useMemo`, `useCallback`, `Fragment`）。
  - **库优先 (Library First)**：前端数据处理优先使用 **Ramda 和 Lodash**。
  - **先检索，后编写**：始终检查 `src/utils` 是否存在相关功能。

- **命名规范**：
  - **组件目录/文件**：**PascalCase** (如 `SysUserSelector.tsx`)。
  - **常规目录/文件**：**camelCase** (如 `authUtils.ts`)。
  - **变量**：描述性 + 助动词 (如 `isLoading`, `hasPermission`)。
  - **导出**：统一使用 **Named Export**。

- **语法细节**：
  - 纯函数：使用 `function` 关键字。
  - 分号：**禁止省略分号**。
  - 条件语句：单行省略花括号 (如 `if (cond) return;`)，**禁止使用 else** (改用 Early Return)。

### 2. 组件逻辑拆分规范 (Logic Separation)

为了保持代码的可读性与组织性，必须遵循以下结构规范：

- **强制目录化**：**禁止在 `components/` 根目录下直接添加包含多个逻辑文件的组件**。如果组件拆分了单独的 Hook 文件（如业务逻辑或响应逻辑），则**必须**为该组件建立独立的 PascalCase 目录。
- **UI 与逻辑分离**：`index.tsx` 应当只关注 DOM 结构与样式，严禁在主文件中编写复杂的计算或状态处理逻辑。
- **响应逻辑 Hooks**：涉及交互响应、事件处理、UI 状态同步的逻辑，必须编写为单独的 Hook（如 `useComponentAction.ts`）。
- **业务逻辑 Hooks**：涉及 API 调用、数据转换、业务校验、全局状态管理的逻辑，必须拆分到单独的 Hook（如 `useComponentService.ts`）。
- **目录内组织**：
  ```text
  /ComponentName
    ├── index.tsx
    ├── useComponentAction.ts
    ├── useComponentService.ts
    └── types.ts (可选)
  ```

### 3. 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 文件。
  - **逻辑属性优先**：禁止使用 `left`, `right`, `ml-`, `pr-` 等硬编码方向。必须使用 **start** 和 **end**（如 `ms-`, `pe-`, `text-start`, `inset-inline-start`）以适配多语言/RTL 环境。。
  - **Flex 布局优先**：除非 Flex 布局无法实现，否则必须优先使用 Flex 布局，禁止使用过时的浮动或复杂的绝对定位。
- **性能优化 (Performance)**：
  - **避免无效重绘**：严禁因局部小数据变更导致大型父组件重新渲染。
  - **状态下沉**：保持 State 粒度最小化。
  - **稳定引用**：合理使用 `useMemo` 和 `useCallback`。
- **React 组件**：
  - **必须使用 Function Components**。
  - 最小化 `use client`, `useEffect`, `setState`。

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

- **Guard Clauses**：在函数开头处理错误/边缘情况并尽早返回。
- **Happy Path**：核心成功逻辑放在函数最底部。
- **反馈**：前端始终抛出用户友好的错误信息。

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

### 核心规范

- **常量**：必须定义在 `src/defines/`，禁止硬编码。
- **请求**：使用 `utils/request.ts`。
- **文本国际化**：所有文本必须进入 `src/locales/`，禁止在代码中直接书写中文或英文常量字符串。
- **清理**：功能实现后，执行最后的“瘦身”扫描。

### 新页面开发 4 步

1. **API 定义**：`src/services/pageName/` 创建 `typings.d.ts` 和 `index.ts`。
2. **页面目录**：创建 `src/pages/PageName/` (PascalCase)。
3. **页面入口**：创建 `index.tsx` (内部逻辑需抽离至 Hooks)。
4. **配置**：**必须** 在 `locales` 添加多语言翻译，`routes.tsx` 添加路由。

---

**注意：当你完成代码修改后，请主动执行清理：彻底删除无用的导入、变量、注释、冗余逻辑，确保文本已全部多语言化，逻辑已抽离至 Hooks，且样式符合逻辑属性规范。**