one_divine_lot/docs/04-迭代记录/01-分仓管理工具/程序结构设计.md

# 程序结构设计：01-分仓管理工具

> 迭代设计 v2 的程序结构细化 ｜ 2026-08-27

## 一、整体目录结构

```
one_divine_lot/
├── package.json              # 插件元数据 + dsh.client 声明（web 平台）
├── src/                       # 源码（服务端 + 客户端）
│   ├── index.js               # 插件入口：apply(ctx)，组装各模块
│   ├── settings.js            # 设置管理：ctx.settings.register（策略 CRUD + 开关）
│   ├── storage.js             # 本地存储：分仓分配 JSON 读写
│   ├── api.js                 # 服务端 RPC API：connection.rpc.intercept('/api') 端点
│   ├── data-source/
│   │   ├── types.js           # 统一数据模型（Position / AssetSummary / DataSource 接口）
│   │   └── qmt-bridge-rest.js # QMT Bridge REST 适配器（fetch 直连）
│   ├── position/
│   │   └── manager.js         # 分仓逻辑：持仓↔策略份额分配、聚合视图
│   └── client/
│       ├── index.js           # 客户端插件入口：注册 conversation.view entries
│       └── views/
│           ├── StrategyTab.jsx  # 策略标签 tab 组件（渲染该策略持仓）
│           └── PositionList.jsx # 持仓列表子组件
├── lib/                        # 构建输出（与 src 结构对应）
│   ├── index.js
│   ├── settings.js
│   ├── storage.js
│   ├── api.js
│   ├── data-source/
│   ├── position/
│   └── client/                 # 客户端 bundle（浏览器端加载）
└── docs/                       # 神之一手框架文档（既有）
```

## 二、模块职责与依赖

### 1. index.js（插件入口）
```js
const name = 'one-divine-lot';
const inject = ['tools', 'settings', 'webServer'];  // 依赖 DSH 服务
async function apply(ctx, config) {
  const settings = registerSettings(ctx);          // 设置管理
  const storage = new Storage(config);             // 本地存储
  const dataSource = new QmtBridgeRestDataSource(config);  // REST 数据源
  const manager = new PositionManager({ dataSource, storage });  // 分仓逻辑
  registerApi(ctx, manager);                       // 服务端 API
  registerClient(ctx);                             // 客户端插件（dsh.client）
  ctx.effect(() => () => { /* 清理 */ });
}
export { name, inject, apply };
```

### 2. settings.js（设置管理）
- `ctx.settings.register('one-divine-lot', schema)`
- schema：strategies: array[{ id, name, visible, order }]
- 预置：网格超市、手动做T
- 提供 getStrategies() / watchStrategies()（客户端 API 读取）

### 3. storage.js（本地存储）
- 路径：`~/.dsh/one-divine-lot/allocations.json`
- 结构：`{ [positionCode]: { [strategyId]: shares } }`
- API：load() / save() / get(code) / set(code, strategyShares)

### 4. data-source/qmt-bridge-rest.js（REST 数据源）
- baseUrl：http://192.168.3.43:8610（config 可配）
- getPositions() → GET /trade/positions → Position[]
- getAsset() → GET /trade/asset → AssetSummary
- 字段映射：语义字段优先，m_ 回退（技术约束-001/003）

### 5. position/manager.js（分仓逻辑）

> 2026-08-27 S5 讨论定稿：
> - Q1 按股数分配；Q2 允许未分配余额（sum ≤ 总持仓）；Q3 策略仅为人为分组（无策略逻辑）；
> - Q4 不做统计（无市值/盈亏/占比聚合）；Q5 UI = 策略 tab 内编辑（添加默认0起填 + 指定数量移出）。

- getAllPositions()：全量持仓（QMT，真实数据）
- getPosition(code)：单只持仓
- getStrategyPositions(strategyId)：某策略下的持仓（读分配份额，过滤出份额>0的标的）
- getUnallocated()：未分配持仓（总持仓 - 各策略份额之和 > 0 的标的）
- addToStrategy(code, strategyId, shares)：添加到策略（**份额从0起填**，更新该策略份额，并刷新已分配）
- removeFromStrategy(code, strategyId, shares)：从策略移出（**指定数量**，份额减少，回到未分配）
- getSummary()：返回 { 全部持仓, 各策略份额, 已分配合计, 未分配 }（仅份额，无统计）
- 校验：单策略份额 ≤ 总持仓；已分配合计 ≤ 总持仓（允许未分配余量）

### 6. api.js（服务端 RPC API —— DSH 原生通道）

> **修正（2026-08-27）**：使用 DSH 原生 RPC（connection.rpc.intercept('/api')），不自开 HTTP 路由。

```js
ctx.inject(['connection'], (connectionCtx) => {
  connectionCtx.connection.rpc.intercept('/api', matcher, handler, { authority: 'trusted-host' })
})
```

- 端点（endpoint 命名，channel 相对路径）：
  - `one-divine-lot/strategies` → 策略列表（含 visible）
  - `one-divine-lot/positions` → 全量持仓（QMT）
  - `one-divine-lot/allocations` → 分仓分配
  - `one-divine-lot/summary` → 分仓聚合视图
  - `one-divine-lot/strategy/:id/positions` → 某策略持仓
- 职责：接收 DSH RPC 请求 → 调 manager/data-source（统一接口）→ 返回数据
- **不是请求本身**：真正发 HTTP 到 QMT 的是 data-source/qmt-bridge-rest.js

### 7. client/index.js（客户端插件）
- package.json dsh.client 声明（web 平台）→ DSH clientModules 自动加载
- **tab 结构（2026-08-27 Q5 确认）**：
  - 全部持仓：显示全量真实持仓，已分配部分标注（网格 X / 做T Y / 未分配 Z）
  - 网格策略持仓：初始为空，可从全部持仓添加
  - 做T持仓：初始为空，可从全部持仓添加
- 注册 conversation.view entries（在对话/轨迹/上下文之后）：
```js
ctx.slots.register('conversation.view', {
  id: 'all-positions',
  label: '全部持仓',
  component: AllPositionsTab,
})
ctx.slots.register('conversation.view', {
  id: 'strategy-grid',
  label: '网格策略持仓',
  component: StrategyTab,
})
ctx.slots.register('conversation.view', {
  id: 'strategy-manual-t',
  label: '做T持仓',
  component: StrategyTab,
})
```
- 策略持仓 tab 内编辑：添加（默认0起填）+ 移出（指定数量）

### 8. client/views/StrategyTab.jsx
- 挂载后从服务端 API 拉取该策略持仓
- 渲染：策略下持仓列表（代码/名称/份额/市值/盈亏）
- 展示未分配持仓区域
- 数据刷新：切换 tab 时拉取（本期）

## 三、职责边界（api.js vs qmt-bridge-rest.js）

> 2026-08-27 老师提问澄清，明确两层职责：

| 层 | 文件 | 职责 | 交互对象 |
|---|---|---|---|
| RPC 封装层 | api.js | 接收 DSH 请求，转发给业务层 | 浏览器客户端（DSH RPC 通道） |
| 业务逻辑层 | position/manager.js | 分仓逻辑（份额分配/聚合） | 上层（api.js） |
| 数据源适配层 | data-source/qmt-bridge-rest.js | **真正发 HTTP 请求到 QMT** + 字段映射 + 统一接口 | QMT Bridge REST |

**调用链**：api.js → manager.js → qmt-bridge-rest.js → fetch → QMT REST
**换数据源**：只替换 qmt-bridge-rest.js（统一接口不变，上层无感）—— 技术约束-001

## 四、数据流

```
用户点击「网格策略持仓」tab
  → 客户端 StrategyTab 挂载
  → call('/api', 'one-divine-lot/strategy/grid-supermarket/positions')   // RPC 通道
  → api.js handler 调 manager.getStrategyPositions(id)
      → storage 读分配份额 + dataSource 读全量持仓
      → 过滤出该策略份额>0的持仓
  → RpcResult 返回 → 客户端渲染持仓列表

用户添加份额（在网格 tab 操作）
  → call('/api', 'one-divine-lot/allocations/add', { code, strategyId, shares })
  → manager.addToStrategy(code, strategyId, shares)
      → storage.set 更新份额（校验 ≤ 总持仓）
  → 返回更新后的分配 → 客户端刷新
```

## 五、关键接口签名（待实现时对照类型确认）

- `ctx.settings.register(ns, schema)` → SettingsScope（get/watch/update）
- `webServer.register({kind:'http'|'upgrade', path, handler})` → disposer
- `ctx.slots.register('conversation.view', {id, label, component})`（客户端，具体签名实现时读 slots.d.ts）
- `dsh.client` 声明：`{ "dsh": { "client": { "platform": "web", "inject": [...] } } }`

## 六、开发顺序（编码）

1. package.json + 骨架目录
2. data-source（REST 适配 + 类型）
3. settings（策略注册）
4. storage（分仓 JSON）
5. position/manager（分仓逻辑）
6. api（服务端路由）
7. client（tab 注册 + 组件）
8. 宿主挂载 + 联调验收

## 七、非目标（本期不做）

- 不做份额编辑 UI（二期）
- 不做策略参数的完整管理（网格区间等，后续迭代）
- 不做做T 记录
- 不做风控引擎