10 KiB
10 KiB
程序结构设计：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 - 已分配，一次 addclearStrategyShares(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 栏自动重新拉策略配置（仍无事件）
六、开发顺序（编码）
- 服务端：settings.js（add/rename/remove/move + id 生成）
- 服务端：storage.js（removeStrategyShares/clearStrategy）
- 服务端：manager.js（moveAllUnallocated/clearStrategyShares）
- 服务端：api.js（新端点 + 错误透出）
- 客户端：LoadState.jsx + Toast.jsx（基础组件）
- 客户端：SettingsSection CRUD + 确认弹窗
- 客户端：index.js 动态 tab 注册 + 刷新机制
- 客户端：StrategyTab 全部移入/一键清零
- 构建 + 安装 + 联调验收
七、非目标（本期不做）
- 表格列可配置（T-006 数据池）
- 数据源状态全局监控（O5 澄清为加载兜底）
- 数据实时刷新/WebSocket（T-005）
- 持仓信息补全列（O1）
- 网格参数管理、做T 记录、风控