WorkspaceAPI

工作区(应用中心)API

• 旨在定义产品的安装激活和应用的管理接口
• 采用GraphQL协议及其扩展要求
• 采用OAuth2协议进行接口授权

API定义

应用激活API定义

编号	API	提供方
【AQ1】	查询当前租户应用列表	应用中心
【AQ2】	查询我可访问的应用列表	应用中心
【TQ1】	查询可安装/已安装的"应用标准件模版"列表	各开发工具 + 应用中心封装
【TQ2】	按应用模版ID查询"应用标准件模版"	各开发工具 + 应用中心封装
【AM1】	应用新建	各开发工具 + 应用中心
【AM2】	删除（不删开发工具内应用）	各开发工具 + 应用中心
【AM3】	上下架、属性修改	各开发工具+ 应用中心
【TM1】	应用模版激活	各开发工具 + 应用中心封装
【TM2】	应用升级	各开发工具 + 应用中心封装
【TM3】	应用取消激活	各开发工具 + 应用中心封装

• 注：对于【T2-T4】，返回值App列表，开发工具和应用中心返回的内容会有所不同：开发工具以工具端应用为单位，应用中心以应用入口为单位。

应用评价API定义

编号	API	提供方
【RQ1】	查询应用评价	应用中心
【RQ2】	查询应用评价查询我的应用评价	应用中心
【RM1】	新增应用评价	应用中心
【RM2】	删除应用评价	应用中心
【RM3】	更新应用评价	应用中心

Query

type Query {
  # 服务发现
  configuration: WorkspaceConfiguration
  # 【AQ1】: 查询当前租户应用列表
  apps(filter: AppFilter): [App!]! 
  # 【AQ2】: 查询我可访问的应用列表
  userApps(user:String): [App!]! 
  # 【TQ1】: 查询可安装/已安装的"应用标准件模版"列表
  appTemplates(filter: AppTemplateFilter) : [AppTemplate!]!
  # 【TQ2】: 按应用模版ID查询"应用标准件模版" 
  appTemplate(id: String!) : AppTemplate! 
  # 【RQ1】: 查询应用评价
  appReviews(filter: AppReviewFilter): AppReviewConnection
  # 【RQ2】: 查询我的应用评价
  userAppReviews(user:String, filter: AppReviewFilter): AppReviewConnection
}

Mutation

type Mutation {
    # 【AM1】：新建应用
    createApp(user:String, app: AppInput!): App!
    # 【AM2】：删除应用
    deleteApp(user:String, id: String!): App!
    # 【AM3】：更新应用：调整名称、分类、上下线
    updateApp(user:String, id: String!, app: AppInput!): App!
    # 【TM1】：应用模版激活。如不指定版本，使用当前发布版本 
    activateApp(user:String, template: String!, version:String, patch:String, option:AppUpgradeOption): [App!]!
    # 【TM2】：应用升级，版本号必须指定 
    upgradeApp(user:String, template: String!, version:String!, patch:String, option:AppUpgradeOption): [App!]!
    # 【TM3】: 取消应用激活。对于由模版创建的应用，删除前需先"取消激活"。
    deactivateApp(user:String, template:String!): [App!]!
    # 【RM1】：新建应用评价
    createAppReview(user:String, review: AppReviewInput!): AppReview!
    # 【RM2】：删除应用评价
    deleteAppReview(user:String, id: String!): AppReview!
    # 【RM3】：更新应用评价
    updateAppReview(user:String, id: String!, review: AppReviewInput!): AppReview!
}

Params

• 通用GraphQL参数说明：
  • user：对于用户授权的token无需给出，应用授权token调用用户数据时给出
  • patch: 参考QPatch协议
• 通用URL参数说明：
  • tenant：对于多租户应用的token中无租户信息时才需给出，参考Multitenancy

Types

# 工作区配置
type WorkspaceConfiguration {
    # 版本号
    # 当前定义版本为 20240618
    apiVersion: Int
    # 保留
    features: [ String! ]
}

# 应用
type App {
    id:ID                 # 无意义的唯一id
    name:String!          # 应用机读名称
    uri:String            # 应用首页uri
    text:String!          # 应用名称
    kind:String           # 应用类型（按来源）：[oauth|static|canvas|workflow|exam|survey|checkin]
    trait:String.         # 应用分类（按特征）
    code:String           # 应用开发工具端的标识，如client_id、工作流代码等
    abbreviation:String   # 缩略名
    description:String    # 应用简介
    tags:String           # 应用标签，可以有多个，以逗号分隔，第一个作为主分类
    icon:String           # 图标uri
    palette:String        # 图标调色板颜色，形如：#ff0000
    department:String     # 主管部门描述
    contact:String        # 联系人及其方式描述
    telephone:String      # 联系电话，2023/11 新增
    recommend:Int         # 推荐度，整数
    rating:Int            # 评价汇总，0到100分
    rated:Int             # 评价次数
    system:String         # 所属系统
    uriAdmin:String       # 管理端uri 
    # uriDevel:String       # 开发端uri，2024/03 废弃
    release:Boolean       # 应用是否发布
    visible:Boolean       # 应用是否可见
    created:Int           # 创建时间
    updated:Int           # 更新时间 
    # 当前启用版本
    currentVersion: AppVersion
    # 版本列表
    versions: [AppVersion!]
    # 可选，由应用模版创建的应用才会有此信息。查询时只需给出 name 等基础信息
    template: AppTemplate
    # 可选，对应的应用模版入口，由应用模版创建的应用才会有此信息。查询时只需给出 name 等基础信息
    templateEntry: AppEntry 
    # 额外的应用入口信息
    extraEntries: [ AppEntry ]
    # 可访问该应用的用户身份列表。语法参考：[UserFilter](https://github.com/infoplus/docs/wiki/UserFilter)
    userFilters: [ String! ]
    # 用户当前身份和上述 userFilters 的交集，仅使用用户授权 token 时给出
    # 注意此处可能有包含关系，比如应用允许 `学生` 访问，用户是 `本科生`，则此处内容为 `本科生`
    userFiltersMatched: [ String! ]
    # 应用构件列表
    blocks: [ AppBlock! ]
}
   
# 应用模版
type AppTemplate {
    name:ID                    # 应用模版机读名称
    text:String!               # 应用模版名 
    description:String         # 应用模版简介
    # 应用类型枚举：
    #  canvas: 数据类应用 
    #  workflow：流程类应用 
    #  exam：考试类应用 
    #  survey：问卷类应用 
    #  checkin：签到类应用 
    kind:String! 
    tags:String                # 标签
    autoActivate: Boolean      # 是否新开租户时自动激活 
    autoUpgrade: Boolean       # 是否自动升级
    product: Product           # 所属产品信息
    currentVersion:ProductVersion  # 当前启用版本
    versions:[ProductVersion!]     # 版本列表
    entries: [AppEntry!]       # 应用入口列表
}

# 应用版本
type AppVersion {
    # 应用版本ID
    name: ID!
    # 版本发布时间
    timestamp: Int
    # 是否当前版本
    current: Boolean
}


# 应用入口
type AppEntry {
    name: ID!               # 入口标识，用于部分API
    uri: String!            # 入口链接
    icon:String             # 入口图标链接
    text: String            # 入口文字
    description: String     # 入口描述
    tags: String            # 入口标签
    # 支持屏，空集视为不限
    #   desktop ： 桌面端
    #   mobile  ： 移动端（所有非桌面端）
    #     ios     ： 苹果原生App
    #     android ： 安卓原生App
    #     wechat  :  微信（含企业微信）
    #       wechat_pc  ： 微信PC端
    screens: [String!]
    # 支持用户列表。语法参考：[UserFilter](https://github.com/infoplus/docs/wiki/UserFilter)
    userFilters: [String!]
    # 激活此应用入口的依赖项，比如依赖于infoplus流程或其他子QCanvas 
    dependencies: [AppEntryDependency!]
    # 该入口对应的应用构件列表，202310新增
    blocks: [ AppBlock! ]
}

# 应用入口激活依赖项
type AppEntryDependency {
    # 应用模版ID，可用于activateApp的template参数
    name: ID!               
    # 激活该应用的服务名，参考https://github.com/ketanyun/docs/wiki/QService
    # 目前支持：infoplus、answer、maker
    service: String!        
}

# 有一定业务独立性的应用构件。202310新增
# 可以是一个菜单、一个流程步骤、一组功能等。一般可以独立授权
type AppBlock {
    name: ID!               # 机读标记
    text: String!           # 人读显示名称
    # 构件类型，比如：
    # node ：流程节点
    # menu ：菜单项
    kind: String
    # 可选，该构件的访问链接
    uri: String  
    # 可选，父构件标识（name）
    parent: String 
    # 可使用该构件的用户身份列表 
    userFilters: [ String! ]
    # 用户当前身份和上述 userFilters 的交集，仅使用用户授权 token 时给出
    # 注意此处可能有包含关系，比如应用允许 `学生` 访问，用户是 `本科生`，则此处内容为 `本科生`
    userFiltersMatched: [ String! ]
}

# 产品
type Product {
    id:String                  # 无意义的唯一id
    name:String!               # 产品机读名称
    text:String!               # 产品名称
    description:String         # 产品简介
    created:Int                # 创建时间
    updated:Int                # 更新时间
    tags:String                # 标签
    chart: ProductChart            # 产品包信息
    market: AppMarket              # 所属应用市场信息，可选
    currentVersion:ProductVersion  # 当前启用版本
    versions:[ProductVersion!]     # 版本列表
}

# 产品包信息
type ProductChart {
    name: String!           # Chart名
    text: String            # Chart人读名称
    release: String         # 安装时的Release名
}

# 应用/应用模版的一个版本
type ProductVersion {
    name: ID!             # 机读版本号
    text: String          # 人读版本号，如20210504
    timestamp: Int        # 版本发布时间
    activated: Boolean    # 是否激活（当前查询租户）
    chartVersion: String  # 对应的Chart版本号，仅Chart安装提供
}

# 产品市场
type AppMarket {
    # 应用市场机读代码
    name: ID!
    # 应用市场名称
    text: String
}

# 输入类型：应用筛选器
input AppFilter {
    # 按ID查询
    id: StringFilter
    # 按部门查询
    dept: StringFilter
    # 按显示名查询
    text: StringFilter
}

# 输入类型：应模版用筛选器
input AppTemplateFilter {
    # 按ID查询
    id: StringFilter
    # 按部门查询
    dept: StringFilter
    # 按显示名查询
    text: StringFilter
}

# 应用输入信息
input AppInput {
    # 应用显示名
    text: String
    ...
    # 是否上线
    release: Boolean
    # 上/下线版本
    releaseVersion: String 
    # 是否可见 
    visible: Boolean
    # 发布到的屏，不给出或者为空表示不限制
    screens: [String!] 
    # 发布到的用户范围，不给出或者为空表示无人可见 
    userFilters: [String!]
}

• 应用评价相关类型

# 应用评价
type AppReview {
    name: ID!             # 机读ID
    rate: Int             # 评分，0-100
    text: String          # 评论
    user: AppReviewer     # 评价人 
    created:Int           # 创建时间
    updated:Int           # 更新时间
}

# 评价人信息
type AppReviewer {
    # 用户账号
    account: String 
    # 用户openid
    openid: String
    # 用户实名
    text: String 
}

# 应用评价Connection，用于分页
type AppReviewConnection {
    edges: [AppReviewEdge!]
    pageInfo: PageInfo
    totalCount: Int
}

# 应用评价Edge，用于分页
type AppReviewEdge {
    cursor: String
    node: AppReview
}

# 应用评价输入信息 
input AppReviewInput {
    rate: Int             # 评分，0-100
    text: String          # 评论
}

# 输入类型：应用筛选器
input AppReviewFilter {
    # 按应用查询
    app: StringFilter
}

# 输入类型：应用升级选项
input AppUpgradeOption {
    # 对数据不一致（缺人/岗/服务）的处理策略.可选值：[exception|ignore(默认)]
    consistency: String 
    # 即当应用模版配置和当前版本冲突时的处理策略。可选值：[exception(默认)|ignore|overwrite]
    conflict: String
}

type PageInfo {
    endCursor: String
    hasNextPage: Boolean
    hasPreviousPage: Boolean
    startCursor: String
}