one_divine_lot/docs/04-迭代记录/01-分仓管理工具/技术实现方案.md

技术实现方案：01-分仓管理工具（迭代设计 v2）

一、技术选型

项	选型	依据
数据源	QMT Bridge RESTful 接口（http://192.168.3.43:8610，OpenAPI v3）	技术约束-003（插件直连 REST，非 MCP）
HTTP 客户端	Node 内置 fetch（Node 22+）	零依赖
设置管理	ctx.settings 注册 namespace	DSH 内置 settings 服务
本地存储	JSON 文件（~/.dsh/one-divine-lot/）	分仓数据本地化
客户端 UI	dsh.client 平台 + React 组件	conversation.view 插槽扩展 tab 栏
宿主集成	cordis.patch.yml insert（web profile patch 层）	外部插件挂载

二、架构分层

[DSH 主窗口 conversation 区域]
   └─ view tabs：对话 │ 轨迹 │ 上下文 │ ➕ 策略标签（网格超市 / 手动做T ...）
        └─ 每个策略 tab = 一个 conversation.view 插槽 entry（ViewTab: id + label）
             └─ 渲染组件：加载该策略下的持仓数据
                    │  API 请求
[DSH 宿主] ◀── cordis.patch.yml insert 挂载插件行
   │
[插件核心（apply ctx）]
   ├─ settings：策略 CRUD + 显示开关（ctx.settings.register）
   ├─ storage：策略配置 + 分仓数据 JSON 持久化
   ├─ api：connection.rpc /api 通道端点（持仓、策略、分仓查询）
   ├─ data-source：QmtBridgeRestDataSource（fetch REST）
   └─ position：分仓逻辑（持仓 ↔ 策略份额分配）

三、模块详细设计

模块 1：数据源适配器（QmtBridgeRestDataSource）

• 基础地址：http://192.168.3.43:8610（插件配置项，可改）
• 端点封装：
  • getAsset() → GET /trade/asset（资金摘要）
  • getPositions() → GET /trade/positions（全量持仓，含语义字段 stock_code/volume/available/avg_price/price/market_value/profit/profit_pct）
  • getOrders() → GET /trade/orders（预留）
  • getTrades() → GET /trade/trades（预留）
  • health() → GET /health
• 字段映射：优先语义字段（stock_code 等），回退 m_ 原始字段
• 统一返回 Position[] / AssetSummary（技术约束-001）

模块 2：设置管理（策略=标签）

• ctx.settings.register('one-divine-lot', schema)
• schema 字段：
  • strategies: array of { id, name, visible(默认true), order }
  • 初始预置：网格超市、手动做T（老师可改）
• 用户经 DSH 设置界面维护：增/删/改策略、显示隐藏开关、排序

模块 3：分仓数据存储（本地）

• 文件：~/.dsh/one-divine-lot/allocations.json
• 结构：{ [positionCode]: { [strategyId]: shares } }
  • 示例：{ "600719.SH": { "grid-supermarket": 1000, "manual-t": 800 } }
• 约束：各策略份额之和 ≤ 总持仓（允许未分配余量）
• API：读/写分仓分配（服务端存储，QMT 只提供全量持仓）

模块 4：客户端 tab 栏（conversation.view 扩展）

• package.json 声明 dsh.client（web 平台）
• 客户端插件注册 conversation.view entries：
  • 读取设置中 visible=true 的策略，每个策略注册一个 ViewTab
  • 注册在既有 tab（对话/轨迹/上下文）之后
• 每个策略 tab 渲染：
  • 该策略下持仓列表（从服务端 API 获取）
  • 展示：代码/名称/份额/市值/盈亏
  • 未分配持仓展示在「未分配」区域
• 显示/隐藏：设置变更 → 重新注册/注销 view entry（或按 visible 过滤渲染）

模块 5：服务端 API（供客户端，RPC 通道）

修正：使用 DSH 原生 RPC（connection.rpc），不自开 HTTP 路由。

• ctx.connection.rpc.intercept('/api', matcher, handler, {authority:'trusted-host'})
• 端点：
  • one-divine-lot/strategies → 策略列表（含 visible）
  • one-divine-lot/positions → 全量持仓（QMT）
  • one-divine-lot/allocations → 分仓分配
  • one-divine-lot/allocations/update → 更新分仓分配（份额设置，二期）
  • one-divine-lot/strategy/:id/positions → 某策略下的持仓汇总

四、宿主挂载

• 修改 ~/.dsh/profiles/web/cordis.patch.yml，insert 插件行：

- insert:
    - id: one-divine-lot
      name: "one-divine-lot"   # 插件包名（本地安装或 link）
      config: { ... }

• 插件包需在 profile 的 node_modules 中可用（pnpm link / 本地安装）
• 遵循 editing-cordis-compositions：不改 shipped preset，走用户 profile patch 层

五、实现步骤

1. 服务端骨架：插件包结构 + package.json（dsh.client 声明）+ apply(ctx) 入口
2. 数据源适配：QmtBridgeRestDataSource（REST 直连，字段映射）
3. 设置管理：ctx.settings.register（策略 schema）
4. 存储：allocations.json 读写
5. 服务端 API：connection.rpc.intercept('/api') 端点（策略/持仓/分仓）
6. 客户端插件：conversation.view entries 注册 + 策略持仓渲染组件
7. 宿主挂载：cordis.patch.yml insert + 插件安装
8. 验收：设置→tab 显示→持仓加载→持久化

六、涉及设计约束

• 技术约束-001（统一数据源抽象）/ 003（REST 直连）
• 产品约束-001（全量持仓）/ 002（标签体系）/ 003（标签自定义+显示开关）

七、风险与开放项

1. conversation.view 插槽注册的精确 API（register 签名）需在实现时读取 slots.d.ts 确认；
2. 服务端 API 与客户端通信：走 DSH webServer 标准路由 → 已确认走 DSH 原生 RPC 通道（connection.rpc.intercept）；
3. 策略 tab 的渲染组件挂载到 conversation.view 后，其数据刷新时机（实时/手动/切换时）；
4. 分仓份额编辑入口：设置界面 or tab 内直接编辑（先做 tab 内只读展示，编辑入口二期）；
5. 插件本地安装方式：pnpm link 到 profile node_modules（需确认 profile 的包管理方式）。