# 概要

应用的配置包括以下几个大的方面:

  1. 基础信息:包括应用 Id、服务地址、白名单等
  2. 售卖版本(plans):类似客户端软件的普通版、旗舰版、企业版等
  3. 插件(addons):对其他应用注入的插件
  4. 微前端(micro-front-ends):有前端界面的应用需要注册一个微前端地址
  5. 导航(navigations):要注入的导航列表
  6. 角色(roles):一个角色包含对若干接口、页面的访问权限

# 基础信息

  • server-address:表示应用的 Open API 网关地址,所有的 Open API 调用都会进入这里。
  • whitelist-ips:白名单 IP 地址,在调用平台接口时平台会检查 IP
  • launchers:启动器,可以理解为应用的一种分类。启动器需要在后台提前创建。目前只有一个 socialCloud 启动器

# 售卖版本(plans)

售卖版本,一种配额、功能限制的机制,类似传统软件的家庭版、企业版、旗舰版的概念。通过售卖版本,一个应用可以实现不同的租户有不同的功能。

以微信应用为例,基础版,只允许接入 1 个公众号,不能接入小程序;高级版支持接入最多 10 个公众号,不能接入小程序;旗舰版不限制公众号,且支持小程序。

上述示例的实现方式如下:

  • 配置三个售卖版本,分别是基础版(basic)、高级版(premium)、旗舰版(ultimate)
  • 配置两个角色,分别是公众号管理(woa)、小程序管理(mini)。其中公众号管理属于以上三种版本,而小程序只属于旗舰版。
  • 程序里根据租户购买的售卖版本,硬编码(或自行使用其他配置机制)判断租户的版本来限制公众号。如 if (profile.plan === 'basic') then woaCount = 1

# 插件(addons)

插件是 Engage 平台的一个重要能力,是一种尽可能解决标准化与定制化冲突的设计尝试。应用在实现标准化的功能时,预留一些位置(slot)供其他应用进行扩展。插件在 Engage 中有以下几种类型:

  1. 纯后端的插件
  2. 前后端混合的插件
  3. 纯前端的插件

纯后端的插件,比如有新的客户时,需要通过企业内部的通讯网络来通知,此时可以注册一个插件,只需要提供一个 Open API 即可。纯前端的插件,比如客户的详情页面要展示其关联的微信粉丝,则可以由微信应用注入一个前端组件给客户应用,客户应用的前端会在指定位置渲染粉丝列表。前后端混合就是前两者均有,比如旅程应用,所有的步骤既有前端配置界面,又需要在旅程运行时接收旅程推送过来的人员。

一个应用要支持别的应用注入插件,务必要提供完整的规范文档,插件类型是什么,在什么位置,需要哪些参数,都要说明清楚。某个应用要注册插件时,也会调用目标应用进行校验,如果配置参数不对就可以阻止应用的继续发布。

插件不仅可以在应用详情配置参数中进行配置,也可以在应用详情页下 Tabs 插件中进行添加,此处会对插件进行单独发布处理,不影响其他应用参数。一个插件只需要在这两部分中任何一方配置即可。

注意:apis 和 roles 是作为插件权限标识的指定字段。在对插件其他功能参数进行配置时,请误使用。以免造成权限校验错误。

另外,这里要强调一下,应用配置的插件(addons)是表示向其他应用注入的插件,不是指当前应用支持哪些插件,不要把方向或性质搞反了。

# 微前端(micro-front-ends)

有关微前端的一些认识与实践,可参考 这篇文章

一般一个应用只有一个微前端。注意 index-html 的路径要配置正确,否则无法解析。

# 导航(navigations)

# 角色(roles)

应用内业务流程的操作角色。一个角色会绑定若干个接口和页面。用户只有拥有这个角色,才能访问这些界面和页面,否则会报 403 错误。

# 详细配置参数


# 应用 Id 和名称
id: sample
name: sample
name-en-US: xxx

# 服务地址,可以是 HTTPS/HTTP。主要用于被平台调用的 OpenAPI。
server-address: https://xxx.com/open-api

# 应用自定义配置组件(微前端+组件名称)
setup-page-address: mfe-xx.component-name

# 服务器 IP 地址白名单,在调用平台接口时平台会检查 IP。
whitelist-ips: 
  - '10.120.80.20'
  - '10.120.80.21'

# 依赖,表示该应用的某些功能需要别的应用也被安装时才能正常工作。格式:(数组:所依赖应用id)
dependencies: 
  - 'platform'

# 应用启动器,表示当前应用属于哪些启动器
launchers: [ socialCloud ]
  
# 售卖版本,应用内部可以对不同的版本使用不同的配置(如可接入多少个客户)。应用应该至少有一个基础版。
plans:
  - id: basic
    name: 基础版
    name-en-US: Basic
    # 价格格式:[一年价格,两年价格,三年价格]
    price: 
      - 10  
      - 100 
      - 1000
    description: 仅能创建一个用户,数据量上线 1000 条

# 为其他应用提供的插件,具体参数要视目标应用的要求。
addons:
  # 目标应用配置
  - target: 
      # 目标应用 Id
      application: campaign 
      # 插件适配的类型与版本
      type: step/v1.0.0

# 应用提供的 OpenAPI 列表
open-apis: 
  # URL 必须是 '/v<N>/' 开头,它会跟应用的服务地址组成完整的 URL。
  - path: /v1/pa/query 
    name: 查询公众号
    name-en-US: Query Public Account
    # OpenAPI 请求参数 JSON Schema,暂不实现
    input: {} 
    # OpenAPI 响应参数 JSON Schema,暂不实现
    output: {} 

# 导航,一般有前端页面的应用才需要。
navigations:
  - name: 公众号
    name-en-US: Wechat Public Account
    # 排序值,正整数类型。不允许同一个父级导航下 order 重合,一般为 10 的整数倍。
    order: 10
    # icon 名或 SVG 图片的 URL
    icon: ion-home 
    # 可以是微前端页面 URL(一般以应用 Id 开头),也支持完整的 URL(带域名)。
    entry: 
      - /wechat/pa-list 
    # 匹配哪些 URL,匹配时会激活该导航。按前缀匹配,不支持正则表达式。
    pages: 
      - /wechat/pa-list

# 应用内如果有前端页面(包括插件内),需要在这里声明。前端页面访问应用内接口,不需要经过平台转发,而是直接调用。
# 当然平台会在前端提供一个当前登录用户的全局变量,即 User Token,需要前端传给应用内接口。
micro-front-ends:
  - id: mfe-wechat
    # 匹配哪些页面 URL,以应用 Id 开始。按前缀匹配,不支持正则表达式。
    # 要求全系统唯一,即不能在应用内、应用间有任何重复、重叠。
    pages: 
      - /wechat/
    index-html: https://wechat.xxx.com/mfe-wechat/
    # 需要从 index.html 中匹配的资源,这些资源将会被加载。支持正则表达式。
    resources: 
      - app.*.js 
      - app.*.css
      - vendor.*.js
      - vendor.*.css
      - runtime.*.js

# 应用提供的角色,角色会分配到用户(租户的员工)身上。没有角色的用户则无法访问对应的页面、应用内接口。
# 应用内接口由应用内前端直接访问,不会经过平台转发,因此需要应用自己做接口权限控制,平台会提供登录用户可访问的应用内接口列表。
roles:
  - id: basic-admin
    name: 管理员
    name-en-US: Admin
    # 所属的售卖版本,不填写则表示所有售卖版本都有该角色,支持数组。
    plan:
      - basic 
    # 是否为管理员角色。管理员角色会被自动分配给购买该应用的租户的管理员岗位。
    admin: true 
    # 是否为公共角色。购买该应用的租户下所有岗位(或者说所有员工)都自动具有该角色。
    public: false
    # 匹配哪些应用内接口,以 /v1 开始。按前缀匹配,不支持正则表达式。
    apis: 
      - /v1/wechat/official-account
    # 匹配哪些页面 URL,以应用 Id 开始。按前缀匹配,不支持正则表达式。
    pages: 
      - /wechat/official-account
    # 角色的权限描述:用于标识当前角色的权限描述。格式:{模块名称:{auth:{权限:权限值}, description:模块描述}}
    # 必填权限:读取、创建、编辑、删除、全部、我的部门、我的团队、我的(例:{读取: 1, 编辑: 0, 拉取:1})
    # 权限值描述:-1表示实体没有此操作,0表示角色无权限,1表示角色有权限
    # auth-description: {用户: {auth:{读取:1},description:租户下的员工}}