buffer_platform/docs/futures_analysis_module.md

# 期货智析（futures_analysis）模块 — 功能与逻辑文档

## 一、模块概述

期货智析模块是一个集**数据采集、技术分析、AI智能分析、复盘计划生成、交易复盘**于一体的期货分析平台。采用前后端分离架构，前端为 SPA 单页应用，后端提供 RESTful API。

---

## 二、文件结构

### 后端

| 文件 | 说明 |
|------|------|
| `app/api/futures_analysis.py` | 主 API 路由（~970行），前缀 `/api/v1/futures` |
| `app/api/review_plan.py` | 复盘计划 API，前缀 `/api/v1/review` |
| `app/api/trade_review.py` | 交易复盘 API，前缀 `/api/v1/trade-review` |
| `app/analysis_models.py` | 数据模型定义（~325行），14 个 ORM 模型类 |
| `app/analysis_db.py` | 独立数据库初始化（SQLite + MySQL 动态切换） |
| `app/services/ai_analysis.py` | AI 四维联合分析服务（~513行） |
| `app/services/cache.py` | 缓存服务（SQLite/Redis/MySQL 三级存储） |
| `app/services/collector.py` | 数据采集服务（封装底层采集脚本） |
| `app/services/plan_generator.py` | 复盘计划生成器 |
| `app/services/trade_parser.py` | 结算单解析器 |
| `app/config_store.py` | 统一配置存储（MySQL 优先 + JSON 文件兜底） |

### 前端

| 文件 | 说明 |
|------|------|
| `app/static/futures_analysis.html` | 主页面（~1232行） |
| `app/static/futures_analysis.js` | 前端逻辑（~3855行） |
| `app/static/futures_analysis.css` | 样式表（~3124行） |

### 数据库

| 文件 | 说明 |
|------|------|
| `data/futures_analysis.db` | SQLite 数据库（兜底存储） |

---

## 三、整体分析逻辑流程

### 3.1 数据流全链路

```
数据采集(collector.py) → 缓存存储(cache.py) → API接口(futures_analysis.py) → 前端渲染(JS)
                                                      ↓
                                           AI分析服务(ai_analysis.py)
                                                      ↓
                                           AI结果缓存(AIAnalysisCache表)
```

### 3.2 品种列表加载流程

1. **前端** `loadFuturesList()` 调用 `GET /api/v1/futures/list`
2. **后端** `get_futures_list()` 执行：
   - 从 `config_store` 加载品种配置（品种名称 → 合约代码映射）
   - 遍历每个品种，调用 `get_cached_data()` 从缓存获取 K 线数据
   - 对每个品种计算：
     - 当前价格、涨跌幅
     - 操作建议（`_get_suggestion`）
     - 多周期趋势（`_get_period_trends`）
     - 成功率（`_calc_success_rate`）
     - 趋势评分（`_calc_trend_score`）
     - 压力支撑位（Pivot Point 公式）
3. **前端** 渲染品种卡片网格，同时异步调用 `loadAllAIAnalysis()` 分批加载每个品种的 AI 分析结果

### 3.3 单品种详情分析流程

1. **前端** `showDetailView(symbol)` 切换到详情视图
2. 并行执行三个请求：
   - `loadFuturesDetail(symbol)` → `GET /api/v1/futures/detail/{symbol}` — 详细行情和技术指标
   - `loadKlineData(symbol, period)` → `GET /api/v1/futures/kline/{symbol}` — K 线数据（图表用）
   - `loadHistoryListForAnalysis(symbol)` → `GET /api/v1/futures/ai-analysis/{symbol}/history` — AI 分析历史
3. **后端** `get_futures_detail()` 计算完整技术指标：
   - **MACD**（`_calc_macd`）：EMA12/EMA26 → DIF/DEA → 金叉/死叉信号
   - **RSI**（`_calc_rsi`）：14 周期 RSI → 超买/超卖/正常判断
   - **布林带**（`_calc_boll`）：20 周期 MA ± 2 倍标准差 → 上轨/中轨/下轨信号
   - **KDJ**（`_calc_kdj`）：9 周期 RSV → K/D 值 → 偏多/偏空/中性
   - **Pivot Point**：PP = (H+L+C)/3，R1/R2/S1/S2 标准公式
4. **前端** 使用 ECharts 渲染 K 线图（含 MA5/MA10/MA20 均线、成交量柱、MACD 子图）

### 3.4 AI 智能分析流程（核心）

1. **前端** `runAIAnalysis()` 调用 `POST /api/v1/futures/ai-analysis/{symbol}`
2. **后端** `AIFuturesAnalyzer.analyze()` 执行完整流程：

```
步骤1: get_active_model()
  └─ 从配置中获取当前激活的 AI 模型（支持 OpenAI 兼容接口）

步骤2: prepare_multi_period_data()
  └─ 准备 5 个周期（5min/15min/30min/60min/daily）的 K 线数据
  └─ 每个周期计算技术指标（MA10/MA20/MACD/KDJ/量比等）

步骤3: AIAnalysisPrompt.build_prompt()
  └─ 构建"四维联合判断分析法(4D-XV)"提示词
  └─ 系统角色：20年经验的资深金融分析师
  └─ 要求输出 JSON 格式的四维分析结果

步骤4: call_ai_model()
  └─ 通过 HTTP POST 调用 AI 模型（OpenAI 兼容格式，180秒超时）

步骤5: parse_ai_response()
  └─ 正则提取 JSON 响应

步骤6: save_analysis_cache()
  └─ 保存结果到 AIAnalysisCache 表，附带 K 线时间戳
```

3. **智能缓存策略**（`should_reanalyze`）：
   - 分析超过 15 分钟 → 重新分析
   - K 线数据时间戳比分析时间新 → 重新分析
   - 否则返回缓存结果

4. **前端** `displayAIAnalysisResult()` 渲染分析结果，并通过 `syncAIToPanels()` 同步数据到各个面板

### 3.5 AI 分析输出结构（4D-XV 四维联合分析）

AI 分析返回的 JSON 包含以下字段：

| 字段 | 说明 |
|------|------|
| `summary` | 分析摘要 |
| `four_dimensional` | 四维分析（MACD趋势、成交量资金、KDJ时机、多周期方向） |
| `kdj_diagnosis` | KDJ 诊断详情 |
| `pivot_points` | 压力支撑位 |
| `red_lines_check` | 红线审查（不可违反的交易纪律） |
| `discipline_score` | 纪律评分 |
| `trading_suggestion` | 交易建议（方向、置信度、入场区间、止损、仓位） |
| `scenario_plans` | 情景预案（突破/震荡/反转/消息影响） |
| `risk_warnings` | 风险提示 |
| `experience_lessons` | 经验教训 |

---

## 四、全部功能清单

### 4.1 品种分析（主页面）

| 功能 | 描述 |
|------|------|
| 品种列表展示 | 卡片网格展示所有期货品种，含价格、涨跌、建议、成功率、趋势评分、压力支撑位 |
| 分类筛选 | 全部 / 能源 / 金属 / 农产品 / 金融 四大分类 |
| 搜索 | 按品种名称或合约代码搜索 |
| 趋势筛选 | 点击统计卡片按上涨 / 下跌 / 震荡筛选 |
| 数据刷新 | 单个品种刷新或全部刷新（异步后台执行，进度轮询） |
| 自选品种 | 添加/取消自选，独立自选页面 |
| AI 批量分析 | 一键对所有合约进行 AI 分析（分批 3 个并发，2 秒间隔） |

### 4.2 详情分析页

| 功能 | 描述 |
|------|------|
| 行情概览 | 品种名称、合约代码、当前价、涨跌、开/高/低/量 |
| K 线图表 | ECharts 渲染，支持 5M/15M/30M/1H 四个周期切换，含 MA 均线、成交量、MACD 子图 |
| 技术指标面板 | MACD（金叉/死叉）、RSI（超买/超卖）、布林带、KDJ |
| 关键点位 | Pivot Point 计算的压力位(R1/R2)、支撑位(S1/S2)、中枢(PP) |
| 多周期趋势 | 5/15/30/60 分钟四个周期的趋势方向 |
| AI 思维分析 | 四维联合分析结果展示（摘要、方向、置信度、入场区间、止损、仓位） |
| AI 分析详情弹窗 | 完整的 4D-XV 信号表、红线审查、纪律评分、情景预案、经验教训 |
| 历史分析记录 | 展示该品种的历史 AI 分析记录列表，可点击查看完整报告 |
| 情景预案 | 突破/震荡/反转/消息影响四种情景的概率和应对策略 |

### 4.3 复盘计划（V2）

| 功能 | 描述 |
|------|------|
| 生成复盘报告 | 选择日期，调用 `POST /api/v1/review/generate` 自动生成 |
| 核心结论 | Hero 区域展示日期、核心结论、数据基准 |
| 三档分类 | 绿色（交易机会）/ 黄色（重点关注）/ 红色（规避） |
| 交易机会卡片 | 含方向、入场区间、止损、目标位、触发条件、四维评分条 |
| 全品种排名表 | 支持按综合评分/活跃度/量比/方向排序 |
| 品种详情弹窗 | 评分明细、多周期趋势、枢轴点位、交易计划 |
| 板块热度 | 各板块均分、趋势、龙头品种 |
| 风险提示 | 全局风险提示横幅 |

### 4.4 交易复盘

| 功能 | 描述 |
|------|------|
| 结算单导入 | 支持单个/批量导入 .xls/.xlsx 期货结算单 |
| 去重校验 | 按交易日+品种+时间+价格逐条去重 |
| 6 维统计卡片 | 总盈亏、净盈亏、胜率/盈亏比、交易笔数、最大回撤、日均盈亏 |
| 账户权益曲线 | ECharts 折线+柱状图（累计净盈亏 + 每日盈亏） |
| 品种盈亏气泡图 | 气泡大小=手续费占比，颜色=净盈亏 |
| 每日交易详情表 | 点击日期查看详情弹窗（含 AI 诊断报告、品种盈亏统计、交易流水） |
| 品种盈亏排行表 | 含盈亏比异步计算 |
| 品种详情弹窗 | K 线走势（多周期切换）+ 该品种交易记录 |
| 交易详情弹窗 | 单笔交易详情 + K 线买卖点标注 + AI 交易分析 |
| 批次管理 | 查看/删除导入批次 |
| 按日期删除 | 删除指定日期的所有交易记录 |

---

## 五、数据模型（14 个 ORM 类）

| 模型类 | 表名 | 用途 |
|--------|------|------|
| `FuturesAnalysis` | `futures_analysis` | 期货分析报告（建议、指标、评分、点位） |
| `WatchedSymbol` | `watched_symbols` | 用户关注品种 |
| `AIModelConfig` | `ai_model_configs` | AI 模型配置（提供商、密钥、参数） |
| `AnalysisSettings` | `analysis_settings` | 分析设置（单例 JSON 配置） |
| `AIAnalysisCache` | `ai_analysis_cache` | AI 分析结果缓存（含 K 线时间戳用于智能刷新） |
| `ReviewDate` | `review_dates` | 复盘日期（V1） |
| `SymbolRanking` | `symbol_rankings` | 品种排名（V1） |
| `TradingPlan` | `trading_plans` | 交易计划（V1） |
| `SymbolScoreV2` | `symbol_scores_v2` | V2 品种多维度评分（5维度+综合+关键点位+方向标签） |
| `TradingPlanV2` | `trading_plans_v2` | V2 交易计划（入场/止损/目标/触发条件） |
| `SectorHeat` | `sector_heat` | 板块热度（均分/趋势/龙头/成员） |
| `ReviewPlanV2` | `review_plans_v2` | V2 复盘计划总表（元数据+统计） |
| `TradeRecord` | `trade_records` | 交易记录（从结算单导入的逐笔明细） |
| `TradeImportBatch` | `trade_import_batches` | 导入批次元信息 |

---

## 六、组件连接关系

```
                        +-------------------+
                        |   前端 SPA 页面    |
                        | futures_analysis   |
                        |  .html / .js / .css|
                        +---------+---------+
                                  |
              +-------------------+-------------------+
              |                   |                   |
    /api/v1/futures/*   /api/v1/review/*   /api/v1/trade-review/*
              |                   |                   |
    +---------+--------+  +------+-------+  +--------+--------+
    |futures_analysis.py|  |review_plan.py|  | trade_review.py |
    +----+------+------+  +------+-------+  +--------+--------+
         |      |                |                   |
         |      +-------+--------+----------+--------+
         |              |                   |
    +----+----+  +------+-------+  +--------+--------+
    |cache.py |  |plan_generator|  |  trade_parser   |
    +----+----+  +--------------+  +-----------------+
         |
    +----+----+     +------------------+
    |collector| --> | futures_data_     |
    |  .py    |     | collector(脚本)   |
    +---------+     +------------------+
         |
    +----+----+     +------------------+
    | storage | --> | Redis / MySQL /  |
    | Manager |     | SQLite(兜底)     |
    +---------+     +------------------+
         |
    +----+----+
    |config   | --> symbols_config.json / ai_config.json / MySQL AppConfig
    |_store   |
    +---------+
         |
    +----+-----------+
    |ai_analysis.py  | --> 外部 AI 模型 API (OpenAI 兼容)
    |(AIFuturesAnalyzer)
    +----------------+
```

---

## 七、存储架构

采用**三级降级策略**：

1. **MySQL 优先** — 生产环境主存储
2. **Redis / StorageManager** — 缓存层加速
3. **SQLite 兜底** — 开发/单机环境自动降级

`analysis_db.py` 中的 `get_analysis_db()` 动态检测 MySQL 可用性，透明切换后端，业务代码无需感知底层存储变化。

---

## 八、路由注册

在 `app/main.py` 中注册三个路由：

```python
# 第 179-182 行
app.include_router(futures_analysis.router)   # /api/v1/futures
app.include_router(review_plan.router)         # /api/v1/review
app.include_router(trade_review.router)        # /api/v1/trade-review
```

页面入口：`GET /futures-analysis`

---

## 九、技术指标计算说明

### MACD（Moving Average Convergence Divergence）
- EMA12 = 前一日EMA12 × (1 - 2/13) + 今日收盘价 × 2/13
- EMA26 = 前一日EMA26 × (1 - 2/27) + 今日收盘价 × 2/27
- DIF = EMA12 - EMA26
- DEA = 前一日DEA × (1 - 2/10) + 今日DIF × 2/10
- 信号：DIF > DEA → 金叉（看多）；DIF < DEA → 死叉（看空）

### RSI（Relative Strength Index）
- 14 周期 RSI = 100 - 100 / (1 + RS)，RS = 平均上涨幅度 / 平均下跌幅度
- 信号：RSI > 70 → 超买；RSI < 30 → 超卖；30 ≤ RSI ≤ 70 → 正常

### 布林带（Bollinger Bands）
- 中轨 = 20 周期 MA
- 上轨 = 中轨 + 2 × 标准差
- 下轨 = 中轨 - 2 × 标准差
- 信号：价格触及上轨 → 压力；价格触及下轨 → 支撑

### KDJ（随机指标）
- RSV = (收盘价 - 9日最低价) / (9日最高价 - 9日最低价) × 100
- K = 2/3 × 前一日K + 1/3 × RSV
- D = 2/3 × 前一日D + 1/3 × K
- 信号：K > D → 偏多；K < D → 偏空

### Pivot Point（枢轴点）
- PP = (最高价 + 最低价 + 收盘价) / 3
- R1 = 2 × PP - 最低价
- R2 = PP + (最高价 - 最低价)
- S1 = 2 × PP - 最高价
- S2 = PP - (最高价 - 最低价)