forked from wts/wts
150 lines
4.5 KiB
Markdown
150 lines
4.5 KiB
Markdown
# 添加维修记录 (New Repair Trace) API
|
|
|
|
- **路径**: `/api/v3/new_repair_trace`
|
|
- **方法**: `POST`
|
|
- **功能**: 网维人员为工单添加处理记录、更新状态或修改其他属性。
|
|
|
|
## 描述
|
|
|
|
此接口是网维人员的核心工具，用于记录对报修工单的每一次操作。无论是状态变更（如“改日修”、“已完成”）、优先级调整，还是添加备注，都通过此接口完成。每一次调用都会在工单下生成一条新的追踪记录 (trace)。
|
|
|
|
## 认证
|
|
|
|
- **需要 JWT**: 是
|
|
- **权限要求**:
|
|
- 必须是网维人员 (`operator` 或更高权限) 才能调用此 API。
|
|
- 只有管理员 (`admin`) 才能修改工单的 `priority` (优先级)。
|
|
|
|
## 请求
|
|
|
|
### 请求头
|
|
|
|
| Header | 类型 | 描述 |
|
|
| --------------- | ------ | ------------------------- |
|
|
| `Authorization` | string | `Bearer <your_jwt_token>` |
|
|
| `Content-Type` | string | 必须是 `application/json` |
|
|
|
|
### 请求体 (JSON)
|
|
|
|
| 字段 | 类型 | 描述 | 校验规则 |
|
|
| ---------------- | -------- | -------------------------------------------------------------------- | ------------ |
|
|
| `tid` | integer | 要更新的工单 ID | `required` |
|
|
| `remark` | string | 本次操作的备注信息，例如 | `required` |
|
|
| `new_status` | string | 工单的新状态 | (可选) |
|
|
| `new_priority` | string | **(仅管理员)** 工单的新优先级 | (可选) |
|
|
| `new_appointment`| string | 新的预约上门日期 (RFC3339 日期格式, 例如: "2025-12-08T00:00:00Z") | (可选) |
|
|
| `new_category` | string | 新工单类型 | （可选） |
|
|
|
|
**请求示例 (更新状态和备注)**:
|
|
|
|
```json
|
|
{
|
|
"tid": 123,
|
|
"remark": "已电话联系用户，指导其重启路由器后网络恢复正常。工单完成。",
|
|
"new_status": "solved"
|
|
}
|
|
```
|
|
|
|
**请求示例 (重新安排上门时间)**:
|
|
|
|
```json
|
|
{
|
|
"tid": 124,
|
|
"remark": "用户今天没空，改约明天下午。",
|
|
"new_status": "scheduled",
|
|
"new_appointment": "2025-12-08T00:00:00Z"
|
|
}
|
|
```
|
|
|
|
## 响应
|
|
|
|
### 成功响应 (200 OK)
|
|
|
|
| 字段 | 类型 | 描述 |
|
|
| ------- | ------- | -------------------- |
|
|
| `success` | boolean | `true` 表示操作成功 |
|
|
| `msg` | string | 成功的提示信息 |
|
|
|
|
**响应示例**:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"msg": "new trace added"
|
|
}
|
|
```
|
|
|
|
### 失败响应
|
|
|
|
#### 400 Bad Request (请求错误)
|
|
|
|
- 请求体绑定失败、格式错误或未通过验证。
|
|
- 当设置了 `new_appointment` 但 `new_status` 不是 `scheduled` 时。
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"msg": "invalid request body: ...",
|
|
"errType": 2
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"msg": "only appointed status can set appointment time",
|
|
"errType": 2
|
|
}
|
|
```
|
|
|
|
#### 400 Bad Request (业务逻辑错误)
|
|
|
|
| `msg` 内容 | `errType` | 描述 |
|
|
| ----------------------- | --------- | ------------------------------------------ |
|
|
|"无法找到对应的工单" | `logic` | 提供的 `tid` 对应的工单不存在。 |
|
|
| "无法找到对应的网维成员" | `logic` | 操作者（网维人员）信息不存在。 |
|
|
|"您的工单状态更新请求不符合逻辑"| `logic` | 新状态不符合工单状态流转规则 |
|
|
|
|
#### 403 Forbidden (权限错误)
|
|
|
|
- 当非网维人员尝试调用此接口时。
|
|
- 当非管理员尝试修改 `new_priority` 时。
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"msg": "only Network Support staff can access this API",
|
|
"errType": 3
|
|
}
|
|
```
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"msg": "only admin can change ticket priority",
|
|
"errType": 3
|
|
}
|
|
```
|
|
|
|
#### 500 Internal Server Error (服务器内部错误)
|
|
|
|
当发生未预料到的数据库错误或其他内部错误时返回。
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"msg": "system met a uncaught error,please view logs.",
|
|
"errType": 1
|
|
}
|
|
```
|
|
|
|
## 注意事项
|
|
|
|
- 这是网维人员更新工单的主要方式。
|
|
- `remark` 字段是必填的，用于记录每次操作的内容。
|
|
- 只有在 `new_status` 设置为 `scheduled` 时，才能提供 `new_appointment` 字段。
|
|
- 工单状态的变更必须遵循预定义的逻辑流程。
|
|
- 只有管理员有权限调整工单的优先级。
|
|
- 这个 API 的底层实现是 `logic.AppendTrace`，与 `cancelTicket` API 共享部分逻辑。
|
|
|