# 项目规范

## 项目说明
- 本项目基于 Vue 3 + TypeScript
- UI 组件库：Vant 4.9
- 优先使用 Vant 组件，避免重复造轮子
- 使用 Vite 作为构建工具

## 文件结构规范

### Vue 单文件组件（SFC）格式
1. **必须使用标准 SFC 格式**，文件扩展名为 `.vue`
2. **块顺序固定**：`<template>` 、 `<script>` 、 `<style>`，不可调换
3. **TypeScript 支持**：如需使用 TypeScript，`<script>` 块需声明 `lang="ts"`

## Vue 3 语法规范

### Script 部分
- **默认使用 `<script setup lang="ts">` 语法**，简化组件定义
- 使用 Vue 3 Composition API：`ref`、`reactive`、`computed`、`watch`、`watchEffect`、`provide`、`inject` 等
- **禁止使用 Vue 2 语法**：
  - 禁止使用 `this`、`$refs`、`$emit` 等
  - 推荐使用 `defineProps`、`defineEmits`、`defineExpose`、`defineModel`

### Template 部分
- 编写**语义化、易读的 HTML 结构**
- 使用 Vue 3 指令：`v-if`、`v-for`、`v-model`、`v-bind`、`v-on` 等
- 事件处理使用 `@` 简写形式
- `v-for` 必须添加 `:key` 属性，并使用唯一标识符
- 避免在模板中写复杂的表达式，复杂逻辑应提取到 `setup` 中
- 示例：
  ```vue
  <template>
    <div class="service-card">
      <h2>{{ title }}</h2>
      <p v-if="description">{{ description }}</p>
      <ul>
        <li v-for="item in items" :key="item.id">{{ item.name }}</li>
      </ul>
      <button @click="handleClick">点击</button>
    </div>
  </template>
  ```

### Style 部分
- **必须添加 `scoped` 属性**，避免样式全局污染
- 需要穿透样式时，使用 `:deep()` 选择器（Vue 3.0+ 推荐语法）或 `/deep/`（兼容模式）
- 优先使用 Vant 组件自带样式，减少自定义样式
- 使用 less 作为 css 预处理器，优先使用原生 css 变量
- 简单覆盖浏览器默认样式

## UI 组件使用规范

### Vant 组件
- **优先使用 Vant 组件**，避免重复造轮子
- 常用组件已在 `main.ts` 中全局注册，可直接使用
- 如需使用未注册的组件，在 `<script>` 中按需导入
- 组件使用示例：
  ```vue
  <van-button type="primary" size="large">按钮</van-button>
  <van-icon name="success" />
  <van-list
    v-model:loading="loading"
    v-model:finished="finished"
    :finished-text="'没有更多了'"
    @load="onLoad"
  >
    <van-cell v-for="item in items" :key="item.id" :title="item.title" />
  </van-list>
  ```
- 组件属性优先使用 TypeScript 类型约束：
  ```typescript
  import { VanButtonProps } from 'vant'
  
  const buttonProps = ref<Partial<VanButtonProps>>({
    type: 'primary',
    size: 'large'
  })
  ```

### 第三方组件
- 若需使用其他第三方 UI 组件，必须在 `<script>` 中导入
- 在模板中以标签形式使用，遵循组件文档规范
- 使用 date-fns 作为日期处理库
- 使用 lodash 作为工具库
- 使用 axios 作为请求库
- 使用 vue-i18n 作为国际化库，自动翻译对应的语言
- 使用 pinia 作为状态管理库
- 使用 crypto-js 作为加密库，使用 aes 算法
- 使用 vConsole 作为调试库，在开发环境下启用
- 使用 animate.css 作为动画库，添加基础的页面动画效果

## 代码质量要求

1. **禁止输出无用内容**：仅保留符合 Vue 3 SFC 约定的代码结构及必要注释
2. **遵循 Vue 3 最佳实践**：所有组件、方法、属性和事件需按 Vue 3 推荐方式声明和使用
3. **保持代码简洁**：避免冗余代码，优先使用组合式 API 的简洁写法
4. **类型安全**：使用 TypeScript 时，确保类型定义完整准确，避免使用 `any` 类型
5. **代码规范**：遵循 eslint 和 prettier 的代码规范
6. **注释规范**：
   - 组件文件头部添加组件功能说明
   - 复杂逻辑添加内联注释
   - API 调用添加注释说明用途

## 响应式数据管理

- 使用 `ref()` 定义基本类型响应式数据
- 使用 `reactive()` 定义对象类型响应式数据
- 使用 `computed()` 定义计算属性
- 使用 `watch()` 或 `watchEffect()` 处理副作用
  - `watch` 用于监听特定数据源的变化
  - `watchEffect` 用于自动收集依赖的副作用
- 优先使用双向绑定传值，尽可能避免直接操作组件实例方法
- 复杂状态管理使用 Pinia 存储

## 路由与导航

- 使用 `vue-router` 的 Composition API：`useRoute()`、`useRouter()`
- 路由跳转使用 `router.push()` 或 `router.replace()`
- 查询参数通过 `route.query` 获取
- 路由参数通过 `route.params` 获取
- 优先使用异步加载路由组件，使用 `load` 属性
- 路由守卫使用 Composition API 风格

## 性能优化

- 使用 prefetch 预加载非关键资源
- 使用 lazyload 懒加载非关键资源
- 自动生成 favicon 文件，并支持 PWA 和 OG标签 的规范
- 精简构建产物，去除无用代码和注释，移除 sourcemap 文件
- 定义好开发、测试和生产环境的环境变量，定义好 vite 开发服务器的代理
- 使用 `v-memo` 指令优化 v-for 列表渲染性能
- 避免在模板中使用复杂计算，将计算逻辑移至 setup 中