one_divine_lot/docs/05-需求池/已完成/R-003.md

# R-003 分仓管理工具完善与优化 · 已完成

> 归档日期：2026-08-28 ｜ 需求状态：**已完成**
> 原索引：docs/05-需求池/需求池索引.md（主索引保留 R-003 条目，指向本归档）
> 讨论记录：本文件末尾（完整讨论过程整合于此，2026-08-29）

## 需求摘要

对 R-002（分仓管理工具）进行完善与优化，本期范围 = **O2 + O3 + O5 + O6**：

- **O2 策略 tab 动态化**：tab 由服务端策略配置驱动，增删改/显示开关实时同步（隐藏策略的 tab 不显示；策略变更提示手动刷新）
- **O3 设置界面完善（策略 CRUD）**：新增（自动英文 id）/ 重命名（不影响分配）/ 删除（弹窗确认 + 份额回未分配）/ 排序（上移下移）/ 显隐；预置策略可删（彻底自由）
- **O5 数据加载失败兜底**：加载失败提示（含原因）+ 重试按钮；自动重试 2 次；超时提示（**非数据源状态监控**）
- **O6 份额编辑体验**：单票「全部移入」（未分配全部进当前策略）+ 策略「一键清零」（弹窗确认）+ 操作 Toast 反馈

**实现期间追加（2026-08-28）**：设置页 tab 化（通用设置 / 策略分组两个子 tab）；通用设置三个 switch（全部持仓 / 交易记录 / 关注列表，控制会话 tab 显隐）；策略显示开关改用 switch 控件。

## 核心逻辑（定稿版）

1. **策略 tab 动态化**：客户端启动时拉取策略配置，按 visible 策略动态注册 conversation.view tabs（slots.register 返回 disposer，可注销重注册）；全部持仓固定保留；
2. **策略 CRUD**：设置页「策略分组」子 tab 提供新增/重命名/删除/排序/显隐；删除弹窗确认 + 份额回未分配（产品约束-004）；预置策略可删；
3. **加载失败兜底**：LoadState 三态组件（loading/error+重试/success），自动重试 2 次（间隔 2s），超时（15s 可配置）提示；
4. **份额快捷操作**：单票全部移入（move-all-shares 端点）、策略一键清零（remove-all-shares 端点，弹窗确认）；
5. **设置 tab 化**：通用设置（三个 switch 控制通用 tab 显隐）+ 策略分组；切换后提示「刷新页面后生效」。

## 实现记录

| 项 | 内容 |
|---|---|
| 实现迭代 | 02-分仓管理工具完善与优化 |
| 实现方式 | 沿用独立插件 one-divine-lot（服务端 + 客户端改造） |
| 服务端 | S1-S4：settings.js（策略 CRUD + tabs 配置）、storage.js（清份额）、manager.js（全部移入/清零）、api.js（strategies/add/remove/move + move-all-shares/remove-all-shares + tabs/tabs-update 端点） |
| 客户端 | S5-S8：LoadState/Toast 基础组件、SettingsSection 设置 tab 化 + CRUD、client/index.js 动态 tab 注册、StrategyTab 快捷操作 |
| 构建安装 | S9：pnpm build + 宿主动态加载（无需重启即更新客户端 bundle） |

## 验收结果（2026-08-28 老师确认）

- ✅ 策略隐藏/显示（switch 控件）验证 OK
- ✅ 新增策略正常，tab 增加正常
- ✅ 删除策略正常，tab 消失正常
- ✅ 策略排序调整正常（getStrategies 按 order 排序修复后）
- ✅ 全部持仓/策略 tab 表格正常显示（React 空值崩溃修复后）
- ✅ 三个通用 tab（全部持仓/交易记录/关注列表）+ 策略 tabs 按配置注册
- ✅ 设置页两个子 tab（通用设置/策略分组）
- ✅ 服务端 API 全链路验证通过（tabs、strategies CRUD、快捷操作）

## 经验沉淀

- **React JSX 空值崩溃**：LoadState 的 children 立即求值，positions 为 null 时崩溃被 slot 边界静默吞掉 → 必须空值保护（(positions ?? []).map）
- **useRpc 引用稳定性**：每次渲染返回新函数导致 effect 无限循环 → useCallback 稳定化
- **getStrategies 排序一致性**：设置页/tab 栏/move 逻辑必须共用同一 order 排序，否则顺序不一致
- **服务端 API 需重启生效**：客户端 bundle 宿主动态读取，但服务端模块（api.js 等）需重启 DSH 才加载新代码

## 关联文档

- 讨论记录（完整）：本文件「需求讨论记录」章节
- 迭代记录：docs/04-迭代记录/02-分仓管理工具完善与优化/
- 设计约束：产品约束-004（删除策略份额回未分配）

---

## 需求讨论记录（2026-08-29 整合）

> 本需求从提出到定稿的完整讨论过程（原文件 docs/05-需求池/R-003.md 整合于此）。

## 需求概述

对 R-002（分仓管理工具）的**完善与优化**：修复已知缺陷、补齐产品约束未覆盖的部分、优化使用体验。本期**不新增全新功能域**（如网格参数管理、做T 记录、行情监控等另行评估），聚焦「把 R-002 做扎实」。

## 候选优化方向（讨论中，未收敛）

> 以下候选方向来自迭代 01 复盘与代码现状审视，待与老师逐项讨论确定本期范围。

| 方向 | 现状问题 | 优化内容 | 优先级候选 |
|---|---|---|---|
| O1 持仓信息完整性 | 全部持仓 tab 只显示份额相关字段，QMT 返回的现价/市值/盈亏/可用等**未展示**（与产品约束-001「完整展示持仓信息」不符） | 全部持仓 tab 补充现价/市值/盈亏/可用等字段展示 | 高 |
| O2 策略 tab 动态化 | 客户端 tab 写死 3 个（全部持仓+2策略），设置中增删/隐藏策略后 tab **不同步** | tab 由服务端策略配置驱动，增删改/显示开关实时反映到 tab 栏 | 高 |
| O3 设置界面完善 | 设置 section 只有显示/隐藏开关，**无增/删/改策略 UI**（API 已支持 strategies/update） | 补全策略 CRUD UI（新增/重命名/删除/排序） | 高 |
| O4 数据刷新机制 | tab 数据只在进入/操作后加载一次，交易时段价格/市值**不会自动更新** | 定时轮询 or WebSocket 实时推送（后者关联草稿 T-005，需评估是否纳入本期） | 中 |
| O5 数据加载失败兜底 | 页面数据加载失败时仅显示「加载失败」文字，无重试入口 | 加载失败的常规提示信息（失败原因）+ 重试按钮；不是数据源状态监控，而是页面加载的兜底体验 | 中 |
| O6 份额编辑体验 | 添加/移出需逐票输入股数，无快捷操作 | 快捷操作（全部移入/全部移出/一键清零）、步进优化、操作反馈 | 低 |
| O7 其他 | 老师补充 | 待讨论 | - |

## 讨论进程

### 2026-08-28 · 第 2 轮：范围圈定（老师确认）

**老师拍板**：本期范围 = **O2 + O3 + O5 + O6**。

- ✅ **O2 策略 tab 动态化**：tab 由服务端策略配置驱动，增删改/显示开关实时同步
- ✅ **O3 设置界面完善**：补全策略 CRUD UI（新增/重命名/删除/排序）
- ✅ **O5 数据加载失败兜底**：加载失败提示 + 重试（非数据源状态监控）
- ✅ **O6 份额编辑体验**：快捷操作优化
- ❌ **O1 持仓信息补全**：本期不做（后续评估）
- ❌ **O4 数据实时刷新**：本期不做；WebSocket 实时推送（草稿 T-005）**不转正**，继续留草稿区待后续评估

### 2026-08-28 · 第 3 轮：核心逻辑收敛（进行中）

针对 O2/O3/O5/O6 的关键决策点逐项讨论，收敛后进入定稿。

**已确认决策（老师拍板，2026-08-28）**：

| 决策点 | 结论 |
|---|---|
| O2-1 tab 数据来源 | 每次进入/设置变更后重新拉取策略配置，tab 栏同步刷新 |
| O2-2 隐藏策略的 tab | 隐藏即不显示（与 R-002 定稿一致） |
| O2-3 tab 栏刷新触发 | 设置保存后客户端全局刷新 |
| O3-1 新增策略 | 自动生成英文 id（slug），如「长线持有」→ long-term-hold |
| O3-2 删除策略的份额处理 | **份额回到未分配**（老师确认，数据不丢） |
| O3-3 重命名 | 分配数据挂 id 不挂名称，改名不影响 |
| O3-4 排序 | 支持上移/下移按钮（不做拖拽） |
| O3-5 预置策略 | **可删除，彻底自由**（老师确认，与其他策略一视同仁） |
| O5-1 失败提示位置 | 数据加载区域显示失败提示信息（原因）+ 重试按钮 |
| O5-2 失败重试 | 加载失败显示提示 + 手动重试按钮；自动重试 2 次（间隔 2s） |
| O5-3 超时 | 保持 15s 可配置，超时显示「数据源超时」 |
| O6-1 快捷操作 | 全部移入（未分配→当前策略）、一键清零（策略内全部移出） |
| O6-2 份额步进 | 保留 step=100，手动输入任意值仍可用 |
| O6-3 操作反馈 | 顶部轻提示：成功绿、失败红，3s 自动消失 |

### 2026-08-28 · 第 4 轮：剩余不确定点收敛（老师确认）

针对定稿前剩余不确定点，老师逐项拍板：

| # | 不确定点 | 结论 |
|---|---|---|
| 1 | O2/O3 联动机制 | **提示用户手动刷新**（策略变更后，设置页/主界面提示「策略已变更，请手动刷新」；不做自动广播/轮询，简单可靠） |
| 2 | O3 删除策略确认 | **删除弹窗提示确认**（破坏性操作需二次确认） |
| 3 | O5 数据源状态条 | **当前无任何数据源状态显示**——O5 需要从零新增「数据源状态」能力（确认当前缺失，需新增而非增强） |
| 4 | O6 全部移入边界 | **单票级**（表格行内操作，把该票未分配份额全部移入当前策略） |
| 5 | O6 一键清零确认 | **清零前弹窗提示**，用户确认后执行 |

### 2026-08-28 · 第 5 轮：O5 本质澄清（老师明确）

**老师澄清**：我们要的不是「数据源状态监控」，而是**页面加载数据失败时，无法正常显示的常规提示信息 + 让用户重试**。

- ❌ 不做：全局数据源状态监控（可用/不可用状态栏、状态点等）
- ✅ 要做：页面/表格数据加载失败 → 显示**常规失败提示（含原因）** + **重试按钮**；超时等异常同样给出提示
- 修正：O5 从「数据源健壮性（状态展示）」修正为「**数据加载失败兜底提示 + 重试**」

### 2026-08-28 · O8 拆分独立

老师提出：将「数据池（数据集）中间层 + 策略表格动态字段配置」从 R003 拆分，独立成新需求草稿（T-006，草稿/数据池中间层与策略表格动态字段配置.md），另行讨论定稿。R003 本期范围保持 O2/O3/O5/O6。

---

### 2026-08-28 · 设置 tab 化扩展（老师新增，迭代 02 实现中追加）

老师新增需求（迭代 02 实现期间追加）：
- **设置页 tab 化**：「神之一手」设置改为两个子 tab：**通用设置** / **策略分组**；
- **通用设置**：三个 switch 配置项 —— 全部持仓 / 交易记录 / 关注列表（对应会话窗的 tab）；
  - 本期实现三个 tab（交易记录/关注列表为空占位），开关默认全开；
  - 开关控制对应 tab 的显示/隐藏，切换后提示「刷新生效」；
- **策略分组**：现有策略 CRUD（移到该子 tab 下）。

此扩展纳入迭代 02 实现范围（R003 的补充优化）。

---

## 定稿结论（2026-08-28 老师确认）

**R-003 已定稿**，本期范围 = **O2 + O3 + O5 + O6**，共 20 项决策收敛（详见上文讨论进程）。

### 定稿摘要（三要素核对）

1. **边界清楚**：✅ 本期做 O2（tab 动态化）/ O3（策略 CRUD）/ O5（加载失败兜底提示+重试）/ O6（份额快捷操作）；不做 O1（持仓信息补全）/ O4（实时刷新）/ T-005（WS）；O8 数据池已拆分至 T-006 草稿
2. **核心逻辑明确**：✅ 20 项决策全部收敛（O2×3 / O3×5 / O5×3 / O6×4 / 范围排除×5）
3. **老师确认**：✅ 2026-08-28 老师明确「确定」

**范围排除明确**：O1 持仓信息补全、O4 数据实时刷新、T-005 WebSocket 均不纳入本期；O8 数据池（T-006）独立草稿另行讨论。表格列保持代码写死（T-006 落地前不改）。