# VeighNa 4.4 原生 UI 功能深度分析

## 分析目的

分析 VeighNa 4.4.0 原生 Qt UI 的完整功能，为 Web 前端实现对等功能提供参考。

---

## 一、UI 架构概览

### 1.1 MainWindow（主窗口）

**文件**: `vnpy/trader/ui/mainwindow.py`

**窗口标题格式**: `VeighNa Trader 社区版 - {version}   [{trader_path}]`

**核心结构**:
- Dock 系统组件（可拖拽、浮动、最小化）
- 菜单栏（系统、功能、帮助）
- 工具栏（左侧，固定大小和间距）
- 窗口设置保存/恢复（默认布局 + 自定义布局）

---

## 二、Dock 组件清单

### 2.1 TradingWidget（交易组件）

**位置**: `LeftDockWidgetArea`

**功能**:

#### 下单表单区域
| 字段 | 类型 | 说明 |
|------|------|------|
| 交易所 | ComboBox | 下拉选择 |
| 代码 | LineEdit | 文本输入，回车确认 |
| 名称 | LineEdit | 只读显示 |
| 方向 | ComboBox | LONG（多）/SHORT（空） |
| 开平 | ComboBox | OPEN（开）/CLOSE（平）/CLOSETODAY（平今）/CLOSEYESTERDAY（平昨） |
| 类型 | ComboBox | LIMIT（限价）/MARKET（市价）/STOP（止损） |
| 价格 | LineEdit | 数字输入，可选 |
| 数量 | LineEdit | 数字输入，必填 |
| 接口 | ComboBox | 下拉选择 |
| 价格随行情更新 | CheckBox | 勾选后价格自动跟随最新价 |

#### 按钮
- **委托按钮** - 发送订单
- **全撤按钮** - 撤销所有活动订单

#### 市场深度显示（盘口）
```
┌─────────────────────┐
│ 卖5价    卖5量     │
│ 卖4价    卖4量     │
│ 卖3价    卖3量     │
│ 卖2价    卖2量     │
│ 卖1价    卖1量     │
│ ────────────────   │
│ 最新价    涨跌幅%  │
│ ────────────────   │
│ 买1价    买1量     │
│ 买2价    买2量     │
│ 买3价    买3量     │
│ 买4价    买4量     │
│ 买5价    买5量     │
└─────────────────────┘
```

**颜色方案**:
- 买盘（Bid）: `rgb(255, 174, 201)` 粉红色
- 卖盘（Ask）: `rgb(160, 255, 160)` 浅绿色
- 多头（LONG）: 红色
- 空头（SHORT）: 绿色

#### 交互特性
- 行情双击更新: 双击 TickMonitor 或 PositionMonitor 的行，自动填充交易表单
- 持仓反向填充: 双击持仓时自动设置反向方向和平仓
- 价格自动更新: 勾选"价格随行情更新"后，价格跟随最新价

---

### 2.2 TickMonitor（行情监控）

**位置**: `RightDockWidgetArea`

**表格列**:
| 列名 | 字段 | 更新 | 排序 |
|------|------|------|------|
| 代码 | symbol | 否 | ✅ |
| 交易所 | exchange | 否 | ✅ |
| 名称 | name | **是** | ✅ |
| 最新价 | last_price | **是** | ✅ |
| 成交量 | volume | **是** | ✅ |
| 开盘价 | open_price | **是** | ✅ |
| 最高价 | high_price | **是** | ✅ |
| 最低价 | low_price | **是** | ✅ |
| 买1价 | bid_price_1 | **是** | ✅ |
| 买1量 | bid_volume_1 | **是** | ✅ |
| 卖1价 | ask_price_1 | **是** | ✅ |
| 卖1量 | ask_volume_1 | **是** | ✅ |
| 时间 | datetime | **是** | ✅ |
| 接口 | gateway_name | 否 | ✅ |

**数据键**: `vt_symbol`（按此键更新现有行）

---

### 2.3 OrderMonitor（委托监控）

**位置**: `RightDockWidgetArea`

**表格列**:
| 列名 | 字段 | 更新 | 排序 |
|------|------|------|------|
| 委托号 | orderid | 否 | ✅ |
| 来源 | reference | 否 | ✅ |
| 代码 | symbol | 否 | ✅ |
| 交易所 | exchange | 否 | ✅ |
| 类型 | type | 否 | ✅ |
| 方向 | direction | 否 | ✅ |
| 开平 | offset | 否 | ✅ |
| 价格 | price | 否 | ✅ |
| 总数量 | volume | **是** | ✅ |
| 已成交 | traded | **是** | ✅ |
| 状态 | status | **是** | ✅ |
| 时间 | datetime | **是** | ✅ |
| 接口 | gateway_name | 否 | ✅ |

**数据键**: `vt_orderid`

**交互**: 双击单元格撤单

---

### 2.4 ActiveOrderMonitor（活动委托监控）

**位置**: `RightDockWidgetArea`

**说明**: 继承自 OrderMonitor，只显示活动状态的订单

**过滤逻辑**:
```python
if order.is_active():
    showRow(row)      # 显示活动订单
else:
    hideRow(row)      # 隐藏已完成/已撤销订单
```

**活动状态**: 未成交、部分成交

---

### 2.5 TradeMonitor（成交监控）

**位置**: `RightDockWidgetArea`

**表格列**:
| 列名 | 字段 | 更新 | 排序 |
|------|------|------|------|
| 成交号 | tradeid | 否 | ✅ |
| 委托号 | orderid | 否 | ✅ |
| 代码 | symbol | 否 | ✅ |
| 交易所 | exchange | 否 | ✅ |
| 方向 | direction | 否 | ✅ |
| 开平 | offset | 否 | ✅ |
| 价格 | price | 否 | ✅ |
| 数量 | volume | 否 | ✅ |
| 时间 | datetime | 否 | ✅ |
| 接口 | gateway_name | 否 | ✅ |

**数据键**: 空（只插入新行，不更新）

---

### 2.6 PositionMonitor（持仓监控）

**位置**: `BottomDockWidgetArea`

**表格列**:
| 列名 | 字段 | 更新 | 排序 |
|------|------|------|------|
| 代码 | symbol | 否 | ✅ |
| 交易所 | exchange | 否 | ✅ |
| 方向 | direction | 否 | ✅ |
| 数量 | volume | **是** | ✅ |
| 昨仓 | yd_volume | **是** | ✅ |
| 冻结 | frozen | **是** | ✅ |
| 均价 | price | **是** | ✅ |
| 盈亏 | pnl | **是** | ✅ |
| 接口 | gateway_name | 否 | ✅ |

**数据键**: `vt_positionid`

**交互**: 双击单元格更新交易组件

---

### 2.7 AccountMonitor（资金监控）

**位置**: `BottomDockWidgetArea`

**表格列**:
| 列名 | 字段 | 更新 | 排序 |
|------|------|------|------|
| 账号 | accountid | 否 | ✅ |
| 余额 | balance | **是** | ✅ |
| 冻结 | frozen | **是** | ✅ |
| 可用 | available | **是** | ✅ |
| 接口 | gateway_name | 否 | ✅ |

**数据键**: `vt_accountid`

---

### 2.8 LogMonitor（日志监控）

**位置**: `BottomDockWidgetArea`

**表格列**:
| 列名 | 字段 | 更新 | 排序 |
|------|------|------|------|
| 时间 | time | 否 | ❌ |
| 信息 | msg | 否 | ❌ |
| 接口 | gateway_name | 否 | ❌ |

**数据键**: 空（只插入新行）

**时间格式**: `HH:MM:SS.mmm`（毫秒）

---

## 三、菜单系统

### 3.1 系统菜单

**动态生成网关连接选项**:
```
系统
├── 连接{Gateway1}
├── 连接{Gateway2}
├── ...
├── ────────
└── 退出
```

**退出确认**: 显示确认对话框

---

### 3.2 功能菜单

**动态生成 App 选项**（基于已加载的 Apps）:
```
功能
├── {App1显示名}
├── {App2显示名}
├── ...
```

---

### 3.3 菜单栏操作

| 菜单项 | 功能 |
|--------|------|
| 配置 | 打开全局配置对话框 |
| 微信 | 打开微信通知对话框 |

---

### 3.4 帮助菜单

```
帮助
├── 查询合约
├── 还原窗口
├── 测试邮件
├── 社区论坛
└── 关于
```

---

## 四、对话框组件

### 4.1 ConnectDialog（网关连接对话框）

**标题**: `连接{GatewayName}`

**功能**:
- 动态生成表单字段（基于 Gateway 的 default_setting）
- 字段类型支持:
  - `str` - LineEdit
  - `int` - LineEdit（数字验证）
  - `bool` - LineEdit
  - `list` - ComboBox（下拉选择）
- 密码字段自动隐藏显示
- 加载上次保存的设置
- 保存本次设置
- 连接网关

**表单格式**:
```
{字段名} <{类型}>: [输入控件]
```

---

### 4.2 ContractManager（合约管理器）

**标题**: `合约查询`

**尺寸**: 1000x600

**功能**:
- 过滤输入（支持代码或交易所筛选）
- 查询按钮
- 合约表格（12列）

**表格列**:
| 列名 | 字段 |
|------|------|
| 本地代码 | vt_symbol |
| 代码 | symbol |
| 交易所 | exchange |
| 名称 | name |
| 合约分类 | product |
| 合约乘数 | size |
| 价格跳动 | pricetick |
| 最小委托量 | min_volume |
| 期权产品 | option_portfolio |
| 期权到期日 | option_expiry |
| 期权行权价 | option_strike |
| 期权类型 | option_type |
| 交易接口 | gateway_name |

---

### 4.3 GlobalDialog（全局配置）

**标题**: `全局配置`

**最小宽度**: 800

**功能**:
- 显示所有全局配置字段
- 字段名和类型显示
- 修改后保存
- 提示: "全局配置的修改需要重启后才会生效！"

**表单格式**:
```
{字段名} <{类型}>: [当前值]
```

---

### 4.4 WechatDialog（微信通知）

**标题**: `微信通知`

**最小宽度**: 380

**页面结构**（StackedWidget）:
1. **状态页** - 显示绑定状态和信息
2. **加载页** - 加载中
3. **二维码页** - 显示登录二维码
4. **等待页** - 等待用户发送消息
5. **结果页** - 绑定结果

**状态页内容**:
- Bot ID
- 用户 ID
- 网关
- 推送间隔设置（SpinBox，1-8640秒）
- 开始绑定按钮
- 测试消息按钮
- 解除绑定按钮

**推送间隔说明**:
> 控制两次微信推送之间的间隔时间。间隔内的新消息会暂存，并在下次推送时合并发送。用户每发送 1 条消息，机器人可在 24 小时内推送 10 条；超限后需用户再次发送消息才能恢复。

---

### 4.5 AboutDialog（关于对话框）

显示软件版本和相关信息的对话框。

---

## 五、工具栏

**位置**: `LeftToolBarArea`

**特性**:
- 固定图标大小: 40x40
- 按钮间距: 10
- 不可浮动
- 不可移动

---

## 六、右键菜单（通用）

所有表格组件（BaseMonitor）都有统一右键菜单:

| 菜单项 | 功能 |
|--------|------|
| 调整列宽 | 根据内容自动调整所有列宽 |
| 保存数据 | 导出表格为 CSV 文件 |

---

## 七、单元格类型

### 7.1 BaseCell
基础单元格，文本居中对齐

### 7.2 EnumCell
枚举单元格，显示 `enum.value`

### 7.3 DirectionCell
方向单元格，根据方向设置颜色:
- SHORT: 绿色
- LONG: 红色

### 7.4 BidCell
买盘单元格，粉红色

### 7.5 AskCell
卖盘单元格，浅绿色

### 7.6 PnlCell
盈亏单元格，根据盈亏设置颜色:
- 正: 红
- 负: 绿
- 零: 黑

### 7.7 TimeCell
时间单元格，格式: `HH:MM:SS.mmm`

### 7.8 DateCell
日期单元格，格式: `YYYY-MM-DD`

### 7.9 MsgCell
消息单元格，左对齐

---

## 八、事件系统

### 8.1 事件类型

| 事件类型 | 说明 | 监听组件 |
|----------|------|----------|
| EVENT_TICK | 行情数据 | TickMonitor, TradingWidget |
| EVENT_TRADE | 成交数据 | TradeMonitor |
| EVENT_ORDER | 委托数据 | OrderMonitor, ActiveOrderMonitor |
| EVENT_POSITION | 持仓数据 | PositionMonitor |
| EVENT_ACCOUNT | 资金数据 | AccountMonitor |
| EVENT_LOG | 日志数据 | LogMonitor |
| EVENT_QUOTE | 报价数据 | QuoteMonitor |

### 8.2 数据更新逻辑

**有数据键**（如 vt_symbol）:
- 如果键已存在 → 更新现有行
- 如果键不存在 → 插入新行

**无数据键**:
- 总是插入新行

---

## 九、窗口状态管理

### 9.1 保存
保存内容:
- 窗口几何信息（geometry）
- Dock 状态（state）

### 9.2 加载
支持两种布局:
- `default` - 默认布局
- `custom` - 自定义布局

---

## 十、交互特性总结

### 10.1 表格功能
- 排序: 大部分表格支持排序
- 列宽调整: 右键菜单
- CSV 导出: 右键菜单
- 列状态保存/恢复: 自动保存列宽和排序状态

### 10.2 双击交互
| 组件 | 双击行为 |
|------|----------|
| TickMonitor | 更新交易组件 |
| OrderMonitor | 撤单 |
| PositionMonitor | 更新交易组件（反向） |
| QuoteMonitor | 撤销报价 |

### 10.3 数据更新模式
| 组件 | 更新字段 |
|------|----------|
| TickMonitor | name, last_price, volume, OHLC, bid/ask, datetime |
| OrderMonitor | volume, traded, status, datetime |
| PositionMonitor | volume, yd_volume, frozen, price, pnl |
| AccountMonitor | balance, frozen, available |

---

## 十一、颜色方案

| 用途 | 颜色 |
|------|------|
| 多头（LONG） | 红色 |
| 空头（SHORT） | 绿色 |
| 买盘（Bid） | `rgb(255, 174, 201)` |
| 卖盘（Ask） | `rgb(160, 255, 160)` |
| 盈利 | 红色 |
| 亏损 | 绿色 |
| 零盈亏 | 黑色 |

---

## 十二、与当前 Web 前端对比

### 12.1 已实现功能

| 功能 | VeighNa Qt | Web 前端 | 对等程度 |
|------|------------|----------|----------|
| 登录认证 | ✅ | ✅ | ✅ 完全对等 |
| 总览 Dashboard | ✅ | ✅ | ⚠️ 部分对等 |
| 行情监控 | ✅ | ✅ | ⚠️ 缺少多档盘口 |
| 交易下单 | ✅ | ✅ | ❌ 缺少深度盘口 |
| 委托监控 | ✅ | ✅ | ⚠️ 缺少双击撤单 |
| 持仓监控 | ✅ | ✅ | ⚠️ 缺少双击交互 |
| 日志监控 | ✅ | ✅ | ✅ 完全对等 |
| 策略管理 | ✅ | ✅ | ✅ 完全对等 |

### 12.2 缺失功能

| 功能 | VeighNa Qt | Web 前端 | 优先级 |
|------|------------|----------|--------|
| **成交监控** | ✅ | ❌ | 🔴 高 |
| **资金监控** | ✅ | ❌ | 🔴 高 |
| **活动委托视图** | ✅ | ❌ | 🟡 中 |
| **网关连接管理** | ✅ | ❌ | 🔴 高 |
| **合约管理** | ✅ | ❌ | 🟡 中 |
| **全局配置编辑器** | ✅ | ❌ | 🟢 低 |
| **市场深度盘口** | ✅ | ❌ | 🟡 中 |
| **窗口布局保存** | ✅ | ❌ | 🟢 低 |
| **表格排序** | ✅ | ❌ | 🟡 中 |
| **CSV 导出** | ✅ | ❌ | 🟢 低 |
| **微信通知** | ✅ | ❌ | 🟢 低 |
| **右键菜单** | ✅ | ❌ | 🟢 低 |

---

## 十三、实现优先级建议

### Phase 1: 核心缺失功能（必须实现）

1. **成交监控页面**
   - 表格显示所有成交记录
   - 支持排序
   - WebSocket 接收 EVENT_TRADE

2. **资金监控页面**
   - 表格显示所有账户资金
   - 支持排序
   - WebSocket 接收 EVENT_ACCOUNT

3. **网关连接管理**
   - 网关列表显示
   - 连接对话框（动态表单）
   - 连接/断开操作

### Phase 2: 体验增强功能

4. **活动委托视图**
   - 只显示活动订单的委托列表
   - 过滤已完成/已撤销订单

5. **市场深度盘口**
   - TradingWidget 中添加五档盘口
   - 颜色区分买/卖盘

6. **合约管理**
   - 合约查询页面
   - 搜索过滤

### Phase 3: 完善功能

7. **表格排序**
8. **CSV 导出**
9. **全局配置编辑器**
10. **双击交互**（撤单、更新交易表单）

---

## 十四、技术实现要点

### 14.1 后端 API 需求

| API | 方法 | 说明 |
|-----|------|------|
| /api/trades | GET | 获取所有成交记录 |
| /api/accounts | GET | 获取所有账户资金 |
| /api/gateways | GET | 获取所有可用网关 |
| /api/gateways/{name}/connect | POST | 连接网关 |
| /api/gateways/{name}/disconnect | POST | 断开网关 |
| /api/gateways/{name}/setting | GET | 获取网关连接配置模板 |
| /api/contracts | GET | 获取所有合约 |

### 14.2 WebSocket 事件

需要监听的事件:
- `EVENT_TRADE` - 成交数据
- `EVENT_ACCOUNT` - 账户数据
- `EVENT_GATEWAY` - 网关状态变化

### 14.3 前端组件

新增页面:
- `TradesPage` - 成交监控
- `AccountPage` - 资金监控
- `GatewayPage` - 网关管理
- `ContractPage` - 合约管理
- `ActiveOrdersPage` - 活动委托

---

*分析日期: 2026-07-02*
*VeighNa 版本: 4.4.0*