kyugao
dd98b4d45b
- 新增 02-计划/计划-数据存储SQLite.md（PLAN-007） - 新增 04-迭代记录/06-数据存储SQLite/ 五份文档（迭代目标/技术实现方案/验收标准/UI交互调用分析/迭代复盘） - 归档 R-008 至 已完成/（含归档头 + 讨论记录索引），索引更新为已实现（已归档） - 设计约束更新：技术方案约束-012 标注 SQLite 变更、数据存储设计.md 第 9 节变更预告 - 需求池说明.md 新增「归档与转正规范」；迭代记录说明.md 新增「实现经验沉淀」 - 验收标准修正 db 文件名笔误（one-divine-lot.db → store.db）
62 lines
4.7 KiB
Markdown
62 lines
4.7 KiB
Markdown
# 计划：数据存储管理（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）+ 启动自动迁移（幂等）；
|
||
6. **MarketDataHub 适配**：行情持久化切至 market_quotes_cache 表（投影 last_price/last_close）；
|
||
7. **构建 + 测试**：pnpm run build + typecheck + 独立数据目录回归测试（技术约束-011）；
|
||
8. **验收**：对照迭代 06 验收标准逐条核验，记录迭代复盘。
|
||
|
||
## 验收要点
|
||
|
||
- 数据落 SQLite（one-divine-lot.db），store.json/store.market.json 迁移后废弃（迁移前备份）；
|
||
- 对外行为不变：份额分配 CRUD、行情缓存查询/写回、重启后首屏有价；
|
||
- 幂等：重复启动不重复迁移；迁移失败不破坏原 JSON；
|
||
- 旧 allocations.json 迁移链路仍有效（并入 SQLite 迁移）；
|
||
- 技术约束-011：回归测试用独立数据目录（ODL_TEST_DATA_DIR）。
|