# 计划：WS 盘中价格实时更新（前端直连 QMT Bridge WebSocket）（阶段航点）

> 编号：PLAN-004 ｜ 粒度：阶段航点（大粒度） ｜ 创建：2026-08-31 ｜ 状态：**已完成（2026-09-01 迭代 04 验收通过，R-005 已实现）**
> 派生自终极目标：目标-001（DSH 插件形态）、目标-008（真实交易系统接入·统一数据源抽象）
> 依据需求：**R-005（已定稿，2026-08-31）** —— 符合入范围门槛（已定稿方可进入计划）
> 设计约束：技术约束-001/003/008（沿用）、技术约束-010（新增：前端直连 WS）、产品约束-007（新增：现价列展示）

## 目标

在 3 个监控表格（全部持仓 / 手动做T / 网格超市）中实现**盘中价格实时更新**：前端直连 QMT Bridge WebSocket 订阅全市场 tick，事件驱动更新关注股票的现价（lastPrice），红涨绿跌着色 + 变化高亮。

## 范围

**做**：
1. **WS 行情客户端**（前端）：连接 `ws://<激活配置host>:8610/ws`，订阅 `whole` 全市场 tick；维护 code→lastPrice 实时价格 Map；
2. **订阅生命周期**：订阅前 REST 拉一次 `/data/tick` 快照补初值（WS 只推增量）；连接断开静默重连 + 状态提示；切换激活 QMT 配置时 WS 随之切换；
3. **关注列表**：3 表格自动汇总出现的 code（全部持仓 + 手动做T + 网格超市），作为过滤集合；
4. **现价展示**：3 表格新增「现价」列（lastPrice），红涨绿跌着色（对比昨收 lastClose），价格变化轻微高亮；
5. **事件驱动**：收到 WS 推送 → 更新价格 Map → 通知订阅方（React state/事件）→ 表格行重渲染现价。

**不做**（本期）：
- 市值/盈亏/五档实时展示；
- 插件服务端中转 WS；
- 关注列表手动配置；
- 断线重连 UI 引导（仅静默重连 + 状态提示）。

## 程序结构（改造后）

```
src/
├── index.js                        # 服务端入口（小改）：新增 API 暴露激活连接 host（供前端建 WS）
├── api.js                          # 服务端 API（改）：新增 qmt-connections/active-host 端点（返回 { host, baseUrl, wsUrl }）
├── client/
│   ├── index.js                    # 客户端入口（改）：注册行情 Provider，包装 3 个表格
│   ├── market/
│   │   └── MarketDataProvider.jsx  # 新增：WS 行情客户端 + 价格 Map + 订阅/重连/切换 + Context 下发
│   └── views/
│       ├── AllPositionsTab.jsx     # 改：新增「现价」列 + 涨跌色 + 高亮
│       ├── StrategyTab.jsx         # 改：新增「现价」列 + 涨跌色 + 高亮
│       └── PriceCell.jsx           # 新增：现价单元格组件（格式化 + 涨跌色 + 高亮）
└── cordis.patch.yml                # 不改（QMT 配置已在 settings）
```

## 实现步骤（建议顺序）

1. **文档骨架**：R-005 转正 + PLAN-004 + 迭代 04 子目录 + 迭代说明（本步）；
2. **服务端 API**：新增 `qmt-connections/active-host` 返回激活配置 host（前端据此建 WS）；
3. **WS 行情客户端**：MarketDataProvider（连接/订阅/价格 Map/重连/配置切换）；
4. **现价列 UI**：PriceCell + 3 表格接入；
5. **构建安装**：dsh plugin add，重载页面；
6. **验收**：对照验收标准逐条核验，记录迭代 04。