一 IDE使用
1.1 IDE介绍
IDE共分为6个大区域，其中C区域是主要的工作区。
1.1.1 A-主菜单区
主菜单区是IDE的主菜单及用户信息等功能区，类似于其他桌面软件的主菜单：
- 主菜单：重要的全局功能统一入口；
- 用户信息区：当前登录用户信息，以及登入登出等快捷操作。
1.1.2 B-核心功能导航区
IDE核心功能导航区域，分为上下两个部分：
- 工作空间：管理工作空间，提供增删改查操作，如果工作空间下有产品或应用，则不能删除。
- 产品：管理账户下所有产品，产品包含产品组件；
- 应用：管理账户下所有应用，应用包含一个应用组件，以及任意多个的业务组件；
- 画图：当打开不同的组件进行编辑的时候，画图区域会根据组件类型呈现可以使用的元数据模型元素，模型元素分为两大类：
- 类型元素：表示元数据的类型，在组件上一般是以一个矩形框的方式展现，通过鼠标拖拽来绘制；
- 关系元素：表示两个元素的关系，在组件上一般是以线条的方式展现，通过选中元素，然后再在组件上的源元素点击，即可绘制出关系，最后通过鼠标将关系的目标拖拽到目标元素，完成关系的绘制。
- 模型库：元型平台的模型中心，您可以在此挑选适合于您的模型，通过使用模型可将模型转化为自己的模型，并进行扩展。平台依托于最佳实践，提供了大量免费的基础业务模型。
- 设置：账户的全局设置；
1.1.3 C-工作区
工作区是多文档结构，组件的编辑、以及其他一些工作页面都在此区域呈现，每个打开的文档就是一个页签（Tab），文档如果编译未保存，页签上会加注星号（*）。
1.1.4 D-输出区
工作过程中信息输出区域：
- 错误列表：使用IDE过程中发生的错误列表，包括模型错误、校验错误等，双击可定位到具体错误对应的元数据（如果存在的话）；
- 输出：IDE各种操作的信息输出区域；
1.1.5 E-属性区
属性区是编辑模型的时候设置属性的区域，包括：
- 属性编辑：所有元数据的属性设置，都在此进行编辑；
- 类型浏览器：用于浏览账户下的元数据，是以应用开始进行展开的树结构；
- 服务浏览器：用于浏览应用可调用的服务；
1.1.6 F-页脚
页脚包含IDE的相关链接及版权说明。
1.2 快捷键
| 操作 | 快捷键 | 描述 |
| 复制 | Ctrl+C | 复制选定的模型 |
| 粘贴 | Ctrl+V | 粘贴被复制的模型 |
| 剪切 | Ctrl+X | 剪切选定的模型 |
| 保存 | Ctrl+S | 保存当前打开的组件 |
| 删除 | DEL | 删除选定的模型 |
| 还原上一步 | Ctrl+Z | 回退上一步操作 |
| 重做上一步 | Ctrl+Y | 重做上一步操作 |
二 平台设置
平台集成了非常复杂的功能，所有也提供了较为完善的设置中心，平台设置分为三层：
- 应用或产品设置：针对特定的应用、产品提供的设置，如果并未提供，则向下一层找；
- 用户的全局设置：由云IDE-B区（核心功能导航区）下方的全局设置进入，如果这里也未提供，则继续向下一层找；
- 平台及的默认设置：由平台提供的默认设置。
平台设置分为几大分组：
- 公共设置：平台的一些公共设置
- 编辑器设置：关于云IDE编辑器的设置
- 代码生成设置：流水线中代码生成阶段需要提供的设置
- 应用发布设置：流水线中应用发布的相关设置
具体每个分类的设置项，请参见云IDE的设置页面，在此不再详细说明。
三 建模
打开任意组件，即可在C工作区中进行建模，不同的组件对应了不同的模型元素，根据具体的需求来选择合适的模型元素。
- 首先在左侧选择应用面板，“我的应用”中将出现所有当前可用的应用；
- 展开应用，点击某个组件后面的按钮“打开组件“，即可在工作区中看到如图所示的模型界面
- 在模型界面中，选择任意模型元素，后侧的属性区域将随之而发生变化
- 可以在属性区域中对模型的属性进行逐项的设置
在最左侧选择“画图”工具，则左侧面板会显示当前模型可用的模型元素，比如业务模型，模型元素如下：
注意：文档名称前面的星号“*”，代表文档已经编辑尚未保存
四 流水线
通过流水线页面，可以设定流水线执行的配置。
五 代码生成
目前平台处于初级阶段，支持的运行期语言及框架有限，后续会逐步的扩展到更多的语言及框架。
5.1 后端服务
目标语言：Java+SpringCloud+SpringBoot
每个应用将生成基于目标语言的一个微服务。
后端架构如下：
主要分为几个部分：
- 控制层：对外提供接口，对内封装了商业逻辑和实体的通用CRUD
- 商业逻辑层：封装了实体和DTO层，所有数据操作，都是通过实体为入口，不直接接触数据服务层和Mapper层；
- 数据服务层：负责完成实体的数据操作，隔离了实体和Mapper层
- Mapper层：具体的数据库操作层，使用Mybatis框架。
注意：绿色框的商业逻辑，是需要用户扩展代码来实现的，建议扩展的时候也遵循上述规则，不要跨层调用，否则可能会在后续的扩展和升级过程中面临一些复杂的场景。
5.2 前端项目
目标语言：VUE3+ElementUI Plus+TS
前端分为四层：
- UIPage：采用组件进行组装，主要包括：
- 页面结构及布局
- 头尾定义
- 导航定义
- UIView：即页面组件，每个View是一个完整的子功能，可以多个View组成更为复杂的VIew，基于ViewModel，主要包括：
- 界面及交互
- 服务通讯
- 逻辑实现
- ViewModel：View的数据提供者，通常可直接使用前端Entity，有需要的时候，可以进行Entity的裁剪、封装等，主要定义了数据前端呈现的一些元数据信息，比如：是否显示、是否录入、前端校验等。
- 前端本地服务：对服务器端服务的代理，无论服务器端服务是什么形式，这里都生成对应的代理，前端开发通过代理进行服务器端调用，与使用本地服务无异。同时，前端人员可以定义自己的本地服务，但是不能直接访问服务端，必须通过代理。
5.3 数据库
目标数据库：MySQL
生成的数据库脚本包括：
- 应用的DDL脚本（每个应用一个数据库）
- 应用的权限数据等系统级初始化脚本
- 应用本身的预置数据脚本
所有脚本文件都以后缀.sql文件提供，可通过GIT拉取
5.4 文档
生成的文档包括：
- 前端API文档：前端开发人员参考的API接口文档
- 后端文档：后端开发人员参考的接口文档
- 元数据文档：模型设计人员或其他相关人员参考的元数据文档
以上三个文档都源于模型，大部分的内容是相同的，只是针对不同的受众，做了一些细节上的调整和处理
六 扩展实现
平台提供了丰富的扩展机制，常见的主要有三种扩展：
- 基于平台必须提供的扩展实现：比如：商业逻辑的实现代码
- 基于平台生成的代码进行扩展，不破坏原有生成代码，比如：前端View增加按钮
- 完全自定义的扩展：生成的代码包含所有源代码，理论上可以加入任意的自定义扩展来达成目的，不过这个过程中尽量复用平台已经生成的代码，而不要重新造轮子。
6.1 前端扩展
6.1.1 平台封装的公共组件
平台提供了一系列的公共组件供使用，此类公共组件不与元数据进行绑定：
- <mp-bread-crumbs>：面包屑控件
- <mp-group>：属性分组控件
- <mp-pagination>：分页控件
6.1.2 可复用的业务组件
【业务属性编辑控件】
实体表单中的每个录入项，都是一个封装后的业务属性编辑控件，在页面扩展或开发自定义页面的时候，可以通过组合这些录入控件来快速构建表单页面。
以实体Form组件为例，前端显示如下：
前端代码如下，引用了多个属性控件：
<el-row :gutter="10" type="flex" class="flex-wrap-wrap" display:flex>
<el-col :span="colSpan" :offset="0">
<mp-attr ref="codeCom" :attribute="getAttr('code')" v-model='value.code' @valueChanged='valueChanged' />
</el-col>
<el-col :span="colSpan" :offset="0">
<mp-attr ref="nameCom" :attribute="getAttr('name')" v-model='value.name' @valueChanged='valueChanged' />
</el-col>
<el-col :span="colSpan" :offset="0">
<mp-attr ref="phoneCodeCom" :attribute="getAttr('phoneCode')" v-model='value.phoneCode' @valueChanged='valueChanged' />
</el-col>
<el-col :span="colSpan" :offset="0">
<mp-attr ref="isDefaultCom" :attribute="getAttr('isDefault')" v-model='value.isDefault' @valueChanged='valueChanged' />
</el-col>
<el-col :span="colSpan" :offset="0">
<mp-attr ref="shortNameCom" :attribute="getAttr('shortName')" v-model='value.shortName' @valueChanged='valueChanged' />
</el-col>
<el-col :span="colSpan" :offset="0">
<mp-attr ref="sequenceCom" :attribute="getAttr('sequence')" v-model='value.sequence' @valueChanged='valueChanged' />
</el-col>
</el-row>
国家（Country）实体，包含了属性：
- 国家代码(Code)：标准国家代码，比如：中国为zh-cn
- 名称(Name)：国家的完整名称，比如：中华人民共和国
- 电话代码(PhoneCode)：即国际电话区号，比如：中国为0086
- 是否是缺省国家(IsDefault)：true代表获取省份数据的时候缺省获取此国家下的省份
- 简称(ShortName)：国家的简称，比如：中华人民共和国简称中国
- 排序(Sequence)：指定国家列表中的顺序号，升序排列
以名称属性为例，引用了属性控件<mp-attr>，此控件从模型元数据中获取相关的值，其标签属性包括：
- ref=”nameCom”：定义组件的引用名称，用于本组件内引用此属性控件
- :attribute=”getAttr(‘name’)”：绑定名称属性元数据，getAttr为组件内方法，通过name获取名称元数据。属性元数据包含的内容，是由模型中对实体属性的定义决定的，具体的设置项可参见文档的建模语言说明。
- v-model=”value.name”：绑定属性控件的值，value是当前组件绑定的业务实体的实例
- @valueChanged=”valueChanged”：当属性空间内的值发生变化以后，进行事件处理，实体的编辑、保存在本组件内部进行，属性控件仅负责单个属性的处理
业务属性控件，根据不同的数据类型会使用不同的底层控件，绑定了以下属性元数据：
- 缺省值：即属性在模型中设置的缺省值，或系统定义的缺省值
- 录入控件标题：绑定了属性的显示名称；
- PlaceHolder：绑定了属性的描述
- 数据类型相关：比如精度、小数位等
- 是否可空
- 校验相关：比如最大值、最小值、正则表达式等
【业务属性查询控件】
当业务属性设置为可查询的时候，可以使用封装的业务属性查询控件，与上述业务属性编辑控件类似，也是通过绑定业务属性元数据来动态输出相应的查询控件。
以国家查询Search组件为例，前端呈现为：
前端相关代码：
<mp-attr-search :attribute="getAttr('code')" v-model="codeValue" />
<mp-attr-search :attribute="getAttr('name')" v-model="nameValue" />
<mp-attr-search :attribute="getAttr('phoneCode')" v-model="phoneCodeValue" />
<mp-attr-search :attribute="getAttr('isDefault')" v-model="isDefaultValue" />
<mp-attr-search :attribute="getAttr('shortName')" v-model="shortNameValue" />
<mp-attr-search :attribute="getAttr('sequence')" v-model:model-min-value="sequenceMinValue" v-model:model-max-value="sequenceMaxValue" />
以名称查询为例，引用了业务属性查询控件<mp-attr-search>控件，其参数为：
- :attribute=”getAttr(‘name’)”： 绑定名称属性元数据，getAttr为组件内方法，通过name获取名称元数据。属性元数据包含的内容，是由模型中对实体属性的定义决定的，具体的设置项可参见文档的建模语言说明
- v-model=”nameValue”：数据的双向绑定变量，可以设置搜索条件的初始值
- v-model:model-min-value, v-model:model-max-value，对于数值型、日期型的属性，提供的是区间查询
与业务属性编辑控件相似，搜索控件的行为通过绑定属性元数据来实现。
【参照控件】
以下两种情况会使用参照控件：
- 当存在实体引用的时候，根据模型的设置，可能会输出参照控件（编辑、查询都会使用到）
- 属性的数据类型为枚举类型时，会使用枚举参照控件
以实体参照控件为例，菜单会关联应用，在菜单编辑和查询区域，就会使用应用的参照控件：
通过引用参照控件的代码：
<ApplicationRef ref="applicationCom" :attribute="getAttr('application_Id')" v-model="value.application_Id" @valueChanged="valueChanged" />
实体参照控件<ApplicationRef>说明：
- ref=”applicationCom”： 定义组件的引用名称，用于本组件内引用此属性控件
- :attribute=”getAttr(‘application_Id’)”： 绑定应用ID属性元数据，getAttr为组件内方法，通过application_Id获取应用元数据。属性元数据包含的内容，是由模型中对实体属性的定义决定的，具体的设置项可参见文档的建模语言说明。
- v-model=”value.application_Id”： 绑定属性控件的值，value是当前组件绑定的业务实体的实例
- @valueChanged=”valueChanged”： 当属性空间内的值发生变化以后，进行事件处理，实体的编辑、保存在本组件内部进行，属性控件仅负责单个属性的处理
- 实体参照控件，会根据模型定义，从服务端自行查询结果集并显示在待选列表中，调用方不用关心。
【业务操作控件】
业务操作通常对应了一个按钮或链接，在UI模型中定义的操作，在前端可以通过业务操作控件来使用，业务操作控件绑定也UI模型中的操作元数据。
以实体的编辑保存操作为例，呈现为一个“保存”按钮，其代码如下：
<mp-action :mdButton="mdPage.GetButton('btnEditSave')" type="primary" @click="onFinish" />
- :mdButton=”mdPage.GetButton(‘btnEditSave’)”：设定按钮绑定的操作元数据，mdPage是页面元数据，通过GetButton方法根据操作名称获取UIButton元数据；
- type=”primary”：主按钮，沿用ElementUI中Button的定义
- @click=”onFilish”：点击按钮事件处理
- 操作按钮会自动进行权限绑定和处理，调用方不用关心
6.1.3 扩展生成的View和Page
生成的View和Page，主要通过插槽的方式来提供扩展，以国家实体Country为例：
【查询视图CountrySearch】
| 插槽位置 | 插槽名称 | 初始内容 | 说明 |
| 属性前插槽 | attrBefore | 空 | 表单属性列表前面区域 |
| 属性后插槽 | attrAfter | 空 | 表单属性列表后面、操作按钮前面区域 |
| 查询按钮插槽 | search-query | 查询按钮 | 仅包含查询按钮，重写可覆盖 |
| 重置按钮插槽 | search-reset | 重置按钮 | 仅包含重置按钮，重写可覆盖 |
| 按钮后插槽 | search-btn-after | 空 | 查询、重置按钮之后的区域，可增加其他按钮 |
【表格视图CountryTable】
扩展插槽位于表格后面的操作列中：
| 插槽位置 | 插槽名称 | 初始内容 | 说明 |
| 按钮前插槽 | table-btn-before | 空 | 按钮之前的区域，可增加其他按钮 |
| 详情按钮插槽 | table-lookup | 详情按钮 | 仅包含详情按钮，重写可覆盖 |
| 编辑按钮插槽 | table-edit | 编辑按钮 | 仅包含编辑按钮，重写可覆盖 |
| 删除按钮插槽 | table-del | 删除按钮 | 仅包含删除按钮，重写可覆盖 |
| 按钮后插槽 | table-btn-after | 空 | 按钮之后的区域，可增加其他按钮 |
【详情页面CountryDetail】
扩展插槽位于详情视图的最下方
| 插槽位置 | 插槽名称 | 初始内容 | 说明 |
| 详情按钮插槽 | detail-toolbar | 空 | 详情视图下方的工具条插槽，可以增加自己的内容 |
【编辑页面CountryEdit】
扩展插槽位于表单视图的最下方
| 插槽位置 | 插槽名称 | 初始内容 | 说明 |
| 清空/重置按钮插槽 | edit-reset | 清空/重置按钮 | 仅包含清空/重置按钮，重写可覆盖 |
| 取消按钮插槽 | edit-cancel | 取消按钮 | 仅包含取消按钮，重写可覆盖 |
| 创建/编辑保存插槽 | edit-save | 创建/编辑保存按钮 | 仅包含创建/编辑保存按钮，重写可覆盖 |
| 按钮后插槽 | edit-btn-after | 空 | 按钮之后的区域，可增加其他按钮 |
【列表页面CountryList】
| 插槽位置 | 插槽名称 | 初始内容 | 说明 |
| 顶部插槽 | top | 无 | 页面顶部区域，可自定义 |
| 查询视图插槽 | 包含了查询视图的所有插槽 | ||
| 新建按钮插槽 | list-add | 新建按钮 | 查询区域右侧增加了新建按钮 |
| 表格视图插槽 | 包含了表格视图的所有插槽 | ||
| 详情视图插槽 | 包含了详情视图的所有插槽 | ||
| 编辑视图插槽 | 包含了编辑视图的所有插槽 | ||
| 底部插槽 | buttom | 无 | 页面底部区域，可自定义 |
6.1.4 扩展TS服务
可以通过自定义代码类，整合生成的ts服务来为上层提供更强大的接口。
注意：不要修改系统生成的服务代码，重新生成后将会覆盖掉
6.1.5 增加自定义页面
- 在UI模型的设计中，可以增加自定义页面；
- 在前端项目中，添加自定义的页面代码，路径为：@/views/名字空间分隔/页面名称.vue
在自定义页面中，可以通过组合上述的所有组件来构建自己的个性化页面，或者完全自定义。
6.2 后端扩展
6.2.1 实体扩展
如图所示，实体“项目”定义了四个方法，以统计方法为例，具有5个输入参数，同时开启了插入前和更新后事件：
会在生成实体的扩展代码，同时生成方法体，由用户提供具体实现，扩展代码的包路径以extension开头，其他与生成代码一致，以下是生成的扩展代码：
/**
* 项目 实体扩展实现
* @Date: 2021/3/24 下午11:19:26
*/
@Service
public class MMPProjectExtend implements IMMPProjectExtend {
/**
* 插入前事件
* @param entity 插入前的实体
* @param isTransaction 是否开启事务
*/
@Override
public void beforeInsert(IMMPProject entity, boolean isTransaction) {
// TODO : 实现你的事件扩展代码
}
/**
* 更新后事件
* @param entity 更新后的实体
* @param isTransaction 是否开启事务
*/
@Override
public void afterUpdate(IMMPProject entity, boolean isTransaction) {
// TODO : 实现你的事件扩展代码
}
/**
* 统计 : 统计
* @param entity 实体 - 实体
* @param taskStatus 任务状态 - 任务状态
* @param mobile 手机号 - 手机号
* @param email 邮箱 - 邮箱
* @param startPos 开始位置 - 开始位置
* @return -
*/
public int statistics(IMMPProject entity, EnumTaskStatus taskStatus, String mobile, String email, int startPos) {
// TODO : 实现你的方法扩展代码
throw new NoSuchMethodException("请提供扩展实现代码");
}
}
方法扩展说明：
- 扩展代码文件，仅生成一次，用户可以自行修改，不会被覆盖
- 生成的扩展代码，需要扩展的地方，会用TODO标记，同时方法体直接抛出NoSuchMethodException异常，编译器会捕获此异常，用户可根据编译器的错误逐个修复
事件扩展说明：
实体支持的事件列表如下：
| 事件名称 | 方法名称 | 说明 |
| 插入前事件 | beforeInsert | 在执行数据库插入之前执行，需要提供扩展实现代码 |
| 插入后事件 | afterInsert | 在执行数据库插入之后执行，需要提供扩展实现代码 |
| 更新前事件 | beforeUpdate | 在执行数据库更新之前执行，需要提供扩展实现代码 |
| 更新后事件 | afterUpdate | 在执行数据库更新之后执行，需要提供扩展实现代码 |
| 逻辑删除前事件 | beforeDelete | 在执行数据库逻辑删除之前执行，需要提供扩展实现代码 |
| 逻辑删除后事件 | afterDelete | 在执行数据库逻辑删除之后执行，需要提供扩展实现代码 |
| 恢复前事件 | beforeRestore | 在执行数据库恢复之前执行，需要提供扩展实现代码 |
| 恢复后事件 | afterRestore | 在执行数据库恢复之后执行，需要提供扩展实现代码 |
| 物理删除前事件 | beforeRemove | 在执行数据库物理删除之前执行，需要提供扩展实现代码 |
| 物理删除后事件 | afterRemove | 在执行数据库物理删除之后执行，需要提供扩展实现代码 |
与实体方法体实现的差异在于，此处并不会抛出编译器错误，所以即使不提供实现代码，也是可以顺利编译和运行的。
6.2.2 实现商业逻辑
如下入所示，业务模型定义了一系列的商业逻辑，下面以选择的商业逻辑“查询任务列表”为例：
生成的扩展代码如下：
/**
* 查询任务列表
* 根据任务状态枚举查询任务列表
* @Date: 2021/3/24 下午11:19:26
*/
@Service
public class BLGetTasks extends BLGetTasksBase {
/**
* 执行
*
* @param personId 人员ID - 人员ID
* @param pageNo 查询页号 - 查询页号
* @param taskStatus 任务状态 - 任务状态
* @param pageSize 分页大小 - 分页大小
* @param email 邮箱 - 邮箱
* @param phone 手机号 - 手机号
* @return 任务进度列表
*/
@Override
protected List<IMMPTask> _run(String personId, int pageNo, EnumTaskStatus taskStatus, int pageSize, String email, String phone) {
throw new NoSuchMethodException("请提供扩展实现代码");
}
}
说明：
- 扩展代码文件，仅生成一次，用户可以自行修改，不会被覆盖
- 生成的扩展代码，方法体直接抛出NoSuchMethodException异常，编译器会捕获此异常，用户可根据编译器的错误逐个修复
6.2.3 实现分布式事务
如上面模型所示，商业逻辑“添加项目类型”是一个支持分布式事务的逻辑，所以在生成的扩展代码中，除了执行逻辑的_run方法以外，还需要实现分布式事务所需要的方法（_prepare, _commit, _rollback）：
/**
* 添加项目类型
* 添加项目类型
* @Date: 2022/1/20 下午8:50:05
*/
@Service
public class BLAddOneProjectType extends BLAddOneProjectTypeBase {
/**
* 执行
*
* @param projectType 项目类型 - 项目类型
* @return 是否成功
*/
@Override
protected boolean _run(IMMPProjectType projectType) {
throw new NoSuchMethodException("请提供扩展实现代码");
}
/**
* Prepare boolean.
*
* @param projectType 项目类型 - 项目类型
* @return the boolean
*/
@Override
protected boolean _prepare(IMMPProjectType projectType) {
throw new NoSuchMethodException("请提供扩展实现代码");
}
/**
* Commit boolean.
*
* @param projectType 项目类型 - 项目类型
* @return the boolean
*/
@Override
protected boolean _commit(IMMPProjectType projectType) {
throw new NoSuchMethodException("请提供扩展实现代码");
}
/**
* Rollback boolean.
*
* @param projectType 项目类型 - 项目类型
* @return the boolean
*/
@Override
protected boolean _rollback(IMMPProjectType projectType) {
throw new NoSuchMethodException("请提供扩展实现代码");
}
}
6.2.4 自定义代码
由于服务端生成的代码，是完整的代码，所以用户可以在代码中完全自定义自己所需要的一切内容，但是，请尽量调用生成的代码，以便于后续的模型升级或平台升级。
6.3 脚本扩展
6.3.1 自定义脚本
在应用的GIT目录下，路径/SQLScripts/extension/里面，可以放置需要执行的SQL脚本，在流水线中会自动调用执行，但是有如下规则：
- 脚本必须以后缀“.sql”结尾
- 执行顺序依赖于文件命名，所以，需要优先执行的文件，命名要靠前，排序方式为字母升序
- 脚本需要支持可重复执行（即保持幂等性），比如以replace into 代替insert into
- 自定义脚本文件，在建库及系统脚本执行完成之后执行
七 发布与部署
通过流水线发布与部署
八 验证与访问
流水线支持完成后，系统的管理后台即可运行使用，以下是管理后台相关内容：
- 访问地址：http://{ip}:{port}/，其中访问地址，可以在产品配置页面查看
- 管理员账户：admin
- 管理员密码：Mp123456
