# director-allocation

**Repository Path**: pcx2311/director-allocation

## Basic Information

- **Project Name**: director-allocation
- **Description**: 导调预研
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-06-28
- **Last Updated**: 2024-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 导调
## 技术栈
- 🥝 [Vue3](https://cn.vuejs.org)
- 🍓 [Typescript](https://www.typescriptlang.org/zh/play#code/)
- 🍋 [Vite](https://vitejs.cn/)
- 🍍 [Pinia](https://pinia.web3doc.top/)
- 🍉 [Vue-router](https://router.vuejs.org/)
- 🍊 [Less](https://less.bootcss.com/)
- 🍒 [Unocss](https://unocss.dev/)
- 🍑 [Axios](https://github.com/axios/axios)
- 🍌 [Naive-ui](https://www.naiveui.com/zh-CN/os-theme)
- 🍇 [Element-plus](https://doc-archive.element-plus.org/#/zh-CN/)
- 🥑 [Mitt](https://github.com/developit/mitt)
- 🥭 [VueUse](https://vueuse.org/guide/)
- 🍏 [Echarts(选用)](https://echarts.apache.org/zh/index.html)
- 🍈 [Antv(选用)](https://antv.antgroup.com/)
- 🥥 [Lodash(选用)](https://www.lodashjs.com/)

## 目录
 1) [总体介绍](#1总体介绍)
 2) [开发规范](#2开发规范)
 3) [开发流程](#3开发流程)
 4) [提交规范](#4git提交规范)

### 1、总体介绍
 - 基于Vue3+Vite+Typescript基础搭建，及代码检查美化，辅助开发工具;
 - 运行要求：node版本>=18,npm>=9;
 - 基础使用：[Vue3](https://cn.vuejs.org); [Typescript](https://www.typescriptlang.org/zh/play#code/); [Vite](https://vitejs.cn/); [Pinia](https://pinia.web3doc.top/); [Vue-router](https://router.vuejs.org/); [Axios](https://github.com/axios/axios); [Less](https://less.bootcss.com/);
 - 组件选用：
   - UI组件类：[Naive-ui(默认)](https://www.naiveui.com/zh-CN/os-theme), [Element-plus(默认)](https://doc-archive.element-plus.org/#/zh-CN/);
   - CSS类：[Unocss(默认)](https://unocss.dev/), [Postcss](https://www.postcss.com.cn/);
   - 事件处理：[Mitt(默认)](https://github.com/developit/mitt);
   - 图表类：[Echarts](https://echarts.apache.org/zh/index.html), [Antv](https://antv.antgroup.com/);
   - 工具类：[VueUse(默认)](https://www.vueusejs.com/), [Day.js](https://day.nodejs.cn/);
   - 数据处理：[Lodash](https://www.lodashjs.com/);
   - Icon字体类：[UI组件自带Icon](), [阿里图标(iconfont)](https://www.iconfont.cn/), [Icon](https://icones.netlify.app/collection/carbon);
   - 动画效果： [Animate.css](https://animate.style/), [Dynamicsjs](http://dynamics.js.com/);
 - 工具使用：[Volar](), [Eslint](), [Prettier](), [unplugin-auto-import](), [unplugin-vue-components]();
 - 选用原则：可控性, 稳定性, 适用性, 易用性, 通用不小众需要有良好的社区维护；CSS，图表，地图等组件不重复引用类似组件；

### 2、开发规范
  遵循 [阿里前端开发规范](https://github.com/airbnb/javascript),  [JavaScript Standard 代码规范](https://standardjs.com/rules-zhcn);
#### 2.1、目录及文件命名
 1) 项目命名 : 全部采用小写方式，以中划线分隔。
    ```html
    例：`mall-management-system`
    ```
 2) 目录命名 : 全部采用小写方式，以中划线分隔，有复数结构时，要采用复数命名法， 缩写不用复数，使用 kebab-case 命名。
    ```html
    例：`head-search / page-loading / authorized`
    ```
 3) JS、CSS、HTML、图片文件等命名 : 全部采用小写方式， 以中划线分隔; 
    ```html
    例：`render-dom.js /index.html / company-logo.png`
    ```
 4) CSS内容命名 ：class类名使用小写字母，以中划线分隔，id 采用驼峰式命名;
 5) VUE命名：  组件文件名为 PascalCase 格式;
    ```html
    例：`/components/MyComponent.vue`
    ```

#### 2.2、代码内容
  - 方法名、参数名、成员变量、局部变量都统一遵从驼峰形式，不能以下划线或美元符号结束; 
  - 常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚；例：`MAX_STOCK_COUNT`;
  - if 语句, 即使只有单行, 也要用花括号括起来, 例如:`if(){return;}`。
  - 避免使用不必要的三元语句，等等。
    ```ts
    // bad
    const foo = a ? a : b;
    const bar = c ? true : false;
    const baz = c ? false : true;
    const quux = a != null ? a : b;
    // good
    const foo = a || b;
    const bar = !!c;
    const baz = !c;
    const quux = a ?? b;
    ```
   
  具体可见[阿里前端开发规范](https://developer.aliyun.com/article/851617?spm=5176.26934562.main.6.5c9f57f4UrTvbi),  [JavaScript Standard 代码规范](https://standardjs.com/rules-zhcn)。

### 3、开发流程
#### 3.1、运行要求
```sh
node.js版本 >=18, npm 版本 >=9
```
#### 3.2、运行启动
下载 VsCode 插件：
```json
{
  "recommendations": [
    "Vue.volar",
    "Vue.vscode-typescript-vue-plugin",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode"
  ]
}
```
进入目录依次执行：
 - 依赖下载
```sh
npm install
```
 - 测试环境运行 或者 正式环境运行
```sh
npm run dev  或者  npm run prod 
```

#### 3.3、开发说明
##### 3.3.1、目录文件说明
```
.vscode                          vscode设置，插件等配置
public                           公用目录
|-- config                           配置信息，包括服务配置等
src                              源码目录
|-- assets                           静态资源，images, icons, fonts等
|-- components                       公用组件
|-- constants                        常量信息，项目所有Enum, 全局常量等
|-- plugins                          插件，全局使用
|-- router                           路由，统一管理
|-- server                           所有服务api接口
|-- directives                       自定义指令
|-- setup                            组件，工具等初始化
|-- store                            Pinia, 统一管理
|-- styles                           统一样式
|-- utils                            工具类
|-- views                            视图目录
|   |-- role                             role模块名
|   |-- |-- role-list.vue                    role列表页面
|   |-- |-- role-add.vue                     role新建页面
|   |-- |-- role-update.vue                  role更新页面
|   |-- |-- index.less                       role模块样式
|   |-- |-- components                       role模块通用组件文件夹
|   |-- other                            other模块名
.env                             基础配置文件
.env.development                 开发环境配置文件
.env.production                  正式环境配置文件
.eslintrc.cjs                    eslint配置文件
.prettierrc.json                 prettier配置文件
auto-imports.d.ts                unplugin-auto-import 生成的文件
components.d.ts                  unplugin-vue-components 生成的文件
uno.config.ts                    unoCss原子化css配置文件
tsconfig.json                    typeScript配置文件
```

##### 3.3.2、开发要求
 - ###### 组件开发
 1) 组件选择 [优先使用](#1总体介绍) 通用的 [推荐组件](#1总体介绍)，
    - 图表类：[Echart](), [Antv]();
    - 数据处理：[Lodash]();
    - 事件处理：[Mitt]();
    - 工具类：[VueUse](https://www.vueusejs.com/); [Day.js](https://day.nodejs.cn/);
    - Icon图标类：[UI组件自带Icon](), [阿里图标](), [Icon](); 
    - 动画效果： [Animate.css](https://animate.style/), [Dynamics.js](http://dynamicsjs.com/);

 2) 组件须使用 [Vue3.2+, setup 语法糖](https://cn.vuejs.org/guide/introduction.html#api-styles)，简洁高效；
 3) 使用 [unplugin-vue-components]() 和 [unplugin-vue-components]() 不需要手动注册引用`vue组件，常见引用`和`Api接口`;
 4) 单文件组件应该让标签顺序保持为 `<template> 、<script>、 <style>`或者 `<script>、 <template> 、<style>`;
 - ###### JS，CSS开发
  1) ts,css 导入导出遵循 ES Module, CSS Module 规范;
      ```ts
      // CSS Module
      import styles from "./index.module.less";
      ```
      ```ts
      // ES Module  // 导出
      // ./utils/index.ts
      export * from './string.ts'
      // ./utils/string.ts
      export function fn(){
          return 'pp'
      }
      // 导入
      import { fn } from '~/utils'
      fn()
      ```
  2) 原则上使用原子化CSS

      ```Less
      // @apply 原子化css 详见 Unocss (https://unocss.dev/) 文档
      .app {
          @apply w-full h-1/2 text-14px;
          &:hover{
            @apply bg-[#ccc]
            transform:scale(1.5)
          }
      }
      ```
  3) ts 中尽量不使用any，使用class等具体数据对象
  4) 当`<script>`等较大时，应当独立出 ts 文件；

      ```html
      index
      | -- index.vue
      | -- index.module.ts
      | -- index.less
      ```

 - ###### 开发风格
 1) router目录尽量按照views中的结构保持一致;
 2) Pinia 按照业务进行拆分不同的 ts 文件;
 3) views目录，模块命名要与后端、router、api 等保持一致;
 4) /server/api/文件要以api为结尾，例：`employee-api.js`、`login-api.js`;
 5) Vue3中 ref 命名，必须以Ref结尾，例：`ref='componentRef'`;
 6) 总之应遵循 [Vue3 风格指南](https://cn.vuejs.org/style-guide/) 开发要求;

##### 3.3.3、注释说明
整理必须加注释的地方
 1) 公共组件使用 必须 加注释说明;
 2) api 目录的接口文件 必须 加注释说明;
 3) store 中的 state, action 等 必须 加注释;
 4) vue 文件的 utils, 工具类方法 必须 加注释说明用途;
 5) vue 文件的 template 须加注释;
 6) vue 文件的 js方法与函数须添加注释，若文件较大添加 start-end 注释;
 7) vue 文件的 data 变量, 非常见单词要加注释;


#### 3.4、打包说明
目前默认分 [线上]()和[开发]() 环境，可扩展配置多个环境，具体可修改 `vue-prototype.ts;package.json`文件，同时增加.env.xxxx，server-xxxx.js 文件配置。
- 开发环境: 配置文件`.env.development`， 服务配置`service-dev.js` 
- 线上环境: 配置文件`.env.production`， 服务配置`service-prod.js`

打包开发环境：
```sh
npm run build:dev
```
打包正式环境：
```sh
npm run build  或者  npm run build:prod
```
- 打包完成 [默认去除]() debugger，console.log;（修改位置：`./vite.config.js`）
- 打包完成 zip包生成目录：`./archive/dist-dev-2024111085503.zip` (包名修改：`.env.xxxx`文件中)

### 4、Git提交规范
#### Git 项目开发
- 多人协作开发需要建个人分支，勿同时同一分支开发
- .idea，node_modules，archive，logs等非代码文件，切勿提交
- 项目阶段结束，需要详细记录说明md，包括项目说明，版本说明

#### Git commit
- Chore : 对构建过程或辅助工具和库（如文档）的更改，代码无变动 
- Feat : 新功能
- Fix : bug修复
- Style : 不影响代码含义的更改（空白、格式设置、缺失 分号等）
- Docs : 文档修改，注释更改
- Refactor : 代码重构
- Test : 测试添加、测试重构等，代码无变动
- Revert : 恢复先前的提交