epdc-analysis-mp-yushan/README.md

# e锦水小程序开发文档

## 一、该小程序框架 所包含的功能以如下：

### 1、引入前端打包工具gulp，实现代码压缩等功能

### 2、通过gulp,使typescript 编译产生 javascript

### 3、通过gulp,引入css预处理器 sass 编译产生 css 可实现换肤功能

### 4、引入eslint, 用于统一团队代码规范

### 5、之后不再写 js 和 wxss，为了便于快速生成小程序页面和组件(.ts .scss .json .wxml)，新增脚本，新增命令行
```
npm run new:page
// 请输入要生成的页面路径，会生成在src/目录下
eg： pages/auto/auto  // 会在pages自动生成auto页面

npm run new:component
// 请输入要生成的组件路径，会生成在src/目录下
eg: components/loadMore/loadMore 会在通用组件下生成 上拉加载 组件

```

### 6、可以通过 cross-env 搭配 gulp-preprocess 实现多环境变量，不过暂时感觉意义不大

## 二、该小程序框架 代码规范如下：

### 1、小程序开发规范----ts/js代码规范

### （1）、页面级API顺序
```
  Page({
    data: {
      // 页面数据
    }
    onLoad () {
    // 页面实例创建完成
    },
    onShow () {
      // 页面出现在前台时执行
    },
    onReady () {
      // 页面首次渲染完毕时执行
    },
    onHide () {
      // 页面从前台变为后台时执行
    },
    onUnload () {
      // 页面销毁时执行
    },
    onPullDownRefresh () {
      // 触发下拉刷新时执行
    },
    onReachBottom () {
      // 页面触底时执行
    },
    onPageScroll () {
      // 页面滚动时执行
    },
    onShareAppMessage () {
      // 页面被用户分享时执行
    },
    onResize () {
      // 页面尺寸变化时执行
    },
    onTabItemTap (item) {
      // tab 点击时执行
    },
    // 最后写自定义方法, 每一个方法加注释 页面生命周期和内置方法不需要加注释，没用到的方法不需要写出来
    customMethod () {}
  })
```
### （2）、组件级API顺序
```
  Component({
    data: {
      // 组件数据
    },
    properties: {
      // props 数据
    },
    lifetimes: {
      created () {
        // 组件实例刚刚被创建
      }
      attached () {
        // 实例创建完成 并加入页面Dom树
      },
      ready () {
        // 组件在视图层布局完成
      },
      detached () {
        // 组件实例从页面DOM树移除
      }
    },
    pageLifetimes: {
      show () {
        // 组件所在页面进入前台
      },
      hide () {
        // 页面进入后台
      },
      reside () {
        // 页面尺寸变化
      }
    },
    methods: {
      // 组件内的方法 记得每一个方法加注释，组件生命周期和内置方法不需要加注释，没用到的内置方法不需要写
    }
  })
```
### （3）、有时某个字段有多个状态，传给后端的是状态对应的数字，可以使用枚举来区分，同时将注释填写完整。 其他同事阅读代码时，更容易理解。
```
  const selfStatus = 4
  /* eslint-disable no-unused-vars */
  enum Status {
    success = 1, // 成功
    fail = 2, // 失败
    error = 3, // 产生错误
    pending = 4 // 加载中
  }
  if (selfStatus === Status.success) {
    this.setData({
      status: Status.success
    })
  } else if (selfStatus === Status.fail) {
    this.setData({
      status: Status.fail
    })
  } else if (selfStatus === Status.error) {
    this.setData({
      status: Status.error
    })
  } else if (selfStatus === Status.pending) {
    this.setData({
      status: Status.pending
    })
  }
  console.log(this.data.status) // 4

```
### （4）、项目存在迭代升级，后端接口会随时更新，前端对于每个功能模块采用 命名空间的方式来适应后端迭代升级。
```
// 后端接口  加入命名空间定义
// 命名空间v1
export namespace indexV1 {
  /**
   * 未转项目议题列表（热议中，已关闭）接口
   * @param {string} deptId 部门Id
   * @param {Number} pageIndex 页码
   * @param {Number} pageSize 页容量
   * @param {string} stateType 状态类型：1.热议中，2.已关闭
   */
  export function getUnpassedList ({ deptId, pageIndex, pageSize, stateType }: { deptId: string, pageIndex: number, pageSize: number, stateType: string }) {
    return request({
      method: "GET",
      url: "cloudAnalysis/issue/getUnpassedList",
      options: {
        deptId,
        pageIndex,
        pageSize,
        stateType
      }
    })
  }
}

// 命名空间v2
export namespace indexV2 {
  /**
   * 未转项目议题列表（热议中，已关闭）接口
   * @param {string} deptId 部门Id
   * @param {Number} pageIndex 页码
   * @param {Number} pageSize 页容量
   * @param {string} stateType 状态类型：1.热议中，2.已关闭
   */
  export function getUnpassedList ({ deptId, pageIndex, pageSize, stateType }: { deptId: string, pageIndex: number, pageSize: number, stateType: string }) {
    return request({
      method: "GET",
      url: "cloudAnalysis/issue/getUnpassedList",
      options: {
        deptId,
        pageIndex,
        pageSize,
        stateType
      }
    })
  }
}

// 接口使用
import { indexV1, indexV2 } from "../../api/index"

async getIssueListV1 () {
  const para = {
    deptId: "",
    pageIndex: 1,
    pageSize: 10,
    stateType: "1"
  }
  try {
    let resV1 = await indexV1.getUnpassedList(para) // 使用v1版本的接口
    let resV2 = await indexV2.getUnpassedList(para) // 使用v2版本的接口
    console.log(resV1)
    console.log(resV2)
  } catch (e) {
    console.log(e)
  }
}
```

### （5）、所有后端接口 全部放入 api 文件夹下对应的模块文件内，便于统一管理，每个接口注释其作用，入参类型、含义。 

* 接口参数 <= 3, 接口函数形参逐一填写
* 接口参数 > 3 && <= 5 可以一个形参（对象）或者形参逐一写上
* 接口参数 > 5 必须 一个形参（对象）

```
 /**
   * 未转项目议题列表（热议中，已关闭）接口
   * @param {string} deptId 部门Id
   * @param {Number} pageIndex 页码
   * @param {Number} pageSize 页容量
   * @param {string} stateType 状态类型：1.热议中，2.已关闭
   */
  export function getUnpassedList ({ deptId, pageIndex, pageSize, stateType }: { deptId: string, pageIndex: number, pageSize: number, stateType: string }) {
    return request({
      method: "GET",
      url: "cloudAnalysis/issue/getUnpassedList",
      options: {
        deptId,
        pageIndex,
        pageSize,
        stateType
      }
    })
  }

  // 或者 
  export function getUnpassedList ( options: { deptId: string, pageIndex: number, pageSize: number, stateType: string }) {
    return request({
      method: "GET",
      url: "cloudAnalysis/issue/getUnpassedList",
      options
    })
  }
```
### （6）、页面跳转 不要使用相对路径，一律使用绝对路径，便于某个模块或某个页面复用
```
  wx.navigateTo({
    url: "/pages/index/index"
  })

  wx.navigateTo({
    url: "/subpages/reality/pages/realityIndex/realityIndex"
  })
  
```

### 2、小程序开发规范---- wxml代码规范

### （1）、当标签属性超过三个时，一律换行展示，不要一梭到底
```
<cover-view 
  catchtap="onChnageUnionCondition"
  data-condition="{{item.value}}"
  class="list-item"
  wx:for="{{categoryList}}"
  wx:for-index="index"
  wx:for-item="item" wx:key="index">
  <cover-view class="name">{{item.label}}</cover-view>
  <cover-view wx:if="{{selectUnionCondition.value === item.value}}" class="select">√</cover-view>
</cover-view>
```

### （2）、 除了动态属性，禁止在wxml里面写内联样式

### （3）、最外层的components放公共组件（公共组件可以全局配置为全局组件这样就不需要用到的时候在引入），业务模块组件在自己所在页面下建components存放
```
src
├─api
├─components ---- 公共组件/通用组件
├─filters
├─pages
├ ├─index
├ ├─components --- 模块组件/页面拆分组件
├ ├─index.json
├ ├─index.ts
├ ├─index.scss
├ └index.wxml
└subpages

```

### 3、小程序开发规范---- wxss/scss规范

### （1）、 class名严禁使用驼峰式命名，一律使用中划线连接 eg: load-more