获取工单追踪记录 API

路径: /api/v3/get_traces
方法: GET
功能: 获取指定工单的所有处理和状态变更记录。

描述

此接口用于查询一个特定工单从创建到当前状态的所有追踪记录（Traces）。用户可以查看自己工单的处理进度，网维人员则可以查看所有他们有权访问的工单的完整历史记录。

认证

需要 JWT: 是
权限要求:
- 工单的创建者 (user 权限) 可以查看该工单的追踪记录。
- 网维人员 (operator 或更高权限) 可以查看任何工单的追踪记录。

请求

请求头

Header	类型	描述
`Authorization`	string	`Bearer <your_jwt_token>`

查询参数

参数	类型	描述	是否必须
`tid`	string	要查询的工单 ID。	是

请求示例:

GET /api/v3/get_traces?tid=123

响应

成功响应 (200 OK)

响应体包含一个 traces 数组，其中每个元素都是一条工单处理记录。

字段	类型	描述
`success`	boolean	`true` 表示操作成功
`msg`	string	成功的提示信息
`traces`	array	追踪记录对象数组
`trace.opid`	integer	操作记录的唯一 ID
`trace.tid`	integer	所属工单的 ID
`trace.updated_at`	string	本次记录的更新时间
`trace.op`	string	操作人员的 ID (如果是用户自己取消，可能为特殊值如 "-1")
`trace.op_name`	string	操作人的姓名
`trace.new_status`	string	本次操作后工单的新状态
`trace.new_priority`	string	本次操作后工单的新优先级
`trace.new_appointment`	string	本次操作后工单的新预约时间
`trace.new_category`	string	本次操作后工单的类型
`trace.remark`	string	本次操作的备注信息

响应示例:

{
  "success": true,
  "msg": "query success",
  "traces": [
    {
      "opid": 1,
      "tid": 123,
      "updated_at": "2025-12-06T10:00:00Z",
      "op": "-1",
      "new_status": "fresh",
      "new_priority": "mainline",
      "new_appointment": "",
      "remark": "工单已创建"
    },
    {
      "opid": 3,
      "tid": 123,
      "updated_at": "2025-12-06T15:30:00Z",
      "op": "W007",
      "new_status": "solved",
      "new_priority": "",
      "new_appointment": "",
      "remark": "问题已解决，用户确认网络恢复正常。"
    }
  ]
}

如果工单不存在，traces 数组将为空（或返回 ErrNoSuchTicket 错误）。

失败响应

400 Bad Request (请求错误)

tid 参数缺失或格式不正确。
无法获取工单信息（例如，工单不存在）。

{
  "success": false,
  "msg": "missing required URL parameter: tid",
  "errType": 2
}

400 Bad Request (业务逻辑错误)

`msg` 内容	`errType`	描述
"无法找到对应的工单"	`logic`	提供的 `tid` 对应的工单不存在。

403 Forbidden (权限错误)

当用户尝试查看不属于自己的工单，并且该用户不是网维人员时返回。
当非活跃用户（如 unregistered）尝试调用此接口时返回。

{
  "success": false,
  "msg": "you can only view ticket traces of your own",
  "errType": 3
}

500 Internal Server Error (服务器内部错误)

当发生未预料到的数据库查询错误或其他内部错误时返回。

{
  "success": false,
  "msg": "system met a uncaught error,please view logs.",
  "errType": 1
}

注意事项

此 API 返回的记录是按时间顺序排列的，可以清晰地展示工单的整个生命周期。
op 字段标识了执行该操作的人员。
这是一个只读操作，不会对工单或追踪记录进行任何修改。

4.7 KiB Raw Blame History Unescape Escape