one_divine_lot/docs/02-计划/计划-QMT连接配置.md

计划：QMT 连接配置（多配置管理 + 会话头部快捷切换）（阶段航点）

编号：PLAN-003 ｜ 粒度：阶段航点（大粒度） ｜ 创建：2026-08-29 ｜ 状态：已完成（2026-08-29 验收通过，R-004 已归档） 派生自终极目标：目标-001（DSH 插件形态）、目标-008（真实交易系统接入·统一数据源抽象） 依据需求：R-004（已定稿，2026-08-29） —— 符合入范围门槛（已定稿方可进入计划） 设计约束：产品约束-005/006、技术约束-003/008/009、UI约束-001/002、技术约束-004/005/006/007（沿用）

目标

为插件增加 QMT Bridge 连接的多配置管理能力：设置页「QMT 连接配置」子 tab 管理 多个连接配置（CRUD / 激活 / 默认 / 测试连接），会话头部（PTC 模式标签旁）常驻 快捷切换控件；激活配置立即切换数据源地址（无需重启 DSH），重启后回到默认配置。

范围

做（对应 R-004 定稿范围，决策编号 Q1-Q10）：

1. 设置页「QMT 连接配置」子 tab（产品约束-005、UI约束-002）：
   • 配置 CRUD：新增 / 编辑 / 重命名 / 删除（字段：名称 + HTTP 地址）；
   • 单选激活（一次只能激活一个），激活立即生效；
   • 默认标记：启动时自动激活默认配置，重启后回到默认；
   • 测试连接：手动触发，请求 /health 返回可达性与延迟；
   • 删除边界：删激活配置→自动切默认；删默认→默认标记转列表第一条并激活之；禁删最后一条；
2. 会话头部快捷切换（产品约束-006、UI约束-001、技术约束-009）：
   • slot conversation.session.header.actions 注册紧凑下拉 chip：QMT: <激活配置名> ▾；
   • 菜单列出全部配置（激活项勾选），点选即激活 + toast 反馈；
   • 头部仅切换，管理仍在设置页；
3. 生效机制（技术约束-008）：
   • 激活/修改后立即切换（更新数据源实例 baseUrl，按请求读取已核实）；
   • 启动时自动激活默认配置；列表为空时回退 cordis 注入的 qmtBaseUrl 兜底；
4. 存储（技术约束-008）：复用 one-divine-lot settings namespace，新增 qmtConnections（list + activeId + defaultId）。

不做（本期）：

• 认证/多账户支持（QMT Bridge 当前无鉴权）；
• 连接状态监控与断线重连（后续）；
• 超时（timeoutMs）配置化 —— 保持代码默认 15000ms（Q5）；
• 宿主配置（cordis.patch.yml qmtBaseUrl）自动迁移 —— 首次使用手动录入（Q4）；
• 激活前强制连通性校验 —— 测试连接为手动操作（Q3）；
• 头部菜单管理能力（增删改/测试连接/设默认）—— 留在设置页（Q10）。

程序结构（改造后）

src/
├── index.js                        # 服务端入口（改）
│   ├── 数据源创建后注册为可寻址组件；启动时按「默认配置」初始化激活地址（列表空→cordis qmtBaseUrl 兜底）
│   └── inject + ['settings', 'webServer']（不变）
├── settings.js                     # 设置管理（改）
│   ├── schema 增加 qmtConnections: { list: [{id,name,baseUrl,order}], activeId, defaultId }
│   ├── 新增 QMT 连接配置 CRUD（与策略 CRUD 同模式：列表读写 + 整表 update）
│   │   ├── getQmtConnections(scope)            # 读列表（按 order 排序）
│   │   ├── addQmtConnection(scope, {name, baseUrl})
│   │   ├── renameQmtConnection(scope, id, {name, baseUrl})
│   │   ├── removeQmtConnection(scope, id)      # 删除边界处理（产品约束-005）
│   │   ├── activateQmtConnection(scope, id)    # 激活（写 activeId）
│   │   ├── setDefaultQmtConnection(scope, id)  # 设默认（写 defaultId）
│   │   └── resolveStartupConnection(scope, config)  # 启动激活地址解析（默认→激活→cordis 兜底）
│   └── generateQmtConnectionId(name, existingIds)   # slug id（复用拼音映射与去重逻辑）
├── data-source/qmt-bridge-rest.js  # 数据源（改：小改）
│   └── 新增 setBaseUrl(url)  # 运行期更新实例地址（技术约束-008：按请求读取，改字段即生效）
│       （timeoutMs 不暴露 setter —— Q5）
├── api.js                          # 服务端 HTTP API（改）
│   ├── METHODS 增加：qmt-connections / qmt-connections/add
│   │   / qmt-connections/update / qmt-connections/remove
│   │   / qmt-connections/activate / qmt-connections/set-default
│   │   / qmt-connections/test（服务端代理 GET {baseUrl}/health，返回 {ok, latencyMs, status}）
│   └── 编排：activate/update/remove 成功后调用 dataSource.setBaseUrl(激活地址)
├── client/
│   ├── index.js                    # 客户端入口（改）
│   │   └── slots.register({ name: 'conversation.session.header.actions', id: 'odl-qmt-switch', order: -9 }, QmtConnectionChip)
│   └── views/
│       ├── QmtConnectionChip.jsx   # 新增：头部快捷切换控件（下拉 chip + 菜单 + toast 反馈）
│       └── SettingsSection.jsx     # 改：新增第三个子 tab「QMT 连接配置」
│           └── 内部新组件 QmtConnectionsSettings：配置列表 + 行内操作 + 新增/编辑表单 + 删除确认弹窗
└── cordis.patch.yml                # 不改：qmtBaseUrl 保留为兜底种子（Q4 不迁移）

改动说明（按文件）

文件	改动	依据
src/settings.js	schema 增 qmtConnections；新增 7 个 CRUD/激活/默认/启动解析函数	技术约束-008、产品约束-005
src/data-source/qmt-bridge-rest.js	新增 setBaseUrl(url)；其余不动	技术约束-008（按请求读取地址）
src/api.js	新增 7 个 qmt-connections 端点；activate/update/remove 编排 setBaseUrl	技术约束-004（webServer 自开路由）、-008
src/index.js	启动时解析并设置激活地址；数据源实例传递给 api 注册	技术约束-008
src/client/index.js	注册会话头部 slot（odl-qmt-switch，order=-9）	技术约束-009
src/client/views/QmtConnectionChip.jsx	新增头部切换控件（复用 ConnectionProvider/useRpc + Toast）	产品约束-006、UI约束-001
src/client/views/SettingsSection.jsx	新增「QMT 连接配置」子 tab 与配置管理界面	产品约束-005、UI约束-002
cordis.patch.yml	不改动	Q4（不迁移）

实现步骤（建议顺序）

1. 服务端数据层：settings.js 增 schema 与 CRUD/激活/默认/启动解析函数（纯函数，先行可测）；
2. 数据源热切换：qmt-bridge-rest.js 增 setBaseUrl；index.js 启动时 resolveStartupConnection 并设置初始激活地址；把 dataSource 传给 registerApi；
3. 服务端 API：api.js 增 7 个端点 + 激活编排 setBaseUrl；本地 curl 验证 CRUD/激活/测试连接；
4. 设置页 UI：SettingsSection.jsx 增「QMT 连接配置」子 tab（列表/表单/确认弹窗，复用 ConfirmDialog/Toast）；走通设置页全流程；
5. 头部快捷切换：client/index.js 注册头部 slot；新增 QmtConnectionChip.jsx（读列表/激活/失败反馈）；验证与 PTC 标签并排显示与切换生效；
6. 构建安装：服务端+客户端构建，dsh plugin add 安装，重载页面；
7. 验收：对照下节验收标准逐条核验，记录迭代 03。

验收标准

1. 设置页出现「QMT 连接配置」子 tab，配置 CRUD 完整可用（名称 + HTTP 地址）；
2. 激活某配置后，数据源立即切到该地址（无需重启 DSH）——通过切换后刷新持仓/测试连接验证目标端点随激活配置变化；
3. 默认配置行为正确：启动自动激活默认；重启后回到默认（即使运行中切过其他配置）；列表为空时按 cordis qmtBaseUrl 兜底且页面/数据源可用；
4. 测试连接返回可达性 + 延迟；激活不强制先测试；
5. 删除边界符合产品约束-005：删激活→自动切默认；删默认→默认转移列表第一条并激活；删最后一条被禁止；
6. 会话头部 PTC 标签旁出现 QMT: <激活配置名> chip，点选菜单项即激活并 toast 反馈；头部仅切换（无管理入口）；
7. 现有功能（分仓/策略/设置现有子 tab）不回归。

验收方法

• 建第二个配置指向任一可达地址，激活后通过「测试连接」与持仓加载观察目标地址变化；
• 重启 DSH（或重载插件）验证回到默认配置；
• 删除激活/默认配置验证自动切换与默认转移；删至最后一条验证禁止提示；
• 头部 chip 切换后观察 toast 与数据源目标变化（配合测试连接）。