init

2026-08-29 16:20:33 +08:00
commit cba31428dc
52 changed files with 6553 additions and 0 deletions
@@ -0,0 +1,116 @@
+# 技术实现方案：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 的包管理方式）。