编程规范
代码组织
- 单一职责：每个源文件应具有清晰、聚焦的作用域/目的
- 拆分大文件：当文件过大或处理过多关注点时应拆分
- 常量抽取：将常量移动到专用的
constants.js文件 - 环境变量统一：编程时若涉及到环境变量部分的代码，必须统一从前后端各自的
.env.*中读取 - UTF-8 编码：使用
UTF-8编码，若遇到携带BOM标记的文件，则必须移除BOM以避免编码出现问题，如果文件中出现乱码，需要及时检测并修复编码问题
JavaScript
- 使用 ES6+ 特性：优先采用现代 JavaScript 语法与特性
- JSDoc 规范：严格遵守 JSDoc 注释规范，记录函数参数、返回值与复杂逻辑
TypeScript
- 显式返回类型：尽可能显式声明返回类型
- 避免复杂内联类型：将复杂类型提取为独立的
type或interface声明 - 类型分离：当使用 TypeScript 时，始终将类型与接口分离到
types.ts或types/*.ts - TSDoc 规范 ：严格遵守 TSDoc 注释规范，记录函数参数、返回值与复杂逻辑
注释
- 中文注释：尽可能遵守中文注释规范，以便开发者更好地理解
- 清晰简洁：注释应当简明扼要，避免冗长
- 解释“为什么”而非“怎么做”：注释应描述理由或意图，而非代码行为
测试（Vitest）
- 测试文件命名：
foo.js→foo.test.js（同目录） - 使用
describe/itAPI（不使用test） - 对复杂输出使用
toMatchSnapshot - 对语言特定快照使用带显式路径的
toMatchFileSnapshot
前端样式（Sass、UnoCss）
- UnoCSS 优先：Sass 仅在 UnoCSS 无法满足需求时使用
- BEM 命名：当使用 Sass 时，采用 BEM 命名约定
包管理器（pnpm）
- 统一使用 pnpm：前后端项目均使用 pnpm 作为包管理器
- 独立的依赖管理：前后端项目应维护自己的依赖列表，避免全局依赖冲突
- 禁止使用.pnpm-store：禁止在项目中生成和使用 pnpm 的全局存储目录
.pnpm-store
应用开发
框架选择
| 使用场景 | 选择 |
|---|---|
| 前端 | Vite + Vue3 |
| 后端 | Nestjs + Prisma ORM v7 + PostgreSQL |
Vue 约定
| 约定 | 偏好 |
|---|---|
| Script 语法 | 始终使用 <script setup> |
| JavaScript | 优先使用现代 JavaScript 语法，而非 TypeScript |
| 状态 | 优先 shallowRef() 而非 ref() |
| 对象 | 使用 ref()，避免 reactive() |
| Vue 路由 | Vue Router |
| UI 组件库 | Element Plus |
| 样式 | UnoCSS, Sass |
| 工具库 | VueUse, Lodash |
| 仓库状态管理 | Pinia, pinia-plugin-persistedstate（持久化插件） |
| Ajax 请求 | Axios |
Vue 设计原则
- 模块化/组件化：优先使用模块化和组件化的方式组织代码，避免单一文件过大或过于复杂
- 单一职责：每个模块或组件应专注于一个功能或职责，避免过多关注点混杂在一起
- 单页面专用组件：当某个页面需要设计专用组件时，可以在该页面目录下创建
components文件夹，例如：src/views/<page-name>/components/<ComponentName>.vue，存放该页面专用组件，避免在全局组件目录下创建仅供单页面使用的组件
Vue 页面结构约定
生成新的 Vue 页面时，必须使用按页面分文件夹的结构：
src/views/<page-name>/index.vue
规则：
<page-name>必须为 kebab-case- 绝不在
src/views下直接创建单文件页面（禁止：src/views/home.vue） - 若用户仅提供页面名称（未含路径），应自动推断并创建文件夹结构
- 需要时将相关文件放在同一文件夹中（例如
index.ts、types.ts、style.scss、__tests__）
示例：
- 请求：“Create Home page” 或 “Create AboutMe page”
- 输出路径：
src/views/home/index.vue或src/views/about-me/index.vue - 禁止：
src/views/home.vue或src/views/about-me.vue
Vue 组件结构约定
生成新的 Vue 组件时，必须使用按组件分文件夹的结构：
src/components/<ComponentName>/<ComponentName>.vue
规则：
<ComponentName>必须为 PascalCase- 绝不在
src/components下直接创建单文件组件（禁止：src/components/HelloWorld.vue） - 若用户仅提供组件名称（未含路径），应自动推断并创建文件夹结构
- 需要时将相关文件放在同一文件夹中（例如
index.ts、types.ts、style.scss、__tests__）
示例：
- 请求：“Create HelloWorld component”
- 输出路径：
src/components/HelloWorld/HelloWorld.vue - 禁止：
src/components/HelloWorld.vue
Vue 文件模板
严格按照 <template> 在上，<script setup> 在中，<style> 在下的结构生成 Vue 文件，如下：
<template></template>
<script setup></script>
<style lang="scss" scoped></style>前端 API 接口文件路径规范
src/api/ # 接口层：按业务模块组织 API 请求与请求封装
├── modules/ # API 请求文件
└── request/ # Axios 封装与配置（请求拦截器和响应拦截器等）⚠ 注意：api 接口文件禁止直接放在 src/api 下- 违规的 api 接口文件路径：
src/api/user.js - 合法的 api 接口文件路径：
src/api/modules/system/user.js、src/api/modules/menu/index.js、src/api/modules/login.js
前端本地持久化缓存
- Pinia 持久化：使用
pinia-plugin-persistedstate插件将 Pinia 状态持久化到localStorage
图标 icons
当前端需要使用 图标/字体图标/icons 时，必须遵循以下约定：
优先级：iconfont 图标 > Element Plus 图标 > UnoCSS 图标 > SVG 图标
- iconfont 图标：高优先级，先查询项目中
src/assets/iconfont下有无引入iconfont资源，优先使用iconfont的字体图标，文档链接：iconfont - Element Plus 图标：中优先级，使用 Element Plus 内置图标，满足常规 UI 需求，文档链接：Element Plus Icon
- UnoCSS 图标：次优先级，使用 UnoCSS 的图标功能，它支持多种图标集，文档链接：UnoCSS Icons
- SVG 图标：最低优先级，当其他图标无法满足需求时，才能使用 SVG 图标，并将 SVG 文件放在
src/assets/svgs目录下，使用vite-svg-loader加载器进行处理 - 图标命名：SVG 图标文件命名应使用 kebab-case，例如：
user-profile.svg、home.svg