# WebSocket 事件定义

## 事件类型

| 事件类型 | 触发时机 | 接收方 |
|---------|---------|-------|
| `WORKFLOW_CREATED` | 工单创建 | 处理人 |
| `WORKFLOW_ASSIGNED` | 工单分配 | 处理人 |
| `WORKFLOW_REASSIGNED` | 工单重新委派 | 原处理人、新处理人 |
| `WORKFLOW_STATUS_CHANGED` | 状态变更 | 发起人、处理人 |
| `WORKFLOW_REVOKED` | 工单撤销 | 处理人 |
| `WORKFLOW_MODIFIED` | 工单内容修改 | 处理人 |
| `WORKFLOW_TIMEOUT` | 工单超时 | 发起人、处理人 |
| `WORKFLOW_COMPLETED` | 工单完成 | 发起人 |

## 事件 Payload 结构

```json
{
    "event_type": "WORKFLOW_STATUS_CHANGED",
    "workflow_id": "project-20260108100000-admin",
    "workflow_type": "project_detail",
    "from_status": "pending_review",
    "to_status": "approved",
    "operator_id": 1,
    "operator_name": "超级管理员",
    "timestamp": "2026-01-08T15:30:00Z",
    "extra": {
        "remark": "审批通过"
    }
}
```

## 各事件详细说明

### WORKFLOW_CREATED

工单创建事件

```json
{
    "event_type": "WORKFLOW_CREATED",
    "workflow_id": "project-20260108100000-admin",
    "workflow_type": "project_detail",
    "title": "项目信息填写-ProjectA",
    "creator_id": 1,
    "creator_name": "超级管理员",
    "assignee_id": 123,
    "assignee_name": "张三",
    "priority": 3,
    "deadline": "2026-01-15T18:00:00Z",
    "timestamp": "2026-01-08T10:00:00Z"
}
```

### WORKFLOW_ASSIGNED

工单分配事件

```json
{
    "event_type": "WORKFLOW_ASSIGNED",
    "workflow_id": "project-20260108100000-admin",
    "assignee_id": 123,
    "assignee_name": "张三",
    "assigned_by_id": 1,
    "assigned_by_name": "超级管理员",
    "remark": "请在3天内完成项目信息填写",
    "timestamp": "2026-01-08T10:05:00Z"
}
```

### WORKFLOW_REASSIGNED

工单重新委派事件

```json
{
    "event_type": "WORKFLOW_REASSIGNED",
    "workflow_id": "project-20260108100000-admin",
    "from_assignee_id": 123,
    "from_assignee_name": "张三",
    "to_assignee_id": 456,
    "to_assignee_name": "李四",
    "reassigned_by_id": 1,
    "reassigned_by_name": "超级管理员",
    "remark": "张三请假，转交给李四处理",
    "timestamp": "2026-01-09T09:00:00Z"
}
```

### WORKFLOW_STATUS_CHANGED

状态变更事件

```json
{
    "event_type": "WORKFLOW_STATUS_CHANGED",
    "workflow_id": "project-20260108100000-admin",
    "workflow_type": "project_detail",
    "from_status": "in_progress",
    "to_status": "pending_review",
    "event": "complete",
    "operator_id": 123,
    "operator_name": "张三",
    "timestamp": "2026-01-08T14:00:00Z",
    "extra": {
        "remark": "项目信息填写完成"
    }
}
```

### WORKFLOW_REVOKED

工单撤销事件

```json
{
    "event_type": "WORKFLOW_REVOKED",
    "workflow_id": "user-20260108090000-zhangsan",
    "workflow_type": "user_registration",
    "revoked_by_id": 100,
    "revoked_by_name": "张三",
    "remark": "用户取消注册",
    "timestamp": "2026-01-08T11:00:00Z",
    "extra": {
        "target_user_deleted": true
    }
}
```

### WORKFLOW_MODIFIED

工单内容修改事件

```json
{
    "event_type": "WORKFLOW_MODIFIED",
    "workflow_id": "project-20260108100000-admin",
    "modified_by_id": 1,
    "modified_by_name": "超级管理员",
    "modified_fields": ["deadline", "priority"],
    "timestamp": "2026-01-08T16:00:00Z",
    "extra": {
        "old_deadline": "2026-01-15T18:00:00Z",
        "new_deadline": "2026-01-20T18:00:00Z",
        "old_priority": 3,
        "new_priority": 1
    }
}
```

### WORKFLOW_TIMEOUT

工单超时事件

```json
{
    "event_type": "WORKFLOW_TIMEOUT",
    "workflow_id": "project-20260108100000-admin",
    "workflow_type": "project_detail",
    "deadline": "2026-01-15T18:00:00Z",
    "current_status": "in_progress",
    "assignee_id": 123,
    "assignee_name": "张三",
    "timestamp": "2026-01-15T18:00:01Z"
}
```

### WORKFLOW_COMPLETED

工单完成事件

```json
{
    "event_type": "WORKFLOW_COMPLETED",
    "workflow_id": "project-20260108100000-admin",
    "workflow_type": "project_detail",
    "final_status": "approved",
    "result": "success",
    "creator_id": 1,
    "creator_name": "超级管理员",
    "timestamp": "2026-01-10T10:00:00Z",
    "extra": {
        "total_duration_hours": 48,
        "steps_completed": 3
    }
}
```

## 前端处理策略

| 事件 | 前端行为 |
|-----|---------|
| `WORKFLOW_CREATED` | 待办列表增加新工单提醒 |
| `WORKFLOW_ASSIGNED` | 显示分配通知，可跳转工单详情 |
| `WORKFLOW_REASSIGNED` | 原处理人：显示提示弹窗，切换只读模式；新处理人：显示接收通知 |
| `WORKFLOW_STATUS_CHANGED` | 更新工单状态显示，刷新流程图高亮 |
| `WORKFLOW_REVOKED` | 自动关闭处理页面，引导至工单列表 |
| `WORKFLOW_MODIFIED` | 提示"工单已被修改"，自动刷新或提示手动刷新 |
| `WORKFLOW_TIMEOUT` | 显示超时警告，标红显示 |
| `WORKFLOW_COMPLETED` | 显示完成通知，可查看结果 |

## 并发冲突处理

### 乐观锁冲突场景

当用户正在处理工单时，收到 `WORKFLOW_REASSIGNED` 或 `WORKFLOW_MODIFIED` 事件：

1. **WORKFLOW_REASSIGNED 处理流程**：
   - 显示弹窗：「此工单已被重新委派给XXX，您的处理权限已转移」
   - 页面切换为只读模式
   - 提供"返回列表"按钮
   - 若用户仍尝试提交，后端返回 409 Conflict

2. **WORKFLOW_MODIFIED 处理流程**：
   - 显示提示：「工单内容已被修改，请刷新页面」
   - 若用户有未保存的本地修改，提示冲突
   - 提供"刷新"和"查看变更"选项

### 版本号同步

前端需在每次获取工单详情时缓存 `version` 字段，提交操作时携带该版本号：

```javascript
// 获取工单详情
const { data } = await api.getWorkflowDetail(workflowId);
this.workflowVersion = data.version;

// 提交状态转换
await api.transitionWorkflow({
    workflow_id: workflowId,
    version: this.workflowVersion,  // 必传
    event: 'complete',
    remark: '处理完成'
});
```
