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）
84 lines
6.2 KiB
Markdown
84 lines
6.2 KiB
Markdown
# R-008 数据存储管理（JSON → SQLite）· 已完成
|
||
|
||
> 归档日期：2026-09-01 ｜ 需求状态：**已完成**
|
||
> 原索引：docs/05-需求池/需求池索引.md（主索引保留 R-008 条目，指向本归档）
|
||
> 实现迭代：06-数据存储SQLite（验收通过，迭代复盘见 docs/04-迭代记录/06-数据存储SQLite/迭代复盘.md）
|
||
> 讨论记录：需求从 T-008 草稿转正，2026-09-01 定稿（D1-D8）；实现过程中的语义迁移 Bug 修复与「一键清零」移除见迭代 06 技术实现方案变更记录
|
||
|
||
---
|
||
|
||
> 状态：**已定稿**（2026-09-01，老师确认）｜ 登记日期：2026-09-01
|
||
> 来源：T-008 草稿转正（docs/05-需求池/草稿/T-008-数据存储管理SQLite.md）
|
||
> 优先级：P1
|
||
> 关联：docs/03-设计约束/数据存储设计.md（将变更）、技术约束-012（将变更）
|
||
|
||
## 想法描述
|
||
|
||
将神之一手的数据存储从 **JSON 文件**（store.json / store.market.json / store.schema.json）升级为 **SQLite 数据库**，并引入「数据存储管理」能力。
|
||
|
||
**背景**：当前存储基于 JSON data store（R-006，2026-08-31 定），设计约束明确「数据量很少，无需数据库」。现准备引入 SQLite，意味着数据量/查询复杂度已增长到需要数据库的程度，需重新评估该设计决策。
|
||
|
||
## 现状（代码审查 2026-09-01）
|
||
|
||
| 项 | 现状 |
|
||
|---|---|
|
||
| 存储介质 | JSON 文件：store.schema.json（schema）/ store.json（份额分配，策略为中心）/ store.market.json（行情快照缓存） |
|
||
| 存储模块 | src/component/DataStore.js（读写/迁移/schema）、MarketDataHub.js（行情缓存写回）、AllocationStorage.js（遗留旧存储，迁移源） |
|
||
| 数据流 | 启动 load → 实盘 ingest → 防抖 3s 写回 store.market.json；原子写（临时文件 + rename） |
|
||
| 依赖 | 无数据库依赖（package.json 无 sqlite） |
|
||
| 设计约束 | docs/03-设计约束/数据存储设计.md：「数据量很少（无需数据库/Circe），用 JSON 文件 + 类 JSON Schema」 |
|
||
|
||
## 动机（为什么要 SQLite）
|
||
|
||
（待老师补充确认 —— 初步推测）：
|
||
- [ ] 数据量增长：行情缓存 / 交易记录 / 复盘记录等数据积累，JSON 全量读写成本变高？
|
||
- [ ] 查询需求：按 code / 时间 / 策略做复杂查询（如历史行情、交易复盘筛选），JSON 内存过滤不便？
|
||
- [ ] 写入频率：盘中行情防抖写回 + 未来更多高频写入，JSON 原子写压力大？
|
||
- [ ] 多数据集统一管理：份额 / 行情 / 交易记录 / 复盘记录统一入一个库？
|
||
|
||
## 待讨论点
|
||
|
||
- [ ] **动机确认**：老师确认上 SQLite 的具体原因（上述哪条 / 其他）——决定改造范围；
|
||
- [ ] **库选型**：better-sqlite3（同步 API，Node 原生绑定）？node:sqlite（Node 22+ 内置）？其他？（技术约束-001：复用优先，需论证）
|
||
- [ ] **schema 设计**：表结构 —— strategies / allocation（份额）/ market_quotes / trades / reviews？如何对齐现有 store.schema.json 语义？
|
||
- [ ] **迁移策略**：现有 store.json / store.market.json / 旧 allocations.json 如何迁入 SQLite（一次性迁移？启动自动迁移 + 备份？参照 R-006 迁移模式）？
|
||
- [ ] **保留还是废弃 JSON**：SQLite 落地后 JSON 文件是否完全废弃（读兼容 / 写切换 / 双写过渡）？
|
||
- [ ] **策略定义位置**：策略（id/name/visible/order）仍存 DSH settings 还是迁入 SQLite？（现有设计决策：存 settings）
|
||
- [ ] **数据存储管理能力**：本需求「数据存储管理」具体指什么 —— 数据浏览/导出？备份/恢复？清理（行情缓存膨胀治理）？还是仅存储引擎替换？
|
||
- [ ] **设计约束变更**：数据存储设计.md 的「无需数据库」决策需修订 —— 变更理由与记录；
|
||
- [ ] **依赖引入**：新增原生依赖（better-sqlite3 需编译）对插件构建/分发的影响（技术约束-005 bundle 格式）；
|
||
- [ ] **优先级与排期**：机制定稿后确定。
|
||
|
||
> 成熟后按「三要素」（边界清楚 / 核心逻辑明确 / 老师确认）讨论定稿，再转正到根目录形成正式需求。
|
||
## 讨论结论（2026-09-01 第一轮）
|
||
|
||
### 已确认决策
|
||
|
||
| # | 决策点 | 结论 |
|
||
|---|---|---|
|
||
| D1 | 动机 | **需要复杂查询/筛选** + **为未来功能铺路**（多数据集统一管理）；非数据量/写入压力问题 |
|
||
| D2 | 库选型 | **node:sqlite**（Node ≥22.5，实测本机 22.23.1 可用）；存储层封装独立模块隔离 experimental 风险 |
|
||
| D3 | 能力范围 | **仅存储引擎替换**（JSON→SQLite），对外行为不变，最小改动；本期不做数据管理界面/导出/清理 |
|
||
| D4 | 表范围 | 本期：**strategies + allocation + market_quotes** 三表；**不建 trades 表**（R-007 时再建） |
|
||
| D5 | 策略定义位置 | **仍存 DSH settings**（不迁 SQLite，设置页交互不变） |
|
||
| D6 | 迁移策略 | **一次性迁移脚本** + **启动检测自动迁移**（检测旧 JSON 存在且 SQLite 空 → 自动迁移，幂等） |
|
||
| D7 | JSON 去留 | **迁移后废弃**（迁移前自动备份） |
|
||
| D8 | 优先级 | **P1** |
|
||
|
||
### 实测验证记录（2026-09-01）
|
||
|
||
- 本机 Node v22.23.1，`node:sqlite` 可用（`DatabaseSync`，内置 SQLite 3.51.3），但标记 **Experimental**（`ExperimentalWarning`）；
|
||
- better-sqlite3 实测 ESM 加载正常，但原生模块需编译；分发需预编译产物；
|
||
- 选型考量：本项目倾向稳妥 + 零依赖分发 → node:sqlite；存储层封装（SqliteStore）隔离 experimental 风险，未来可切换。
|
||
|
||
### 设计约束变更（待执行）
|
||
|
||
- 技术约束-012（数据存储遵循 JSON data store）需**变更**：SQLite 落地后更新为遵循 SQLite 存储设计；
|
||
- docs/03-设计约束/数据存储设计.md 需修订：「无需数据库」决策 → SQLite（记录变更理由：复杂查询 + 未来功能铺路）；
|
||
- 变更需在定稿时同步执行（本需求转正后）。
|
||
|
||
### 转正条件（三要素核对）
|
||
|
||
- [x] 边界清楚：仅引擎替换 + 三表 + 不建 trades + 策略仍存 settings；
|
||
- [x] 核心逻辑明确：node:sqlite + 自动迁移 + JSON 废弃（D1-D8 全部确认）；
|
||
- [ ] **老师确认定稿**（待确认）—— 确认后转正为正式需求 R 编号，进入计划/迭代。 |