sanguo_vnpy_v2/requirements/veighna-ui-analysis.md

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，只显示活动状态的订单

过滤逻辑:

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