# 计划：数据存储管理（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）。