docs(迭代06): 数据存储SQLite迭代文档 + 需求归档(R-008)

- 新增 02-计划/计划-数据存储SQLite.md(PLAN-007)
- 新增 04-迭代记录/06-数据存储SQLite/ 五份文档(迭代目标/技术实现方案/验收标准/UI交互调用分析/迭代复盘)
- 归档 R-008 至 已完成/(含归档头 + 讨论记录索引),索引更新为已实现(已归档)
- 设计约束更新:技术方案约束-012 标注 SQLite 变更、数据存储设计.md 第 9 节变更预告
- 需求池说明.md 新增「归档与转正规范」;迭代记录说明.md 新增「实现经验沉淀」
- 验收标准修正 db 文件名笔误(one-divine-lot.db → store.db)
This commit is contained in:
2026-09-01 18:04:28 +08:00
parent 9b719f13ba
commit dd98b4d45b
12 changed files with 782 additions and 3 deletions
@@ -0,0 +1,61 @@
# 计划:数据存储管理(JSON → SQLite)(阶段航点)
> 编号:PLAN-007 | 粒度:阶段航点(大粒度) | 创建:2026-09-01 状态:**进行中**
> 派生自终极目标:目标-003(按策略监控市场)、目标-005(市场复盘)、目标-006(交易复盘)——复杂查询/多数据集统一存储是复盘与监控的数据底座
> 依据需求:**R-008(已定稿,2026-09-01D1-D8 全部确认)** —— 符合入范围门槛
> 设计约束:技术约束-012(变更中)、数据存储设计.md(第 9 节变更预告)
## 目标
将神之一手的数据存储从 **JSON data store**store.json / store.market.json / store.schema.json)升级为 **SQLite 数据库**node:sqlite):**仅存储引擎替换,对外行为不变**。引入 strategies + allocation + market_quotes 三表,策略定义仍存 DSH settings,JSON 迁移后废弃(迁移前自动备份)。
## 范围
**做**
1. **存储层封装**:新增 SqliteStore 模块,封装 node:sqliteDatabaseSync)——隔离 experimental 风险,提供 init/migrate/upsert/query 能力;对外行为与 DataStore 兼容(D2);
2. **表结构**strategy_holdings**持仓生命周期表**:自增 holding_id + strategy_id/code/shares/created_at/closed_at,一对多「多」侧单表)+ market_quotes_cachecode → last_price/last_close 两列,行情快照缓存)两表(D4;2026-09-01 讨论修正:不用 strategies JSON 列 + allocation 冗余双表;行情不用 snapshot JSON 列;持仓加生命周期为交易记录关联铺路);
3. **策略定义位置**:仍存 DSH settings,不迁 SQLiteD5);
4. **迁移**:一次性迁移脚本(scripts/)+ 启动检测自动迁移(旧 JSON 存在且 SQLite 空 → 自动迁移,幂等,迁移前自动备份)(D6);
5. **JSON 废弃**:迁移后废弃 JSON 文件(迁移前备份)(D7);
6. **DataStore 改造**:数据读写/迁移/schema 逻辑切换至 SQLite 后端,**存储层 API 升级为持仓生命周期语义**openHolding/addShares/reduceShares/closeHolding/getCurrentHoldings/getHoldingHistory,废弃整策略重写的 setDataset/removeDataset);
7. **MarketDataHub 适配**:行情持久化走 SQLite market_quotes_cache 表(落盘只投影 last_price/last_close 两列),防抖写回逻辑不变。
**不做**
- 不建 trades 表(R-007 交易记录时再建,D4);
- 不做数据管理界面/导出/清理(D3:本期仅存储引擎替换);
- 不引入新依赖(node:sqlite 为 Node 内置,零依赖分发,技术约束-005 不受影响);
- 不改策略设置交互(D5);
- 不实现复杂查询 API(本期仅保证现有行为不变,查询能力为后续功能铺路)。
## 程序结构(改造后)
```
src/
├── component/
│ ├── SqliteStore.js # 新增:SQLite 存储层封装(node:sqlite
│ ├── DataStore.js # 改:读写/迁移切换至 SqliteStore(API 升级为持仓生命周期)
│ └── MarketDataHub.js # 改:行情持久化走 SqliteStore.market_quotes_cache
├── index.js # 改:实例化 SqliteStore 注入 DataStore
scripts/
└── migrate-json-to-sqlite.mjs # 新增:一次性迁移脚本(独立可执行)
```
## 实现步骤(建议顺序)
1. **文档骨架**PLAN-007 + 迭代 06 子目录(本步);
2. **约束变更**:技术约束-012 更新 + 数据存储设计.md 第 9 节落实(SQLite 表结构设计替代 JSON schema);
3. **SqliteStore**node:sqlite 封装(init/事务/upsert/query/备份);
4. **DataStore 改造**load/save/行情读写切换 SqliteStore,存储层 API 升级为持仓生命周期,保留迁移检测;
5. **PositionManager 适配**:整策略重写 → 单票生命周期操作;
6. **迁移脚本**:一次性迁移脚本(JSON → SQLite)+ 启动自动迁移(幂等);
6. **MarketDataHub 适配**:行情持久化切至 market_quotes_cache 表(投影 last_price/last_close);
7. **构建 + 测试**pnpm run build + typecheck + 独立数据目录回归测试(技术约束-011);
8. **验收**:对照迭代 06 验收标准逐条核验,记录迭代复盘。
## 验收要点
- 数据落 SQLiteone-divine-lot.db),store.json/store.market.json 迁移后废弃(迁移前备份);
- 对外行为不变:份额分配 CRUD、行情缓存查询/写回、重启后首屏有价;
- 幂等:重复启动不重复迁移;迁移失败不破坏原 JSON;
- 旧 allocations.json 迁移链路仍有效(并入 SQLite 迁移);
- 技术约束-011:回归测试用独立数据目录(ODL_TEST_DATA_DIR)。