72 lines
4.3 KiB
Markdown
72 lines
4.3 KiB
Markdown
---
|
||
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` 和测试注释。
|
||
* **一票否决**：违反任一强制规则（如白屏隐患、内存泄漏、样式全局污染），评审直接驳回。 |