116 lines
5.8 KiB
Markdown
116 lines
5.8 KiB
Markdown
# 技术实现方案：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 插件行：
|
||
```yaml
|
||
- 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 的包管理方式）。 |