# WebSocket 测试指南

## 概述

Phase 3 实现了 WebSocket 实时数据推送功能，包括：
- WebSocket 连接管理
- 事件监听器（Tick, Order, Trade, Position, Account, Log, Contract）
- 订阅管理
- 心跳机制

## 启动服务器

```bash
cd /Users/chufeng/.openclaw/sanguo_projects/sanguo_vnpy_v2

# 启动 FastAPI 服务器
uvicorn sanguo_web.api:app --host 0.0.0.0 --port 8000 --reload
```

## 测试方法

### 方法 1: 使用 HTML 测试页面

1. 在浏览器中打开：
   ```
   file:///Users/chufeng/.openclaw/sanguo_projects/sanguo_vnpy_v2/tests/websocket_test.html
   ```

2. 点击"连接"按钮建立 WebSocket 连接

3. 选择要订阅的数据类型：
   - 行情 (Tick)
   - 订单 (Order)
   - 成交 (Trade)
   - 持仓 (Position)
   - 账户 (Account)
   - 日志 (Log)
   - 合约 (Contract)

4. 可选：输入品种代码（如：IF2501.CFFEX,IH2501.CFFEX）并订阅

5. 查看实时消息日志

### 方法 2: 使用 Python 测试脚本

```bash
# 安装依赖
pip install websockets

# 运行测试
cd /Users/chufeng/.openclaw/sanguo_projects/sanguo_vnpy_v2
python tests/test_websocket.py
```

测试脚本会执行以下测试：
1. 基本连接测试
2. 订阅功能测试
3. 消息接收测试
4. 心跳机制测试
5. 错误处理测试
6. 认证连接测试

### 方法 3: 使用 wscat 命令行工具

```bash
# 安装 wscat
npm install -g wscat

# 连接 WebSocket
wscat -c ws://localhost:8000/ws

# 发送订阅消息
{"type":"subscribe","data":{"subscription":["tick","order","trade"]}}

# 发送心跳
{"type":"ping","data":{}}

# 订阅品种
{"type":"subscribe_symbol","data":{"symbol":["IF2501.CFFEX"]}}
```

### 方法 4: 使用 JavaScript 控制台

在任何网页中打开浏览器控制台，运行：

```javascript
// 创建 WebSocket 连接
const ws = new WebSocket('ws://localhost:8000/ws');

// 监听连接事件
ws.onopen = () => {
    console.log('Connected');

    // 订阅行情数据
    ws.send(JSON.stringify({
        type: 'subscribe',
        data: { subscription: ['tick', 'order', 'trade'] }
    }));
};

// 监听消息
ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    console.log('Received:', message);
};

// 发送心跳
ws.send(JSON.stringify({ type: 'ping', data: {} }));
```

## WebSocket 消息格式

### 订阅消息（客户端 -> 服务器）

```json
{
  "type": "subscribe",
  "data": {
    "subscription": ["tick", "order", "trade"]
  }
}
```

### 订阅品种（客户端 -> 服务器）

```json
{
  "type": "subscribe_symbol",
  "data": {
    "symbol": ["IF2501.CFFEX", "IH2501.CFFEX"]
  }
}
```

### 心跳消息（客户端 -> 服务器）

```json
{
  "type": "ping",
  "data": {}
}
```

### 推送消息（服务器 -> 客户端）

```json
{
  "type": "tick",
  "data": {
    "vt_symbol": "IF2501.CFFEX",
    "symbol": "IF2501",
    "exchange": "CFFEX",
    "last_price": 3500.0,
    "bid_price_1": 3499.0,
    "ask_price_1": 3501.0,
    "volume": 12345,
    "datetime": "2025-01-01T09:30:00"
  }
}
```

## 订阅类型

| 类型 | 说明 | 事件类型 |
|------|------|----------|
| tick | 行情数据 | eTick. |
| order | 订单数据 | eOrder. |
| trade | 成交数据 | eTrade. |
| position | 持仓数据 | ePosition. |
| account | 账户数据 | eAccount. |
| log | 日志数据 | eLog |
| contract | 合约数据 | eContract. |

## 验收标准

Phase 3 完成验收：
- [x] WebSocket 管理器完成
- [x] WebSocket 路由完成
- [x] 事件监听器完成
- [x] 心跳机制完成
- [x] 订阅管理完成
- [x] WebSocket 集成到 FastAPI
- [x] 测试脚本和页面创建

## 故障排查

### 连接失败
1. 检查服务器是否运行
2. 检查 URL 是否正确
3. 检查防火墙设置

### 没有收到消息
1. 检查是否已订阅相应数据类型
2. 检查 VeighNa 网关是否连接
3. 检查是否有行情数据

### 心跳无响应
1. 检查服务器负载
2. 检查网络连接稳定性