千牛轻任务接入方案

接口小二：凡天（PD）、震子（开发） 

一、轻任务概述：

    轻任务是基于千牛消息机制的一种业务任务的创建、分派、追踪、处理、提醒、反馈的轻量化机制，目的在于链接多端、多角色、多流程的协同工作。

    基础场景举例如下：

1、某客服在交易插件中针对订单发起轻任务，说明该订单需要退款，同时指派给售后进行处理，任务新建完成后，该售后会及时收到弹窗提醒，点击就可以回到相应的订单处理页面。

2、c店店主外出时接待了某个客户，承诺回去处理这个客户的订单，直接在聊天窗口新建任务给自己，回去后在PC上打开任务中心，可以查到该条“待办任务”，点击任务单元，可以快速的呼起该客户的聊天窗口，及时处理后续事务。或者指派给在电脑面前的同事，让其继续接待该用户。

3、子账号操作某业务插件没有权限时，会自动提醒是否申请权限，主账号收到审批任务之后，点击跳转到审批详情页，操作并保存后，任务自动完成。

4、某账号在消息中心收到退款消息，点击“转为任务”，指派给某同事处理。

5、对中差评的场景提前设定好任务模板，默认选择了任务处理人、任务内容之后，勾选自动任务，一旦中差评出现，系统将自动按照原先预设置的任务内容指派提醒指定处理人。（预设置模板正在开发中，后续能够支持PC端及移动端）

二、轻任务在客户端的展现形式

    千牛PC客户端（2.02.00N以上）和千牛移动客户端（iOS_v2.4、Android_v2.3版本以上）会包含完整的轻任务功能。

1、千牛PC客户端的轻任务展现

a)   工具栏插件(在插件中心的工具栏插件下，启用名为“任务中心”的官方插件)：

 

b)   桌面插件(在小工具下启用名为“任务中心”的官方插件):

c)   新建任务组件（即将升级）：

d)   处理和转发任务组件：

2、    千牛移动客户端的轻任务展现

以IOS端为例，任务中心：

        

   

处理任务组件：                    新建任务组件：

           

三、ISV插件的轻任务接入方法

1、千牛PC客户端的接入方法

以交易插件为例，ISV需要在工具栏插件、旺旺插件两处接入接入轻任务：

 

l  已关联轻任务的订单，在订单列表项或订单详情页面展示“处理任务”入口

l  未关联轻任务的订单，在订单列表项或订单详情页面增加“新建任务”入口

 

具体做法是：

?  根据订单号通过轻任务接口搜索，查看是否已经关联轻任务。具体接口见下文taobao.qianniu.tasks.get的介绍。

?  轻任务接口支持批量订单号的查询，可通过一次接口调用返回整个订单列表的轻任务关联情况。

?  对于有关联轻任务的订单，需要展示处理任务入口。官方提供统一的任务处理组件。

?  对于还没有关联任务的订单，需要增加创建任务的入口。官方提供统一的任务创建组件。

 

基本入口部署的要求，以下面这款PC交易插件为例：

?  要求在订单列表单元必须有清晰的任务入口：在未有任务时，显示“添加任务”，有关联任务时，显示“处理任务”；官方不对样式、颜色做严格要求；

?  添加任务、处理任务、转交任务、添加备注都仅支持官方组件的形式调用，允许ISV通过API调用的方式，前置完成、删除等操作；

?  “添加任务”时，允许带参传入，支持任务内容、任务类型、处理人等所有属性单元；

?  每个业务ID（订单、客户）限定只能有一条任务，允许ISV进行批量添加任务；

?  ISV可以根据自己业务需要，调用官方“任务中心”页面，支持参数传入的筛选展示。也允许ISV自己开发一个“任务管理”页面，范例如下图所示：

 

旺旺插件部分，基本入口部署的要求如下所示：

?  同工具栏插件相同，要求在订单列表单元必须有清晰的任务入口；

?  如果业务方的样式是采用列表的形式，空间有限，如上图最右侧所示，要求鼠标移动到“处理任务”页面上时，能够tips展示任务内容，点击之后呼起“处理任务”组件；

 

2、千牛移动插件的接入方法

千牛移动的接入方式与PC端类似，以交易插件为例，ISV插件需要在以下两个地方接入轻任务：

 

l  已关联轻任务的订单，在订单列表项或订单详情页面展示“处理任务”入口

l  未关联轻任务的订单，在订单列表项或订单详情页面增加“新建任务”入口

 

具体做法是：

?  根据订单号通过轻任务接口搜索，查看是否已经关联轻任务。具体接口见下文taobao.qianniu.tasks.get的介绍。

?  轻任务接口支持批量订单号的查询，可通过一次接口调用返回整个订单列表的轻任务关联情况。

?  对于有关联轻任务的订单，需要展示处理入口。官方提供统一的任务处理组件。

?  对于还没有关联任务的订单，需要增加创建任务的标记。官方提供统一的任务创建组件。

基本入口部署的要求，以下面某款交易插件为例：

 

?  要求在订单列表单元及订单详情页必须有清晰的任务入口：添加任务或者处理任务；

?  在订单详情页，当有任务存在时，横栏展现任务内容，点击可以呼起处理组件；

?  移动端的“新建任务”、“处理任务”仅支持官方组件的形式调用；

 

四、轻任务主要接口及组件参数

1、数据结构

先向大家介绍一下，轻任务包含2部分数据，一个是任务元数据taskMeta，一个是任务数据task。例如，主帐号发起1个任务给2个子帐号，则会产生1条任务元数据和2条任务数据。

Task属性介绍：

//open.taobao.com/apidoc/dataStruct.htm?path=scopeId:11279-dataStructId:21118-apiId:22594-invokePath:tasks

TaskMeta属性介绍：

//open.taobao.com/apidoc/dataStruct.htm?path=scopeId:11279-dataStructId:21117-apiId:-invokePath:.meta

在所有属性中，特别说明3个参数：

biz_type确定了业务的具体类型，biz_id确定的具体的操作对象。

 

下方为业务类型的具体定义：

业务类型		业务描述	业务标识biz_id	Biz_nick
member	ServiceChat	客户跟进	客户nick	客户nick
Item	ItemShelf	上下架	商品id
	ItemStock	库存处理
	ItemAudit	审核结果处理
	ItemRecommand	橱窗操作
	other	其它
trade	TradeModify	修改订单（价格/地址）	订单id	客户nick
	TradeDelay	延长收货时间
	TradeMoney	退款
	TradeReturn	退换货
	TradeShipQuery	问题件
	TradeInvoice	开发票
	TradeBadComment	中差评
	other	其它
fenxiao	Buy	采购管理
	Ship	收发货
	Return	退货退款
	other	其它
liangzi	Wave	波动跟踪
	Goal	目标管理

注意：在您接入的时候，请与负责小二： 凡天 联系，确认使用的任务类型及相应的业务跳转行为。上述类型支持服务端快速配置扩展。

2、TOP接口

a)   任务查询读取接口taobao.qianniu.tasks.get：

//open.taobao.com/apidoc/api.htm?spm=0.0.0.0.AGLi4n&path=scopeId:11279-apiId:22594

一般情况下，只需要传入biz_type, status和biz_id三个参数。例如：在PC订单管理插件中，需要查询订单是否有未关联的任务，可使用如下查询：

QN.top.invoke({

              cmd: "taobao.qianniu.tasks.get",

              param: {

                   biz_type:”trade”,//订单管理

                   status:"0",//未完成

                   biz_ids:"123456,53453",//订单编号,支持多个，逗号分离

                   fields:"id,biz_id,biz_type,sender_nick",//需要返回的字段

              }

              success:function(rsp){},

              error:function(rsp){}

         });

千牛移动插件中调用方式请参考移动SDK。

3、轻任务组件

为了简化ISV开发过程，千牛官方提供了新增任务的组件(模块)和处理任务的组件(模块)，ISV通过sdk调用即可。下方为PC和移动千牛下的组件(模块)参数，使用方法请参见各平台的通用组件调用说明。

最后还附了一张通用协议的参数列表，待8月底将实现完全统一。

 

a)    PC轻任务组件调用参数

category	cmd	param	rsp	msg
'qtask_create' 轻任务创建组件	''	{ uuid:'组件标识', biz_type:'任务类型', items:[ {nick:‘客户nick’, biz_id:’订单号’} ] } 注：biz_id视场景而定，如订单任务中为订单ID，客户管理中为客户nick。items为数组，即支持批量创建，如同时传入多个订单。Biz_type请参见4.1节。	{ result:‘0/1’, meta_ids: [{biz_id: ’订单1’, meta_id:’123’}] } ※  result=“1”，任务全部创建成功，否则部分创建失败，成功部分写入meta_ids字段
'qtask_transfer' 轻任务转交组件	''	{ uuid:'组件标识', meta_ids:[‘123’,‘124’] }	{ result:‘0/1’, meta_ids:[‘123’,‘124’] }
'qtask_deal' 轻任务处理组件	''	{ uuid: '组件标识', task_ids:[’123’,‘124’,…] }	{ result:‘0/1’, task_ids:[‘123’,‘124’] }

b)   千牛移动轻任务模块调用方式

移动千牛使用如下跳转格式：

tbsellerplatform://?session_event=event_back_platform&module=module_qtask&sub_module=?&service_id=由参数组成的key-value串。其使用方法与通用跳转方式一致，请参照千牛移动开发手册。

 

 

具体参数为：

功能	模块名	子模块名	参数
创建任务	module_qtask	submodule_qtask_create	BizID=a&BizNick=b&BizType=c&SubBizType=d 注：biz_id视场景而定，如订单任务中为订单ID，客户管理中为客户nick。 Biztype和subbiztype请参见4.1节。 subbiztype可为空。
任务详情页 （含任务查看、处理与转发）	module_qtask	submodule_qtask_detail	MetaID=123 任务元ID
任务列表	module_qtask	submodule_qtask_list	index = 0 表示需要跳到我的待办还是我的安排中的哪个tab，0表示待办 1表示安排

 

可以使用openUrl跳转链接的方式：

tbsellerplatform://?session_event=event_back_platform&module=?&sub_module=?&service_id=?

其中：service_id为所有参数拼起来的encode串。

例如调创建任务模块，那service_id就是BizID=a&BizNick=b&BizType=c整个串经过urlencode后的值。

 

在千牛这边的通用协议支持后，PC和移动统一后的轻任务通用协议参数列表。请注意，只有特定版本以上的千牛客户端才支持通用协议。通用协议部分可以咨询旺旺 朱棣。

通用协议	参数	说明	原模块名/组件名/插件名
任务中心/任务列表	uuid	调用序列号，由调用方自定义。客户端保证同一序列号的窗口不会打开多个。PC端需要。	PC插件 renwuzhongxin 移动模块 module_qtask submodule_qtask_list
	index	列表定位，0进入我的待办，1进入我的安排。
	biz_nick	搜索的关键词，当前仅PC支持。
	status	仅PC端支持此参数，表示任务状态。0表示未完成， 2表示完成。
任务创建	uuid	调用序列号，由调用方自定义。客户端保证同一序列号的窗口不会打开多个。PC端需要。	PC组件： 'qtask_create' 移动模块： module_qtask submodule_qtask_create
	items	Json数组格式的字符串，支持批量创建。其中，biz_id, biz_nick, biz_type为必填，其它字段为选填。批量创建时多个任务共用第一个任务体的选填内容。注意大小写，为了与任务field匹配，均采用小写。 例： [{biz_id:订单编号, biz_nick:买家nick, biz_type:”trade”, content:”任务内容”, remind_time:”提醒时间” priority:0, receiver_nick:”接收人的nick,支持多个人,用逗号分离”},{这里是第二个任务}]
任务详情/任务处理	uuid	调用序列号，由调用方自定义。客户端保证同一序列号的窗口不会打开多个。PC端需要。	PC组件： qtask_deal 移动： module_qtask submodule_qtask_detail
	meta_ids	任务元ID，多个用逗号分离。目前仅PC端支持批量。

 

4、权限包的说明

我们优先推荐大家使用上述提到的组件，以统一处理过程。此外，下述基础包已经和千牛基础权限包合并开放：

 

基础包：

taobao.qianniu.tasks.get 读取我处理的任务，支持复杂搜索

taobao.qianniu.tasks.count读取我处理的任务的条数，支持复杂搜索

taobao.qianniu.taskmetas.get 读取任务元，主要场景是读取我安排的任务，支持复杂搜索

taobao.qianniu.taskmetas.count 读取任务元条数，主要场景是读取我安排的任务的条数，支持复杂搜索

taobao.qianniu.task.message.send 发消息催一下处理人

taobao.qianniu.task.remove 删除处理的任务

taobao.qianniu.task.comments.get 读取任务备注

taobao.qianniu.task.finish 完成任务

taobao.qianniu.tasks.latest 最近处理的任务

taobao.qianniu.tasklist.count 获取指定业务的任务条数

taobao.qianniu.tasklist.biz.latest 获取指定业务id的最近任务列表

taobao.qianniu.tasklist.biz.get 获取指定业务id的任务列表

taobao.qianniu.tasklist.get 获取指定业务的任务列表

 

 

FAQ

关于此文档暂时还没有FAQ