docs(迭代09/10): Tab 设置统一管理 + UI 主题适配 全量文档
迭代09 (R-011 Tab 设置统一管理): - 需求 R-011 (定稿 Q1-Q5) + 需求池索引 - 计划 PLAN-010 + 迭代09 四件套 (目标/技术方案/验收/复盘) - 约束: 产品约束-009 / UI约束-003 / 技术约束-014 - UI约束-002 修订: 通用设置→Tab 设置 迭代10 (R-012 UI 适配 DSH 主题): - 需求 R-012 (定稿: 暂定跟随系统) + 需求池索引 - 计划 PLAN-011 + 迭代10 四件套 - 约束: UI约束-004 (主题适配约定)
This commit is contained in:
@@ -0,0 +1,82 @@
|
||||
# 技术实现方案：09-Tab 设置统一管理
|
||||
|
||||
> 迭代编号：09 ｜ 依据：PLAN-010、R-011、产品约束-009、UI约束-003、技术约束-014
|
||||
|
||||
## 1. 数据模型（src/settings.js）
|
||||
|
||||
### 1.1 tabs 有序数组（新 schema）
|
||||
|
||||
```js
|
||||
tabs: z.array(z.object({
|
||||
id: z.string().required(), // 唯一 id：'tab-all-positions' / 'tab-strategy-<id>'
|
||||
kind: z.enum(['builtin', 'strategy']).required(),
|
||||
refKey: z.string().optional(), // builtin 专用：'allPositions' | 'tradeRecords' | 'watchlist'
|
||||
refId: z.string().optional(), // strategy 专用：策略 id
|
||||
name: z.string().required(), // 展示名（策略行 join 时刷新）
|
||||
visible: z.boolean().default(true),
|
||||
order: z.number().default(0),
|
||||
})).default(DEFAULT_TABS)
|
||||
```
|
||||
|
||||
### 1.2 归一化迁移（读取时）
|
||||
|
||||
getTabs(scope) 逻辑：
|
||||
- 读取 settings.tabs：若为数组 → 直接返回（按 order 排序）；
|
||||
- 若为旧布尔对象（或缺失）→ 生成默认内置三条（全部持仓/交易记录/关注列表，保留原显隐值），策略按 strategies 旧 order 接续追加（旧 hidden → visible=true）；
|
||||
- 首次写入时落库归一化后的数组（幂等，不重复迁移）。
|
||||
|
||||
### 1.3 strategies 收窄
|
||||
|
||||
strategies schema 去掉 visible/order（仅 {id, name}）；getStrategies 不再排序/过滤 visible；策略展示名统一由 getTabs join strategies 得出（Q4 自动跟随改名）。
|
||||
|
||||
## 2. API 层（src/api/strategies.js）
|
||||
|
||||
| 端点 | 变更 |
|
||||
|---|---|
|
||||
| tabs | 返回合并后的完整 tabs 数组（含策略行 name join） |
|
||||
| tabs/update | 整表更新 { tabs }（顺序 + 显隐）；策略行 name 由服务端 join 刷新，客户端可只传 id 顺序 |
|
||||
| strategies/add | 联动 append tab 条目（末尾，order = max+1） |
|
||||
| strategies/remove | 联动删除对应 tab 条目（refId === 策略 id） |
|
||||
| strategies/move | **废弃**（从 METHODS 移除） |
|
||||
| strategies/update | 仅剩重命名（联动刷新 tabs 中策略行 name） |
|
||||
|
||||
## 3. 客户端注册（src/client/index.js）
|
||||
|
||||
合并 registerGeneralTabs + registerStrategyTabs → registerAllFromTabs(tabs)：
|
||||
```js
|
||||
const sorted = tabs.slice().sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
|
||||
for (const t of sorted) {
|
||||
if (t.visible === false) continue;
|
||||
const render = t.kind === 'builtin' ? GENERAL_RENDER[t.refKey] : (props) => createElement(StrategyTab, { ...props, strategyId: t.refId, strategyName: t.name });
|
||||
// slots.register conversation.view, order: t.order
|
||||
}
|
||||
```
|
||||
- GENERAL_RENDER = { allPositions, tradeRecords, watchlist } 映射常量；
|
||||
- 移除硬编码 order 10/11/12 与 13+ 间隔（直接用 t.order）；
|
||||
- fetchTabConfig → fetchTabs 返回数组。
|
||||
|
||||
## 4. 设置页 UI（src/client/views/SettingsSection.jsx）
|
||||
|
||||
### 4.1 「Tab 设置」子 tab
|
||||
|
||||
- 子 tab 导航：general → tabs（更名），标签「Tab 设置」；
|
||||
- 表格列：拖动手柄（≡）｜ 名称（内置行带「内置」徽标、策略行带「策略」徽标）｜ 显示（Switch）；
|
||||
- **无重命名/删除按钮（任何行）**；
|
||||
- 拖动（原生 DnD）：
|
||||
- tr draggable，onDragStart 记 id；onDragOver 阻止默认 + 计算插入位；onDrop 重排数组；
|
||||
- 落点 → 立即调 tabs/update（整表提交）→ 提示「已保存，刷新页面后生效」；
|
||||
- 显隐开关：切换 → 立即调 tabs/update → 提示。
|
||||
|
||||
### 4.2 策略分组瘦身
|
||||
|
||||
- 移除排序箭头列（↑↓）与显示列（Switch）；
|
||||
- 保留：新增输入框 + 新增按钮 / 重命名 / 删除（确认弹窗 + 份额回未分配沿用）；
|
||||
- 顶部加提示：顺序与显示请在「Tab 设置」中调整。
|
||||
|
||||
## 5. 兼容与风险
|
||||
|
||||
- **迁移**：读取归一化幂等；旧策略 visible=false 迁移后 visible=true（Q3，产品约束-009 一致）；
|
||||
- **名称 join**：tabs 存 refId，展示时 join strategies；策略改名后 tabs 行 name 自动跟随（Q4）；
|
||||
- **注册**：refresh = 刷新页面重载插件（无事件机制，沿用）；
|
||||
- **RPC**：strategies/move 废弃需同步移除客户端调用（settings UI 不再有箭头）；
|
||||
- **回归**：技术约束-011 —— 写操作测试用独立数据目录（ODL_TEST_DATA_DIR / dataDir 参数）。
|
||||
@@ -0,0 +1,41 @@
|
||||
# 迭代复盘：09-Tab 设置统一管理（内置 + 策略分组，显示/隐藏 + 拖动排序）
|
||||
|
||||
> 复盘日期：2026-09-02 ｜ 迭代状态：**已完成（老师确认）**
|
||||
> 关联需求：R-011（Tab 设置：统一管理所有 tab，已定稿 Q1-Q5）
|
||||
> 关联计划：PLAN-010（计划-Tab设置统一管理）
|
||||
|
||||
## 结果
|
||||
|
||||
迭代 09 达成：设置页「通用设置」升级为「Tab 设置」，成为所有会话 tab（系统内置 + 策略分组）**唯一的顺序与显隐入口**：两类 tab 混排一张表，每行 = 拖动手柄（原生 HTML5 DnD）+ 名称（内置带「内置」徽标、策略带「策略」徽标）+ 显示/隐藏开关；**任何 tab 均不支持重命名与删除**；拖动落点立即持久化；策略分组子 tab 瘦身为 新增/重命名/删除。
|
||||
|
||||
## 过程事实
|
||||
|
||||
1. **需求定稿（R-011）**：老师提出设置页默认 tab 与策略 tab 一起排序（内置标记、不可重命名/删除）→ AI 分析现状（两套数据、两套 order 空间，内置恒在策略前）→ 提出统一 tabs 有序数组方案 → 老师确认 D1-D7 + Q1-Q5（拖动落点立即持久化 / 新增追加末尾 / 旧隐藏策略迁移后显示 / 名称 join 自动跟随 / 全部 tab 禁重命名删除）；
|
||||
2. **数据层（settings.js）**：tabs 从布尔对象 → 统一有序数组（kind: builtin|strategy + refKey/refId + visible + order）；strategies 收窄为 {id, name}；旧格式读取时静默归一化迁移（schema union 兼容存量 + normalizeTabs 转换）；addStrategy/removeStrategy 联动 tabs；
|
||||
3. **API 层（strategies.js）**：tabs/update 语义改整表（顺序 + 显隐）；strategies/add 联动追加 tab（末尾）；strategies/remove 联动删除 tab 条目；废弃 strategies/move；
|
||||
4. **客户端注册（client/index.js）**：合并 registerGeneralTabs + registerStrategyTabs 为统一注册（读 tabs 数组按 order 排序、过滤 visible，builtin 走内置 render、strategy 走 StrategyTab），移除硬编码 order 间隔（10/11/12 与 13+）；
|
||||
5. **设置页 UI（SettingsSection.jsx）**：「Tab 设置」子 tab（混排表格 + 徽标 + 显隐开关 + 拖动排序 + 落点立即持久化）；策略分组瘦身（移除排序箭头与显隐开关，加指引提示）；
|
||||
6. **验证**：回归测试 35 项全通过（scripts/test-r011-tabs.mjs 数据层 23 项 + test-r011-api.mjs API 层 12 项）+ 真实 schema resolve 验证（旧配置归一化正确）+ 构建 + typecheck 通过。
|
||||
|
||||
## 经验教训（复盘沉淀）
|
||||
|
||||
### 1. schemastery 无 z.enum / .optional()，schema 兼容存量用 z.union 双分支
|
||||
- schemastery 只有 z.union([z.const(...), ...]) 无 z.enum，可选字段不调 .required() 即可；
|
||||
- **关键**：DSH settings 的 resolve 会用 schema 校验存量 user 层——新 schema 直接替换会导致旧配置（布尔对象 tabs）校验失败、插件启动报错；
|
||||
- **沉淀**：settings schema 变更必须先验证存量兼容——用 z.union 双分支（旧格式 + 新格式），旧值通过校验、读取时再归一化；改动 settings schema 前跑 schema-resolve 测试。
|
||||
|
||||
### 2. 读取时归一化 + schema 双分支 = 无感迁移
|
||||
- 本次没有写一次性迁移脚本，而是「schema 接受旧格式 + normalizeTabs 读取时转新」：存量用户升级零操作、零报错；
|
||||
- 归一化结果在首次写操作（updateTabs/add/remove）时落库为数组，之后自然持久化；
|
||||
- **沉淀**：settings 结构变更优先「schema 兼容 + 读取归一化」而非迁移脚本，符合 R-006/R-008 的迁移经验（幂等、无需用户操作）。
|
||||
|
||||
### 3. 前端字符串与 JSX 引号冲突
|
||||
- 写 JSX 组件代码时，代码里同时有 JS 单双引号与 JSX 属性引号，用模板字符串包整段时内部反引号/插值冲突，多次报错；
|
||||
- **沉淀**：批量生成代码用数组 join（每行独立字符串），避免模板字符串嵌套转义地狱。
|
||||
|
||||
## 遗留/后续
|
||||
|
||||
1. **Tab 设置拖动交互**：当前实现为整行 draggable（原生 DnD），落点插入到目标行位置；后续可优化为拖动手柄专属拖拽 + 拖拽中的视觉反馈（插入线）；
|
||||
2. **关注列表 tab**：仍为占位（PlaceholderTab），后续迭代实现；
|
||||
3. **迁移落库时机**：旧配置首次读取不落库（纯读），首次写操作时才持久化新数组——如老师希望启动即落库可加一次性迁移（当前行为无感知差异，可接受）；
|
||||
4. **多 DSH 实例/多用户**：tabs 顺序为全局设置（非按会话），符合现状（strategies 亦为全局）。
|
||||
@@ -0,0 +1,26 @@
|
||||
# 迭代目标：09-Tab 设置统一管理（内置 + 策略分组，显示/隐藏 + 拖动排序）
|
||||
|
||||
> 迭代编号：09 ｜ 创建：2026-09-02 ｜ 状态：进行中
|
||||
> 依据计划：PLAN-010 ｜ 需求：R-011（已定稿，2026-09-02，Q1-Q5 确认）
|
||||
|
||||
## 目标描述
|
||||
|
||||
将设置页「通用设置」升级为「Tab 设置」，成为所有会话 tab（系统内置 + 策略分组）**唯一的顺序与显隐入口**：两类 tab 混排一张表，每行 = 拖动手柄 + 名称 + 显示/隐藏开关；任何 tab 均不支持重命名与删除；拖动落点立即持久化。
|
||||
|
||||
## 目标分解
|
||||
|
||||
1. **数据模型统一**（settings.js）：tabs 布尔对象 → 有序数组，旧格式自动归一化；strategies 收窄为 {id, name}；
|
||||
2. **API 层**（api/strategies.js）：tabs/update 整表（顺序 + 显隐）；strategies/add 联动追加 tab；strategies/remove 联动删除 tab；废弃 strategies/move；
|
||||
3. **客户端注册**（client/index.js）：合并为统一注册，读 tabs 数组（order 排序 + visible 过滤），移除硬编码 order；
|
||||
4. **设置页 UI**（SettingsSection.jsx）：「Tab 设置」子 tab（混排 + 徽标 + 显隐开关 + 拖动排序）+ 策略分组瘦身（仅 新增/重命名/删除 + 指引提示）。
|
||||
|
||||
## 讨论过程
|
||||
|
||||
- 2026-09-02 老师提出需求：设置页默认几个 tab 与策略 tab 一起排序，内置标记、不可重命名/删除；
|
||||
- 2026-09-02 AI 分析现状（两套数据/两套 order 空间），提出统一 tabs 有序数组方案；
|
||||
- 2026-09-02 老师确认 D1-D7：Tab 设置只做 显示/隐藏 + 排序（拖动），策略命名/删除留策略分组；
|
||||
- 2026-09-02 老师确认 Q1-Q5：拖动落点立即持久化 / 新增追加末尾 / 旧隐藏策略迁移后显示 / 名称 join 自动跟随 / 全部 tab 禁重命名删除，R-011 定稿。
|
||||
|
||||
## 对老师的配合需求
|
||||
|
||||
- 验收时验证：拖动排序落点立即生效（刷新后 tab 栏按新顺序）；显隐开关切换后刷新生效；策略分组瘦身后的新增/重命名/删除仍正常；老配置自动迁移无报错。
|
||||
@@ -0,0 +1,26 @@
|
||||
# 验收标准：09-Tab 设置统一管理
|
||||
|
||||
> 迭代编号：09 ｜ 依据：PLAN-010 验收要点 + R-011 定稿
|
||||
|
||||
## 验收标准线
|
||||
|
||||
1. 「通用设置」子 tab 更名为「Tab 设置」，表格混排内置 + 策略全部 tab；
|
||||
2. 内置行带「内置」徽标、策略行带「策略」徽标；
|
||||
3. 每行可拖动排序，落点**立即持久化**（刷新后会话 tab 栏按新顺序，内置与策略可交错）；
|
||||
4. 每行有显示/隐藏开关，切换立即持久化（刷新后隐藏的 tab 消失/显示的出现）；
|
||||
5. **任何行均无重命名/删除按钮**；
|
||||
6. 策略分组子 tab 只留 新增/重命名/删除，无排序箭头/显隐开关，有指引提示；
|
||||
7. 新增策略出现在 Tab 设置列表末尾；删除策略后对应 tab 条目消失（份额回未分配沿用）；
|
||||
8. 老配置（布尔对象 tabs + 策略 order/visible）读取自动归一化，无报错、无数据丢失；
|
||||
9. 会话 tab 栏按新顺序与显隐注册；
|
||||
10. 现有功能不回归（全部持仓/交易记录/策略持仓/QMT 切换/删除策略份额回退）。
|
||||
|
||||
## 验收方法
|
||||
|
||||
- 构建：pnpm run build + typecheck 通过；
|
||||
- 单元/回归脚本：独立数据目录跑策略 CRUD + tabs 读写（技术约束-011）；
|
||||
- 手动（需 DSH 运行 + 老师确认）：设置页 Tab 设置拖动排序 / 显隐切换 / 策略分组瘦身 / 老配置迁移；会话 tab 栏顺序与显隐验证。
|
||||
|
||||
## 验收目标
|
||||
|
||||
- 全部 10 条验收标准线通过，迭代 09 标记「验收通过」，R-011 实现状态更新，归档流程走查。
|
||||
Reference in New Issue
Block a user