VUE前端项目规范.md---大模型辅助开发使用约束

前端代码开发与输出规范

通用要求

语言：思考过程与输出内容一律使用中文。
上下文引用：每次对话必须明确引用项目中的 README.md 相关内容，确保开发行为与项目目标一致。
项目架构：基于Vue.js + ElementUI + Vue Router + Vuex + Axios的前端架构。
文档位置: 项目文档统一存放在 /docs 目录下，并使用 .md 格式编写。
Git提交规范: 所有代码提交必须遵循 GIT_COMMIT.md 中定义的提交规范，AI助手在生成提交信息时必须参考该文档。

代码风格

保持统一的代码风格（如缩进使用2个空格、分号使用、换行等）。
遵循Vue.js官方风格指南和ESLint规范。
优先保障代码的可读性，避免过度压缩或炫技式写法。

命名与注释

命名规范

变量名、函数名：采用小驼峰命名法（camelCase）
组件名：采用大驼峰命名法（PascalCase），如 UserList.vue
文件名：Vue组件使用大驼峰，其他文件使用小驼峰或短横线分隔
常量：使用全大写加下划线，如 API_BASE_URL
CSS类名：使用短横线分隔，如 user-list-item

注释规范

所有函数、组件、关键逻辑块必须附带清晰、准确、简洁的中文注释
注释应说明"为什么"而不仅是"做什么"
@author 格式: username / useremail（从Git配置获取）
@since 格式: yyyy-MM-dd HH:mm:ss（代码生成时的时间戳）

Vue组件注释示例

<template>
  <!-- 用户列表页面 -->
  <div class="user-list">
    <!-- 搜索区域 -->
    <el-form :model="searchForm" inline>
      <el-form-item label="用户名">
        <el-input v-model="searchForm.username" placeholder="请输入用户名"></el-input>
      </el-form-item>
    </el-form>
  </div>
</template>

<script>
/**
 * 用户列表组件
 * @author zhangsan / zhangsan@example.com
 * @since 2025-01-15 14:30:25
 */
export default {
  name: 'UserList',
  data() {
    return {
      searchForm: {
        username: ''
      }
    }
  },
  methods: {
    /**
     * 查询用户列表
     * 根据搜索条件获取用户数据并更新表格
     * @author zhangsan / zhangsan@example.com
     * @since 2025-01-15 14:30:25
     */
    getUserList() {
      // 实现逻辑
    }
  }
}
</script>

编码规范

Vue组件规范

单个函数长度不超过50行，超出时应考虑拆分或重构
组件文件不超过300行，超出时应拆分为多个子组件
禁止使用全局变量，优先使用Vuex状态管理或props/emit传递数据
模块导入：使用ES6 import/export语法，避免require
代码格式：使用2个空格缩进，行尾加分号

JavaScript规范

使用ES6+语法（箭头函数、解构赋值、模板字符串等）
优先使用const，其次let，避免使用var
函数参数不超过3个，超出时使用对象参数
避免深层嵌套，最多3层

Vue特定规范

组件props必须定义类型和默认值
使用computed处理复杂逻辑，避免在template中写复杂表达式
合理使用生命周期钩子，避免在created中执行DOM操作
组件销毁时清理定时器和事件监听器

样式规范

CSS/SCSS规范

使用SCSS预处理器，支持变量和嵌套
类名使用短横线分隔命名法（kebab-case）
避免使用!important，通过提高选择器权重解决
合理使用CSS变量定义主题色彩

ElementUI使用规范

优先使用ElementUI组件，避免重复造轮子
自定义样式时使用scoped避免全局污染
主题定制通过variables.scss文件统一管理

响应式设计

使用ElementUI的栅格系统实现响应式布局
移动端适配使用媒体查询
图片使用相对单位，支持高分辨率屏幕

测试要求

单元测试

为核心业务逻辑和工具函数编写单元测试
使用Jest + Vue Test Utils进行组件测试
测试覆盖率不低于70%（考虑前端项目特点）
测试用例需覆盖正常路径、边界条件和异常场景

E2E测试

关键业务流程编写端到端测试
使用Cypress或Playwright进行自动化测试
覆盖主要用户操作路径

手动测试

新功能开发完成后进行浏览器兼容性测试
测试不同屏幕尺寸的响应式效果
验证无障碍访问性（a11y）

代码优化

优化需基于性能瓶颈或可维护性问题，避免无意义的"提前优化"。
任何优化后必须通过完整测试验证，确保功能正确性。
在性能与可读性之间优先保障可读性，除非性能是明确瓶颈。

代码重构

重构前需明确目标（如提升可读性、消除重复、改善结构等）。
重构后必须通过全部现有测试，并补充必要新测试。
重构不得降低代码可读性或引入隐式复杂度。

文档要求

所有模块、接口、关键算法必须配套详细的技术文档。
文档应包含：功能说明、使用示例、输入/输出定义、依赖关系等。
文档需与代码同步更新，避免"文档腐化"。

开发工具与脚本

代码生成信息获取脚本

项目提供了自动获取代码生成信息的脚本，用于生成规范的@author和@since注释。

脚本位置:

Windows: scripts/get-code-info.bat
Linux/macOS: scripts/get-code-info.sh

使用场景:

生成新的Vue组件时
添加新的工具函数时
需要标注作者和时间信息时

开发工具配置

ESLint配置

使用Vue官方ESLint配置
自定义规则适配项目需求
保存时自动格式化代码

Prettier配置

统一代码格式化规则
配置文件：.prettierrc
与ESLint集成避免冲突

VS Code配置

推荐安装插件：

Vetur（Vue语法高亮）
ESLint（代码检查）
Prettier（代码格式化）
Auto Rename Tag（标签自动重命名）

Git提交规范

规范文档引用

完整的Git提交规范请参考：GIT_COMMIT.md

AI助手职责

当开发人员请求生成Git提交信息时，AI助手必须：

自动分析代码变更
- 执行 git status 查看变更文件
- 执行 git diff 分析具体变更内容
- 识别变更类型（新功能、修复、重构等）
生成规范提交信息
- 格式：[no] [type] [subject]
- 使用当前周任务编号（需开发人员提供）
- 选择正确的type类型
- subject不超过50字符
- body列出所有关键变更（使用 - 标识）
质量保证
- ✅ 包含任务编号
- ✅ 正确的type类型
- ✅ 简洁的subject
- ✅ 完整的body
- ✅ 格式规范

提交类型速查

type	说明	使用场景
`feat`	新功能	新增页面、组件、业务功能
`fix`	缺陷修复	修复Bug、样式问题、逻辑错误
`refactor`	代码重构	重构组件、优化代码结构
`docs`	文档变更	修改README、注释、开发文档
`style`	样式调整	CSS样式修改、UI调整
`perf`	性能优化	优化加载速度、减少包体积
`test`	测试代码	新增或修改单元测试、E2E测试
`build`	构建调整	webpack配置、依赖管理、打包优化
`chore`	其他变更	配置文件、开发工具配置

使用示例

[sop-72] feat 新增用户管理页面

- 新增UserList.vue用户列表组件
- 实现用户查询、新增、编辑功能
- 添加用户状态管理和权限控制
- 集成ElementUI表格和分页组件

任务编号管理

开发人员每周提供一次任务编号
AI助手自动记录到GIT_COMMIT.md文档中
生成提交信息时自动使用当前任务编号

触发场景

AI助手应在以下场景主动提供Git提交信息生成服务：

开发人员明确请求生成提交信息
完成代码开发任务后
开发人员询问如何提交代码时

自动执行Git操作

重要：AI主动询问机制

生成提交信息后，AI必须主动询问：“是否需要我直接执行git提交并推送到远程仓库？”
开发人员无需主动说明，AI会自动提示
开发人员确认后，AI自动执行：
- git add 添加文件
- git commit 提交到本地
- git push 推送到远程仓库
- 提供详细的执行结果反馈

posted @ 2025-12-01 16:17 大稳·杨阅读(7) 评论(0) 收藏举报

刷新页面返回顶部

大稳·杨