From 82de2f98c0f5a5970161050a626dcc189b0b7b2f Mon Sep 17 00:00:00 2001 From: Lxy Date: Sat, 4 Jul 2026 15:45:41 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=88=9B=E5=BB=BA=20analysis-storage-r?= =?UTF-8?q?efactor=20Design=20Doc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...-07-04-analysis-storage-refactor-design.md | 188 ++++++++++++++++++ .../analysis-storage-refactor/.comet.yaml | 4 +- .../.comet/handoff/brainstorm-summary.md | 42 ++++ 3 files changed, 232 insertions(+), 2 deletions(-) create mode 100644 docs/superpowers/specs/2026-07-04-analysis-storage-refactor-design.md create mode 100644 openspec/changes/analysis-storage-refactor/.comet/handoff/brainstorm-summary.md diff --git a/docs/superpowers/specs/2026-07-04-analysis-storage-refactor-design.md b/docs/superpowers/specs/2026-07-04-analysis-storage-refactor-design.md new file mode 100644 index 0000000..ead1edc --- /dev/null +++ b/docs/superpowers/specs/2026-07-04-analysis-storage-refactor-design.md @@ -0,0 +1,188 @@ +--- +comet_change: analysis-storage-refactor +role: technical-design +canonical_spec: openspec +--- + +# Analysis Storage Refactor - Technical Design + +## 1. 架构概览 + +### 1.1 目标架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 应用层 │ +│ app/api/futures_analysis.py ←→ app/services/cache.py │ +│ ↓ │ +│ StorageManager │ +│ (storage_manager.py) │ +└─────────────────────────────────────────────────────────────┘ + ↓ + ┌─────────────────────┼─────────────────────┐ + ↓ ↓ ↓ + ┌─────────┐ ┌─────────┐ ┌─────────┐ + │ Redis │ │ MySQL │ │ SQLite │ + │ (缓存) │ │(持久化) │ │ (兜底) │ + └─────────┘ └─────────┘ └─────────┘ +``` + +### 1.2 核心组件 + +| 组件 | 职责 | +|------|------| +| `StorageManager` | 封装三级存储逻辑，提供统一读写接口 | +| `analysis_db.py` | Analysis 数据库连接管理，降级逻辑 | +| `analysis_models.py` | ORM 模型定义（不变） | +| `analysis_migration.py` | SQLite → MySQL 数据迁移 | + +### 1.3 表清单 + +| 表名 | 用途 | 缓存 TTL | +|------|------|----------| +| `futures_analysis` | 期货分析报告 | 5 分钟 | +| `watched_symbols` | 用户关注品种 | 10 分钟 | +| `ai_model_configs` | AI 模型配置 | 10 分钟 | +| `analysis_settings` | 分析设置 | 10 分钟 | +| `ai_analysis_cache` | AI 分析缓存 | 5 分钟 | +| `review_dates` | 复盘日期 | 1 小时 | +| `symbol_rankings` | 品种排名 | 1 小时 | +| `trading_plans` | 交易计划 | 1 小时 | +| `symbol_scores_v2` | V2 品种评分 | 1 小时 | +| `trading_plans_v2` | V2 交易计划 | 1 小时 | +| `sector_heat` | 板块热度 | 1 小时 | +| `review_plans_v2` | V2 复盘计划 | 1 小时 | +| `trade_records` | 交易记录 | 不缓存 | +| `trade_import_batches` | 交易导入批次 | 不缓存 | + +## 2. 降级策略 + +### 2.1 读取流程 + +``` +读取请求 + ↓ +检查 Redis 缓存 + ↓ 命中 +返回数据 + ↓ 未命中 +检查 MySQL 可用性 + ↓ 可用 +查询 MySQL → 回填 Redis → 返回 + ↓ 不可用 +降级到 SQLite → 返回 +``` + +### 2.2 写入流程 + +``` +写入请求 + ↓ +删除 Redis 缓存 + ↓ +写入 MySQL（事务） + ↓ 成功 +回填 Redis → 返回 + ↓ 失败 +写入 SQLite → 返回 +``` + +### 2.3 降级状态检测 + +- 惰性检测：30 秒间隔 +- Redis 不可用时跳过缓存层 +- MySQL 不可用时降级到 SQLite + +## 3. 数据迁移 + +### 3.1 迁移时机 + +应用启动时（`lifespan`），在 MySQL 表结构初始化后执行。 + +### 3.2 迁移逻辑 + +```python +def migrate_analysis_sqlite_to_mysql(): + """将 SQLite analysis 数据迁移到 MySQL""" + # 1. 检测 MySQL 表是否已有数据 + mysql_count = count_mysql_analysis_tables() + if mysql_count > 0: + logger.info("MySQL analysis 表已有数据，跳过迁移") + return + + # 2. 从 SQLite 读取数据 + sqlite_data = read_sqlite_analysis_data() + + # 3. 批量写入 MySQL + write_mysql_analysis_data(sqlite_data) + + logger.info("Analysis 数据迁移完成") +``` + +### 3.3 幂等性 + +- 检测 MySQL 表是否已有数据 +- 有数据则跳过迁移 +- 迁移失败不影响应用启动 + +## 4. 缓存策略 + +### 4.1 缓存键设计 + +``` +analysis:{table_name}:{id} +analysis:{table_name}:list:{query_hash} +``` + +### 4.2 缓存失效 + +- 写入时删除相关缓存 +- TTL 过期自动失效 + +### 4.3 缓存回填 + +- 读取时未命中，查询 MySQL 后回填 +- TTL 与表类型对应 + +## 5. 兼容性 + +### 5.1 ORM 模型 + +- 保持不变 +- 使用 `AnalysisBase` 作为基类 + +### 5.2 API 接口 + +- 保持不变 +- 通过 `get_analysis_db()` 依赖注入 + +### 5.3 SQLite 文件 + +- 保留 `data/futures_analysis.db` +- 降级时使用 + +## 6. 测试策略 + +### 6.1 单元测试 + +| 场景 | 测试方法 | +|------|----------| +| Redis 缓存命中 | Mock Redis，验证不查询 MySQL | +| Redis 缓存未命中 | Mock Redis 返回 None，验证查询 MySQL | +| MySQL 降级到 SQLite | Mock MySQL 不可用，验证查询 SQLite | +| 数据迁移 | 验证 SQLite 数据完整迁移到 MySQL | + +### 6.2 集成测试 + +- 启动应用，验证 MySQL 表创建 +- 执行迁移，验证数据完整性 +- 调用 API，验证功能正常 + +## 7. 风险与缓解 + +| 风险 | 缓解措施 | +|------|----------| +| 数据迁移失败 | 保留 SQLite 作为降级方案，迁移失败时自动降级 | +| Redis 缓存不一致 | 写入时先删缓存，再写 MySQL，最后回填缓存 | +| 表结构不兼容 | 复用现有 ORM 模型，MySQL 自动创建表结构 | +| 性能下降 | Redis 缓存减少 MySQL 查询压力 | diff --git a/openspec/changes/analysis-storage-refactor/.comet.yaml b/openspec/changes/analysis-storage-refactor/.comet.yaml index a5e78da..5d8ccf1 100644 --- a/openspec/changes/analysis-storage-refactor/.comet.yaml +++ b/openspec/changes/analysis-storage-refactor/.comet.yaml @@ -1,5 +1,5 @@ workflow: full -phase: design +phase: build context_compression: off build_mode: null build_pause: null @@ -10,7 +10,7 @@ isolation: null verify_mode: null auto_transition: true base_ref: 62a95ca -design_doc: null +design_doc: docs/superpowers/specs/2026-07-04-analysis-storage-refactor-design.md plan: null verify_result: null verification_report: null diff --git a/openspec/changes/analysis-storage-refactor/.comet/handoff/brainstorm-summary.md b/openspec/changes/analysis-storage-refactor/.comet/handoff/brainstorm-summary.md new file mode 100644 index 0000000..5e2f093 --- /dev/null +++ b/openspec/changes/analysis-storage-refactor/.comet/handoff/brainstorm-summary.md @@ -0,0 +1,42 @@ +# Brainstorm Summary + +- Change: analysis-storage-refactor +- Date: 2026-07-04 + +## 确认的技术方案 + +将 `futures_analysis.db`（14 张表）迁移到 MySQL `buffer_platform` 数据库，并引入 Redis 缓存层，与行情数据存储策略保持一致（Redis→MySQL→SQLite 三级降级）。 + +### 核心设计 + +1. **复用现有连接**：使用 `storage_manager.py` 中的 `mysql_engine` 和 `redis_client` +2. **扩展 StorageManager**：新增 analysis 表读写方法 +3. **降级策略**：Redis 缓存 → MySQL 持久化 → SQLite 兜底 +4. **数据迁移**：启动时自动迁移现有 SQLite 数据到 MySQL + +### 缓存策略 + +| 表类型 | 缓存 TTL | 说明 | +|--------|----------|------| +| AI 分析结果 | 5 分钟 | 频繁读取，短期缓存 | +| 复盘计划 | 1 小时 | 每日更新，中期缓存 | +| 交易记录 | 不缓存 | 写入后不再修改 | +| 配置表 | 10 分钟 | 低频读取 | + +## 关键取舍与风险 + +| 取舍/风险 | 决策/缓解 | +|-----------|-----------| +| 表名前缀 | 保持原名，通过 ORM 模型区分 | +| 数据迁移失败 | 保留 SQLite 作为降级方案 | +| Redis 缓存一致性 | 写入时先删缓存，再写 MySQL，最后回填 | + +## 测试策略 + +1. 单元测试：三级降级场景 +2. 集成测试：数据迁移完整性 +3. 功能测试：现有功能（AI 分析、复盘计划、交易记录）正常工作 + +## Spec Patch + +无（复用已有 delta spec 结构）