one_divine_lot/docs/02-计划/计划-数据存储SQLite.md

计划：数据存储管理（JSON → SQLite）（阶段航点）

编号：PLAN-007 ｜ 粒度：阶段航点（大粒度） ｜ 创建：2026-09-01 ｜ 状态：进行中 派生自终极目标：目标-003（按策略监控市场）、目标-005（市场复盘）、目标-006（交易复盘）——复杂查询/多数据集统一存储是复盘与监控的数据底座 依据需求：R-008（已定稿，2026-09-01，D1-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:sqlite（DatabaseSync）——隔离 experimental 风险，提供 init/migrate/upsert/query 能力；对外行为与 DataStore 兼容（D2）；
2. 表结构：strategy_holdings（持仓生命周期表：自增 holding_id + strategy_id/code/shares/created_at/closed_at，一对多「多」侧单表）+ market_quotes_cache（code → last_price/last_close 两列，行情快照缓存）两表（D4；2026-09-01 讨论修正：不用 strategies JSON 列 + allocation 冗余双表；行情不用 snapshot JSON 列；持仓加生命周期为交易记录关联铺路）；
3. 策略定义位置：仍存 DSH settings，不迁 SQLite（D5）；
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）+ 启动自动迁移（幂等）；
7. MarketDataHub 适配：行情持久化切至 market_quotes_cache 表（投影 last_price/last_close）；
8. 构建 + 测试：pnpm run build + typecheck + 独立数据目录回归测试（技术约束-011）；
9. 验收：对照迭代 06 验收标准逐条核验，记录迭代复盘。

验收要点

• 数据落 SQLite（one-divine-lot.db），store.json/store.market.json 迁移后废弃（迁移前备份）；
• 对外行为不变：份额分配 CRUD、行情缓存查询/写回、重启后首屏有价；
• 幂等：重复启动不重复迁移；迁移失败不破坏原 JSON；
• 旧 allocations.json 迁移链路仍有效（并入 SQLite 迁移）；
• 技术约束-011：回归测试用独立数据目录（ODL_TEST_DATA_DIR）。