工单管理 API

@cz 最后修改于 2020-09-29 14:56:18 rev.5770 - 最近修改

工单管理 API

概述

工单管理包含了提交工单，分派工单等功能.

系统前缀

API:

https://{domain-name}/v2/worksheet/

版本

V1.0

作者

@author ChengZhen

项目

项目属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	-	ObjectId	-	项目 ID
code	true	String	32	项目代号
content	-	String	-	项目内容，支持 Markdown 格式
created	true	Date	-	创建日期
description	-	String	100	项目简要描述
icon	true	String	32	项目图标
members	-	Array	-	项目成员
name	true	String	32	项目名称
ownerId	-	ObjectId	-	所属企业号 ID
status	true	String	32	项目状态
type	true	String	32	项目类型
updated	true	Date	-	最后更新日期

项目状态:

open 正在进行中的项目
closed 已关闭的项目

查询项目列表

GET /project/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	String	0	开始返回的记录的索引
limit	String	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
q	String	-	查询过滤条件
ownerId	ObjectId	-	所属的企业账号
status	String	-	项目状态

响应结果:

返回项目列表

{
    "total": Number,
    "stat": {
        "closed": Number,
        "created": Number,
        "resolved": Number,
        "started": Number
    },
    "projects": [{
        "id": String,
        "created": Date,
        "description": String,
        "icon": String,
        "name": String,
        "status": String,
        "updated": Date
    }]
}

创建一条新的项目

POST /project/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
description	-	String	项目简要描述
icon	-	String	项目图标
name	true	String	项目名称

响应结果:

返回创建的项目的内容

{
    "id": String,
    "created": Date,
    "description": String,
    "icon": String,
    "name": String,
    "status": String,
    "updated": Date
}

修改指定的项目

POST /project/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	OjbectId	项目 ID
description	-	String	项目简要描述
icon	-	String	项目图标
name	-	String	项目名称
status	-	String	项目状态

响应结果:

返回修改后的项目的内容

{
    "id": String,
    "created": Date,
    "description": String,
    "icon": String,
    "name": String,
    "status": String,
    "updated": Date
}

查询指定的项目

GET /project/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	项目 ID

响应结果:

返回项目内容

{
    "id": String,
    "created": Date,
    "description": String,
    "icon": String,
    "name": String,
    "status": String,
    "updated": Date
}

删除指定的项目

POST /project/del

不能删除已经包含有工单的项目

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	OjbectId	项目 ID

响应结果:

返回删除的项目的内容

{
    "id": String,
    "created": Date,
    "description": String,
    "icon": String,
    "name": String,
    "status": String,
    "updated": Date
}

工单

表示工作单

工单属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	-	ObjectId	-	工单 ID
activities	-	Array	-	虚拟属性, 工单动态列表
assigned	-	Date		受理时间
assignee	-	Object	-	受理人
attachments	-	Array	-	附件列表
code	true	String	32	工单编号
created	true	Date	-	创建日期
creator	-	Object	-	创建用户
description	-	String	200	问题描述
expiration	-	Date	-	截止日期
level	true	Number	-	优先级
ownerId	-	ObjectId	-	所属企业号 ID
projectId	-	ObjectId	-	项目
resolved	-	Date		解决时间
resolver	-	Object		解决者
resolution	-	String	32	解决方案
status	true	String	32	状态
target	-	Object	-	工单对象
title	true	String	32	工单标题
type	true	String	32	工单类型
updated	true	Date	-	最后更新日期

状态 - status：

created - 未受理
started - 受理中
resolved - 已解决
closed - 已关闭

优先级 - level：

1 - 低
2 - 一般
3 - 高
4 - 紧急

工单类型 - type:

story
bug
epic
task

查询工单列表

GET /worksheet/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	String	0	开始返回的记录的索引
limit	String	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
select	String	-	选择要返回的字段
assignee	String	-	受理人名称
creator	String	-	创建人名称
ownerId	ObjectId	-	所属企业账号
projectId	ObjectId	-	所属项目ID
status	String	-	状态
targetId	String	-	处理对象 ID

响应结果:

返回工单列表

{
    "total": Number,
    "stat": {},
    "worksheets": [{
        "id": String,
        "assigned": Date,
        "code": Number,
        "created": Date,
        "description": String,        
        "level": Number,
        "resolved": Date,
        "status": String,
        "title": String,
        "updated": Date,
        "project": {
            "id": String,
            "name": String
        },
        "target": {
            "id": String,
            "type": String,
            "name": String
        },
        "creator": {
            "id": String,
            "username": String,
            "realname": String
        },
        "assignee": {
            "id": String,
            "username": String,
            "realname": String
        },
        "resolver": {
            "id": String,
            "username": String,
            "realname": String
        }
    }]
}

创建一条新的工单

POST /worksheet/add

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
description	-	OjbectId	工单描述内容
level	-	Number	优先级
projectId	-	OjbectId	所属项目 ID
title	true	String	工单标题

响应结果:

返回创建的工单的内容

{
    "id": String,
    "assigned": Date,
    "code": Number,
    "created": Date,
    "description": String,        
    "level": Number,
    "resolved": Date,
    "status": String,
    "title": String,
    "updated": Date,
    "project": {
        "id": String,
        "name": String
    },
    "target": {
        "id": String,
        "type": String,
        "name": String
    },
    "creator": {
        "id": String,
        "username": String,
        "realname": String
    },
    "assignee": {
        "id": String,
        "username": String,
        "realname": String
    },
    "resolver": {
        "id": String,
        "username": String,
        "realname": String
    }
}

修改指定的工单

POST /worksheet/update

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	OjbectId	工单 ID
action	true	String	操作类型
description	-	OjbectId	工单描述内容
level	-	Number	优先级
projectId	-	OjbectId	所属项目 ID
title	-	String	工单标题

响应结果:

返回修改后的工单的内容

{
    "id": String,
    "assigned": Date,
    "code": Number,
    "created": Date,
    "description": String,        
    "level": Number,
    "resolved": Date,
    "status": String,
    "title": String,
    "updated": Date,
    "project": {
        "id": String,
        "name": String
    },
    "target": {
        "id": String,
        "type": String,
        "name": String
    },
    "creator": {
        "id": String,
        "username": String,
        "realname": String
    },
    "assignee": {
        "id": String,
        "username": String,
        "realname": String
    },
    "resolver": {
        "id": String,
        "username": String,
        "realname": String
    }
}

操作类型

assign 指派受理人
close 关闭这个工单
comment 评论这个工单
reopen 重新打开这个工单
resolve 解决这个工单
start 受理这个工单
edit 编辑这个工单

查询指定的工单

GET /worksheet/get

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	ObjectId	工单 ID

响应结果:

返回工单内容

{
    "id": String,
    "assigned": Date,
    "code": Number,
    "created": Date,
    "description": String,        
    "level": Number,
    "resolved": Date,
    "status": String,
    "title": String,
    "updated": Date,
    "project": {
        "id": String,
        "name": String
    },
    "target": {
        "id": String,
        "type": String,
        "name": String
    },
    "creator": {
        "id": String,
        "username": String,
        "realname": String
    },
    "assignee": {
        "id": String,
        "username": String,
        "realname": String
    },
    "resolver": {
        "id": String,
        "username": String,
        "realname": String
    },
    "activities": [{
        "id": String,
        "message": String,
        "type": String,
        "created": Date,
        "updated": Date,
        "target": {
            "id": String,
            "code": Number,
            "title": String
        },
        "user": {
            "id": String,
            "username": String,
            "realname": String
        }
    }]
}

删除指定的工单

POST /worksheet/del

请求参数:

NAME	REQUIRED	TYPE	DESCRIPTION
id	true	OjbectId	工单 ID

响应结果:

返回删除的工单的内容

{
    "id": String,
    "assigned": Date,
    "code": Number,
    "created": Date,
    "description": String,        
    "level": Number,
    "resolved": Date,
    "status": String,
    "title": String,
    "updated": Date,
    "project": {
        "id": String,
        "name": String
    },
    "target": {
        "id": String,
        "type": String,
        "name": String
    },
    "creator": {
        "id": String,
        "username": String,
        "realname": String
    },
    "assignee": {
        "id": String,
        "username": String,
        "realname": String
    },
    "resolver": {
        "id": String,
        "username": String,
        "realname": String
    }
}

动态

动态属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	-	ObjectId	-	动态 ID
created	true	Date	-	创建日期
details	-	Object	-	详细信息
message	true	String	32	动态备注
ownerId	-	ObjectId	-	所属企业号 ID
projectId	-	ObjectId	-	所属项目 ID
target	-	Object	-	虚拟属性, 相关工单
targetId	-	ObjectId	-	相关的工单的 ID
type	true	String	32	动态类型
updated	true	Date	-	最后更新日期
user	-	Object	-	相关用户

查询动态列表

GET /activity/list

请求参数:

NAME	TYPE	DEFAULT	DESCRIPTION
offset	String	0	开始返回的记录的索引
limit	String	100	最多返回的记录数
order	String	asc	排序方式 (asc, desc)
orderBy	String	-	排序字段名
select	String	-	选择要返回的字段
ownerId	ObjectId	-	所属企业号 ID
projectId	ObjectId	-	所属项目 ID
targetId	String	-	所属工单 ID
type	String	-	动态类型

响应结果:

返回工单列表

{
    "total": Number,
    "stat": {},
    "activities": [{
        "id": String,
        "message": String,
        "type": String,
        "created": Date,
        "updated": Date,
        "target": {
            "id": String,
            "code": Number,
            "title": String
        },
        "user": {
            "id": String,
            "username": String,
            "realname": String
        }
    }]
}

版本

对于软件项目可以创建版本

版本属性列表

NAME	SORTABLE	TYPE	MAX	DESCRIPTION
id	-	ObjectId	-	动态 ID
name	true	String	-	版本名称
created	true	Date	-	创建日期
started	true	Date	-	开始日期
released	true	Date	-	发布日期
description	-	String	-	描述
status	true	String	-	状态
progress	-	String	-	进度
updated	true	Date	-	最后更新日期

统计

查询统计信息

GET /system/stat

返回统计信息

{
    "total": Number,
    "all": {
        "closed": Number,
        "created": Number,
        "resolved": Number,
        "started": Number,
        "total": Number
    },
    "projects": [{
        "icon": String,
        "id": String,
        "name": String, 
        "status": String,
        "closed": Number,
        "created": Number,
        "resolved": Number,
        "started": Number,
        "total": Number
    }]
}

查询服务信息

GET /system/status

返回服务信息

{
    "name": String,
    "version": String,
    "descriptoin": String,
}