# VWED WebSocket接口文档

本文档描述了VWED系统WebSocket相关的API接口，主要用于实时推送任务执行结果和状态更新。

## 基础信息

- 基础路径：`/ws`
- 接口标签：`WebSocket`
- 协议：WebSocket协议（ws://或wss://）

## 接口清单

| 序号 | 接口名称 | 接口路径 | 协议 | 接口描述 |
| --- | --- | --- | --- | --- |
| 1 | 任务执行结果实时推送 | `/task-execution/{task_record_id}` | WebSocket | 实时推送指定任务记录的执行结果更新 |
| 2 | 任务执行结果广播 | `/task-execution-broadcast/{task_record_id}` | WebSocket | 接收任务执行结果广播消息 |

## 接口详情

### 1. 任务执行结果实时推送

#### 接口说明

建立WebSocket连接，实时接收指定任务记录的执行结果更新。服务器会定期推送任务状态变化，客户端也可以主动请求获取当前状态。

#### 连接路径

```
ws://your-domain/ws/task-execution/{task_record_id}?interval={interval}
```

#### 路径参数

| 参数名 | 类型 | 是否必须 | 描述 |
| --- | --- | --- | --- |
| task_record_id | string | 是 | 任务记录ID |

#### 查询参数

| 参数名 | 类型 | 是否必须 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| interval | integer | 否 | 2 | 推送间隔（秒），范围1-30秒 |

#### 客户端消息格式

客户端可以向服务器发送以下格式的JSON消息：

##### 心跳检测

```json
{
    "type": "ping",
    "timestamp": "2025-06-11T12:00:00.000Z"
}
```

##### 获取当前状态

```json
{
    "type": "get_status",
    "timestamp": "2025-06-11T12:00:00.000Z"
}
```

#### 服务器消息格式

##### 任务执行结果更新

```json
{
    "type": "task_execution_update",
    "task_record_id": "任务记录ID",
    "timestamp": "2025-06-11T12:00:00.000Z",
    "message": "成功获取任务记录执行结果",
    "data": [
        {
            "created_at": "2025-06-11T12:00:00.000Z",
            "context": "[块执行名称] 执行内容描述",
            "status": "SUCCESS/FAILED/RUNNING"
        }
    ]
}
```

##### 心跳响应

```json
{
    "type": "pong",
    "timestamp": "2025-06-11T12:00:00.000Z"
}
```

##### 错误消息

```json
{
    "type": "error",
    "task_record_id": "任务记录ID",
    "timestamp": "2025-06-11T12:00:00.000Z",
    "message": "错误描述信息"
}
```

#### 响应字段说明

##### 任务执行结果字段

| 字段名 | 类型 | 描述 |
| --- | --- | --- |
| type | string | 消息类型，固定为"task_execution_update" |
| task_record_id | string | 任务记录ID |
| timestamp | string | 消息时间戳，ISO 8601格式 |
| message | string | 响应消息描述 |
| data | array | 执行结果数组 |
| data[].created_at | string | 结果创建时间，ISO 8601格式 |
| data[].context | string | 执行内容描述 |
| data[].status | string | 执行状态：SUCCESS（成功）、FAILED（失败）、RUNNING（执行中） |

#### 连接示例

##### JavaScript客户端示例

```javascript
// 建立WebSocket连接
const taskRecordId = "your-task-record-id";
const interval = 2; // 推送间隔2秒
const wsUrl = `ws://localhost:8000/ws/task-execution/${taskRecordId}?interval=${interval}`;

const websocket = new WebSocket(wsUrl);

// 连接建立
websocket.onopen = function(event) {
    console.log("WebSocket连接已建立");
    
    // 发送心跳包
    websocket.send(JSON.stringify({
        type: "ping",
        timestamp: new Date().toISOString()
    }));
};

// 接收消息
websocket.onmessage = function(event) {
    const data = JSON.parse(event.data);
    
    switch(data.type) {
        case "task_execution_update":
            console.log("任务执行结果更新:", data.data);
            break;
        case "pong":
            console.log("心跳响应:", data.timestamp);
            break;
        case "error":
            console.error("服务器错误:", data.message);
            break;
    }
};

// 连接关闭
websocket.onclose = function(event) {
    console.log("WebSocket连接已关闭");
};

// 连接错误
websocket.onerror = function(error) {
    console.error("WebSocket连接错误:", error);
};
```

##### Python客户端示例

```python
import asyncio
import json
import websockets

async def websocket_client():
    task_record_id = "your-task-record-id"
    interval = 2
    uri = f"ws://localhost:8000/ws/task-execution/{task_record_id}?interval={interval}"
    
    async with websockets.connect(uri) as websocket:
        print("WebSocket连接已建立")
        
        # 发送心跳包
        await websocket.send(json.dumps({
            "type": "ping",
            "timestamp": datetime.now().isoformat()
        }))
        
        # 监听消息
        async for message in websocket:
            data = json.loads(message)
            
            if data["type"] == "task_execution_update":
                print(f"任务执行结果更新: {data['data']}")
            elif data["type"] == "pong":
                print(f"心跳响应: {data['timestamp']}")
            elif data["type"] == "error":
                print(f"服务器错误: {data['message']}")

# 运行客户端
asyncio.run(websocket_client())
```

#### 特性说明

1. **智能推送**：服务器只在数据发生变化时才推送更新，避免不必要的网络流量
2. **心跳检测**：支持客户端主动发送心跳包，维持连接活跃状态
3. **错误处理**：完善的错误处理机制，连接异常时自动清理资源
4. **状态查询**：客户端可随时主动请求获取当前任务状态
5. **多客户端支持**：同一任务记录可支持多个客户端同时连接

### 2. 任务执行结果广播

#### 接口说明

建立WebSocket连接，接收任务执行结果的广播消息。与实时推送接口的区别在于，此接口主要用于被动接收广播，不会主动定期推送。

#### 连接路径

```
ws://your-domain/ws/task-execution-broadcast/{task_record_id}
```

#### 路径参数

| 参数名 | 类型 | 是否必须 | 描述 |
| --- | --- | --- | --- |
| task_record_id | string | 是 | 任务记录ID |

#### 客户端消息格式

##### 心跳检测

```json
{
    "type": "ping",
    "timestamp": "2025-06-11T12:00:00.000Z"
}
```

#### 服务器消息格式

与任务执行结果实时推送接口相同，参见上述文档。

#### 使用场景

1. **监控面板**：多个监控客户端同时监听任务状态变化
2. **日志收集**：收集任务执行过程中的状态变化记录
3. **事件通知**：当任务状态发生变化时接收通知

## 错误码说明

| 错误码 | 描述 | 解决方案 |
| --- | --- | --- |
| 1006 | 连接异常关闭 | 检查网络连接，重新建立连接 |
| 1011 | 服务器内部错误 | 检查服务器状态和日志 |
| 1013 | 临时服务不可用 | 稍后重试连接 |

## 最佳实践

### 1. 连接管理

- 实现连接断开后的自动重连机制
- 合理设置推送间隔，避免过于频繁的请求
- 及时关闭不需要的连接，释放服务器资源

### 2. 错误处理

- 监听`onerror`和`onclose`事件，处理连接异常
- 实现重连退避策略，避免连接风暴
- 记录错误日志，便于问题排查

### 3. 性能优化

- 使用合适的推送间隔（建议2-5秒）
- 客户端及时处理接收到的消息，避免消息积压
- 对于不活跃的任务，考虑降低推送频率

### 4. 安全考虑

- 在生产环境中使用WSS协议（WebSocket Secure）
- 实现适当的身份验证和授权机制
- 限制连接数量，防止资源滥用

## 注意事项

1. **任务记录ID有效性**：确保传入的任务记录ID存在且有效
2. **网络稳定性**：WebSocket连接对网络质量要求较高，不稳定的网络可能导致频繁断连
3. **浏览器兼容性**：确保目标浏览器支持WebSocket协议
4. **资源清理**：页面关闭或组件销毁时，及时关闭WebSocket连接
5. **消息处理**：合理处理接收到的消息，避免阻塞UI线程

## 更新日志

| 版本 | 日期 | 更新内容 |
| --- | --- | --- |
| 1.0.0 | 2025-06-11 | 初始版本，支持任务执行结果实时推送和广播功能 |