# 马士兵管理平台模板

## 技术架构

-   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 语句
-   vuex-persistedstate
    > vuex 数据持久化
-   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: 其他                |

## 全局方法

> 使用示例

```javascript
import { copy } from '@/plugins/global-api.js';
copy('hello world');
```

```javascript
const { proxy } = getCurrentInstance();
proxy.$copy('hello world');
```

| 名称     | 功能介绍              |
| -------- | --------------------- |
| copy     | 复制文本              |
| download | 下载指定地址文件      |
| excel    | 导出 excel 文件并下载 |
| dict     | 字典查询              |
| name     | 昵称和姓名拼接显示    |

## 全局组件

| 名称          | 功能介绍     |
| ------------- | ------------ |
| ElEditor      | 富文本编辑器 |
| ElUploadImage | 图片上传     |
| TableList     | 通用列表组件 |

## 心得总结

### prettier

> 统一代码格式

安装依赖

```
npm install --save-dev prettier
```

安装 VS Code 插件 prettier

> 新建工作区设置文件 .vscode/settings.json  
> 设置保存代码时自动格式化  
> 自动解决 eslint 代码格式问题  
> 设置个文件类型默认格式化工具

```
{
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.fixAll": true,
        "source.organizeImports": true
    },
    "[vue]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[json]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[javascript]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[jsx]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[jsonc]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "[html]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    },
    "vetur.format.defaultFormatter.html": "prettier",
}
```

### commitlint

> 提供 commit message 校验功能

安装依赖

```
npm install --save-dev @commitlint/config-conventional @commitlint/cli
```

编写配置

> 在项目根目录下创建 commitlint.config.js 或者 .commitlintrc.js  
> 并在其中定义好可以使用前缀，如果格式不符将报错并导致提交失败

```
module.exports = {
    extends: ['@commitlint/config-conventional'],
    rules: {
        'type-enum': [
            2,
            'always',
            ['feat', 'fix', 'doc', 'style', 'refactor', 'test', 'revert', 'build', 'merge', 'perf', 'conf', 'chore'],
        ],
        'type-case': [0],
        'type-empty': [0],
        'scope-empty': [0],
        'scope-case': [0],
        'subject-full-stop': [0, 'never'],
        'subject-case': [0, 'never'],
        'header-max-length': [0, 'always', 72],
    },
};

```

提交代码

```
git commit -m "feat: xxx"
```

> 注意要使用英文冒号，冒号后面跟空格

### HUSKY

> 可以对 git hooks 进行管理

安装依赖

```
npm install -D husky
```

在 package.json 中添加脚本

```
{
    //...
    "scripts": {
        //...
        "prepare": "husky install"
    }
    //...
}
```

> prepare 脚本会在 npm install（不带参数）之后自动执行。也就是说当我们执行 npm install 安装完项目依赖后会执行 husky install 命令，该命令会创建.husky/目录并指定该目录为 git hooks 所在的目录。

添加 git hooks

```
npx husky add .husky/pre-commit "npx lint-staged"
```

> 运行完该命令后我们会看到 .husky/ 目录下新增了一个名为 pre-commit 的 shell 脚本。  
> 也就是说在在执行 git commit 命令时会先执行 pre-commit 这个脚本。  
> 这个脚本的功能是运行 lint-staged 检查待提交的代码规范约束。  
> 不能直接写 lint-staged，会报错找不到命令，npm run lint-staged 也可以不过需要在 package.json 中添加 lint-staged 这个命令，所以使用 npx lint-staged。

```
npx husky add .husky/commit-msg 'npx commitlint --edit "$1"'
```

> 运行完该命令后我们会看到 .husky/ 目录下新增了一个名为 commit-msg 的 shell 脚本。  
> 也就是说在在执行 git commit 命令时会执行 commit-msg 这个脚本。  
> 这个脚本的功能是运行 commitlint 检查 git commit 的 message 格式规范。  
> 同 lint-staged 需要使用 npx 来运行命令，$1 代表开发者提交代码时输入的 commit message，老版本husky中使用$HUSKY_GIT_PARAMS 来表示，已弃用