# 接口规范

# 单应用接入

单应用接入时请提供应用访问的 url(原则上应以域名访问)以及是否需要访问控制，如果需要访问控制请提供需要访问的人员岗位信息。

# 系统集成接入

# 前言

本标准按照 GB/T 1.1—2009《标准化工作导则第 1 部分：标准的结构和编写》给出的规则起草。
请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。
本标准由上海交通大学网络信息中心提出并归口。
本标准起草单位：上海交通大学网络信息中心。
本标准主要起草人：王罡、蒋磊宏、杜晋博。

# 范围

本标准给出了独立运行的业务管理信息系统接入交我办的接口规范。
本标准适用于提供指定用户的待办任务等 5 类任务应提供的接口及输入输出规范。5 类任务包括：可办任务、待办任务、进行中任务、已完成任务、已办任务等。

# 规范性引用文件

下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件。
凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。
GB/T 4880.1 语种名称代码第 1 部分：2 字母代码
XB/SJTU 001—2020 单点登录接口规范

# 术语和定义

下列术语和定义适用于本文件。

# jAccount 账号

jAccount 账号是用户登录上海交通大学校内网站的身份认证统一账号，分为集体账号和个人账号。
集体账号常用于提供部门级服务，如部门服务邮箱，部门服务计费。个人账号提供用户校内身份认证，能关联用户在校内当前和曾经拥有的全部身份，如学生、教职工、博士后、校友等身份。一个个人 jAccount 账号必须设置默认身份，以便校内应用判定当前用户登录身份的优先选择。

# 可办任务

可办任务是指用户可以在业务管理信息系统中发起办理的业务功能点。

# 待办任务

待办任务是指业务管理信息系统中正在等待用户处理的业务流程环节。

# 进行中任务

进行中任务是指用户曾办理目前尚未完成的业务流程。

# 已完成任务

已完成任务是指用户曾办理，且当前已完成的业务流程。

# 已办任务

已办任务是指用户曾办理的业务流程，不区分是否已经完成。

# 任务详情

任务详情指已办任务的详细步骤列表。

# 缩略语

下列缩略语适用于本文件。
URI 统一资源标识符（Uniform Resource Identifier）
URL 统一资源定位符（Uniform Resource Locator）
GUID 全局唯一标识符（Globally Unique IDentifier）

# 接口技术要求

# 概述

　　交我办通过整合数据资源和业务流程，将学校管理和服务涉及到的众多业务集中在网上服务大厅进行展示和运行，包括网站和移动APP形式提供的服务大厅。
　　接入交我办的业务管理信息系统可根据自身情况，选择提供指定用户的待办等5类任务中的一类或多类，其中进行中任务、已完成任务和已办任务应同时选择或同时不选择。
　　本文件给出了业务管理信息系统在向交我办提供指定用户的待办等任务信息时应提供的接口及输入输出规范，本接口将被交我办的服务端调用，完成业务系统的服务入口和待办等任务与交我办的整合。任意一项接口均以HTTP GET的方式提供，接口地址由业务管理信息系统自行指定。

# 性能要求

　　为保障用户的访问体验，所有接口对单个用户查询的最长响应时间不应超过3秒，超时的响应将被丢弃。发生超时响应时，对应接口所提供的任务将不被显示，交我办网站/App同时会提示用户相关业务管理信息系统响应超时。
　　业务管理信息系统应尽可能优化接口性能，交我办根据用户体验的要求可能随时调整该时限的具体值。

# 输入参数

适用于所有接口的输入参数：

以下参数适用于所有接口，用于告知接口所查询的用户信息以及返回数据期望的语言。交我办将在业务管理信息系统提供的接口地址上附加以下 URL 参数：

参数	说明
userId	用户的 jAccount 账号。该参数有且仅有一个。
occupy	用户的身份/岗位信息。该参数有且仅有一个。以冒号分隔的校内组织机构部门代码、身份类型以及该类型下的编号。如果用户有多个身份类型，则多个值之间用逗号分隔。
locale	请求返回数据的语种代码，应遵守 GB/T 4880.1，如 zh 表示汉语（中文）。如果业务系统支持外国语，应返回和请求语言一致的语种代码，如果不支持或者被请求的语种不被支持，按业务管理信息系统支持的默认语种代码返回。

示例 1：

如果可办任务接口为 http://host/me/apps,则以下接口表示请求 marstone 在该业务系统中的所有可办任务：

http://host/me/apps?userId=marstone&occupy=40100:BuiltInFaculty:60630,40100:BuiltInService:60630 ,03000:BuiltInStudent:0120379004,03000:BuiltInStudentDoctor:0120379004
注：以上参数表示用户的 jAccount 为 marstone，该用户具有的身份为：
网络信息中心（部门代码：40100）的教职工，工号 60630，
网络信息中心（部门代码：40100）的在职教职工，工号 60630，
电院（部门代码：03000）的学生，学号 0120379004，
电院（部门代码：03000）的博士生，学号 0120379004。

交我办定义的身份类型见身份岗位代码表。

仅用于已办任务查询接口的输入参数：

以下参数仅适用于已办任务（含进行中任务和已完成任务）查询接口，用于告知接口对返回数据的进一步筛选、排序和分页需求。交我办将在业务管理信息系统提供的接口地址上附加以下 URL 参数：

参数	说明
start	返回数据的起始行。0 表示第一行
limit	返回数据的行数。
order	返回数据的排序。可能值为 create、update、action、auto，具体含义见后。
orderTimes	返回数据的时间范围。格式："1476000000~1477000000"，时间值以 Unix 时间戳指定，具体含义由 order 确定。
keyword	返回数据应匹配的搜索关键字，具体匹配逻辑由业务管理信息系统自定
sep	返回数据是否别人发起的，该参数为空表示返回全部数据，为 true 返回别人发起的数据，为 false 返回自己发起的数据

查询参数 order 的具体说明

取值	说明
create	根据业务流程的创建时间排序
update	根据业务流程的最后更新时间排序
action	根据用户最后一次参与该业务流程的时间排序
auto	视情况选择业务流程的最后更新时间（如果用户是该业务流程的发起人）或者用户最后一次参与该业务流程的时间（如果用户不是该业务流程的发起人）进行排序

以上查询参数除 orderTimes 以外，业务管理信息系统必须全部支持。对于排序规则 order，业务管理信息系统可以视自身情况选择性支持其中几种，对于不能支持的排序类型，可对应为其他能够支持的排序类型，不应报错，且必须保障结果为稳定的。

# 响应数据

所有接口的响应的数据格式为 JSON，应符合以下通用格式：

Response<T>
{
  "errno":{int}, //0 表示成功，否则表示失败
  "error":{string}, //human-readable 错误信息
  "total":{int}, //当分页参数被使用时，返回不分页情况下的总数
  "entities":[{T 对象}] //返回的实体列表，非列表情况的实体存储于 enities[0]中
}

1
2
3
4
5
6
7

其中 entities 所包含的 T 对象定义见各个接口说明。其中 T 对象，对于可办任务指 App、待办任务指 Task, 进行中任务、已完成任务和已办任务指 Process，具体定义见可办任务、待办任务和进行中任务、已完成任务和已办任务。

# 可办任务

可办任务的入口宜为 app，返回的对象为 App，App 对象表示一个服务事项。以“奖学金申请”为例的可办任务 App 对象接口数据结构定义见示例 2：

示例 2： “奖学金申请”为例的可办任务，App 对象的数据结构定义如下：

App
{
  "id":{guid}, // 无意义的唯一 id，应为 GUID 格式，并保持稳定
  "name":{string}, //显示业务分类名称，如：奖学金申请
  "uri":{string}, //启动 uri
  "code":{string}, //应用代码，可用于部分 api 调用，表示该 app 的发布版
  "abbreviation":{string}, //缩略名
  "description":{string}, //服务摘要
  "tags":{string}, //应用标签，可以有多个，以逗号分隔
  "icon":{uri}, //图标 uri
  "palette":{string}, //调色板颜色，形如：#ff0000
  "department":{string}, //负责部门
  "contact":{string}, //联系人及其方式描述
  "online":{long}, //上线时间的时间戳，unix 时间戳
  "offline":{long}, //下线时间的时间戳，unix 时间戳
  "recommend":{integer}, //推荐度，可办任务按推荐度逆序排列
  "rating":{integer}, //评价汇总
  "rated":{integer}, //评价次数
  "visible":{boolean}, //是否可见
  "ready":{boolean}, //是否提供线上服务。默认为 false。交我办网站和 App 会特殊显示非线上服务
  "system":{string} //所属系统。工作流应用的此字段为空；用于区分管理学校内其他系统提供的“可办“
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

示例 2 中应提供的字段为：id、name、uri。
通过本接口提供的可办任务将出现在交我办大厅的指定分类下，具体的分类在接口接入学校任务中心时由网络信息中心指定。如需要为不同业务分类提供可办任务，需提供多个接口。
如接口需要为其提供的可办任务指定二级分类，需通过 tags 包含如下特殊标签：
#CategoryName:{二级分类名称}
#CategoryOrder:{二级分类排序号}
#CategoryColumns:{二级分类下一行展示的任务数量}
#TypesMore:{其他分类，多个以|分隔}
#CategoryNameMore:{其他二级分类，多个以|分隔}
#CategoryOrderMore:{其他二级分类排序，多个以|分隔}
本接口应保障同一业务分类名称对应的排序号和任务数量一致，否则展示效果不可预知。二级分类按排序号正序排列，同一二级分类下可办任务按 recommend 逆序排列。更详细的标签说明请参考应用设置中标签的部分

# 待办任务

待办任务的入口宜为 todo，返回对象为 Task，Task 对象表示一个具体办理环节。以“小张的奖学金申请”中的“院系审核”待办任务为例，Task 对象的数据结构定义见示例 3：
示例 3： Task 对象的数据结构：

Task
{
  "id":{guid}, // 无意义的唯一 id，应为 GUID 格式，并保持稳定
  "name":{string}, //当前任务名，如："待审核"、"申请单填写"
  "uri":{string}, //展示表单所需的 uri
  "tags":{string}, //该任务的标签，可以有多个，以逗号分隔
  "description":{string}, //摘要
  "process":{process 对象}, //所属实例，见 5.7 中 Process 对象定义
  "assignUser":{profile 对象}, //指派给的用户，可能为空，表示未指定具体用户，见 5.8
  "assignTime":{long}, //指派时间，unix 时间戳
  "actionUser":{profile 对象}, //实际完成的用户，仅在进行中任务和已完成任务中有效
  "actionTime":{long}, //完成时间，unix 时间戳
  "actionName":{string}, //办理时选择的动作名称
  "expireTime":{long}, //超时时间，unix 时间戳
  "remark":{string}, //办理用户填写的备注信息
  "status":{int}, //状态：1.待做，2.已做，3.草稿
  "actions":[{ //可一键办理的步骤
    "id":{integer}, //actionId
    "name":{string}, //显示名
    "code":{string}, //action code
    "remarkRequired":{boolean}, //是否备注必填
  }]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Task 对象应提供的字段为：id、name、uri、process、assignTime、status。

注意

对于实现了待办接口的系统，为了在用户办理后该事项能自动从交我办的待办列表中消失，系统应发送任务更新消息，具体文档请参考

# 进行中任务、已完成任务和已办任务

进行中任务的入口宜为 doing，已完成任务的入口宜为 done，已办任务的入口宜为 completed。
请注意进行中任务、已完成任务和已办任务三个接口为一组，要在交我办上正确显示已办事项应该同时实现这三个接口。
这三个接口的返回对象均为 Process，Process 对象表示 App 对象的一个具体实例。以“小张的奖学金申请”为例，Process 对象的数据结构定义见示例 4：

示例 4： Process 对象的数据结构：

Process
{
  "id":{guid}, // 无意义的唯一 id，应为 GUID 格式，并保持稳定
  "name":{string}, //流程实例的名称
  "uri":{string}, //查看流程实例用到的 uri
  "tags":{string}, //该流程的标签，可以有多个，以逗号分隔
  "entry":{string}, //流程流水号
  "create":{long}, //流程的创建时间，unix 时间戳
  "update":{long}, //流程最后操作时间，unix 时间戳
  "sort":{long}, //流程的排序时间，unix 时间戳。见接口参数中对order的要求，该属性应提供实际用于排序的时间值。
  "app":{app 对象}, //所属应用，见 App 对象
  "owner":{profile 对象}, //所属用户，见 Profile 对象
  "status":{string}, //流程状态：doing、done、killed
  "rate":{int}, //评价星级，1-5
  "review":{string}, //评价内容
  "pendingTasks":{string}, //当前的待办
  "tasks":[{task 对象}] //任务列表
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

　　Process对象应提供的字段为id、name、owner、app.name，宜提供的字段为create、update、tasks以及task 对象中的actionUser、actionTime，以便正确显示任务信息和展开显示任务的办理历史过程。对于已办任务（含进行中任务和已完成任务）的接口，应该提供sort字段以便于实现多个业务系统数据的整合。
　　如果您的系统已办任务不包含任务详情列表，tasks对象请返回空数组[]。如果有任务列表，且实现了任务详情接口，那么tasks对象请返回null，此时用户在交我办pc或者app端点击已办任务详情时会请求任务详情接口。如果有任务列表，且没开发任务详情接口，可以在tasks数组中直接返回任务详情列表；如果无详情接口且直接返回所有任务会引发查询效率问题，建议直接返回空数组即可。
　　对于Process对象中的返回的task对象(或者任务详情接口返回的task对象)需要提供的字段id、name、uri、assignTime、actionTime、actionUser、actionName、status。

# 任务详情

任务详情入口宜为 process，任务 id 以参数 id 传递。接口返回对象为 Process，同已完成任务返回的数据结构，详情接口返回的 Process 对象的 tasks 应该已填充该事项的所有详细任务，其数据接口为 Task。

# Profile 对象

Profile 对象表示一个用户，在 Task 对象和 Process 对象中均使用到，其定义如下：

Profile
{
  "name":{string}, //用户姓名
  "account":{string} //用户的 jAccount 账号
}

1
2
3
4
5

提供 Profile 对象时，仅应提供 account。

← 界面规范管理规定 →