wangzengming
/
light-databoard
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '4eb432c321'
${ noResults }
light-databoard/docs/ticket_api.md

14 KiB
Raw Blame History Escape

工单模块接口文档

工单列表接口

Method

  • /ticket/list

请求参数示例:

{
    "jsonrpc": "2.0",
    "method": "/ticket/list",
    "params": {
        "page": 1,
        "page_size": 20,
        "status": ["new", "in_progress"],
        "start_time": "2024-03-01T00:00:00Z",
        "end_time": "2024-03-15T23:59:59Z"
    },
    "session": "viFuv4G2XJMxO4GIIsVfbJ2eKwy6QyuWLXmqZY69dy0G9iTY",
    "timestampin": "1706325301436"
}

参数说明:

参数名 类型 说明 必填 备注
page integer 当前页码 否 默认1
page_size integer 每页记录数 否 默认20，最大100
status string[] 过滤状态列表 否 多个状态组合查询
priority string[] 过滤优先级列表 否 low/medium/high
start_time string 创建时间范围-开始时间 否 RFC3339格式
end_time string 创建时间范围-结束时间 否 RFC3339格式

成功响应示例:

{
    "jsonrpc": "2.0",
    "result": {
        "count": 15,
        "rows": [
            {
                "id": 123,
                "title": "网络故障报修",
                "status": "in_progress",
                "priority": "high",
                "creator_id": 1001,
                "created_name": "张三",
                "updated_name": "李四",
                "created_at": "2024-03-13T09:15:00Z",
                "updated_at": "2024-03-14T10:30:00Z",
                "contact_info": "13800138000",
                "fault_time": "2024-03-13T09:00:00Z",
                "expected_completion_time": "2024-03-13T10:00:00Z",
                "handler": "王五",
                "images": ["http://example.com/image1.jpg", "http://example.com/image2.jpg"],
                "dispatch_time": "2024-03-13T09:10:00Z",
                "process_time": "2024-03-13T09:30:00Z"
            }
        ]
    },
    "error": {
        "message": "ok",
        "code": 200
    }
}

返回参数说明:

参数名 类型 说明 备注
count int 总记录数
rows object[] 工单记录列表

rows字段说明

参数名 类型 说明 备注
id int 工单ID
title string 工单标题 最大长度100字符
status string 当前状态 字符串枚举值
priority string 优先级 low/medium/high
creator_id uint 创建人ID 关联账户系统
created_name string 创建人姓名 从账户系统获取
updated_name string 最后修改人姓名 从账户系统获取
created_at string 创建时间 RFC3339格式
updated_at string 最后更新时间 RFC3339格式
contact_info string 联系方式 需格式校验
fault_time string 故障发生时间 RFC3339格式
expected_completion_time string 预计完成时间 RFC3339格式
handler string 处理人员 最大长度100字符
images string[] 故障图片列表 图片URL数组
dispatch_time string 派单时间 RFC3339格式
process_time string 处理时间 RFC3339格式

错误响应示例:

{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "无效的时间格式",
        "code": 400,
        "data": {
            "field": "start_time"
        }
    }
}

创建工单接口

消息协议

  • JSONRPC-2.0

Method

  • /ticket/create

请求参数示例:

{
    "jsonrpc": "2.0",
    "method": "/ticket/create",
    "params": {
        "title": "网络故障报修",
        "description": "<p>办公室A区网络中断</p>",
        "source": "市民举报",
        "priority": "high",
        "status": "new",
        "creator_id": 1001,
        "device_id": 5001,
        "contact_info": "13800138000",
        "fault_time": "2024-03-13T09:00:00Z",
        "expected_completion_time": "2024-03-13T10:00:00Z",
        "handler": "王五",
        "images": ["http://example.com/image1.jpg", "http://example.com/image2.jpg"],
        "dispatch_time": "2024-03-13T09:10:00Z",
        "process_time": "2024-03-13T09:30:00Z"
    },
    "session": "viFuv4G2XJMxO4GIIsVfbJ2eKwy6QyuWLXmqZY69dy0G9iTY",
    "timestampin": "2024-03-13T09:15:00Z"
}

参数说明:

参数名 类型 说明 必填 备注
title string 工单标题 是 最大长度100字符
description string 工单描述（富文本） 是 需进行HTML消毒处理
source string 来源渠道 是 市民举报/巡检发现/监控系统
priority string 优先级 是 low/medium/high（字符串枚举）
status string 工单状态 是 new/reviewed/dispatched/assigned/in_progress/completed/closed/rejected
creator_id uint 提交用户ID 是 对应账户系统的用户ID
device_id uint 关联设备ID 是 设备管理系统中的设备ID
contact_info string 联系方式 是 根据类型格式校验
fault_time string 故障发生时间 是 RFC3339格式
expected_completion_time string 预计完成时间 否 RFC3339格式
handler string 处理人员 否 最大长度100字符
images string[] 故障图片列表 否 图片URL数组
dispatch_time string 派单时间 否 RFC3339格式
process_time string 处理时间 否 RFC3339格式

成功响应示例:

{
    "jsonrpc": "2.0",
    "result": {
        "id": 123,
        "title": "网络故障报修",
        "description": "<p>办公室A区网络中断</p>",
        "source": "市民举报",
        "priority": "high",
        "creator_id": 1001,
        "status": "new",
        "fault_time": "2024-03-13T09:00:00Z",
        "expected_completion_time": "2024-03-13T10:00:00Z",
        "handler": "王五",
        "images": ["http://example.com/image1.jpg", "http://example.com/image2.jpg"],
        "dispatch_time": "2024-03-13T09:10:00Z",
        "process_time": "2024-03-13T09:30:00Z",
        "created_at": "2024-03-13T09:15:00Z",
        "updated_at": "2024-03-13T09:15:00Z"
    },
    "error": {
        "message": "ok",
        "code": 200
    }
}

错误响应示例:

{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "缺少必填参数: title",
        "code": 400
    }
}

状态流转规则:

  1. 新建(new) → 已派发(dispatched) | 已驳回(rejected)
  2. 已派发(dispatched) → 已分配(assigned)
  3. 已分配(assigned) → 处理中(in_progress)
  4. 处理中(in_progress) → 已完成(completed)
  5. 已完成(completed) → 已关闭(closed)
  6. 所有状态均可变更为已关闭(closed)

修改工单接口

Method

  • /ticket/update

请求参数示例:

{
    "jsonrpc": "2.0",
    "method": "/ticket/update",
    "params": {
        "id": 123,
        "title": "更新后的故障描述",
        "description": "<p>网络故障已定位到交换机</p>",
        "status": "in_progress",
        "priority": "medium",
        "updater_id": 1002,
        "fault_time": "2024-03-13T09:00:00Z",
        "expected_completion_time": "2024-03-13T10:00:00Z",
        "handler": "王五",
        "images": ["http://example.com/image1.jpg", "http://example.com/image2.jpg"],
        "dispatch_time": "2024-03-13T09:10:00Z",
        "process_time": "2024-03-13T09:30:00Z"
    },
    "session": "viFuv4G2XJMxO4GIIsVfbJ2eKwy6QyuWLXmqZY69dy0G9iTY",
    "timestampin": "1706325301436"
}

成功响应示例:

{
    "jsonrpc": "2.0",
    "result": {
        "id": 123,
        "title": "更新后的故障描述",
        "description": "<p>网络故障已定位到交换机</p>",
        "status": "in_progress",
        "priority": "medium",
        "created_name": "张三",
        "updated_name": "王五",
        "created_at": "2024-03-13T09:15:00Z",
        "updated_at": "2024-03-14T14:20:00Z",
        "contact_info": "13800138000",
        "fault_time": "2024-03-13T09:00:00Z",
        "expected_completion_time": "2024-03-13T10:00:00Z",
        "handler": "王五",
        "images": ["http://example.com/image1.jpg", "http://example.com/image2.jpg"],
        "dispatch_time": "2024-03-13T09:10:00Z",
        "process_time": "2024-03-13T09:30:00Z"
    },
    "error": {
        "message": "ok",
        "code": 200
    }
}

错误响应示例:

{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "无效的状态变更: new → closed",
        "code": 400,
        "data": {
            "current_status": "new",
            "target_status": "closed"
        }
    }
}

删除工单接口

Method

  • /ticket/delete

请求参数示例:

{
    "jsonrpc": "2.0",
    "method": "/ticket/delete",
    "params": {
        "id": 123,
        "operator_id": 1002
    },
    "session": "viFuv4G2XJMxO4GIIsVfbJ2eKwy6QyuWLXmqZY69dy0G9iTY",
    "timestampin": "1706325301436"
}

参数说明:

参数名 类型 说明 必填 备注
id int 工单ID 是
operator_id uint 操作人ID 是 需校验删除权限

成功响应示例:

{
    "jsonrpc": "2.0",
    "result": {
        "id": 123,
        "deleted_at": "2024-03-15T14:30:00Z"
    },
    "error": {
        "message": "ok",
        "code": 200
    }
}

返回参数说明:

参数名 类型 说明 备注
id int 被删除工单ID

错误响应示例:

{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "无权删除该工单",
        "code": 403,
        "data": {
            "required_role": "admin"
        }
    }
}

特殊说明:

  1. 采用软删除机制，仅标记deleted_at字段
  2. 需校验操作人权限：
    • 工单创建人
    • 系统管理员角色
  3. 已关闭工单不可删除
  4. 返回204状态码时表示物理删除成功

工单流转接口

Method

  • /ticket/transition

请求参数示例:

{
    "jsonrpc": "2.0",
    "method": "/ticket/transition",
    "params": {
        "id": 123,
        "status": "in_progress",
        "operator_id": 1002,
        "comment": "开始处理故障",
        "handler": "王五"
    },
    "session": "viFuv4G2XJMxO4GIIsVfbJ2eKwy6QyuWLXmqZY69dy0G9iTY",
    "timestampin": "1706325301436"
}

参数说明:

参数名 类型 说明 必填 备注
id int 工单ID 是
status string 目标状态 否 不指定则自动流转到下一状态
operator_id uint 操作人ID 否 需校验操作权限
comment string 状态变更说明 否 最大长度500字符
handler string 处理人员 否 状态变更为assigned/in_progress时必填

自动流转规则:

  1. 新建(new) → 已派发(dispatched)
  2. 已派发(dispatched) → 已分配(assigned)
  3. 已分配(assigned) → 处理中(in_progress)
  4. 处理中(in_progress) → 已完成(completed)
  5. 已完成(completed) → 已关闭(closed)

状态流转规则:

  1. 新建(new) → 已派发(dispatched) | 已驳回(rejected)
  2. 已派发(dispatched) → 已分配(assigned)
  3. 已分配(assigned) → 处理中(in_progress)
  4. 处理中(in_progress) → 已完成(completed)
  5. 已完成(completed) → 已关闭(closed)
  6. 所有状态均可变更为已关闭(closed)

状态变更条件:

  1. 完成状态(completed)条件：
    • 必须已分配处理人员
    • 必须已开始处理（有处理时间）
  2. 关闭状态(closed)条件：
    • 必须处于完成状态
    • 不能超过预计完成时间

特殊说明:

  1. 状态变更必须符合流转规则
  2. 操作人必须具有相应权限
  3. 状态变更为assigned或in_progress时，必须指定处理人员
  4. 状态变更为in_progress时，系统会自动记录处理时间
  5. 状态变更为dispatched时，系统会自动记录派单时间
  6. 每次状态变更都会记录操作日志
  7. 不指定目标状态时，系统会自动流转到下一状态