## 简介

基于 Vite + Ts + Vue3 架构，使用 ibiz 平台模型生成代码

## 目录结构

```
|─ ─ app
    |─ ─ public                                     public文件夹
        |─ ─ assets                                 静态资源文件夹
        |─ ─ vite.svg                               图标
    |─ ─ src                                        工程文件夹
        |— — api                                    数据服务相关文件
            |— — xxx                                应用实体
                |— — data-service                   数据服务
                    |— — xxx-service-base.ts        数据服务对象基类
                    |— — xxx-service.ts             数据服务对象
                |— — dto-help                       应用实体DTO辅助类
                    |— — xxx-helpes.ts              应用实体DTO服务类集合
                |— — interface                      应用实体接口
                |— — xxx-base.ts                    应用实体对象基类
                |— — xxx-keys.ts                    应用实体属性集合
                |— — xxx.ts                         应用实体对象
        |— — app
            |— — app.ts                             当前应用对象
        |— — components                             组件，主要包含基础组件、功能组件、布局组件、部件组件
            |— — common                             基础组件
            |— — function                           功能组件，包括缺省页面、数据导入、登陆等组件
            |— — layout                             布局组件，包括首页视图布局，视图布局组件
            |— — layout-element                     布局元素组件，视图布局面板中使用的预置组件
            |— — widgets                            部件组件
        |— — config                                 配置文件夹
            |— — app-code-list-config.ts            应用代码表配置
            |— — app-config.ts                      应用配置
            |— — app-counter-config.ts              应用计数器配置
            |— — app-entity-config.ts               应用实体配置
            |— — app-func-config.ts                 应用功能配置
            |— — app-theme-config.ts                应用主题配置
            |— — app-view-config.ts                 应用视图配置
            |— — app-view-msg-config.ts             应用视图消息配置
        |— — core                                   核心，包括控制器与接口
            |— — controller                         控制器
                |— — app
                    |— — app-controller.ts          应用控制器，由src/app/app.ts继承具体实现
                |— — common
                    |— — controller-base.ts         控制器基类
                |— — view                           视图控制器
                |— — widgets                        部件控制器
            |— — interface                          接口
                |— — app                            应用级接口，包括应用接口、应用配置接口、应用数据接口、项目配置接口
                |— — common                         通用基础接口，包括应用上下文接口、视图详情接口、实体详情接口、布局配置接口等
                |— — modules
                    |— — app-func                   应用功能模块，包括应用功能接口、应用功能助手接口
                    |— — code-list                  代码表模块，包括代码表接口、代码表助手接口
                    |— — common                     通用模块，包括能力接口、控制器输入参数接口、控制器接口、事件接口、请求响应结果接口、仓库数据接口
                    |— — counter                    计数器模块，包括计数器助手接口
                    |— — ctrl-service               部件服务模块，包括部件服务接口
                    |— — data-service               数据服务模块，包括实体标准接口、实体临时数据服务接口
                    |— — dev-action                 debug服务模块，包括debug服务助手接口
                    |— — dialog                     对话框模块，包括对话框助手接口、自定义对话框配置接口
                    |— — global-action              全局界面行为模块，包括全局界面行为助手接口
                    |— — global-notification        全局通知模块，包括全局通知助手接口
                    |— — loading                    加载模块，包括加载助手接口
                    |— — notification               消息提示模块，包括消息提示助手接口
                    |— — open-view                  打开视图模块，包括打开视图操作结果接口、打开视图助手接口
                    |— — service-register           服务注册模块，包括服务注册统一接口
                    |— — ui-engine                  界面引擎模块，包括界面引擎输入参数接口、界面引擎输入模型接口、界面引擎执行结果参数接口
                    |— — ui-service                 界面服务模块，包括界面服务接口、界面行为执行结果接口
                    |— — view-logic                 视图逻辑模块，包括视图逻辑输入参数接口、视图逻辑助手接口
                    |— — view-msg                   视图消息模块，包括视图消息助手接口、视图消息接口、视图消息组接口
                |— — view                           视图相关接口
                    |— — ability                    视图能力接口
                    |— — controller                 视图控制器接口
                    |— — controller-params          视图控制器输入参数接口
                    |— — data-action                视图操作响应接口
                    |— — event                      视图事件接口与行为类型
                    |— — model                      视图模型接口
                    |— — store                      视图仓库数据接口
                |— — widgets                        部件相关接口
                    |— — ability                    部件能力接口
                    |— — controller                 部件控制器接口
                    |— — controller-params          部件控制器输入参数接口
                    |— — data-action                部件操作响应接口与部件数据行为接口
                    |— — event                      部件事件接口与行为类型
                    |— — model                      部件模型接口
                    |— — store                      部件仓库数据接口
            |— — modules
                |— — code-list                      代码表模块
                    |— — code-list-helper-base.ts   代码表助手抽象基类
                |— — control-vo                     部件VO模块
                    |— — control-vo-base.ts         部件VO基类
                |— — counter                        计数器模块
                    |— — counter-helper-base.ts     计数器助手抽象基类
                |— — ctrl-service                   部件服务
                |— — data-service                   数据服务模块
                    |— — data-service-base.ts       数据服务基类
                    |— — entity-base.ts             实体基类
                |— — db-service                     IndexDB模块
                    |— — db-service.ts              IndexDB库服务类
                    |— — entity-db-service.ts       应用实体库服务类
                |— — loading                        加载模块
                    |— — app-loading-helper.ts      应用加载助手类
                    |— — loading-helper.ts          加载助手类
                |— — logic                          界面逻辑模块
                    |— — const                      常量
                    |— — logic-param                界面逻辑参数
                |— — ui-engine                      界面引擎模块
                |— — ui-service                     界面服务模块
                    |— — ui-service-base.ts         界面服务基类
                |— — view-msg                       视图消息模块
                    |— — view-msg-helper-base.ts    视图消息助手抽象基类
            |— — utils                              工具类
        |— — directives                             指令
        |— — helper                                 各类助手，对core中的助手模块进行项目级的开发
        |— — hooks
            |— — use-app.ts                         应用hooks
            |— — use-ctrl.ts                        部件hooks
            |— — use-editor.ts                      编辑器hooks
            |— — use-view.ts                        视图hooks
        |— — http
            |— — http.ts                            http工具
            |— — interceptor.ts                     拦截器
        |— — locales                                国际化文件
        |— — plugins                                项目插件文件
            |— — ctrl-item                          部件项插件
            |— — de-method                          实体方法插件
            |— — editor                             编辑器插件
            |— — ui-action                          界面行为插件
            |— — ui-logic                           界面逻辑插件
            |— — view                               视图插件
            |— — widget                             部件插件
        |— — register                               注册中心
            |— — common-comp-register.ts            通用组件注册
            |— — common-directive-register.ts       通用指令注册
            |— — entity-service-register.ts         实体数据服务注册
            |— — page-comp-register.ts              视图注册
            |— — ui-service-register.ts             界面服务注册
            |— — user-comp-register.ts              自定义组件注册
        |— — router                                 路由
            |— — guard                              路由守卫
                |— — auth-guard.ts                  权限守卫
            |— — routes
                |— — entity-route.ts                实体视图路由
                |— — user-route.ts                  用户路由
                |— — view-route.ts                  首页视图路由
        |— — setting                                项目级配置文件
        |— — store                                  全局状态管理，Vue3使用pinia
            |— — modules
                |— — app.ts                         应用模块
                |— — auth-resource.ts               权限资源模块
                |— — view-action.ts                 视图行为模块
                |— — view-ctx.ts                    视图上下文模块
        |— — styles                                 样式文件
        |— — ui-service                             界面服务
            |— — xxx                                实体标识
                |— — xxx-ui-service-base.ts         实体界面服务基类
                |— — xxx-ui-service.ts              实体界面服务
                |— — yyy-ui-logic-base.ts           实体界面逻辑基类
                |— — yyy-ui-logic.ts                实体界面逻辑
        |— — utils
            |— — ui-util.ts                         界面工具类
        |— — views                                  视图
            |— — xxx                                模块标识
                |— — xxx-model.ts                   视图模型
                |— — xxx.vue                        视图vue文件
        |— — widgets                                部件
            |— — app
                |— — yyy                            部件标识，无数据能力的部件，例如菜单
                    |— — yyy-model.ts               部件模型
                    |— — yyy.vue                    部件vue文件
            |— — xxx                                应用实体标识
                |— — yyy                            实体部件标识
                    |— — yyy-model.ts               实体部件模型
                    |— — yyy-vo.ts                  实体部件对应vo对象类，只有数据部件才有此文件
                    |— — yyy.vue                    实体部件vue文件
        |─ ─ App.vue                                入口组件
        |─ ─ main.ts                                应用入口
    |─ ─ tests                                      单元测试文件
        |─ ─ app                                    src下app文件测试内容
        |─ ─ core                                   src下core文件测试内容
        |─ ─ global                                 单元测试全局控制文件
    |─ ─ types                                      类型声明
    |─ ─ user                                       用户自定义文件，映射src目录
    |─ ─ .env                                       环境基础文件
    |─ ─ .env.development                           开发环境配置文件
    |─ ─ .env.production                            生产环境配置文件
    |─ ─ .eslintignore                              eslint忽略文件
    |─ ─ .eslintrc.cjs                              eslint配置
    |─ ─ .gitignore                                 git忽略文件
    |─ ─ .prettierignore                            prettier忽略文件
    |─ ─ .prettierrc.cjs                            prettier配置文件
    |─ ─ auto-imports.d.ts                          vue自动导入声明
    |─ ─ components.d.ts                            组件声明
    |─ ─ copy.js                                    拷贝脚本
    |─ ─ index.html
    |─ ─ package.json                               依赖管理文件
    |─ ─ README.md
    |─ ─ tsconfig.json                              ts配置文件
    |─ ─ vite-config.ts                             vite配置文件
    |─ ─ yarn.lock                                  yarn版本锁定文件
```

## 准备

- [node](http://nodejs.org/) -项目开发环境
- [Vite](https://vitejs.dev/) - 熟悉 vite 特性
- [Vue3](https://v3.vuejs.org/) - 熟悉 Vue 基础语法
- [TypeScript](https://www.typescriptlang.org/) - 熟悉`TypeScript`基本语法
- [Es6+](http://es6.ruanyifeng.com/) - 熟悉 es6 基本语法
- [Ant-Design-Vue](https://2x.antdv.com/docs/vue/introduce-cn/) - ui 基本使用

## 使用

- 安装依赖

```bash
yarn install
```

修改`vite.config.js`中的 service.proxy 块，指向代理地址

```json
server: {
 port: 8080,
 proxy: {
  '/api': {
   target: '代理地址',
   changeOrigin: true,
   rewrite: (path) => path.replace(/^\/api/, ''),
  },
 },
},
```

**注：**应用基础路径可自由修改，但与代理中的地址必须映射

- 运行

```bash
yarn dev
```

- 打包

```bash
yarn build
```

- 代码生成

该项目依赖于`@ibiz-template/vue3`，动态解析由 Ibiz 平台构建的模型生成成果物代码。而对于模型的解释规范便是`模板`。

当执行以下命令时，模板会生成代码。

```bash
yarn generate
```

该脚本命令调用`@ibiz-template/vue3`包提供的 template 脚本，通过传入的参数生成代码

```bash
template generate -m ./model -o ./ --app Web --dev
```

脚本参数说明

| 参数              | 是否必须 | 说明                                                 |
| ----------------- | -------- | ---------------------------------------------------- |
| generate          | 是       | 生成代码                                             |
| -m [modelPath]    | 是       | 指定模型地址                                         |
| -t [templatePath] | 否       | 指定自定义模板地址，会合并模板内容到内置模板中再发布 |
| -o [outPath]      | 是       | 生成代码输出地址                                     |
| --app [appName]   | 是       | 指定识别的应用模型标识                               |
| --dev             | 否       | 开发模式启动                                         |
| --clean           | 否       | 清理输出目录                                         |
| --all             | 否       | 结合-t 使用，将指定自定义模板全量覆盖内置模板        |

**示例**

使用本地模板全量覆盖内置模板

```bash
template generate -m ./model -t ./template -o ./ --app Web --dev -all
```

- 单元测试

```bash
yarn test
```

- 覆盖率测试报告

```bash
yarn coverage
```

## 二次开发

### 模板开发

| 文件     | 说明     | 内容                                                         |
| -------- | -------- | ------------------------------------------------------------ |
| template | 模板文件 | 对模型进行解析，解析过后生成的文件与基础文件进行合并，最终便生成了完整的成果物代码 |
| asset    | 基础文件 | 基础组件、核心逻辑、样式等内容                               |

模板开发有两种方式：

​		1.直接修改template或asset下的相应文件

​		2.其他路径新建模板路径，在成果物生成代码的脚本后增加相应指令（-t [templatePath]）

#### 使用场景

当需要对所有项目进行改动，或者此次更改希望所有应用都能享受到，则可以采用模板二次开发。

### 成果物开发

成果物是指生成的完整项目，能够正常的启动、打包。

#### 成果物开发方式一

在成果物中存在user目录，其映射当前项目根目录，例如

`user/src/App.vue`映射项目根目录`/src/App.vue`

`user/index.html`映射项目根目录`/index.html`

在生成成果物代码时，user目录下的文件会将src下映射的文件覆盖。因此，进行成果物二次开发时，只需要在user下创建对应的文件即可。这种模式能够更直观的看到哪些文件进行了二次开发，方便管理，同时避免通过`generate`指令重新生成代码后覆盖二次开发。

#### 成果物开发方式二

在做过二次开发的文件里面第一行添加`/* pub-rule @skip-overwrite  */`忽略模板覆盖

#### 使用场景

只是某个项目具有特殊的需求，其他项目并不需要。

#### 特殊说明

1. 在进行成果物开发后，需要启用调试模式(环境文件中`VITE_DEBUG`)方便 ba 确认当前页面是否做过二次开发，开发也需遵从组件二次开发和逻辑二次开发相关规范。
2. 部分模板发布的文件存在基本文件和其继承的base文件，例如实体服务、UI服务等，此类文件更推荐修改基本文件，避免因模型变更后导致文件内容异常。

**组件二次开发**

- 使用方式

在二次开发组件中使用 `AppDevActionBar` 组件

```vue
<AppDevActionBar remark="二次开发备注文案"></AppDevActionBar>
```

- 接收参数

| 参数   | 类型   | 说明         |
| ------ | ------ | ------------ |
| remark | 字符串 | 二次开发备注 |

- 示例

现在需要将多语言切换组件进行二次开发，调整页面，其对应成果物路径为`项目根目录/src/components/common/lang/src/lang.vue`，如果当前修改需要在所有应用下都使用，则直接在依赖包的asset目录下找到该文件进行修改即可；若只是当前应用需要，则在当前应用成果物代码的user目录下新建`src/components/common/lang/src/lang.vue`，其内容如下：

```vue
<template>
 <a-dropdown trigger="click" class="app-lang">
  <div class="app-lang__caption">
   <AppDevActionBar remark="该组件修改了XX逻辑"></AppDevActionBar>
   <span>
    {{ caption }}
    <CaretDownOutlined size="18" />
   </span>
  </div>
  <template #overlay>
   <a-menu @click="selectLang">
    <a-menu-item
     v-for="item in localList"
     :name="item.type"
     :key="item.type"
     >{{ item.name }}
    </a-menu-item>
   </a-menu>
  </template>
 </a-dropdown>
</template>
<script setup lang="ts">
.......
</script>
```

**逻辑二次开发**

- 使用方式

在二次开发逻辑方法中使用`@ProcessLog`注解,注意此类注解只能用到函数上

```ts
@ProcessLog('二次开发备注文案')
```

- 接收参数

| 参数   | 类型   | 说明         |
| ------ | ------ | ------------ |
| remark | 字符串 | 二次开发备注 |

- 示例

现在有一实体名为order，其在成果物中的数据服务路径为`项目根目录/src/api/order/data-service`，其下文件有

| 名称                  | 说明                                   |
| --------------------- | -------------------------------------- |
| order-service-base.ts | order实体数据服务base文件，包含API方法 |
| order-service.ts      | order实体数据服务，继承base文件        |

现在需要修改order实体的Get方法。

在user目录下新建文件，路径为`user/src/api/order/data-service/order-service.ts`

从order-service.ts中复制Get方法到上述文件中，进行逻辑的调整，并且补充`@ProcessLog`注解，其中写入调整描述，方便BA查看。

```typescript
 @ProcessLog('重写了order实体的Get方法，具体调整为...')
 /**
  * Get
  *
  * @param {IParam} [context={}]
  * @param {IParam | IParam[]} [data]
  * @returns {Promise<any>}
  * @memberof OrderService
  */
 public async Get(
  context: IContext = {},
  data: IParam | IParam[]
 ): Promise<any> {
  // 重写逻辑
 }
```