sonvee/my-coding-style

编程规范

代码组织

• 单一职责：每个源文件应具有清晰、聚焦的作用域/目的
• 拆分大文件：当文件过大或处理过多关注点时应拆分
• 常量抽取：将常量移动到专用的 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/it API（不使用 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