|
|
# 工单模块接口文档
|
|
|
|
|
|
## 工单列表接口
|
|
|
|
|
|
#### 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. 不指定目标状态时，系统会自动流转到下一状态 |
