|
|
|
|
|
# 马士兵严选管理平台
|
|
|
|
|
|
|
|
|
|
|
|
## 技术架构
|
|
|
|
|
|
|
|
|
|
|
|
- vite
|
|
|
|
|
|
> 新兴主流项目编译构建工具，与 webpack 相比构建速度极快
|
|
|
|
|
|
- vue3
|
|
|
|
|
|
> vue 最新版本，声明式 API，组件内各功能点代码耦合性低，易扩展维护
|
|
|
|
|
|
- vue-router
|
|
|
|
|
|
> SPA 路由系统
|
|
|
|
|
|
- vuex
|
|
|
|
|
|
> 数据状态管理，规范组件之间数据传递，更好得监测数据状态变化
|
|
|
|
|
|
- axios
|
|
|
|
|
|
> AJAX 请求封装库，用于调用 API 接口
|
|
|
|
|
|
- element-plus
|
|
|
|
|
|
> 基础组件库
|
|
|
|
|
|
|
|
|
|
|
|
## 插件
|
|
|
|
|
|
|
|
|
|
|
|
- jsx
|
|
|
|
|
|
> javascript & react 语法，封装组件时编码更加灵活方便，功能开发时不推荐使用
|
|
|
|
|
|
- svg-icon
|
|
|
|
|
|
> 根据自定义 svg 文件生成 icon
|
|
|
|
|
|
- auto-import
|
|
|
|
|
|
> 编译时自动引入依赖
|
|
|
|
|
|
- components
|
|
|
|
|
|
> 编译时自动局部注册 ElementPlus 组件和 src/components 目录下的自定义组件
|
|
|
|
|
|
- style-import
|
|
|
|
|
|
> 编译时按需引用 ElementPlus 样式文件
|
|
|
|
|
|
- global-style
|
|
|
|
|
|
> 编译时自动注入全局样式和变量
|
|
|
|
|
|
- remove-console
|
|
|
|
|
|
> 打包时自动移除 console 语句
|
|
|
|
|
|
- legacy
|
|
|
|
|
|
> 浏览器兼容处理
|
|
|
|
|
|
- eslint
|
|
|
|
|
|
> 不影响 HMR 编译速度的情况下异步进行 eslint 代码校验
|
|
|
|
|
|
- husky
|
|
|
|
|
|
> git hooks 管理
|
|
|
|
|
|
- lint-staged
|
|
|
|
|
|
> git commit 时仅对提交部分代码进行 eslint 校验
|
|
|
|
|
|
- commitlint
|
|
|
|
|
|
> git commit 时对提交信息进行规范校验
|
|
|
|
|
|
|
|
|
|
|
|
## 规范约束
|
|
|
|
|
|
|
|
|
|
|
|
- 使用 VS Code 进行开发，并安装项目推荐的插件
|
|
|
|
|
|
- 不允许修改 src 目录以外的（项目配置）文件
|
|
|
|
|
|
- 有需要优化解决的问题记录到 TODO.md 文件中，包括技术方面的踩坑记录和业务方面的 BUG 记录
|
|
|
|
|
|
- 按照当前项目结构进行功能开发，不允许随意改变项目文件结构
|
|
|
|
|
|
|
|
|
|
|
|
## 项目结构
|
|
|
|
|
|
|
|
|
|
|
|
| SRC 目录 | 用途描述 |
|
|
|
|
|
|
| ---------- | ---------------------------- |
|
|
|
|
|
|
| api | API 接口定义 |
|
|
|
|
|
|
| assets | 资源文件，按功能模块分文件夹 |
|
|
|
|
|
|
| components | 自定义通用组件 |
|
|
|
|
|
|
| configs | 项目框架配置 |
|
|
|
|
|
|
| icons | 图标库，svg 图标文件 |
|
|
|
|
|
|
| layouts | 页面框架布局 |
|
|
|
|
|
|
| plugins | 全局插件模块 |
|
|
|
|
|
|
| router | 本地路由模块 |
|
|
|
|
|
|
| store | 数据状态模块 |
|
|
|
|
|
|
| styles | 全局样式模块 |
|
|
|
|
|
|
| utils | 工具类库模块 |
|
|
|
|
|
|
| views | SFC 模块，页面文件 |
|
|
|
|
|
|
|
|
|
|
|
|
## 开发须知
|
|
|
|
|
|
|
|
|
|
|
|
### 通用组件
|
|
|
|
|
|
|
|
|
|
|
|
- 文件规范命名，使用简单易懂的单词概括组件的功能
|
|
|
|
|
|
- 写好 Props 参数注释
|
|
|
|
|
|
- 具有良好的扩展性和通用性
|
|
|
|
|
|
- 优化、修复问题时考虑向下兼容，尽可能不影响已有代码
|
|
|
|
|
|
- 使用 setup script 语法糖和 jsx 语法
|
|
|
|
|
|
- 有数据绑定功能的必须支持 v-mdoel 语法
|
|
|
|
|
|
|
|
|
|
|
|
### 路由页面
|
|
|
|
|
|
|
|
|
|
|
|
- 严格遵循既定的项目模块结构
|
|
|
|
|
|
- 单个功能页面之间通用组件应单独在页面目录创建 components 文件夹，而不是全部都放进 src/components
|
|
|
|
|
|
- 必须使用 defineComponent 包裹组件定义，并定义好具有唯一性的 name
|
|
|
|
|
|
- 不允许使用 this，严禁滥用 getCurrentInstance()，proxy 对象只用于访问全局方法
|
|
|
|
|
|
- 规范使用 ref、reactive、toRefs、unref 等响应式 API，访问响应式数据时应使用 unref 包裹而不是访问 .value
|
|
|
|
|
|
- 各个功能点应区分代码块并写好注释，不允许延续 vue2 编码思想将各个功能点代码耦合在一起，特别复杂逻辑应代码分块并单独创建文件引入使用
|
|
|
|
|
|
- 不允许以任何形式直接修改 props 传入的值，包括对象中的属性和数组中的元素，如需双向绑定应使用触发事件 update:propsName 的方式
|
|
|
|
|
|
- 页面根元素应包含 \*-container 的 class，无特殊情况使用单根元素，多根元素会影响动画过渡效果
|
|
|
|
|
|
|
|
|
|
|
|
### 工具类库
|
|
|
|
|
|
|
|
|
|
|
|
- 项目已集成 lodash、dayjs，不要重复造轮子
|
|
|
|
|
|
- 全局方法应在 plugins/global-api.js 中注册，而不是写成工具类到处引用
|
|
|
|
|
|
- 注释中应有完善的功能说明、入参出参说明、注意事项等
|
|
|
|
|
|
- 新增工具类后应及时通知所有项目开发者知悉
|
|
|
|
|
|
- 优化修复工具类应向下兼容确保不会影响已有代码，改动较大应召集相关人员商讨解决方案
|
|
|
|
|
|
- 应进行完善的逻辑测试和性能测试，确保不会影响项目稳定性，谨慎使用 setTimeout、setInterval 等循环\递归操作
|
|
|
|
|
|
|
|
|
|
|
|
### 状态管理
|
|
|
|
|
|
|
|
|
|
|
|
- 每个功能模块都要对应一个数据状态管理模块
|
|
|
|
|
|
- 必须通过 mutations 修改 state 中的数据
|
|
|
|
|
|
- 字典数据应全部存放在 state 中统一管理
|
|
|
|
|
|
- 接口调用及后续数据逻辑处理应在 actions 中进行，保证多处调用时行为统一
|
|
|
|
|
|
|
|
|
|
|
|
### 样式相关
|
|
|
|
|
|
|
|
|
|
|
|
- 参考 src/styles/gobalVariables.module.less，颜色、字号、边距、圆角尽可能复用已有的变量
|
|
|
|
|
|
- 没有特殊需求不允许写全局样式，stlye 标签必须加 scoped
|
|
|
|
|
|
- 深度选择器使用 :deep(<selector>){} 语法，>>> 、/deep/、::v-deep 都已弃用
|
|
|
|
|
|
- 没有特殊需求不允许定义或使用 ID 选择器、属性选择器
|
|
|
|
|
|
|
|
|
|
|
|
### 分支管理
|
|
|
|
|
|
|
|
|
|
|
|
- 分支命名：父分支-功能描述-创建日期-创建人；例如：beta-userManagement-0323-xwk
|
|
|
|
|
|
- 紧急修复应基于 dev 分支创建，功能分支应基于 beta 分支创建
|
|
|
|
|
|
- 提测前先将 beta 分支合并到功能分支解决冲突，再将功能分支合并到 test 分支，严禁将 test 分支合并进其他任何分支
|
|
|
|
|
|
- 测试通过后先将 beta 分支合并到功能分支解决冲突，再通过提 push request 通知负责人进行代码审查，审查通过后由负责人合并代码
|
|
|
|
|
|
- 预发通过后先将 dev 分支合并到 beta 分支解决冲突，再将 beta 分支合并到 dev 分支，此操作只能由负责人进行
|
|
|
|
|
|
- 解决冲突时如涉及其他开发者代码，应跟当事人确认无误后再合并
|
|
|
|
|
|
|
|
|
|
|
|
### 提交代码
|
|
|
|
|
|
|
|
|
|
|
|
- 提交前确认项目能正常运行，改动部分功能正常
|
|
|
|
|
|
- 严格遵循 eslint、prettier 代码规范
|
|
|
|
|
|
- 严禁使用 git commit --no-verify -m "xxx" 强制提交代码
|
|
|
|
|
|
- 规范提交信息
|
|
|
|
|
|
|
|
|
|
|
|
| 前缀 | 使用场景 | 示例 |
|
|
|
|
|
|
| -------- | ------------------------------ | -------------------------- |
|
|
|
|
|
|
| feat | 新增功能点、模块 | feat: 用户管理 |
|
|
|
|
|
|
| fix | 修复 BUG | fix: 用户管理分页异常 |
|
|
|
|
|
|
| doc | 文档、注释更新 | doc: README |
|
|
|
|
|
|
| style | 样式、不影响逻辑的代码格式更新 | style: 用户管理标题字号 |
|
|
|
|
|
|
| refactor | 重构功能点、模块 | refactor: 路由模块逻辑重构 |
|
|
|
|
|
|
| test | 测试 | test: 测试工具类 |
|
|
|
|
|
|
| revert | 撤回提交 | revert: 有文件漏提交 |
|
|
|
|
|
|
| build | 编译打包 | build: 编译用户管理 |
|
|
|
|
|
|
| merge | 合并分支 | merge: beta into dev |
|
|
|
|
|
|
| perf | 性能、体验、逻辑优化 | pref: 路由模块解析性能 |
|
|
|
|
|
|
| conf | 配置更新 | conf: 项目 base 路径 |
|
|
|
|
|
|
| chore | 其他 | chore: 其他 |
|
