# 项目代码规范与最佳实践

## 技术栈
- Vue 3 + Composition API
- TypeScript
- UnoCSS
- Element Plus
- Vite
- Pinia (状态管理)
- Vue Router

## 代码规范

### Vue 组件规范
- 使用 Composition API 和 `<script setup>` 语法
- 组件名使用 PascalCase 命名
- Props 必须定义类型，使用 `defineProps<T>()` 语法
- Emits 必须定义类型，使用 `defineEmits<T>()` 语法
- 组件文件使用 `.vue` 扩展名
- 单文件组件结构：`<template>` -> `<script setup>` -> `<style>`

### TypeScript 规范
- 严格模式：启用 `strict: true`
- 类型定义完整，避免使用 `any`
- 接口命名使用 PascalCase，以 `I` 开头（如 `IUserInfo`）
- 类型别名使用 PascalCase
- 枚举使用 PascalCase
- 函数参数和返回值必须定义类型

### UnoCSS 使用规范
- 优先使用 UnoCSS 原子类
- 自定义规则在 `uno.config.ts` 中定义
- 使用语义化的类名（如 `custom-hover`、`layout-border__left`）
- 响应式设计使用 UnoCSS 断点前缀

### 样式规范
- 使用 SCSS 预处理器
- 全局变量在 `@/styles/variables.scss` 中定义
- 组件样式使用 scoped 或 CSS Modules
- 遵循 BEM 命名规范
- 使用 CSS 变量（CSS Custom Properties）

### 文件组织
- 组件放在 `src/components/` 目录
- 页面放在 `src/views/` 目录
- 工具函数放在 `src/utils/` 目录
- 类型定义放在 `src/types/` 目录
- API 接口放在 `src/api/` 目录
- 状态管理放在 `src/stores/` 目录

### 命名规范
- 文件名使用 kebab-case
- 组件名使用 PascalCase
- 变量和函数使用 camelCase
- 常量使用 UPPER_SNAKE_CASE
- 私有属性使用下划线前缀

### 代码质量
- 使用 ESLint + Prettier 进行代码格式化
- 遵循 Vue 3 官方风格指南
- 组件职责单一，避免过度复杂
- 合理使用注释，复杂逻辑必须注释
- 错误处理完善，使用 try-catch 和错误边界

### 性能优化
- 合理使用 `v-memo` 和 `v-once`
- 避免在模板中使用复杂表达式
- 使用 `shallowRef` 和 `shallowReactive` 优化大对象
- 合理使用 `computed` 和 `watch`
- 图片懒加载和资源预加载

### 国际化
- 使用 vue-i18n 进行国际化
- 文本内容使用 `$t()` 函数
- 语言包文件放在 `src/locales/` 目录

### 状态管理
- 使用 Pinia 进行状态管理
- Store 文件放在 `src/stores/` 目录
- 使用 `defineStore` 定义 store
- 合理使用 `persist` 插件进行状态持久化

### 路由管理
- 路由配置放在 `src/router/` 目录
- 使用路由懒加载
- 路由守卫统一管理
- 动态路由权限控制

### API 接口
- 使用 axios 进行 HTTP 请求
- API 接口统一管理在 `src/api/` 目录
- 请求和响应拦截器统一处理
- 错误处理和重试机制

### 构建和部署
- 使用 Vite 作为构建工具
- 环境变量配置在 `.env.*` 文件中
- 构建产物优化（代码分割、压缩等）
- 支持多环境部署（dev/test/prod）

### 安全规范
- 输入验证和 XSS 防护
- CSRF 防护
- 敏感信息不暴露在前端
- 使用 HTTPS 协议

### 可访问性
- 语义化 HTML 标签
- ARIA 属性支持
- 键盘导航支持
- 屏幕阅读器友好

## 开发工具配置
- 使用 VS Code 作为主要开发工具
- 安装 Vue 3 相关插件
- 配置 TypeScript 智能提示
- 启用 ESLint 和 Prettier 自动格式化
- 使用 Git 进行版本控制

## 提交规范
- 使用 Conventional Commits 规范
- 提交信息格式：`type(scope): description`
- 类型：feat, fix, docs, style, refactor, test, chore
- 每次提交前运行 lint 检查

## 注意事项
- 遵循项目现有架构设计
- 不破坏现有功能和组件复用性
- 新功能开发前先了解相关代码结构
- 遇到问题先查看文档和现有代码
- 定期进行代码审查和重构