# docs

**Repository Path**: weldon_lee/docs

## Basic Information

- **Project Name**: docs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-02-01
- **Last Updated**: 2021-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 开发环境

## Node.js

> * 安装v10.x以上
>* 不要安装奇数版本

## 包管理

### npm

修改镜像源：

```bash
npm config set registry https://registry.npm.taobao.org
```

检查镜像源：

```bash
npm config get registry
```

### yarn

通过npm安装：

```bash
npm install --global yarn
```

修改镜像源：

```bash
yarn config set registry https://registry.npm.taobao.org --global
```

检查镜像源：

```bash
yarn config get registry
```

查看yarn的bin路径：

```bash
yarn global bin
```

最后，把yarn的bin路径 `%LOCALAPPDATA%\yarn\bin` 添加到PATH环境变量。

### 为什么使用yarn？

* 速度更快，可并行处理
* 没有包依赖问题

### npm与yarn常用命令对照表

| npm              | yarn                | 简述                 |
| ---------------- | ------------------- | -------------------- |
| npm i            | yarn                | 安装项目依赖包       |
| npm i -S xxx     | yarn add xxx        | 安装依赖包           |
| npm un -S xxx    | yarn remove xxx     | 删除依赖包           |
| npm i -D xxx     | yarn add xxx --dev  | 安装开发环境依赖包   |
| npm -S update    | yarn upgrade        | 升级依赖包           |
| npm ls --depth=0 | yarn list --depth=0 | 查看项目依赖的包列表 |

## VSCode插件

### ESLint

`ESLint` 主要作用于代码的静态分析，官方定义了一整套规则，可以前往 [http://eslint.cn/docs/rules/](http://eslint.cn/docs/rules/) 进行查看，每条规则都可以根据用户的习惯和团队的要求，决定开启或禁用，配置文件在项目根目录下的 `.eslintrc.js` 文件，如下：

```js
// add your custom rules here
rules: {
	'prefer-promise-reject-errors': 'off',
	'no-var': 1,

    // allow debugger during development only
    'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off'
}
```

规则有3个状态可以选择，分别是：

1. `off` 或 `0`，表示关闭此规则，不进行警告和错误提示
2. `warn` 或 `1`，表示对此规则进行警告提示
3. `error` 或 `2`，表示对此规则进行错误提示

### Prettier

`Prettier` 的主要作用是代码格式化，开启保存时格式化功能，配置如下：

1. 在 `setting.json` 文件中添加以下代码：

   ```json
   {
       // ...
       
       // 保存时格式化
       "editor.formatOnSave": true,
       // 使用prettier进行格式化
       "editor.defaultFormatter": "esbenp.prettier-vscode",
       // 保存时修复错误
       "editor.codeActionsOnSave": {
           "source.fixAll": true
       }
   }
   ```

2. 在项目根目录下新建 `.prettierrc` 文件：

   ```json
   {
     "singleQuote": true, // 字符串使用单引号
     "semi": false, // 语句分号结尾
     "useTabs": false, // 使用 tabs 缩进
     "tabWidth": 2 // 2个空格替代 \t
   }
   ```

### Vetur

主要功能如下：

* 语法高亮

* 智能提示

* 代码片断

* Emmet

* Linting / 错误检查

* 格式化

  > 如果项目不使用 `Typescript` ，请手动禁用 `Vetur › Validation: Interpolation` 
  >
  > 在 `VSCode` 点击 `文件 -> 首选项 -> 设置` 找到相应位置，然后把 `√` 去掉。

## 浏览器插件

如果无法直接下载浏览器插件，可从 [https://crxdl.com/](https://crxdl.com/) 下载crx包进行安装

### Vue devtools

* 实时编辑数据
* `time travel` 模式调试 `Vuex`

### Debugger for Chrome

* 在 `VSCode` 中调试前端代码的必装插件，如何配置请查看 [在VSCode中调试Vue项目](#在VSCode中调试Vue项目) 一节

## 调试环境

### 启动调试环境

```bash
yarn run dev
```

### 在VSCode中调试Vue项目

1. 在 vue.config.js` 文件中添加 `devtool` 参数，值为 `source-map`，如下：

```js
// vue.config.js

module.exports = {
  // ...
  chainWebpack(config) {
    config.when(process.env.NODE_ENV !== 'development', (config) => {
      // ...
      config.devtool('source-map')
  }
}
```

2. 在 `.vscode` 文件夹中新建名为 `launch.json` 的文件，文件内容如下：

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "SQ App: chrome",
      "url": "http://localhost:8080",
      "webRoot": "${workspaceFolder}/src",
      "breakOnLoad": true,
      "sourceMapPathOverrides": {
        "webpack:///./src/*": "${webRoot}/*"
      }
    }
  ]
}
```

# SQ脚手架项目

## 目录结构

> ├─dist
> ├─mock
> │  ├─controller
> │  └─utils
> ├─public
> └─src
>     ├─api
>     ├─assets
>     ├─components
>     ├─config
>     ├─directive
>     ├─layouts
>     │  └─components
>     ├─plugins
>     ├─router
>     ├─store
>     │  └─modules
>     ├─styles
>     ├─utils
>     └─views

* /dist	构建生成的项目文件
* /mock	mock相关文件
* /public	静态文件，无需webpack加工的静态文件存放位置
* /src	源文件
* /src/api	后端api的封装代码
* /src/assets	包括js、样式、图片等需要被webpack加工的资源文件
* /src/components	全局通用组件
* /src/config	配置文件
* /src/directive	自定义指令
* /src/layouts	布局模板页
* /src/plugins	插件引入文件
* /src/router	路由定义文件
* /src/store	vuex全局状态定义文件
* /src/styles	样式文件
* /src/utils	工具类文件
* /src/views	页面文件

## 环境变量

项目已经预设有3种环境的变量文件，分别是 `development(开发环境)`、`production(生产环境)`、`staging(预发布环境)`，如果有其他环境也可以自行添加，变量文件存放于项目的根目录，变量文件的文件名格式为：`.env.环境名称`，例如预发布环境的变量文件名是 `.env.staging`，然后在`package.json`文件中添加一行命令，如下：

```json
// package.json
{
    // ...
    "scripts": {
        // ...
		"build:stage": "vue-cli-service build --mode staging",        
    }
}
```

构建命令如下：

```bash
yarn run build:stage
```

环境变量文件中，除了特殊的`NODE_ENV`变量外，自定义的变量必须以`VUE_APP_`为前缀，如下：

```yaml
NODE_ENV = 'development'

# base api
VUE_APP_BASE_API = '/dev-api'
```

然后在代码中直接引用：

```js
console.log(process.env.BASE_API)
```

## 路由定义

项目已预设两组路由，分别是`constantRoutes`和`asyncRoutes`，其中`constantRoutes`所定义的为全局路由，一般不需要改动。新增的页面路由配置一般存放于`asyncRoutes`。

### 基本配置

```js
// src\router\index.js
export const asyncRoutes = [
  {
    path: `/desktop`,
    name: 'desktop',
    component: Desktop,
    hidden: true,
  },
  // ...
]
```

* path	路由路径
* name	路由命名
* component	路由组件
* hidden	是否在菜单中隐藏

### 延迟加载

> 使用`import`加载的页面，会在初次打开时有所延迟，初始页面不要使用此方式

```js
// src\router\index.js
export const asyncRoutes = [
  {
    path: `/desktop`,
    name: 'desktop',
    component: import('@/views/desktop/index'),
    hidden: true,
  },
  // ...
]
```

### 嵌套路由

```json
// src\router\index.js
export const asyncRoutes = [
  {
    path: '/',
    component: Layout,
    redirect: 'index',
    children: [
      {
        path: 'index',
        name: 'Index',
        component: () => import('@/views/index/index'),
        meta: {
          title: '首页',
          icon: 'home',
          affix: true,
          permissions: ['admin'],
        },
      },
    ],
  },
  // ...
]
```

* redirect	重定向
* meta	元数据
* meta/title	在导航栏中显示的标题
* meta/icon	在导航栏中显示的图标
* meta/affix	是否固钉显示
* meta/permissions	权限列表，与用户权限列表有交集的才会在页面中显示

### 全局路由事件

```js
// src\router\index.js

// 全局前置路由事件
router.beforeEach((to, from, next) => {
  console.log(`全局路由beforeEach事件: ${to.fullPath}`)
  next()
})

// 全局后置路由事件
router.afterEach((to, from) => {
  console.log(`全局路由afterEach事件: ${from.fullPath}`)
})
```

## 多应用

如果有多个应用想放到同一个项目进行管理，可以在项目中进行配置。首先是在`layout`页面的`appList`添加新的应用，如下：

```vue
// src\layouts\components\Logo\index.vue

<script>
// ...
export default {
  name: 'Logo',
  data() {
    return {
		appList: [
            // ...
            {
              name: '新应用',
              icon: 'new',
              color: 'red',
              path: '/index',
              appid: '1',
            },
          ],
    }
  }
}
```

然后增加新应用的路由配置：

```javascript
// src\router\index.js

// ...
export const newRoutes = [
	// ...
]
// ...
```

最后配置关联关系：

```javascript
// src\store\modules\routes.js

// ...
const actions = {
  async setRoutes({ commit }, permissions) {
    var tempRouter = []
    switch (localStorage.getItem('appSelect')) {
      // ...
      // 新应用的路由配置
      case '1':
        tempRouter = newRoutes
        break
      // 默认的路由配置
      default:
        tempRouter = asyncRoutes
        break
    }
  }
}
```

## 全局状态（Vuex）

当数据在页面中被多个组件引用时，考虑使用`全局状态（Vuex）`进行存放，`vuex`中主要定义了5种属性，分别是：Modules、State、Getter、Mutation、Action。

* Modules	Modules是分组、每个Modules都包含State、Getter、Mutation、Action
* State	定义数据的地方
* Getter	获取数据的方法
* Mutation	提交变更数据的**同步**方法
* Action	提交变量数据的**异步**方法

### 添加模块

`vuex`模块存放于`src\store\modules`路径下，模板如下 ：

```js
// ./src/store/modules/demo.js`

const state = () => ({
  num： 0,
})

const getters = {
  counting_Getter: (state) => state.num,
}

const mutations = {
  counting_Mutation(state) {
    state.num += 1
  },
}

const actions = {
  counting_Action(context) {
    context.commit('Counting_Mutation')
  },
}

export default { state, getters, mutations, actions }
```

### 在vue组件中调用Mutation

```js
this.$store.commit('demo/counting_Mutation')
```

### 在vue组件中调用Actions

```js
this.$store.dispath('demo/counting_Action')
```

### 在vue组件中直接取值

```js
$store.state.example.num
```

### 在vue组件中通过Getter取值

```js
this.$store.getters['demo/counting_Getter']
```

## Mock

项目已经帮我们集成了mock功能，使用`mockjs`实现。当新增资源时可以创建相应的mock对象，存放路径是`mock\controller\`目录下，mock代码模板如下：

```javascript
// mock\controller\demo.js
const { mock } = require('mockjs')

// 初始化数据
const list = []
const count = 3
for (let i = 0; i < count; i++) {
  list.push(
    mock({
      'id|10000000000-100000000000': 1,
      name: '@ctitle(1, 10)',
      created_at: '@now',
      'order_index|1': '@increment(1)',
    })
  )
}

module.exports = [
  {
    url: '/demo/get',
    type: 'post',
    response(config) {
      // 这里可以对list做过滤处理
      let list_filtered = list.filter(/* 过滤函数 */)
      return {
        total: list.length,
        data: pageList,
      }
    },
  },
  // ...
]
```

mockjs详细的使用方法请查阅[官方文档](https://github.com/nuysoft/Mock/wiki)

## 通用列表组件

在后端接口都遵循项目规范的前提下，很多操作在不同实体上都基本一致，比如简单的增删改查。于是在基础框架下又进一步封装了通用列表组件，可以通过配置方式实现的功能包括：列表页表格，列表字段的排序，列表页上的条件查询，实体的单个与批量删除操作，实体的编辑保存功能，等。以下就是目前已定义的配置项：

| 属性            | 值       | 说明                                                         |
| --------------- | -------- | ------------------------------------------------------------ |
| key             | string   | 必填值。一般是属性在实体中的对应名称                         |
| name            | string   | 中文名。一般用于表单`label`，或表头显示                      |
| required        | bool     | 是否必填。如果设为true，提交保存时该属性必须非空             |
| type            | enum     | 必填值。可选项包括：`text`、`dict`、`bool`、`datetime`、`file`、`list-item`、`cascader`、`rich`、`textarea`... |
| can_search      | boot     | 如果设为`true`，则该属性可以在列表页的查询条件进行过滤       |
| cant_show       | boot     | 如果设为`true`，则不在列表页中显示                           |
| cant_edit       | boot     | 如果设为`true`，则不显示在编辑页面中                         |
| file_key        | string   | 指定同步`file`类型的字段                                     |
| file_prop       | string   | 如果有`file`类型的字段，则会同步`file`类型字段的文件信息     |
| resouce         | string   | 当获取资源接口的地址与`key`不同时，需要设置                  |
| is_remote       | string   | 只对`dict`、`list-item`、`cascader`类型的字段有效，设为`true`意味着列表项会远程的接口中获取，而非静态 |
| is_readonly     | string   | 如果设为`true`，则在编辑页面中显示，但不可修改               |
| default         | object   | 默认值                                                       |
| prop_name       | string   | 属性名。标准的资源实体一般会有`id`、`name`属性，但有些特殊的资源可能命名上无法按照约定，这设置项就是修改其取值属性的属性名称 |
| dict            | array    | 只对`dict`类型有效，该属性配置静态字典列表                   |
| query_obj       | object   | 如果当前属性是远程资源，则调用远程资源时会附带上`query_obj`的内容参数 |
| theme           | string   | 只对`rich`有效，可选：`bubble`、`snow`（`quill`默认支持的两种主题） |
| can_sort        | bool     | 如果设为`true`，则该属性可以在列表头中进行：升序，降序，和默认的排序切换 |
| width           | number   | 固定列宽度                                                   |
| is_multiple     | bool     | 只对`file`类型有效，是否支持多文件上传                       |
| cant_edit_isnew | bool     | 是否在新增资源时，该属性不可编辑                             |
| fixed           | string   | 可选项：`null`，`left`, `right`                              |
| file_load       | function | 文件列表加载接口                                             |
| file_remove     | function | 文件删除接口                                                 |
| file_upload     | function | 文件上传接口                                                 |

例子

```vue
<template>
  <div>
    <list ref="list" :fields="fields" :name="name" :title="title" width="800px" :query-obj="queryObj">
      <template #default="{ row }">
        <el-button type="text" @click="showContent(row)">查看</el-button>
        <el-button v-if="row.status === 0" type="text" @click="Approval(row)">审批</el-button>
        <el-button type="text" @click="$router.push({ path: './attachment/' + row.id })">附件</el-button>
      </template>
    </list>
    <edit ref="edit" :fields="approval_fields" :name="name" title="审批" @fetch-data="fetchData"></edit>
  </div>
</template>

<script>
import { getList, doDelete, doEdit } from '@/api/common'
import List from '@/components/list'
import Edit from '@/components/edit'
export default {
  name: 'Article',
  components: {
    List,
    Edit,
  },
  data() {
    let kindKey = this.$route.fullPath.replace('/article/', '')
    let isBriefing = kindKey === 'briefing'
    let kind = { special: '1', notice: '2', briefing: '3', info: '4' }[kindKey]
    return {
      name: 'article',
      title: '文章',
      queryObj: { classify_kind: kind },
      fields: [
        {
          key: 'title',
          name: '标题',
          type: 'text',
          required: true,
          fixed: 'left',
        },
        {
          key: 'classify',
          name: '栏目',
          type: 'cascader',
          resouce: 'classify',
          can_search: true,
          is_remote: true,
          required: true,
          query_obj: { kind },
        },
        {
          key: 'sub_title',
          name: '副标题',
          type: 'text',
          cant_show: isBriefing,
          cant_edit: isBriefing,
        },
        {
          key: 'file',
          name: '标题图片',
          type: 'file',
          cant_show: true,
          cant_show: isBriefing,
          cant_edit: isBriefing,
        },
        {
          key: 'title_picture',
          name: '标题图片地址',
          type: 'text',
          cant_show: true,
          is_readonly: true,
          file_key: 'file',
          file_prop: 'url',
          cant_show: isBriefing,
          cant_edit: isBriefing,
        },
        {
          key: 'keywords',
          name: '关键字',
          type: 'text',
          cant_show: isBriefing,
          cant_edit: isBriefing,
        },
        {
          key: 'source',
          name: '来源',
          type: 'text',
        },
        {
          key: 'author',
          name: '作者',
          type: 'text',
          cant_show: ['special'].includes(kindKey),
          cant_edit: ['special'].includes(kindKey),
        },
        {
          key: 'kind',
          name: '信息类型',
          type: 'dict',
          dict: [
            { key: '1', label: '文字信息' },
            { key: '2', label: '图片信息' },
            { key: '3', label: '视频信息' },
            { key: '4', label: '文件下载' },
          ],
          can_search: true,
          required: true,
          is_readonly: isBriefing,
          default: isBriefing ? '1' : null,
        },
        {
          key: 'attachment',
          name: '附件(需要先保存文章)',
          type: 'file',
          is_multiple: true,
          cant_show: true,
          cant_edit_isnew: true,
          file_load: async (_, row) => {
            return (await getList('article_attachment', { pageNo: 1, article_id: row.id })).data.map((x) => {
              return { uid: x.id, url: x.file_url, name: x.file_name }
            })
          },
          file_remove: async (id) => {
            await doDelete('article_attachment', { id })
          },
          file_upload: async (res, file, form) => {
            return doEdit('article_attachment', {
              article_id: form.id,
              file_name: file.name,
              file_url: res.data.url,
              file_size: file.size,
              file_type: file.raw.type,
              file_desc: res.data.name,
              status: 0,
            })
          },
        },
        {
          key: 'status',
          name: '状态',
          type: 'dict',
          dict: [
            { key: 0, label: '未审批' },
            { key: 1, label: '审批通过' },
            { key: 2, label: '审批不通过' },
          ],
          can_search: true,
          cant_edit: true,
          width: 100,
        },
        {
          key: 'check_user_name',
          name: '审批人',
          type: 'text',
          cant_edit: true,
        },
        {
          key: 'check_time',
          name: '审批时间',
          type: 'text',
          cant_edit: true,
          width: 150,
        },
        {
          key: 'check_opinion',
          name: '审批意见',
          type: 'text',
          cant_edit: true,
        },
        {
          key: 'is_internal',
          name: '是否内部',
          type: 'bool',
          cant_show: !isBriefing,
          cant_edit: !isBriefing,
        },
        {
          key: 'is_top',
          name: '是否置顶',
          type: 'bool',
          cant_show: isBriefing,
          cant_edit: isBriefing,
        },
        {
          key: 'is_recommend',
          name: '是否推荐',
          type: 'bool',
          cant_show: isBriefing,
          cant_edit: isBriefing,
        },
        {
          key: 'is_new',
          name: '是否新的',
          type: 'bool',
          cant_show: !['notice', 'info'].includes(kindKey),
          cant_edit: !['notice', 'info'].includes(kindKey),
        },
        {
          key: 'read_count',
          name: '阅读次数',
          type: 'text',
          required: true,
          cant_edit: true,
        },
        {
          key: 'publish_time',
          name: '发布时间',
          type: 'datetime',
          can_search: true,
          can_sort: true,
          is_readonly: true,
          width: 150,
        },
        {
          key: 'content',
          name: '内容',
          type: 'rich',
          required: true,
          cant_show: true,
          theme: isBriefing ? 'bubble' : 'snow',
        },
      ],
      approval_fields: [
        {
          key: 'status',
          name: '审批结果',
          type: 'dict',
          dict: [
            { key: '1', label: '审批通过' },
            { key: '2', label: '审批不通过' },
          ],
          required: true,
        },
        {
          key: 'check_opinion',
          name: '审批意见',
          type: 'textarea',
          required: true,
        },
      ],
    }
  },
  methods: {
    fetchData() {
      this.$refs['list'].fetchData()
    },
    Approval(row) {
      let newrow = Object.assign({}, row)
      newrow.status = ''
      this.$refs['edit'].showEdit(newrow).title = '审批'
    },
    showContent(row) {
      this.$router.push({ path: './details/' + row.id })
    },
  },
}
</script>

<style lang="scss">
.msgbox {
  width: 80%;
}
.msgbox .el-message-box__title {
  text-align: center;
}
</style>

```

显示效果如下：

![文件列表](https://gitee.com/bingo-st/docs/raw/master/static/images/articlel_list.png)

# 部署

## 构建生产版本

```bash
yarn run build
```

## 构建预发布版本

```bash
yarn run build:stage
```