开发规范

为了保证 MaoQi-Admin 项目代码的质量和可维护性，团队成员在参与开发时需严格遵循以下开发规范。本规范涵盖命名、代码风格、Git 提交以及目录结构等方面。

1. 命名规范

1.1 项目文件命名

• Vue 组件文件：推荐使用 PascalCase（大驼峰命名法），例如：UserAvatar.vue、RoleSetting.vue。
• 普通 JS/TS 文件：推荐使用 kebab-case（短横线命名法），例如：user-api.ts、date-utils.js。
• 样式文件：推荐使用 kebab-case，例如：global-style.css。

1.2 变量与函数命名

• 变量与函数：使用 camelCase（小驼峰），例如：getUserInfo、activeTab。
• 常量：使用 UPPER_SNAKE_CASE（全大写加下划线），例如：MAX_COUNT、DEFAULT_PAGINATION。
• 类名 / 构造函数：使用 PascalCase（大驼峰），例如：UserService、RequestInterceptor。
• 私有属性/方法：在名称前加下划线前缀，例如：_privateMethod。

2. 代码规范

本项目严格遵循社区主流的前端代码规范，主要通过 ESLint 和 Prettier 进行自动化约束和格式化。

• Vue3 规范：遵循 Vue 官方风格指南 的优先级 A（必要的）和优先级 B（强烈推荐）规则。
• TypeScript 规范：开启 strict: true 严格模式，尽量避免使用 any 类型。为 API 请求的返回数据定义明确的 interface/type。
• 格式化：缩进使用 2 个空格，语句末尾默认不加分号（根据项目 Prettier 配置而定），单行字符最大长度 100。
• 提交代码前，需通过 npm run lint 检查，并确保没有 Error 级别的警告。

3. Git 提交规范

本项目采用 Angular 团队提出的 Conventional Commits 规范。合理的提交日志有助于自动生成 ChangeLog 和回溯问题。

提交格式：<type>(<scope>): <subject>

常用 Type 说明：

• feat: 新增功能 (Feature)
• fix: 修复 Bug
• docs: 修改文档 (Documentation)
• style: 代码格式修改（不影响代码运行的变动，如空格、缩进等）
• refactor: 代码重构（既不修复 bug 也不添加新功能的代码更改）
• perf: 性能优化
• test: 增加或修改测试用例
• chore: 构建过程、辅助工具或依赖包的变动

示例：feat(user): 增加用户重置密码功能

4. 目录结构规范

统一、清晰的目录结构有助于大型项目的长期维护。以下是 MaoQi-Admin 的标准目录结构：

src/
├── api/          # 后端接口请求定义
├── assets/       # 静态资源 (图片、SVG图标、字体等)
├── components/   # 全局通用业务/基础组件
├── hooks/        # 组合式函数 (Composables)
├── layout/       # 系统整体布局组件 (如侧边栏、顶栏)
├── router/       # Vue Router 路由配置与拦截器
├── store/        # Pinia 状态管理
├── typings/      # TypeScript 全局类型声明定义
├── utils/        # 全局工具类函数 (格式化、存储、加密等)
└── views/        # 页面视图 (严格按照业务模块划分文件夹)

5. 样式规范

• 避免使用标签选择器，尽量使用 BEM 规范的类名选择器，或者利用 UnoCSS 的原子类。
• 在 Vue 单文件组件中，<style> 必须加上 scoped 属性，以防样式全局污染。
• 全局主题颜色、间距等必须使用项目中定义的 CSS Variables（如 var(--c-brand)）。