# R-005 WS 盘中价格实时更新 · 已完成

> 归档日期：2026-09-01 ｜ 需求状态：**已完成**
> 原索引：docs/05-需求池/需求池索引.md（主索引保留 R-005 条目，指向本归档）
> 实现迭代：04-WS盘中价格实时更新（验收通过，迭代复盘见 docs/04-迭代记录/04-WS盘中价格实时更新/迭代复盘.md）
> 讨论记录：需求从 T-005 草稿转正，2026-08-31 定稿；实现过程中的架构演进（前端直连→服务端中转+行情缓存）见迭代 04 迭代说明/复盘

---


> 状态：**已定稿**（2026-08-31，老师确认）｜ 登记日期：2026-08-31
> 来源：T-005 草稿转正（docs/05-需求池/草稿/通过ws长连接做市场数据的实时反映.md）
> 关联：T-005（ws 实时数据草稿）、R-002/R-003/R-004（已实现）

## 需求描述

在现有分仓管理工具（one-divine-lot 插件）中，实现**盘中价格实时更新**：

- 前端直连 QMT Bridge 原生 WebSocket（`ws://<激活配置host>:8610/ws`），订阅 `whole`（全市场 tick 增量推送）；
- 事件驱动：收到推送后，自动更新 3 个监控表格（全部持仓 / 手动做T / 网格超市）中**关注股票列表**的**盘中价格**（现价，字段 `lastPrice`）；
- 本期只更新**现价**一项数据，不做市值/盈亏/五档等扩展。

## 核心逻辑（定稿版）

1. **连接拓扑**：前端直连 QMT Bridge WS（老师确认，非插件服务端中转）；
2. **订阅范围**：订阅全市场行情流（`type: whole`，`codes: ['SH','SZ']`），前端按关注列表过滤（老师确认）；
3. **关注列表来源**：3 个表格自动汇总（全部持仓 + 手动做T + 网格超市出现过的 code 合集），无需手动维护（老师确认）；
4. **现价展示**：3 个表格新增「现价」列（显示 `lastPrice`），红涨绿跌着色，价格变化时轻微高亮提示（老师确认）；
5. **刷新机制**：现价叠加层 —— WS 维护 code→lastPrice 实时价格 Map，表格行渲染时叠加；份额/持仓仍由 REST 拉取，不整表重拉（老师确认）；
6. **协议事实**（2026-08-31 实测 GEMWIN 100.110.38.78:8610）：
   - WS 端点：`ws://<host>:8610/ws`（与 REST 同端口，OpenAPI servers 注明）；
   - 订阅：`POST /data/subscribe`，body `{ type: 'whole', codes: ['SH','SZ'] }` → 返回 `{ ok, sub_id }`；
   - 退订：`POST /data/unsubscribe`，body `{ sub_id }`；
   - 推送：`{ type: 'whole', data: { '<code>': TickSnapshot } }`，TickSnapshot 含 `lastPrice / open / high / low / lastClose / volume / amount / askPrice / bidPrice / askVol / bidVol / stime / time` 等；
   - 快照：`GET /data/tick?codes=<code1,code2>` 返回 `{ ok, data: { code: TickSnapshot } }`（WS 只推增量，无 prime；前端可先拉一次快照补齐初值）。

## 边界（不做）

- 不做市值/盈亏/五档等实时数据的展示（本期仅现价）；
- 不做插件服务端中转 WS（老师确认前端直连）；
- 不做断线重连 UI 引导（先做静默重连 + 状态提示）；
- 不做关注列表手动配置（自动汇总）。

## 验收要点（详见迭代 04 验收标准）

1. 3 个表格出现「现价」列，显示关注股票的 lastPrice；
2. 价格变化自动更新（无需手动刷新）；
3. 红涨绿跌着色 + 变化高亮；
4. 连接激活配置的 host 变化时，WS 随之切换（复用 QMT 多配置热切换）。