181 lines
10 KiB
Markdown
181 lines
10 KiB
Markdown
# 程序结构设计：02-分仓管理工具完善与优化
|
||
|
||
> 迭代设计 v2 的程序结构细化 ｜ 2026-08-28
|
||
> 关联：技术实现方案.md（02）、R-003（已定稿）
|
||
|
||
## 一、整体目录结构（基于迭代 01 演进）
|
||
|
||
```
|
||
one_divine_lot/
|
||
├── package.json # 不变（已有 dsh.client 声明）
|
||
├── src/ # 源码（服务端 + 客户端）
|
||
│ ├── index.js # 插件入口：apply(ctx)，组装各模块（少量调整）
|
||
│ ├── settings.js # 设置管理：策略 CRUD 逻辑扩展（新增 id 生成、删除联动）
|
||
│ ├── storage.js # 本地存储：allocations.json（新增：清空策略份额）
|
||
│ ├── api.js # 服务端 HTTP API（webServer /odl/api/*）：新增端点
|
||
│ ├── data-source/
|
||
│ │ ├── types.js # 不变
|
||
│ │ └── qmt-bridge-rest.js # 不变
|
||
│ ├── position/
|
||
│ │ └── manager.js # 分仓逻辑：新增全部移入/清空策略份额
|
||
│ └── client/
|
||
│ ├── index.js # 客户端入口：tab 动态注册（O2 核心改造）
|
||
│ └── views/
|
||
│ ├── AllPositionsTab.jsx # 加载失败兜底（O5）
|
||
│ ├── StrategyTab.jsx # 全部移入/一键清零（O6）
|
||
│ ├── SettingsSection.jsx # 策略 CRUD 补全（O3）
|
||
│ ├── connection.jsx # API 调用错误透出增强（O5）
|
||
│ ├── LoadState.jsx # 【新增】三态加载组件（O5）
|
||
│ └── Toast.jsx # 【新增】轻提示组件（O6/O3）
|
||
└── docs/ # 神之一手框架文档（既有）
|
||
```
|
||
|
||
## 二、模块职责与变更点
|
||
|
||
### 1. index.js（插件入口）
|
||
- 基本不变；新增：把「策略配置读取」能力暴露给 api（已由 settings 提供）
|
||
- 组装链保持：dataSource → settings → storage → manager → api
|
||
|
||
### 2. settings.js（设置管理）—— O3 核心
|
||
- **现有**：registerSettings / getStrategies / getVisibleStrategies / updateStrategies
|
||
- **新增**：
|
||
- `generateStrategyId(name)`：中文/任意名 → 英文 slug（如「长线持有」→ long-term-hold；去空格、转小写、连字符）
|
||
- `addStrategy(scope, name)`：生成 id + 追加到列表末尾（order = max+1）
|
||
- `renameStrategy(scope, id, name)`：只改 name（id 不变，分配数据不受影响）
|
||
- `removeStrategy(scope, id)`：删除策略（**联动清空该策略份额** —— 调用 storage 清理 + 更新策略列表）
|
||
- `moveStrategy(scope, id, dir)`：上移/下移（调整 order）
|
||
- 策略 schema 不变（id/name/visible/order）
|
||
|
||
### 3. storage.js（本地存储）—— 配合 O3/O6
|
||
- **现有**：load/save/get/getAll/set/remove（按 code）
|
||
- **新增**：
|
||
- `removeStrategyShares(strategyId)`：遍历所有 code，删除该 strategyId 的份额（删除策略联动）
|
||
- `clearStrategy(strategyId)`：同 removeStrategyShares（O6 一键清零可复用）
|
||
|
||
### 4. position/manager.js（分仓逻辑）—— O6
|
||
- **现有**：getAllPositions/getStrategyPositions/getUnallocated/addToStrategy/removeFromStrategy/getSummary
|
||
- **新增**：
|
||
- `moveAllUnallocatedToStrategy(code, strategyId)`：把某票**全部未分配份额**移入指定策略（O6 全部移入）—— 未分配 = volume - 已分配，一次 add
|
||
- `clearStrategyShares(strategyId)`：清空某策略全部份额（O6 一键清零）—— 调 storage.clearStrategy + 返回影响标的列表
|
||
- 校验保持：各策略份额之和 ≤ 总持仓
|
||
|
||
### 5. api.js（服务端 API）—— 承载新端点
|
||
- **现有**：/odl/api/* 8 端点（webServer 自开路由，技术约束-004）
|
||
- **新增端点**：
|
||
- `POST /odl/api/strategies/remove`：{ strategyId } → 删除策略 + 联动清份额（O3）
|
||
- `POST /odl/api/strategies/move`：{ strategyId, dir } → 排序（O3）
|
||
- `POST /odl/api/strategies/add`：{ name } → 新增（O3，也可并入 update，分开更清晰）
|
||
- `POST /odl/api/remove-all-shares`：{ strategyId } → 一键清零（O6）
|
||
- 全部移入复用现有 `add-shares`（shares = 未分配数，由客户端先算好或服务端算）
|
||
- `strategies/update` 保留（重命名/显隐仍走整表更新）
|
||
- 错误透出：统一错误码（not-found / strategy-not-found / share-limit 等）
|
||
|
||
### 6. client/index.js（客户端入口）—— O2 核心改造
|
||
- **现有**：写死注册 3 个 tab
|
||
- **改造**：
|
||
- 新增 `loadStrategies()`：fetch /odl/api/strategies，取 visible=true 列表
|
||
- **动态注册**：遍历策略列表，逐个 `slots.register('conversation.view', { id: 'odl-strategy-<slug>', label: 策略名 }, StrategyTab)`
|
||
- 全部持仓 tab 固定保留（order 10，数据源 tab）
|
||
- **刷新机制**：暴露「刷新 tab 栏」函数 —— 重新拉策略配置 → 注销旧策略 tabs → 注册新 tabs
|
||
- **变更提示（无事件机制，老师确认）**：设置页保存成功后**就地提示**「策略已变更，刷新页面后生效」（Toast）；
|
||
- **tab 更新时机**：插件启动时按策略配置注册 tabs → 刷新页面 = 插件重载 = 按最新策略重新注册（基线方案 X）；
|
||
- **可选优化（方案 Y）**：tab 栏利用「会话切换/重新挂载」时机重新拉策略配置自动更新（无需自定义事件，实现时验证框架挂载钩子，失败则保持方案 X）
|
||
- **技术确认（已核实）**：`ctx.slots.register(...)` 返回 **disposer 函数**（注销该 entry）——动态注销旧 tabs 可行：注册时保存 disposer 列表，刷新时逐一调用 disposer 移除，再注册新 tabs
|
||
|
||
### 7. client/views/SettingsSection.jsx —— O3 UI
|
||
- **现有**：策略列表 + 显示开关
|
||
- **改造**：
|
||
- 新增策略：输入框 + 按钮 → call strategies/add { name }
|
||
- 重命名：行内编辑（改 name → strategies/update）
|
||
- 删除：删除按钮 → **确认弹窗**（提示「该策略下 N 股将回到未分配」）→ call strategies/remove
|
||
- 排序：上移/下移按钮 → call strategies/move
|
||
- 保留显示开关
|
||
- 操作反馈：Toast（成功/失败）
|
||
|
||
### 8. client/views/StrategyTab.jsx —— O6 UI
|
||
- **现有**：添加（选标的+份额）/ 移出（指定数量）
|
||
- **改造**：
|
||
- 「全部移入」按钮（行内）：该票未分配全部移入当前策略（call add-shares，shares=未分配）
|
||
- 「一键清零」按钮（顶部）：弹窗确认 → call remove-all-shares
|
||
- 操作反馈：Toast
|
||
- 加载失败：LoadState 兜底（O5）
|
||
|
||
### 9. client/views/AllPositionsTab.jsx —— O5
|
||
- **现有**：直接显示/加载失败文字
|
||
- **改造**：套 LoadState 三态组件（loading/error+重试/success）
|
||
|
||
### 10. 【新增】client/views/LoadState.jsx —— O5
|
||
- 三态组件：loading（加载中）/ error（失败原因 + 重试按钮）/ success（children）
|
||
- 自动重试 2 次（间隔 2s）逻辑内置（或由父组件控制）
|
||
|
||
### 11. 【新增】client/views/Toast.jsx —— O6/O3
|
||
- 轻提示：success（绿）/ error（红），3s 自动消失
|
||
- 简单实现：全局 state + 定时器，或 React portal
|
||
|
||
## 三、职责边界（延续迭代 01）
|
||
|
||
| 层 | 文件 | 职责 |
|
||
|---|---|---|
|
||
| API 封装层 | api.js | 接收 HTTP 请求 → 调业务层 |
|
||
| 业务逻辑层 | position/manager.js + settings.js | 分仓逻辑 + 策略管理 |
|
||
| 数据源适配层 | data-source/qmt-bridge-rest.js | 真正发 HTTP 到 QMT |
|
||
| 存储层 | storage.js | allocations.json 本地持久化 |
|
||
|
||
**调用链**：client → HTTP /odl/api/* → api.js → manager/settings → storage / qmt-bridge-rest → QMT
|
||
|
||
## 四、数据流（关键路径）
|
||
|
||
```
|
||
【O2 动态 tab】
|
||
设置页保存策略变更
|
||
→ SettingsSection 调 strategies/update（或 add/remove/move）
|
||
→ 服务端更新 settings + 联动 storage
|
||
→ 客户端 Toast「策略已变更，请手动刷新」+ 刷新按钮
|
||
→ 用户点刷新 → 重新 loadStrategies() → 注销旧 tabs → 注册新 tabs
|
||
|
||
【O3 删除策略】
|
||
设置页点删除 → 确认弹窗
|
||
→ call strategies/remove { strategyId }
|
||
→ settings.removeStrategy + storage.removeStrategyShares(strategyId)
|
||
→ 份额回未分配（全部持仓 tab 未分配数增加）
|
||
|
||
【O6 全部移入】
|
||
策略 tab 行内「全部移入」
|
||
→ 客户端已知该票未分配数 → call add-shares { code, strategyId, shares: 未分配数 }
|
||
→ manager.addToStrategy（校验 ≤ 总持仓）
|
||
→ Toast 成功 → reload
|
||
|
||
【O6 一键清零】
|
||
策略 tab 顶部「一键清零」→ 确认弹窗
|
||
→ call remove-all-shares { strategyId }
|
||
→ manager.clearStrategyShares → storage.clearStrategy
|
||
→ Toast 成功 → reload
|
||
```
|
||
|
||
## 五、关键接口签名（待实现时对照类型确认）
|
||
|
||
- slots.register('conversation.view', {id, label}, Component) —— 动态注册/注销（读 slots.d.ts 确认 unregister）
|
||
- webServer.register({kind:'prefix', path:'/odl/api', handler}) —— 已有
|
||
- settings scope.get()/update() —— 已有
|
||
- **事件机制：不需要（老师确认，2026-08-28）**——策略变更的提示在设置页内就地显示，tab 更新靠「刷新页面 → 插件重载 → 重新注册」，全程无跨组件事件；
|
||
- 优化（方案 Y）：若框架支持会话切换挂载钩子，tab 栏自动重新拉策略配置（仍无事件）
|
||
|
||
## 六、开发顺序（编码）
|
||
|
||
1. 服务端：settings.js（add/rename/remove/move + id 生成）
|
||
2. 服务端：storage.js（removeStrategyShares/clearStrategy）
|
||
3. 服务端：manager.js（moveAllUnallocated/clearStrategyShares）
|
||
4. 服务端：api.js（新端点 + 错误透出）
|
||
5. 客户端：LoadState.jsx + Toast.jsx（基础组件）
|
||
6. 客户端：SettingsSection CRUD + 确认弹窗
|
||
7. 客户端：index.js 动态 tab 注册 + 刷新机制
|
||
8. 客户端：StrategyTab 全部移入/一键清零
|
||
9. 构建 + 安装 + 联调验收
|
||
|
||
## 七、非目标（本期不做）
|
||
|
||
- 表格列可配置（T-006 数据池）
|
||
- 数据源状态全局监控（O5 澄清为加载兜底）
|
||
- 数据实时刷新/WebSocket（T-005）
|
||
- 持仓信息补全列（O1）
|
||
- 网格参数管理、做T 记录、风控 |