PreferenceAPI

愿景

• 配置API（PreferenceAPI）旨在提供统一化和集中化的配置管理，减少应用研发代价、促进配置共享
  • 三种配置级别：租户 应用 用户
  • 三种操作方式：查询 修改 订阅
  • 两种数据类型：单值 集合
• 会定义一些具体的配置结构，比如 应用授权信息

接口标准

• 接口采用GraphQL规范

### 自定义配置项
type PreferenceItem {
  # 配置项标识
  name: String
  # 配置项显示文字
  text: String
  /** 
   * 数据类型。包括如下情况
   * 原子类型。同GraphQL的Basic Types[1]中的如下四种：[String|Int|Float|Boolean] 
   * 字符串集合(Set)。集合会自动去重复，不保障有序
   */
  type: String
  /**
   * 配置方式（控件），可为空。枚举：[Edit|Check|File|Picture]
   */
  editor: String  
  # 字符串值，仅type为String时有效
  valueString: String
  # 整数值
  valueInt: Int
  # 浮点值
  valueFloat: Float
  # 布尔值
  valueBoolean: Boolean
  # 字符串集合
  valueStrings: [String!]
  # 是否支持多租。为true时，不同租户的用户、应用配置可以不同
  multiTenancy: Boolean 
  # 创建人 openid
  creator: String
  # 创建时间
  created: Int
}

### 用户配置
type UserPreference {
  # 用户 openid 
  openid: ID
  # 用户姓名
  text: String
  # 自定义配置项
  preferences: [PreferenceItem!]
}

### 应用配置
type AppPreference {
  # 应用 client_id
  name: ID
  # 应用名称
  text: String
  # 应用授权信息，JWT格式，具体解释参考License文档[3] 
  license: String
  # 自定义配置项
  preferences: [PreferenceItem!]
}

### 租户配置
type TenantPreference {
  # 租户编码。SaaS应用接口调用时的tenant参数，参考Multitenancy文档[2]
  name: ID
  # 租户名称
  text: String
  # 自定义配置项
  preferences: [PreferenceItem!]
}


### 查询接口定义 
type Query {
  # 查询租户偏好。对于SaaS应用需使用tenant参数，参考Multitenancy文档[2]
  tenantPreference(): TenantPreference!
  # 查询当前应用偏好，支持查询其他应用偏好、支持多租区分
  appPreference(client_id: String): AppPreference!
  # 查询当前用户。支持多租区分
  userPreference(): UserPreference!

  # 查询配置项目列表。支持分页
  preferenceItems(filter: PreferenceItemFilter):  PreferenceItemConnection
}

### 变更接口定义

type Mutation {
  # 修改租户配置。value参数通过JSON格式表示集合
  editTenantPreference(name:String!, type:String, value:String!, multiTenancy:Boolean): PreferenceItem!
  # 租户配置中，集合类型新增元素。如name不存在则自动创建。
  addTenantPreferenceItem(name:String!, value:String!): PreferenceItem!
  # 租户配置中，集合类型删除元素。如name不存在或元素不存在，返回成功、但返回值为空。
  deleteTenantPreferenceItem(name:String!, value:String!): PreferenceItem

  # 修改应用配置。value参数通过JSON格式表示集合
  editAppPreference(name:String!, type:String, value:String!, multiTenancy:Boolean): PreferenceItem!
  # 应用配置中，集合类型新增元素。如name不存在则自动创建。
  addAppPreferenceItem(name:String!, value:String!): PreferenceItem!
  # 应用配置中，集合类型删除元素。如name不存在或元素不存在，返回成功、但返回值为空。
  deleteAppPreferenceItem(name:String!, value:String!): PreferenceItem

  # 修改用户配置。value参数通过JSON格式表示集合
  editUserPreference(name:String!, type:String, value:String!, multiTenancy:Boolean): PreferenceItem!
  # 用户配置中，集合类型新增元素。如name不存在则自动创建。
  addUserPreferenceItem(name:String!, value:String!): PreferenceItem!
  # 用户配置中，集合类型删除元素。如name不存在或元素不存在，返回成功、但返回值为空。
  deleteUserPreferenceItem(name:String!, value:String!): PreferenceItem
}

### 订阅接口不在此文档中定义
### 参考 [MessageQueue](https://github.com/infoplus/canvas-docs/wiki/MQ) 文档中 "preference.changed"

错误码

• 报错格式需符合Provider错误扩展

错误码	Explained
BAD_PARAMETER	参数不合法。并需在detail中给出具体有问题的参数及解释
TENANT_REQUIRED	无法推断租户。参考Multitenancy文档
TENANT_MISMATCH	token租户与tenant参数不一致。参考Multitenancy文档
APP_NOT_FOUND	应用不存在
USER_NOT_FOUND	用户不存在

附录

• [1] GraphQL Basic Types
• [2] Multitenancy
• [3] 应用License