kyugao
bb3f8bd28d
- 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
13 KiB
13 KiB
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，当前未暴露到配置，使用默认值 |
分析结论：
- 核心只需配置一个 HTTP 地址（baseUrl）—— 插件与 QMT Bridge 的所有通信都基于它（/health、/trade/、/data/ 等 REST 端点）；
- 可选配置一个请求超时（timeoutMs）—— 仅在需要调整超时时才需配置，可提供默认值；
- 当前不需要其他连接参数：无认证（QMT Bridge REST 端点无鉴权）、无账户/密码、无额外 header —— 未来若 QMT Bridge 增加鉴权，再扩展配置字段。
2026-08-29 讨论前代码审查补充（支撑决策）：
- 数据源的 baseUrl/timeoutMs 为按请求读取（qmt-bridge-rest.js），激活切换只需更新数据源实例字段，无需重建实例，「立即切换」实现成本低；
- QMT Bridge 已有
/health端点（插件启动检查在用），「测试连接」可直接复用； - 策略配置已有 settings namespace + CRUD + 设置页子 tab 完整先例，连接配置存储可复用该模式。
功能范围（定稿）
做：
- 设置页新增「QMT 连接配置」子 tab（与现有「通用设置 / 策略分组」并列）；
- 配置 CRUD：新增 / 编辑 / 删除 / 重命名；配置字段为名称（识别用）+ HTTP 地址（必填）；超时不纳入表单（Q5）；
- 激活：单选激活，一次只能激活一个；激活后立即切换生效，无需重启 DSH（Q2）；
- 默认：标记某配置为默认；启动时自动激活默认配置，运行中手动激活其他配置立即生效，重启后回到默认（Q1）；
- 测试连接：手动触发，请求
/health返回可达性与延迟；激活不强制先测试（Q3）； - 删除边界：允许删除激活配置（自动切换到默认）；删除默认配置时默认标记转移到列表第一条并激活之；禁止删除最后一条（Q6）；
- 会话头部快捷切换：在会话窗口顶栏注册下拉控件（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