<!--
 * @Author: wjc-home
 * @Date: 2025-12-09 22:38:21
 * @LastEditors: wjc
 * @LastEditTime: 2026-01-14 18:00:23
 * @Description: 项目规则
-->

---

## alwaysApply: true

## 该规则为整个项目的默认规则，所有规则都继承该规则：

- **vuejs**: 版本 3.5.12
- **UI组件库**：nutui-uniapp
- **css 框架**: unocss 66.3.3
- **状态管理**： pinia
- **图标库** 使用 iconify 的图标库：
  - 1. lucide
  - 2. 使用时，注意检查有没有 import { Icon } from '@iconify/vue' 引入
  - 3. 正确的使用 Icon 组件，例如：<Icon icon="lucide:download" />
- **注释规范**：添加注释时，要使用 jsdoc 注释规范
- **注释**：使用中文注释

## 该规则使用于项目的文件命名规则：

- 所有文,包括.vue、.ts、.js、.scss、.css格式的文件，命名使用 kebab-case 命名，首字母都是小写

## 该规则使用于项目的js/ts 的函数命名规则：

- 所有函数命名使用 camelCase 命名
- 函数名要见名知义，简单易读

## 代码风格与惯例：

- **.vue文件**: vue 组件使用组合式API写法；
  - 支持 typescript
  - vue3 的组合式API中，优先使用 ref 来定义响应式数据
- TypeScript 贯穿整个项目
- 组件应为具有正确类型的功能组件
- 组件道具应通过TypeScript接口显式类型化
- CSS 应通过 tailwindcss 的实用类实现
- 在适当情况下使用 CSS 变量进行主题设置
- 遵循 eslint.config.mjs、stylelint.config.mjs、.prettierrc.mjs 的规则

## CSS 代码：

- 定义的 css class 要见名知义，简单易读
- css 用 scss, 使用 scss 语法时，要正确的嵌套 class
- css 使用 unocss 样式框架，使用 scoped 属性
- unocss 的样式类要简单，高效
- 优先直接在元素的class使用 unocss 的样式类，当遇到复杂的 css 样式时，才考虑借助@apply自定义 css class

## HTML 代码：

- html 的结构要简单，高效，不要嵌套过深

## UI/UX要求：

- 所有UI组件应尽可能的使用 element-plus 组件构建
- element-plus 都没有的组件，才考虑自定义组件
- 所有组件必须同时支持光模式和暗模式
- 用户界面应具备响应式且易于访问
- 动画应使用 motion-v 实现，并考虑相应的运动偏好
- 用户体验友好
- 按钮、菜单等可以点击的元素要添加 cursor-pointer 类

## 状态管理：

- 对于全局状态，优先使用 pinia
- 对于pinia状态，优先使用 vue3 的 composition api
- pinia 状态命名 use + 驼峰命名
- 状态文件放置在 src/stores/modules 中

## hooks：

- 复用代码可以使用 vue3 的 hooks 来实现
- 命名：use + 驼峰命名
- 全局的 hooks 放置在 src/hooks 中
- 组件的 hooks 放置在对应的组件的 src/components/\*/hooks 中
- widgets 的 hooks 放置在对应的 widgets 页面的 src/views/widgets/\*/hooks 中

## 性能考量：

- 实现正确的代码拆分和懒加载
- 遵循 Web Vitals 优化的最佳实践

## 与用户的沟通：

- AI助手应始终以中文回应
- 代码示例应遵循项目惯例
- 生成的组件应与现有设计系统相匹配
