迭代19-21收尾: 指示灯自适应探测（R-022/R-023）+ 列设置拖拽排序（R-024）+ Tab设置间隙线统一（R-025）+ 需求池归档（R-014/15/16/17/19 → 已完成）

2026-09-10 14:04:51 +08:00
parent 8782aa9c50
commit 3dfa39b8bf
29 changed files with 1216 additions and 72 deletions
@@ -0,0 +1,45 @@
+# 技术实现方案：19-指示灯状态自适应探测
+
+> 迭代编号：19 ｜ 依据：R-022 + R-023 ｜ 涉及约束：产品约束-012（指示灯体系）、技术约束-016、技术约束-020/021（本迭代新增）
+
+## 方案总览
+
+两只连接类状态缓存统一改「**结果驱动 setTimeout 自适应链**」：每次探测完成（成功/失败/异常）后按结果排下一轮。
+
+| 维度 | QmtHealthMonitor（R-022） | QmtMcpManager（R-023） |
+|---|---|---|
+| 健康/已连接 | intervalMs 默认 5 分钟（稳态，原设计） | intervalMs 默认 5 分钟 |
+| 异常/未知/未连接 | retryMs 默认 10 秒快速重试 | retryMs 默认 10 秒快速重试 |
+| 探测目标 | 激活 baseUrl + /health（GET） | 激活 baseUrl + /mcp（SDK Client 握手，只读） |
+| 停止调度 | stop()（mounted 守卫） | 无激活连接 / dispose() / unmount() |
+| 并发防护 | _inFlight 去重 | _probing 去重 |
+| 前端/API | 零改动（读缓存秒回） | 零改动（getStatus 读缓存秒回） |
+
+## 实现步骤
+
+### R-022 QmtHealthMonitor（src/data-source/QmtHealthMonitor.js）
+
+1. 常量 HEALTH_RETRY_MS=10s；构造注入 { intervalMs, retryMs }（测试用短间隔，对齐 QuoteSync 先例）；
+2. 固定 setInterval(5min) → _nextDelay()/_scheduleNext()（setTimeout 链，探测完成重排）；
+3. resolveActiveBaseUrl 移入 try：解析失败也落 healthy:false 缓存走快速重试
+   （原实现解析在 try 外，抛错场景灯会灰且不自动重试——顺带修复的隐性缺陷）；
+4. start() 立即探测不变；stop() 用 clearTimeout + mounted 守卫。
+
+### R-023 QmtMcpManager（src/mcp/QmtMcpManager.js）
+
+1. 常量 PROBE_RETRY_MS=10s；构造注入 { intervalMs, retryMs }；
+2. probe() 结果写缓存后 _scheduleNext()；target 为空早退置 disabled 并取消定时器；
+3. unmount() 取消定时器；dispose() 置 _disposed + 取消 + 卸载；_probing 防并发；
+4. 探测本体（SDK Client connect/initialize/tools/list）与挂载/重连逻辑零改动。
+
+### 回归
+
+- scripts/test-health-monitor.mjs（10 项：启动即探测/异常快速重试自动恢复/健康稳态不空转/stop 停止调度…）
+- scripts/test-mcp-status.mjs（12 项：无激活连接不调度/异常快速重试自动恢复/已连接稳态不空转/dispose 停止调度/节奏选择；
+  SDK 握手不可纯内存 mock，守护调度机制：stub probe 翻转状态 + 触达真实 _scheduleNext）
+
+## 涉及文件
+
+- src/data-source/QmtHealthMonitor.js、src/mcp/QmtMcpManager.js（核心改动）
+- scripts/test-health-monitor.mjs、scripts/test-mcp-status.mjs（新增回归）
+- lib/*（build 再产物，部署用）
@@ -0,0 +1,45 @@
+# 迭代复盘：19-指示灯状态自适应探测
+
+## 结论
+
+达成（R-022 + R-023 全范围）：会话头部两只「连接类」指示灯（QMT连接 / MCP）统一改为
+**结果驱动自适应探测**——健康/已连接维持 5 分钟稳态（原设计不变），异常/未知每 10 秒快速重试；
+QMT Bridge 与其 MCP 服务启动/恢复后两灯 ≤20s 自动回绿，不再等满 5 分钟 / 不再永不恢复。
+前端指示灯与 sync-status / qmt-health / mcp-status 端点零改动（读缓存秒回语义不变）。
+
+## 事实记录
+
+### R-022 QMT 健康灯（src/data-source/QmtHealthMonitor.js）
+
+- 根因（已证实）：健康缓存固定 5 分钟探测一次激活 /health；其余三灯有高频自愈回路
+  （持仓 10s / 行情 5s / MCP 客户端重连）。Bridge 在两次探测间启动/恢复时缓存停留在上次失败结果。
+- 变更：setInterval(5min) → setTimeout 自适应链（_nextDelay/_scheduleNext，结果驱动）；
+  HEALTH_RETRY_MS=10s；构造注入 { intervalMs, retryMs }；resolveActiveBaseUrl 移入 try
+  （解析失败也落 healthy:false 走快速重试，原实现该场景灯灰且不自动重试）；_inFlight 防并发保留。
+
+### R-023 MCP 状态灯（src/mcp/QmtMcpManager.js）
+
+- 根因（已证实）：状态缓存只在 挂载/切换/手动探测 时刷新，无定时回路；dsh-mcp-client 自带 reconnect
+  只恢复真实连接（fiber 层），不刷新插件状态缓存。
+- 变更：probe() 结果写缓存后 _scheduleNext()；PROBE_RETRY_MS=10s；构造注入 { intervalMs, retryMs }；
+  无激活连接早退置 disabled 并取消定时器；unmount()/dispose() 停止调度；_probing 防并发；
+  探测本体与挂载/重连逻辑零改动。
+
+### 验证
+
+- scripts/test-health-monitor.mjs 10/10 绿；scripts/test-mcp-status.mjs 12/12 绿（调度机制守护）；
+- pnpm typecheck 0 错；pnpm build 通过（lib 两文件均含自适应逻辑）；
+- 存量回归 test-quote-sync / test-position-sync 均 0 退出。
+
+## 待老师确认事项
+
+1. R-022 / R-023 定稿确认（边界：健康/已连接稳态 5 分钟不变 / 异常 10s 重试 / 不新增配置 / API 前端零改动）；
+2. 真实环境人工验收（验收标准.md 第 8 条）：停/启 QMT Bridge → QMT 灯与 MCP 灯 ≤20s 自动回绿、
+   点击仍即时探测、插件重载后缓存秒回。
+
+## 经验沉淀（候选）
+
+- 定时轮询类功能的恢复感知要与故障探测解耦：固定低频定时器做稳态，异常态必须用快速重试把「恢复」
+  也纳入自愈回路——灯类状态"看起来没生效"的根因通常是恢复路径的响应时延，而不是探测本身失效。
+- 「外层有自管重连」不等于「状态缓存会自愈」：重连只恢复真实连接，展示层缓存若无自己的刷新回路，
+  必须单独加状态自适应探测（R-023 教训）。
@@ -0,0 +1,32 @@
+# 迭代目标：19-指示灯状态自适应探测（QMT 健康灯 + MCP 灯）
+
+## 目标
+
+会话头部两只「连接类」指示灯（QMT连接 / MCP）改为**结果驱动自适应探测**：
+健康/已连接时维持 5 分钟稳态探测（低开销），异常/未知时每 10 秒快速重试，
+使 QMT Bridge 与其 MCP 服务启动/恢复后指示灯 ≤20s 自动回绿，不再等满 5 分钟。
+
+## 目标描述
+
+- **背景**：两只灯的数据分别来自 QmtHealthMonitor / QmtMcpManager 的内存状态缓存，刷新机制均为
+  固定/缺失低频定时回路——QMT 健康缓存固定每 5 分钟探测一次（R-022），MCP 状态缓存只在
+  挂载/切换/手动探测时刷新、无定时回路（R-023）。持仓（10s）/ 行情（5s）灯靠各自定时同步秒级自愈；
+  唯独两只连接灯恢复感知滞后，老师实测反馈「QMT连接灯一直没亮」「MCP 灯也不自动恢复」（2026-09-09）。
+- **范围**：只改 QmtHealthMonitor（R-022）与 QmtMcpManager（R-023）的探测调度；前端指示灯组件、
+  sync-status / qmt-health / mcp-status 端点零改动；健康稳态间隔 5 分钟不变；不新增配置项。
+- **验收线**：两灯异常/未知态 ≤10s 重试；健康/已连接态维持 5 分钟不空转；服务恢复后缓存回正常态
+  沿快速重试被感知；无激活连接与 dispose 后停止调度。对应需求 R-022 + R-023。
+
+## 目标讨论过程
+
+1. 老师报告症状（2026-09-09）：Bridge 启动后其他三灯自动点亮，QMT 灯不亮 → 定位为健康缓存固定 5 分钟探测。
+2. AI 提议自适应节奏（健康 5min / 异常 10s），老师确认方向，迭代 19 实施（R-022）。
+3. 老师复查发现 MCP 灯同样不自动恢复（R-023）→ 确认 QmtMcpManager 状态缓存无定时回路，
+   dsh-mcp-client 重连只恢复真实连接、不刷新本类缓存 → 同模式加自适应探测，并入本次迭代。
+4. 决策点见 R-022 / R-023 决策记录。
+
+## 对老师（项目主理人）的配合需求
+
+- 确认 R-022 / R-023 定稿与迭代 19 验收（核实标准见验收标准.md）；
+- 真实环境人工验收：停/启 QMT Bridge → QMT 灯 ≤20s 回绿、MCP 灯 ≤20s 回绿；点击灯/「检测 MCP」仍即时探测；
+  插件重载后灯按缓存秒回并正常。
@@ -0,0 +1,29 @@
+# 验收标准：19-指示灯状态自适应探测
+
+## 验收标准线
+
+| # | 标准 | 判定 |
+|---|---|---|
+| 1 | QMT 健康：异常/未知态按 retryMs（默认 10s）快速重试 | test-health-monitor [2]：≥2 次快速重试且缓存 healthy=false |
+| 2 | QMT 健康：Bridge 恢复后 ≤ 一个重试周期缓存回 healthy=true（灯回绿），无需等 5 分钟 | 同脚本 [2] |
+| 3 | QMT 健康：健康态维持稳态间隔（默认 5 分钟）不空转 | 同脚本 [3] |
+| 4 | QMT 健康：stop() 后停止自动调度 | 同脚本 [4] |
+| 5 | MCP：无激活连接置 disabled 且不调度（真实 probe 早退不触 SDK） | test-mcp-status [1] |
+| 6 | MCP：异常态按 retryMs 快速重试；MCP 服务恢复后自动探测到 connected（灯回绿） | 同脚本 [2] |
+| 7 | MCP：已连接态按 intervalMs 稳态不空转；dispose() 后停止调度；_nextDelay 节奏正确 | 同脚本 [3][4][5] |
+| 8 | 启动即探测 + 读缓存秒回语义不变（QMT 健康 / MCP 状态） | 两脚本 [1]；sync-status/qmt-health/mcp-status 端点零改动 |
+| 9 | 构建产物（lib/）含两处自适应逻辑；typecheck 0 错；存量不回归 | pnpm typecheck + pnpm build；test-quote-sync / test-position-sync 通过 |
+
+## 验收方法
+
+- 自动化：node scripts/test-health-monitor.mjs（10/10）+ node scripts/test-mcp-status.mjs（12/12）全绿；
+  pnpm typecheck；pnpm build；存量回归脚本 0 退出。
+- 人工（老师真实环境）：重启插件后四灯状态秒回；停 QMT Bridge → QMT 灯 ≤10s 转红、MCP 灯 ≤10s 转红、
+  持仓/行情灯按 30s/15s 阈值转黄；**重新启动 QMT Bridge → QMT 灯与 MCP 灯 ≤20s 自动回绿**（本次修复核心）；
+  点击 QMT 灯 /「检测 MCP」仍即时探测并刷新悬停详情。
+
+## 验收目标
+
+修复确认：QMT Bridge 及其 MCP 服务启动/恢复后，会话头部 QMT连接灯与 MCP 灯自动回绿（≤20s），
+与其余两盏数据灯恢复节奏一致；健康/已连接稳态无额外探测开销；前端与 API 行为不变。
+验收通过后 R-022 / R-023 定稿并归档（老师确认）。