---
apply: 始终
---

# 前端开发全局强制准则 (V1.0 - Multi-Framework Pro)

## 1. 性能与资产安全 (Performance & Asset Safety)
* **加载优化 (Loading)**：
    * **强制路由懒加载**：所有页面组件必须使用动态 `import()` 导入。
    * **按需引入**：UI 框架（Naive UI, Element Plus, AntD）必须配置插件实现自动按需引入，严禁全局注册。
* **渲染性能 (Rendering)**：
    * **长列表防御**：展示数据超过 50 条时，必须使用**虚拟列表 (Virtual List)** 或分页加载，禁止直接渲染大批量 DOM。
    * **资产压缩**：禁止在页面加载超过 500KB 的原始图片，必须使用 WebP 格式或 CDN 缩略图参数。
* **内存释放 (Cleanup)**：
    * 定时器 (`setInterval`)、全局事件监听 (`window.addEventListener`)、WebSocket 必须在组件卸载钩子（`onUnmounted` / `useEffect cleanup`）中明确销毁。

## 2. 状态管理与数据流 (State & Data Flow)
* **状态分层原则**：
    * **局部优先**：仅在跨页面/跨多级组件共享时才使用 Pinia 或 Redux。
    * **不可变性 (Immutability)**：严禁直接修改复杂对象的属性，必须使用解构赋值或 `set` 函数确保引用更新。
* **数据安全 (Safety)**：
    * **可选链操作**：渲染后端异步数据必须使用 `?.` 可选链，严禁因 `undefined` 导致页面白屏。
    * **声明式校验**：表单提交前必须通过 Schema 校验，严禁依赖后端接口反馈作为唯一拦截手段。

## 3. 组件架构与规模控制 (Architecture & Scale)
* **单文件硬指标**：**单个组件文件代码禁止超过 1000 行**。
    * **重构门禁**：超过 800 行时，AI/开发者必须将业务逻辑抽离至 `Hooks` (Vue3 `useXXX` / React `useXXX`)。
* **层级规范**：
    * 目录嵌套严禁超过 4 层。
    * **职责分离**：复杂的页面必须拆分为“逻辑容器组件”和“纯 UI 展示组件”。
* **通用逻辑封装**：
    * 业务无关的格式化、正则、计算函数必须存放在 `src/utils`。
    * 跨组件复用的逻辑必须封装为 `Hooks`。

## 4. 命名与样式规范 (Naming & CSS)
* **精简命名**：
    * **组件命名**：采用 `PascalCase`（如 `UserCard.vue`），严禁超过 3 个单词。
    * **方法前缀**：事件处理函数使用 `handle`（如 `handleSearch`），数据获取使用 `fetch` 或 `get`。
* **样式隔离 (Scoped CSS)**：
    * 必须启用 `scoped` 或 `CSS Modules`，严禁定义可能污染全局的类名。
    * **严禁内联样式**：禁止在 HTML 标签上写大量 `style` 属性。
    * **变量化**：颜色、字号必须引用预定义的 CSS 变量，严禁在组件内散落十六进制颜色值。

## 5. 框架专项标准 (Framework Specifics)

### Vue3 (uniapp / Naive UI)
* **语法糖**：必须使用 `<script setup>` 组合式 API。
* **响应式选择**：单一基本类型用 `ref`，结构化对象用 `reactive`。
* **uniapp 适配**：原生 API（扫码、支付）必须在 `src/utils/uni-tools.js` 中二次封装，禁止页面内直接调用原生接口。

### React
* **依赖闭包**：`useEffect` 和 `useCallback` 必须明确声明所有依赖项，严禁由于闭包陷阱导致状态陈旧。
* **组件更新**：优先使用 `React.memo` 优化高频刷新的子组件。

---

## 🤖 智能体执行指令 (Agent Frontend Instructions)

1. **预审行数**：AI 生成代码前统计当前行数。若生成后 > 1000 行，AI 必须拒绝直接输出并主动提供逻辑拆分（Hooks 提取）方案。
2. **安全性补全**：
    * 自动为后端返回的数据访问添加 `?.`。
    * 自动在卸载钩子中生成资源清理代码（如 `clearInterval`）。
3. **按需引入校验**：AI 生成的 UI 组件代码必须采用按需导入模式，严禁 `import { ... } from 'ui-lib'` 全量导入。
4. **命名自检**：自动精简用户提供的冗长类名或方法名。

---

## 强制执行门禁 (Submission Gaterails)
* **ESLint/Prettier**：必须 100% 通过校验。
* **TS 约束**：严禁滥用 `any`。所有后端接口返回数据必须定义 `interface` 或 `type`。
* **生产环境清理**：严禁残留 `console.log` 和测试注释。
* **一票否决**：违反任一强制规则（如白屏隐患、内存泄漏、样式全局污染），评审直接驳回。