wireguard-dashboard/web/.aiassistant/rules/front_code_rule.md

apply

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