# 介绍

本项目是作为公司的前端的模板项目。采用的是 Vue 的全家桶技术。

本文档介绍项目如何使用和扩展、采用的技术栈、目录结构和最佳实践等。你不用一次看完所有内容，但是建议在正式开发前完整读一遍文档。

## 安装、启动和打包

安装：

请安装最新的 node (目前的版本为 11.2.0)

```bash
# 安装yarn。未来所有的包都由yarn来安装。但是执行脚本可以由npm来做。
npm install yarn -g
```

```bash
# 如果没有全局安装Vue Cli 3.x
yarn global add @vue/cli
```

```bash
yarn
```

启动:

```bash
npm start
```

打包:

```bash
npm run build
```

## 技术栈

Vue 2.x
Vuex 3.x
Vue router 2.x

TODO: 架构图

## 构建工具

vue-cli

## 工具安装

### Chrome 插件

[Vue.js devtools](https://chrome.google.com/webstore/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)

## VS Code 插件

1.  Vetur (Author: Pine Wu)
1.  Prettier (Author: Esben Petersen) # 注意: 其他的 vscode 插件可能导致格式化不一致
1.  ESLint (Author: Dirk Baeumer)
1.  Vue 2 Snippets (Author: hollowtree)
1.  GitLens (Author: Eric Amodio) - optional
1.  REST Client (Author: Huachao Mao) - optional
1.  Quokka.js (Author: Wallaby.js) - optional

## 目录结构

| 目录                      | 说明                                                                                                                                                                                                                                                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| build/                    | 打包产出                                                                                                                                                                                                                                                                                                           |
| node_modules/             | 依赖包                                                                                                                                                                                                                                                                                                             |
| src/modules               | 模块化开发，分为基础信息、考务、网考管理、题库、印刷、报表等                                                                                                                                                                                                                                                       |
| src/modules/\*/assets/    | 图片、音频文件等文件. 在多数情况下，应该把资源文件放在 src/modules/\*/features/下，这种情况可以让应用垂直划分，同时可以更干净的删除资源。                                                                                                                                                                          |
| src/auth/                 | 认证信息是全局的                                                                                                                                                                                                                                                                                                   |
| src/components/           | 全局组件                                                                                                                                                                                                                                                                                                           |
| src/modules/\*/constants/ | 集中放置全局  常量，方便更新 API 的服务器地址等                                                                                                                                                                                                                                                                    |
| src/directives/           | 全局的 directive                                                                                                                                                                                                                                                                                                   |
| src/modules/\*/features/  | 实现业务需求的组件。目标是让尽可能多的相关文件在相同的业务组件内。这使得开发团队可以更好的划分任务。业务组件可以依赖全局元素，如 src/auth, src/components, src/directives，或者依赖其它业务组件。但是业务组件不应该依赖其它业务组件的子组件，它应该使用其它组件的 public API。必要时，子组件可能在业务组件中重复。 |
| src/http/                 | 包含非认证  的 HTTP 请求（ 认证的部分应该在 src/auth 中做）。同时包含 router 和 routes。如果 routes 变的很大，可以将它拆分到 src/features 中，然后通过 import 引用。                                                                                                                                               |
| src/modules/\*/store/     | 使用 Vuex 管理状态的单一 store                                                                                                                                                                                                                                                                                     |
| src/styles/               | 全局样式。 局部样式应该放在 src/modules/\*/features/中                                                                                                                                                                                                                                                             |
| src/utils/                | 共享的工具类。 跟业务有关的  工具方法放在 src/features/中                                                                                                                                                                                                                                                          |
| static/                   | 不需要 Webpack 处理的静态文件                                                                                                                                                                                                                                                                                      |
| tests/                    | 单元测试和 E2E 测试                                                                                                                                                                                                                                                                                                |

## 错误处理

### 通用的错误处理

#### API 请求

从用户操作，界面有一处集中显示操作反馈。  
处理顺序如下：

1.  用户操作
2.  触发 vue action
3.  调用 vuex action（无需处理错误）
4.  调用 api，若出错，修改全局错误状态，并通知展示状态
5.  界面展示程序状态，即出错信息

如果用户需要 vuex action 的结果，可以在 vuex action 里面返回 promise，不建议在 component 处理状态。
应该尽可能通过 store 的状态更新使得界面更新。

## 状态处理

无需共享状态的组件可以直接在组件的生命周期中发请求获取数据。一般是纯显示的组件比较多。

共享状态的通过 vuex 来处理。

## 图标处理

采用[vue-awesome](https://github.com/Justineo/vue-awesome)的库。  
在 src/plugins/vueAwesome.js 添加对应的图标。  
图标名称和形状可以在 [Font Awesome](https://fontawesome.com/icons?d=gallery) 查找。  
使用时采用

```html
<v-icon name="lock" scale="3" />
```

## TODO:

1. module state
2. 新项目以 ES2018 为基准，选择 stage 3 的特性，将常用的特性列表在 readme 中给出网址

### 参考资料

1.  [Vue-pizza](https://github.com/prograhammer/vue-pizza)
1.  [Error handling with async-await in Vue and Vuex](https://dimitrioslytras.com/vue-error-handling/)
