# 工单模块接口文档

## 工单列表接口

#### Method
- /ticket/list

#### 请求参数示例:
```json
{
    "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格式                   |

#### 成功响应示例:
```json
{
    "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格式                   |

#### 错误响应示例:
```json
{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "无效的时间格式",
        "code": 400,
        "data": {
            "field": "start_time"
        }
    }
}
```


## 创建工单接口

#### 消息协议
- JSONRPC-2.0

#### Method
- /ticket/create

#### 请求参数示例:
```json
{
    "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格式        |

#### 成功响应示例:
```json
{
    "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
    }
}
```

#### 错误响应示例:
```json
{
    "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

#### 请求参数示例:
```json
{
    "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"
}
```

#### 成功响应示例:
```json
{
    "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
    }
}
```

#### 错误响应示例:
```json
{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "无效的状态变更: new → closed",
        "code": 400,
        "data": {
            "current_status": "new",
            "target_status": "closed"
        }
    }
}
```

## 删除工单接口

#### Method
- /ticket/delete

#### 请求参数示例:
```json
{
    "jsonrpc": "2.0",
    "method": "/ticket/delete",
    "params": {
        "id": 123,
        "operator_id": 1002
    },
    "session": "viFuv4G2XJMxO4GIIsVfbJ2eKwy6QyuWLXmqZY69dy0G9iTY",
    "timestampin": "1706325301436"
}
```

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

#### 成功响应示例:
```json
{
    "jsonrpc": "2.0",
    "result": {
        "id": 123,
        "deleted_at": "2024-03-15T14:30:00Z"
    },
    "error": {
        "message": "ok",
        "code": 200
    }
}
```

#### 返回参数说明:
| 参数名      | 类型     | 说明         | 备注                        |
|-------------|----------|--------------|-----------------------------|
| id          | int      | 被删除工单ID |                             |

#### 错误响应示例:
```json
{
    "jsonrpc": "2.0",
    "result": null,
    "error": {
        "message": "无权删除该工单",
        "code": 403,
        "data": {
            "required_role": "admin"
        }
    }
}
```

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

## 工单流转接口

#### Method
- /ticket/transition

#### 请求参数示例:
```json
{
    "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. 不指定目标状态时，系统会自动流转到下一状态