feat: 迭代03-05 交易记录接入、行情实时、QMT连接配置、data store 标准化

- R-004 QMT连接配置：多配置管理 + 会话头部快捷切换（03-QMT连接配置） - R-005 WS盘中价格实时更新：服务端中转+缓存+前端轮询（04-WS盘中价格实时更新） - R-006 策略数据 JSON data store 标准化（store.json/market.json/schema.json） - R-007 交易记录接入：当日订单+成交单表合并（委托主行+展开成交明细）、时间段查询（今日/本周/本月+手动起止）、费用计算（佣金费率万m_dCommission+最低5元、印花税卖出万5、过户费双向万0.1） - 架构治理：api 按领域拆分、component 目录、QmtHealthMonitor
2026-09-01 13:21:49 +08:00
parent 5a723d514e
commit bb3f8bd28d
57 changed files with 5244 additions and 397 deletions
@@ -0,0 +1,127 @@
+# R-004 QMT 连接配置（多配置管理 + 会话头部快捷切换）· 已完成
+
+> 归档日期：2026-08-29 ｜ 需求状态：**已完成**
+> 原索引：docs/05-需求池/需求池索引.md（主索引保留 R-004 条目，指向本归档）
+> 定稿记录：2026-08-29 老师确认定稿（三要素满足：边界清楚 + 核心逻辑明确 + 老师确认）
+> 来源：老师指令（2026-08-28）
+> 关联：docs/05-需求池/需求池索引.md（R-004）
+> 说明：待确认问题清单与讨论记录原独立记录于 R-004-待确认问题.md，2026-08-29 经老师要求整合入本文档（保留一份），原独立文件已删除。
+
+## 需求概述
+
+在神之一手的**设置页面**新增一个子 tab「QMT 连接配置」，用于管理多个 QMT Bridge 连接配置：
+
+- **多配置管理**：可维护多个连接配置（增 / 删 / 改 / 查）；
+- **一次只能激活一个**：从多个配置中单选激活一个，被激活的配置为当前生效连接；
+- **可设置默认**：标记某配置为默认（默认 = 启动时自动激活的配置，见 Q1）；
+- **快捷切换**：在会话窗口顶栏（PTC 模式标签旁）提供常驻下拉控件，一键切换当前激活的连接，无需进入设置页（见 Q9/Q10）。
+
+## 现状分析：插件当前使用的 QMT 连接信息
+
+> 通过代码审查得出（src/data-source/qmt-bridge-rest.js、src/index.js、cordis.patch.yml）：
+
+| 配置项 | 当前值 | 是否必配 | 说明 |
+|---|---|---|---|
+| **HTTP 基础地址（baseUrl）** | `http://192.168.3.43:8610` | **是（唯一必配）** | 由宿主 cordis.patch.yml 注入 `config.qmtBaseUrl`；数据源所有 REST 请求基于此地址 |
+| **请求超时（timeoutMs）** | 15000ms | 否（有默认值） | 代码常量 REQUEST_TIMEOUT_MS=15000，当前未暴露到配置，使用默认值 |
+
+**分析结论**：
+1. **核心只需配置一个 HTTP 地址**（baseUrl）—— 插件与 QMT Bridge 的所有通信都基于它（/health、/trade/*、/data/* 等 REST 端点）；
+2. **可选配置一个请求超时**（timeoutMs）—— 仅在需要调整超时时才需配置，可提供默认值；
+3. **当前不需要其他连接参数**：无认证（QMT Bridge REST 端点无鉴权）、无账户/密码、无额外 header —— 未来若 QMT Bridge 增加鉴权，再扩展配置字段。
+
+**2026-08-29 讨论前代码审查补充**（支撑决策）：
+- 数据源的 baseUrl/timeoutMs 为**按请求读取**（qmt-bridge-rest.js），激活切换只需更新数据源实例字段，无需重建实例，「立即切换」实现成本低；
+- QMT Bridge 已有 `/health` 端点（插件启动检查在用），「测试连接」可直接复用；
+- 策略配置已有 settings namespace + CRUD + 设置页子 tab 完整先例，连接配置存储可复用该模式。
+
+## 功能范围（定稿）
+
+**做**：
+1. 设置页新增「QMT 连接配置」子 tab（与现有「通用设置 / 策略分组」并列）；
+2. **配置 CRUD**：新增 / 编辑 / 删除 / 重命名；配置字段为名称（识别用）+ HTTP 地址（必填）；超时不纳入表单（Q5）；
+3. **激活**：单选激活，**一次只能激活一个**；激活后**立即切换**生效，无需重启 DSH（Q2）；
+4. **默认**：标记某配置为默认；启动时自动激活默认配置，运行中手动激活其他配置立即生效，重启后回到默认（Q1）；
+5. **测试连接**：手动触发，请求 `/health` 返回可达性与延迟；激活不强制先测试（Q3）；
+6. **删除边界**：允许删除激活配置（自动切换到默认）；删除默认配置时默认标记转移到列表第一条并激活之；**禁止删除最后一条**（Q6）；
+7. **会话头部快捷切换**：在会话窗口顶栏注册下拉控件（slot `conversation.session.header.actions`，与 DSH 内置 PTC 模式标签并排）：chip 形态显示 `QMT: <激活配置名>`，点开列出全部配置（激活项勾选标记），点选即激活并 toast 反馈；头部控件**仅做切换**，配置的增删改/测试连接/默认标记仍在设置页子 tab（Q9/Q10）。
+
+**存储**：复用现有 one-divine-lot settings namespace（与策略配置同机制），不新增独立存储文件（Q8）。
+
+**不做**：
+- 认证/多账户支持（QMT Bridge 当前无鉴权，未来扩展）；
+- 连接状态监控（如断线重连策略）—— 后续；
+- 超时（timeoutMs）配置化 —— 保持代码默认 15000ms（Q5）；
+- 宿主配置（cordis.patch.yml qmtBaseUrl）自动迁移 —— 首次使用手动录入（Q4）；
+- 激活前强制连通性校验 —— 测试连接为手动操作（Q3）。
+
+## 待确认问题（Q1-Q10，已确认）
+
+> 2026-08-29 由老师逐条拍板（AI 提议 + 老师确认）。Q8（存储位置）与 Q9/Q10（快捷切换）为当轮讨论新增。
+
+| # | 问题 | 状态 | 确认日期 | 结论摘要 |
+|---|---|---|---|---|
+| Q1 | **「默认」的语义**：默认 = 插件启动时自动激活的配置？还是仅作为列表中的默认选中项？手动激活非默认配置后，下次启动是否回到默认？ | 已确认 | 2026-08-29 | 默认 = 插件启动时自动激活的配置；运行中手动激活其他配置立即生效，重启后回到默认 |
+| Q2 | **生效机制**：激活配置后**立即切换**（动态重建数据源，无需重启 DSH）？还是保存后**重启生效**？（当前数据源在插件 apply 时创建一次，改为动态切换需调整架构） | 已确认 | 2026-08-29 | 激活后**立即切换**：更新数据源实例的 baseUrl 即可，无需重启 DSH（代码审查已核实：数据源按请求读取地址，改动成本低） |
+| Q3 | **是否提供「测试连接」按钮**：验证地址可达（请求 /health 检查 status=ok），帮助确认配置正确？ | 已确认 | 2026-08-29 | 提供，**手动测**：请求 /health 返回可达性与延迟；激活本身不强制先测试（复用现有 /health 端点） |
+| Q4 | **现有宿主配置迁移**：cordis.patch.yml 中的 `qmtBaseUrl`（192.168.3.43:8610）如何处理 —— 首次启动时作为**初始默认配置**自动迁入设置页？ | 已确认 | 2026-08-29 | **不迁移**：首次使用手动录入配置 |
+| Q5 | **超时是否纳入配置项**：timeoutMs 是否需要出现在配置表单（可选字段），还是保持代码默认值？ | 已确认 | 2026-08-29 | **不纳入**表单：timeoutMs 保持代码默认 15000ms |
+| Q6 | **删除/切换边界**：删除当前激活配置时如何处理（禁止删除？自动切换到默认？）；删除默认配置时默认标记如何转移？ | 已确认 | 2026-08-29 | 允许删除激活配置，删除后自动切换到默认配置；删除的若是默认配置，默认标记转移到列表第一条并激活之；**禁止删除最后一条**配置 |
+| Q7 | **优先级**：老师定级（P0-P2？）—— 建议 P1（提升多环境可用性，单地址当前可用） | 已确认 | 2026-08-29 | **P1** |
+| Q8 | **配置存储位置**（2026-08-29 讨论新增）：连接配置存储于何处？ | 已确认 | 2026-08-29 | 复用现有 one-divine-lot settings namespace（与策略配置同机制），不新增独立存储文件 |
+| Q9 | **快捷切换入口位置**（2026-08-29 讨论新增）：会话窗口顶栏（PTC 模式标签旁）？新建会话页？两处都放？ | 已确认 | 2026-08-29 | **会话头部，PTC 模式标签旁**（slot `conversation.session.header.actions`，多实例挂载点已核实可并排注册，无需改动宿主） |
+| Q10 | **头部菜单能力**（2026-08-29 讨论新增）：仅切换激活？含每项测试连接？含管理入口？ | 已确认 | 2026-08-29 | **仅切换激活**：列出配置、点选激活 + toast 反馈；测试连接与配置管理留在设置页 |
+
+## 讨论记录
+
+> 追加式记录：日期 · 轮次 · 结论。
+
+- **2026-08-29 · 第一轮（代码审查 + 逐条拍板）**：
+  - 讨论前代码审查补充三项事实（见「现状分析」补充节）：① 数据源 baseUrl/timeoutMs 按请求读取，「立即切换」成本低；② /health 端点可复用做测试连接；③ 策略配置的 settings namespace + CRUD + 设置页子 tab 模式可复用。
+  - 讨论中新增 Q8（配置存储位置），连同原 Q1-Q7 共 8 项由老师逐条拍板，结论见上表。
+  - 定稿确认环节：老师反馈「还有要调整的」，追问具体调整点未获选择。故 Q1-Q8 结论按已确认记录，**R-004 暂不定稿**，等待老师补充调整点后继续讨论。
+  - 文档整合：待确认问题清单与讨论记录并入本文档（老师要求保留一份），原独立文件 R-004-待确认问题.md 删除；「功能范围」一节同步按已确认决策对齐（超时移入不做、补充测试连接与删除边界、标注 Q 编号）。
+- **2026-08-29 · 第二轮（新增会话头部快捷切换功能）**：
+  - 老师提出新功能：会话窗口顶栏（PTC 模式标签旁）增加 QMT 连接快捷切换，避免每次进设置页修改。
+  - AI 前置技术调研结论：PTC 标签为 DSH 内置客户端插件 ui-agent-preset 向 slot `conversation.session.header.actions` 注册的会话头部标签；该 slot 为多实例挂载点（按 order 排序、多插件共存），本插件可并排注册控件，无需改动宿主；DSH 预设标签做成只读是因宿主禁止会话中途更换预设，而 QMT 激活是插件自管逻辑（Q2 已定立即切换），头部放真切换控件成立。
+  - 老师拍板：功能**并入 R-004**（不拆独立需求）；入口定**会话头部 PTC 标签旁**（Q9）；头部菜单**仅切换激活**（Q10）。管理能力（增删改/测试连接/默认标记）仍在设置页子 tab。
+- **2026-08-29 · 第三轮（定稿）**：
+  - 老师确认需求定稿。三要素核验：① 边界清楚（做/不做清单完整，含快捷切换）；② 核心逻辑明确（Q1-Q10 全部有结论，含存储、生效机制、删除边界、入口与菜单能力）；③ 老师明确确认。
+  - 决策沉淀：产品约束-005/006、技术约束-008/009（含技术约束-003 关联变更标注）、UI约束-001/002。
+  - 派生计划：PLAN-003（计划-QMT连接配置.md），进入执行范围。
+
+## 实现记录
+
+| 项 | 内容 |
+|---|---|
+| 实现迭代 | 03-QMT连接配置 |
+| 实现方式 | 沿用独立插件 one-divine-lot（服务端 + 客户端改造） |
+| 服务端 | settings.js（qmtConnections schema + CRUD/激活/默认/启动解析 9 函数）、qmt-bridge-rest.js（setBaseUrl 热切换）、index.js（启动激活地址解析 + dataSource 注入）、api.js（7 个 qmt-connections/* 端点 + /health 代理测试 + 激活/编辑/删除热切换编排） |
+| 客户端 | QmtConnectionChip.jsx（会话头部快捷切换 chip，slot conversation.session.header.actions order=-9）、SettingsSection.jsx（「QMT 连接配置」第三个子 tab，卡片形式）、client/index.js（头部 slot 注册） |
+| 构建安装 | pnpm run build（服务端 ESM + 客户端 CJS bundle + wrap）；profile 为 link 引用，构建即生效（服务端需宿主重启加载） |
+
+**实现期间调整（2026-08-29，老师反馈）**：① chip 空配置态由「隐藏」改为「显示 + 引导提示」（消除空态不可见问题）；② 设置页配置由列表形式改为**卡片形式**（自适应网格 + 长文本单行省略悬停看全文，UI约束-002 变更）。
+
+## 验收结果（2026-08-29 线上实测，详见 docs/04-迭代记录/03-QMT连接配置/验收标准.md）
+
+- ✅ 标准 1：设置页子 tab + 配置 CRUD（实录 GEMWIN / QMT_CYY 两条真实配置）
+- ✅ 标准 2：激活立即切换（切不可达配置 → 持仓立即失败；切回 → 立即恢复；全程无重启）
+- ✅ 标准 3：默认/启动行为（单测覆盖启动激活默认并回写、cordis 兜底；线上激活=默认一致）
+- ✅ 标准 4：测试连接（GEMWIN 可达 726ms；QMT_CYY 不可达 10.1s；激活无预检，符合 Q3）
+- ✅ 标准 5：删除边界（线上实测删激活配置自动切回默认；删默认转移/禁删最后一条由单测覆盖）
+- ✅ 标准 7：现有功能不回归（持仓/策略端点正常返回真实数据）
+- ✅ 标准 6：会话头部 chip —— 老师确认完成并标记 R-004 已完成（2026-08-29）
+
+## 经验沉淀
+
+- **服务端改动需重启宿主**：客户端 bundle 页面刷新即加载，服务端模块（api.js/settings.js 等）宿主启动时装入内存——"设置页报 unknown method 但页面能看到新 UI" 即两侧版本差的典型症状
+- **空态可见性**：入口控件「无数据即隐藏」在「数据需要经该入口创建」时形成死锁，空态应显示并给引导
+- **数据源热切换可行性**：baseUrl 为按请求读取的实例字段，运行期改字段即生效——无需重建实例/重启宿主（技术约束-008 的事实依据）
+- **profile link 安装形态**：插件以 symlink 指向工作区时，构建产物即宿主加载物，dsh plugin add 无需重复执行
+- **拼音 slug 兜底**：映射表外中文名会兜底为通用 id（如 qmt-conn），后续可扩词表或时间戳后缀增强区分度
+
+## 关联文档
+
+- 迭代记录：docs/04-迭代记录/03-QMT连接配置/（迭代目标 / 技术实现方案 / 验收标准）
+- 计划：docs/02-计划/计划-QMT连接配置.md（PLAN-003）
+- 设计约束：产品约束-005/006、技术约束-003（变更标注）/008/009、UI约束-001/002