buffer_platform/data/系统架构分析与重构方案.md

# 期货智析系统 - 架构分析与重构方案

> 文档版本：v1.0 | 日期：2026-06-21

***

## 第一部分：当前系统功能清单与交互流程

### 1.1 功能模块总览

| 序号  | 功能模块   | 核心能力                     | 入口页面                                    |
| --- | ------ | ------------------------ | --------------------------------------- |
| F1  | 用户认证   | 登录/登出/角色选择/Token验证       | `/login` → `/role-select`               |
| F2  | 品种配置管理 | 品种CRUD、配置文件上传、批量采集       | `/ui`                                   |
| F3  | 期货品种分析 | 品种列表/详情/K线图/技术指标/数据刷新    | `/futures-analysis` (list-view)         |
| F4  | AI智能分析 | 四维联合分析(4D-XV)、多周期共振、交易建议 | `/futures-analysis` (detail-view)       |
| F5  | 自选品种   | 关注/取消关注品种                | `/futures-analysis` (watched-view)      |
| F6  | 复盘计划   | V2多维度评分、交易计划生成、板块热度      | `/futures-analysis` (review-view)       |
| F7  | 交易复盘   | 结算单导入、交易统计、配对分析、K线标注     | `/futures-analysis` (trade-review-view) |
| F8  | AI模型配置 | 模型CRUD、连接测试、提供商管理        | `/ai-config`                            |
| F9  | 定时采集   | 定时任务CRUD、启停控制、间隔调整       | 后台自动/手动触发                               |
| F10 | 数据缓冲   | K线数据缓存、智能缓存判断、多周期数据聚合    | 内部服务层                                   |

### 1.2 用户交互流程

#### 流程1：登录 → 角色选择 → 主功能

```
用户访问 / → 重定向到 /login
  ├── 输入用户名/密码 → POST /api/v1/auth/login
  │   ├── 成功 → Token存入localStorage → 跳转 /role-select
  │   └── 失败 → 提示错误
  └── Token验证 → GET /api/v1/auth/verify
      └── 有效 → 跳转 /role-select

/role-select (角色选择)
  ├── 管理员 → 可访问所有功能
  └── 普通用户 → 跳转 /futures-analysis
```

#### 流程2：品种分析 → AI分析

```
/futures-analysis (品种列表)
  ├── 加载品种列表 → GET /api/v1/futures/list
  ├── 搜索/筛选品种
  ├── 刷新数据 → POST /api/v1/futures/refresh/{symbol}
  │   └── 调用akshare采集新浪数据 → 缓存到buffer.db
  ├── 点击品种 → 进入详情页
  │   ├── 加载详情 → GET /api/v1/futures/detail/{symbol}
  │   ├── 加载K线图 → GET /api/v1/futures/kline/{symbol}
  │   │   └── ECharts渲染K线+MA+MACD+成交量
  │   ├── 点击"AI分析" → POST /api/v1/futures/ai-analysis/{symbol}
  │   │   ├── 检查缓存 → AIAnalysisCache表
  │   │   ├── 缓存有效(15min内+K线未变) → 直接返回缓存
  │   │   └── 缓存失效 → 准备多周期数据 → 构建Prompt
  │   │       → 调用AI模型API → 解析JSON响应 → 保存缓存
  │   └── 展示AI分析结果（四维分析/交易建议/关键点位/风控）
  └── 查看历史 → GET /api/v1/futures/ai-analysis/{symbol}/history
```

#### 流程3：复盘计划生成

```
/futures-analysis (review-view)
  ├── 点击"生成复盘计划" → POST /api/v1/review/generate
  │   ├── 采集所有品种多周期数据(60m/15m/5m)
  │   ├── 5维度评分(振幅20%+量能15%+涨跌幅15%+趋势35%+活跃度15%)
  │   ├── 归一化 → 分类(green/yellow/red)
  │   ├── 生成交易计划(入场/止损/目标)
  │   ├── 计算板块热度
  │   └── 生成汇总报告
  ├── 查看计划列表 → GET /api/v1/review/v2/plans
  ├── 查看计划详情 → GET /api/v1/review/v2/plan/{plan_id}
  └── 查看品种详情弹窗
```

#### 流程4：交易复盘

```
/futures-analysis (trade-review-view)
  ├── 上传结算单(.xls) → POST /api/v1/trade-review/import
  │   └── 解析xls → 标准化 → 保存trade_records表
  ├── 查看交易记录 → GET /api/v1/trade-review/records
  ├── 查看统计
  │   ├── 每日汇总 → GET /api/v1/trade-review/daily-summary
  │   ├── 品种汇总 → GET /api/v1/trade-review/variety-summary
  │   └── 总体统计 → GET /api/v1/trade-review/statistics
  ├── 配对分析 → GET /api/v1/trade-review/trade-pairs
  ├── K线+买卖点 → GET /api/v1/trade-review/kline-with-trades/{symbol}
  └── AI逐笔分析 → POST /api/v1/trade-review/analyze-trade
```

### 1.3 数据流转调用链

#### 调用链1：数据采集链路

```
[前端] 触发刷新
  → [API] POST /api/v1/futures/refresh/{symbol}
    → [Service] collector.fetch_symbol_data()
      → [External] akshare → 新浪财经API
        → 返回多周期K线数据(5m/15m/30m/60m/daily)
      → [Service] cache.save_market_data()
        → [DB] buffer.db.market_data (按period存储JSON)
        → [DB] buffer.db.symbol_timestamps (更新时间戳)
```

#### 调用链2：AI分析链路

```
[前端] 请求AI分析
  → [API] POST /api/v1/futures/ai-analysis/{symbol}
    → [Service] AIFuturesAnalyzer.analyze()
      → [Service] get_cached_data() → [DB] buffer.db.market_data
      → [Service] prepare_multi_period_data() → 计算技术指标(MACD/KDJ/EMA)
      → [Service] AIAnalysisPrompt.build_prompt() → 构建Prompt
      → [External] AI模型API (阿里百炼qwen3.6-plus)
      → [Service] parse_ai_response() → 解析JSON
      → [Service] save_analysis_cache() → [DB] futures_analysis.db.ai_analysis_cache
```

#### 调用链3：复盘计划生成链路

```
[前端] 生成复盘计划
  → [API] POST /api/v1/review/generate
    → [Service] plan_generator.generate()
      → [Service] 批量采集所有品种数据 → [External] akshare
      → [Service] 5维度评分计算
      → [Service] 归一化 + 分类(green/yellow/red)
      → [Service] 生成交易计划(入场/止损/目标价)
      → [Service] 计算板块热度
      → [DB] futures_analysis.db:
        ├── symbol_scores_v2 (品种评分)
        ├── trading_plans_v2 (交易计划)
        ├── sector_heat (板块热度)
        └── review_plans_v2 (汇总报告)
```

#### 调用链4：交易复盘链路

```
[前端] 上传结算单
  → [API] POST /api/v1/trade-review/import
    → [Service] trade_parser.parse()
      → 解析.xls文件 → 动态识别表头
      → 标准化日期/时间/品种代码
      → [DB] futures_analysis.db.trade_records
      → [DB] futures_analysis.db.trade_import_batches

[前端] 查看统计
  → [API] GET /api/v1/trade-review/{summary-type}
    → [Service] trade_parser 统计函数
      → [DB] 查询trade_records → 聚合计算
      → 返回统计结果
```

#### 调用链5：定时任务链路

```
[启动时] lifespan() → start_scheduler()
  → [Service] scheduler.start_scheduler() → 创建APScheduler实例
  → 恢复已启用任务 → list_tasks() → add_job()

[运行时] APScheduler触发
  → [Service] scheduler.execute_task()
    → [Service] collector.fetch_symbol_data()
      → [External] akshare → 新浪财经
    → [Service] cache.save_market_data() → [DB] buffer.db
    → [Service] cache.update_task_status() → [DB] buffer.db.scheduled_tasks
```

***

## 第二部分：当前系统架构

### 2.1 技术栈

| 层级          | 技术选型               | 说明               |
| ----------- | ------------------ | ---------------- |
| **Web框架**   | FastAPI 0.110+     | 异步Python Web框架   |
| **ASGI服务器** | Uvicorn 0.29+      | 生产级ASGI服务器       |
| **ORM**     | SQLAlchemy 2.0+    | 同步Session模式      |
| **数据库**     | SQLite (aiosqlite) | 双数据库文件           |
| **定时调度**    | APScheduler 3.10+  | 后台线程池调度          |
| **数据采集**    | akshare 1.14+      | 新浪财经数据源          |
| **前端框架**    | 无 (Vanilla JS)     | 原生HTML/CSS/JS    |
| **图表**      | ECharts 5.4.3      | CDN引入            |
| **部署**      | Docker + Compose   | Python 3.11-slim |

### 2.2 系统架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                        前端层 (Vanilla JS)                       │
│  ┌──────────┐ ┌──────────────┐ ┌──────────┐ ┌───────────────┐  │
│  │login.html│ │futures_      │ │ai_config │ │review_plan    │  │
│  │role_select│ │ analysis.html│ │  .html   │ │  .html        │  │
│  └──────────┘ └──────────────┘ └──────────┘ └───────────────┘  │
│         │           │               │              │             │
│         └───────────┴───────────────┴──────────────┘             │
│                             │ HTTP REST API                      │
│                             │ (fetch + localStorage)             │
└─────────────────────────────┼───────────────────────────────────┘
                              │
┌─────────────────────────────┼───────────────────────────────────┐
│                      API路由层 (FastAPI)                         │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌────────┐ ┌───────┐ ┌──────────┐ │
│  │auth  │ │data  │ │tasks │ │futures │ │ai_    │ │review    │ │
│  │.py   │ │.py   │ │.py   │ │_analysis│ │config │ │_plan.py  │ │
│  └──┬───┘ └──┬───┘ └──┬───┘ └───┬────┘ └──┬────┘ └────┬─────┘ │
│     │        │        │         │           │          │        │
│  ┌──┴────────┴────────┴─────────┴───────────┴──────────┴──────┐ │
│  │                    trade_review.py                          │ │
│  └────────────────────────┬────────────────────────────────────┘ │
└───────────────────────────┼─────────────────────────────────────┘
                            │
┌───────────────────────────┼─────────────────────────────────────┐
│                      服务层 (Services)                           │
│  ┌───────────┐ ┌─────────┐ ┌──────────┐ ┌───────────────────┐  │
│  │collector  │ │ cache   │ │scheduler │ │ ai_analysis       │  │
│  │.py        │ │ .py     │ │ .py      │ │ .py               │  │
│  │(akshare)  │ │(TTL缓存)│ │(APSchd)  │ │(Prompt+AI调用)    │  │
│  └─────┬─────┘ └────┬────┘ └────┬─────┘ └────────┬──────────┘  │
│        │             │           │                 │             │
│  ┌─────┴─────┐ ┌─────┴─────────┴──────────────────┴──────────┐ │
│  │plan_      │ │ trade_parser.py                              │ │
│  │generator  │ │ (结算单解析)                                   │ │
│  │.py        │ │                                               │ │
│  └───────────┘ └──────────────────────────────────────────────┘ │
└───────────────────────────┬─────────────────────────────────────┘
                            │
┌───────────────────────────┼─────────────────────────────────────┐
│                      数据层 (SQLite)                             │
│  ┌────────────────────────┴───┐  ┌────────────────────────────┐ │
│  │      buffer.db             │  │    futures_analysis.db      │ │
│  │  ┌──────────────┐          │  │  ┌────────────────────┐    │ │
│  │  │ market_data  │          │  │  │ futures_analysis   │    │ │
│  │  │ (K线缓存)    │          │  │  │ watched_symbols    │    │ │
│  │  ├──────────────┤          │  │  │ ai_model_configs   │    │ │
│  │  │symbol_       │          │  │  │ analysis_settings  │    │ │
│  │  │ timestamps   │          │  │  │ ai_analysis_cache  │    │ │
│  │  ├──────────────┤          │  │  │ review_dates       │    │ │
│  │  │scheduled_    │          │  │  │ symbol_rankings    │    │ │
│  │  │ tasks        │          │  │  │ trading_plans(v1)  │    │ │
│  │  ├──────────────┤          │  │  │ symbol_scores_v2   │    │ │
│  │  │ users        │          │  │  │ trading_plans_v2   │    │ │
│  │  ├──────────────┤          │  │  │ sector_heat        │    │ │
│  │  │ sessions     │          │  │  │ review_plans_v2    │    │ │
│  │  └──────────────┘          │  │  │ trade_records      │    │ │
│  │                            │  │  │ trade_import_batches│   │ │
│  │   6个表                    │  │  └────────────────────┘    │ │
│  │                            │  │   14个表                   │ │
│  └────────────────────────────┘  └────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                            │
┌───────────────────────────┼─────────────────────────────────────┐
│                      外部服务                                    │
│  ┌──────────────┐  ┌──────┴───────┐  ┌───────────────────────┐ │
│  │ 新浪财经API  │  │ AI模型API    │  │ Docker容器             │ │
│  │ (via akshare)│  │ (阿里百炼)   │  │ (python:3.11-slim)    │ │
│  └──────────────┘  └──────────────┘  └───────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

### 2.3 数据库Schema（共20个表）

#### buffer.db（6个表）

| 表名                  | 用途      | 关键字段                                                                         |
| ------------------- | ------- | ---------------------------------------------------------------------------- |
| `market_data`       | K线数据缓存  | symbol, data\_type, period, candles\_json(JSON), current\_price, fetched\_at |
| `symbol_timestamps` | 合约刷新时间戳 | symbol, data\_type, last\_refresh\_at, refresh\_count                        |
| `scheduled_tasks`   | 定时任务配置  | symbol, data\_type, periods, interval\_seconds, task\_type, enabled          |
| `users`             | 用户表     | username, password\_hash, role(admin/user), is\_active                       |
| `sessions`          | 会话管理    | user\_id, token, expires\_at, is\_valid                                      |

#### futures\_analysis.db（14个表）

| 表名                     | 用途       | 关键字段                                                                |
| ---------------------- | -------- | ------------------------------------------------------------------- |
| `futures_analysis`     | 分析报告     | symbol, period, suggestion, entry\_price, target\_price, stop\_loss |
| `watched_symbols`      | 关注品种     | symbol, name, note                                                  |
| `ai_model_configs`     | AI模型配置   | provider, model\_name, api\_key, api\_base, enabled                 |
| `analysis_settings`    | 分析设置(KV) | key, value(JSON)                                                    |
| `ai_analysis_cache`    | AI分析缓存   | symbol, analysis\_data(JSON), kline\_timestamp                      |
| `review_dates`         | 复盘日期     | review\_date, week\_day                                             |
| `symbol_rankings`      | 品种排名(V1) | symbol, rank\_type, rank, value                                     |
| `trading_plans`        | 交易计划(V1) | symbol, plan\_type, score, logic, entry\_price                      |
| `symbol_scores_v2`     | V2多维度评分  | symbol, 5维度分数, composite\_score, category, pivot/R/S                |
| `trading_plans_v2`     | V2交易计划   | symbol, direction, entry\_low/high, stop\_loss, target1/2           |
| `sector_heat`          | 板块热度     | sector\_name, avg\_score, heat\_level, leader\_symbol               |
| `review_plans_v2`      | V2复盘总表   | review\_date, core\_conclusion, bull/bear\_count                    |
| `trade_records`        | 交易记录     | symbol, direction, offset, price, volume, close\_pnl                |
| `trade_import_batches` | 导入批次     | batch\_id, source\_file, futures\_count                             |

### 2.4 API端点清单（共55+个）

| 模块   | 前缀                     | 端点数 | 主要功能               |
| ---- | ---------------------- | --- | ------------------ |
| 认证   | `/api/v1/auth`         | 4   | 登录/登出/验证/用户信息      |
| 数据   | `/api/v1/data`         | 5   | 批量获取/最新数据/缓存状态     |
| 任务   | `/api/v1/tasks`        | 8   | 定时任务CRUD+启停        |
| 配置   | `/api/v1/config`       | 4   | 品种配置/批量操作          |
| 期货分析 | `/api/v1/futures`      | 18  | 品种列表/详情/K线/AI分析/关注 |
| AI配置 | `/api/v1/ai-config`    | 4   | 模型配置/测试连接          |
| 复盘计划 | `/api/v1/review`       | 12  | V1+V2复盘数据管理        |
| 交易复盘 | `/api/v1/trade-review` | 12  | 结算单导入/统计/配对/AI分析   |

### 2.5 前端页面结构

| 页面          | 文件                                                     | 大小      | 视图/组件                                                 |
| ----------- | ------------------------------------------------------ | ------- | ----------------------------------------------------- |
| 登录          | `login.html`                                           | 内联      | 单表单                                                   |
| 角色选择        | `role_select.html`                                     | 内联      | 入口卡片                                                  |
| 品种配置        | `index.html`                                           | 内联      | 管理后台                                                  |
| **期货智析(主)** | `futures_analysis.html` + `.css`(3100行) + `.js`(3200行) | \~6300行 | 5个视图(list/detail/watched/review/trade-review) + 7个模态框 |
| AI配置        | `ai_config.html` + `.css` + `.js`                      | 中等      | 模型配置表单                                                |
| 复盘计划        | `review_plan.html` + `.css`(1760行) + `.js`             | 中等      | 独立复盘页(暗色主题)                                           |

### 2.6 当前架构存在的问题

| 编号  | 问题类别      | 具体问题                                              | 影响         |
| --- | --------- | ------------------------------------------------- | ---------- |
| P1  | **缓存效率**  | 使用SQLite存储K线JSON，每次读取需反序列化整个JSON字符串               | 高延迟，尤其品种多时 |
| P2  | **并发能力**  | SQLite写锁限制，多线程采集时存在竞争                             | 数据更新阻塞     |
| P3  | **前端架构**  | 6300行单文件JS，无模块化，全局变量管理状态                          | 维护困难，易出错   |
| P4  | **代码重复**  | 两套数据库连接、两套Session管理、手动迁移脚本                        | 维护成本高      |
| P5  | **缓存策略**  | 简单TTL机制，无分层缓存，无内存缓存                               | 重复查询数据库    |
| P6  | **AI调用**  | 同步requests调用AI API，阻塞事件循环                         | 并发分析时性能差   |
| P7  | **数据模型**  | 大量JSON字段存储(candles\_json, analysis\_data等)，无法索引查询 | 查询效率低      |
| P8  | **无数据管道** | 采集→缓存→分析→展示紧耦合                                    | 难以扩展和测试    |
| P9  | **认证安全**  | 自研Token系统，SHA256+Salt，无JWT标准                      | 安全性不足      |
| P10 | **部署**    | 单容器，无Redis/消息队列                                   | 无法水平扩展     |

***

## 第三部分：重构方案

### 3.1 数据库重构方案

#### 现状问题

* 双SQLite数据库文件，写锁限制并发

* 大量JSON字段无法索引

* 无迁移管理工具

* K线数据以JSON字符串存储，查询效率低

#### 方案：迁移到 PostgreSQL + Redis 双层架构

```
┌─────────────────────────────────────────────┐
│              Redis (缓存层)                  │
│  ┌────────────────┐ ┌────────────────────┐  │
│  │ K线数据缓存    │ │ AI分析结果缓存     │  │
│  │ (Hash+TTL)     │ │ (String+TTL)       │  │
│  │ 品种:周期→数据 │ │ 品种→分析JSON      │  │
│  └────────────────┘ └────────────────────┘  │
│  ┌────────────────┐ ┌────────────────────┐  │
│  │ 刷新状态/锁    │ │ 会话Token          │  │
│  │ (String+TTL)   │ │ (String+TTL)       │  │
│  └────────────────┘ └────────────────────┘  │
└─────────────────────────────────────────────┘
                    │
┌─────────────────────────────────────────────┐
│           PostgreSQL (持久层)                 │
│                                             │
│  核心业务表:                                  │
│  ├── kline_data     (K线数据，按品种+周期分区) │
│  ├── symbol_info    (品种基础信息)            │
│  ├── scheduled_task (定时任务配置)            │
│  ├── ai_analysis    (AI分析历史记录)          │
│  ├── review_plan    (复盘计划)               │
│  ├── trade_record   (交易记录)               │
│  └── user/session   (用户认证)               │
│                                             │
│  使用 Alembic 管理数据库迁移                   │
└─────────────────────────────────────────────┘
```

**关键改进：**

| 改进点   | 当前           | 重构后              |
| ----- | ------------ | ---------------- |
| 数据库引擎 | SQLite × 2   | PostgreSQL (统一)  |
| K线存储  | JSON字符串字段    | 独立表 + 分区(按品种)    |
| 缓存    | SQLite TTL查询 | Redis Hash + TTL |
| 迁移管理  | 手动脚本         | Alembic自动迁移      |
| 并发写入  | 写锁阻塞         | MVCC无锁读、行级锁写     |
| 索引能力  | JSON无法索引     | 结构化字段可建索引        |

**K线数据表设计（核心优化）：**

```sql
-- K线数据表（按品种分区）
CREATE TABLE kline_data (
    id BIGSERIAL PRIMARY KEY,
    symbol VARCHAR(20) NOT NULL,
    period VARCHAR(10) NOT NULL,    -- 5min/15min/30min/60min/daily
    open_time TIMESTAMP NOT NULL,
    open DECIMAL(12,4),
    high DECIMAL(12,4),
    low DECIMAL(12,4),
    close DECIMAL(12,4),
    volume DECIMAL(18,4),
    amount DECIMAL(18,4),
    created_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(symbol, period, open_time)
);

-- 分区：按品种创建分区表
CREATE TABLE kline_data_ag PARTITION OF kline_data FOR VALUES IN ('AG');
CREATE TABLE kline_data_au PARTITION OF kline_data FOR VALUES IN ('AU');
-- ... 每个品种一个分区

-- 索引
CREATE INDEX idx_kline_symbol_period ON kline_data(symbol, period, open_time DESC);
```

**Redis缓存策略：**

```
# K线数据缓存 (TTL=300s)
kline:{symbol}:{period} → Hash { candles: [...], current_price, fetched_at }

# AI分析缓存 (TTL=900s)
ai_analysis:{symbol} → JSON { result, kline_timestamp, created_at }

# 刷新状态 (TTL=60s)
refresh:status:{symbol} → "running" | "done" | "error"

# 分布式锁
lock:refresh:{symbol} → 防止并发刷新同一品种
```

### 3.2 后端重构方案

#### 现状问题

* 服务层紧耦合，采集→缓存→分析链式调用

* AI调用使用同步requests阻塞事件循环

* 双数据库连接管理混乱

* 无统一错误处理、无中间件链

#### 方案：分层架构 + 异步优化 + 数据管道

```
┌─────────────────────────────────────────────────────────────┐
│                    API Gateway层                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐  │
│  │ 认证中间件│ │ 限流中间件│ │ 日志中间件│ │ CORS中间件    │  │
│  └──────────┘ └──────────┘ └──────────┘ └───────────────┘  │
└─────────────────────────────────────────────────────────────┘
                          │
┌─────────────────────────────────────────────────────────────┐
│                    API路由层 (模块化)                          │
│  ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────────────┐  │
│  │v1/auth  │ │v1/market│ │v1/analysis│ │v1/review        │  │
│  │(认证)   │ │(行情)   │ │(分析)     │ │(复盘+交易)      │  │
│  └────┬────┘ └────┬────┘ └────┬─────┘ └────────┬────────┘  │
└───────┼───────────┼───────────┼────────────────┼────────────┘
        │           │           │                │
┌───────┼───────────┼───────────┼────────────────┼────────────┐
│       │     服务层 (业务逻辑)  │                │             │
│  ┌────┴────┐ ┌────┴─────┐ ┌───┴──────┐ ┌──────┴─────────┐  │
│  │AuthSvc  │ │MarketSvc │ │AnalysisSvc│ │ReviewSvc       │  │
│  │         │ │          │ │           │ │                │  │
│  │- login  │ │- get_list│ │- ai_      │ │- generate_plan │  │
│  │- verify │ │- refresh │ │  analyze  │ │- import_trade  │  │
│  │- RBAC   │ │- kline   │ │- prepare  │ │- statistics    │  │
│  └─────────┘ │  _data   │ │  _data    │ │- trade_pairs   │  │
│              └────┬─────┘ │- cache_   │ └────────────────┘  │
│                   │       │  manage   │                      │
│              ┌────┴─────┐ └───────────┘                      │
│              │CollectSvc│                                     │
│              │- akshare │                                     │
│              │- batch   │                                     │
│              └──────────┘                                     │
└──────────────────────────────────────────────────────────────┘
        │           │           │
┌───────┼───────────┼───────────┼──────────────────────────────┐
│       │     基础设施层         │                               │
│  ┌────┴─────┐ ┌──┴───────┐ ┌─┴──────────┐ ┌──────────────┐  │
│  │PostgreSQL│ │  Redis   │ │AI Client   │ │Scheduler     │  │
│  │(SQLAlchemy│ │(aioredis)│ │(httpx async│ │(APScheduler  │  │
│  │ async)   │ │          │ │ + 重试)     │ │ or Celery)   │  │
│  └──────────┘ └──────────┘ └────────────┘ └──────────────┘  │
└──────────────────────────────────────────────────────────────┘
```

**关键改进：**

| 改进点   | 当前                       | 重构后                          |
| ----- | ------------------------ | ---------------------------- |
| 数据库连接 | 同步SQLAlchemy + 双引擎       | 异步SQLAlchemy + 统一引擎          |
| AI调用  | `requests.post()` (同步阻塞) | `httpx.AsyncClient` (异步非阻塞)  |
| 缓存    | SQLite TTL查询             | Redis + 本地LRU双层缓存            |
| 错误处理  | 各模块独立try/catch           | 全局异常中间件                      |
| 认证    | 自研Token                  | JWT (python-jose)            |
| 数据库迁移 | 手动脚本                     | Alembic                      |
| 配置管理  | .env + JSON文件            | Pydantic Settings + 统一配置     |
| 日志    | 基础logging                | structlog结构化日志               |
| 任务调度  | APScheduler线程池           | APScheduler(轻量) 或 Celery(重量) |

**缓存优化策略（三层缓存）：**

```
请求 → L1: 内存缓存 (TTLCache, 10s)
         ↓ miss
       L2: Redis缓存 (TTL 300s)
         ↓ miss
       L3: PostgreSQL数据库
         ↓ 回填L2
```

* **L1 内存缓存**：使用 `cachetools.TTLCache`，缓存热点数据（品种列表、配置），10秒过期

* **L2 Redis缓存**：K线数据、AI分析结果，按TTL策略过期

* **L3 数据库**：持久化存储，仅在缓存miss时访问

**AI分析异步化：**

```python
# 当前（阻塞）
response = requests.post(url, json=payload, timeout=180)

# 重构后（异步）
async with httpx.AsyncClient() as client:
    response = await client.post(url, json=payload, timeout=180)
```

### 3.3 前端重构方案

#### 现状问题

* 6300行单文件JS，无模块化

* 全局变量管理状态，易冲突

* 无构建工具，无法Tree-shaking/压缩

* 内联CSS + 外部CSS混用，样式不统一

* 两套主题(浅色/暗色)手动维护

#### 方案：保持原生JS + 引入模块化 + 统一设计系统

> **原则**：前端样式风格保持不变，系统功能不变。引入轻量级工程化改造，不引入重型框架。

```
┌──────────────────────────────────────────────────────┐
│                  前端架构                              │
│                                                      │
│  ┌────────────────────────────────────────────────┐  │
│  │              页面层 (HTML)                      │  │
│  │  login.html | futures_analysis.html | ...      │  │
│  └────────────────────┬───────────────────────────┘  │
│                       │                              │
│  ┌────────────────────┴───────────────────────────┐  │
│  │           模块层 (ES Modules)                   │  │
│  │                                                │  │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────────────┐  │  │
│  │  │api.js   │ │store.js │ │router.js        │  │  │
│  │  │(HTTP封装)│ │(状态管理)│ │(视图路由)       │  │  │
│  │  └─────────┘ └─────────┘ └─────────────────┘  │  │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────────────┐  │  │
│  │  │chart.js │ │theme.js │ │components.js    │  │  │
│  │  │(图表封装)│ │(主题管理)│ │(通用组件)       │  │  │
│  │  └─────────┘ └─────────┘ └─────────────────┘  │  │
│  │  ┌─────────────────────────────────────────┐  │  │
│  │  │ views/                                   │  │  │
│  │  │  ├── list-view.js    (品种列表)          │  │  │
│  │  │  ├── detail-view.js  (品种详情)          │  │  │
│  │  │  ├── watched-view.js (自选)              │  │  │
│  │  │  ├── review-view.js  (复盘计划)          │  │  │
│  │  │  └── trade-review.js (交易复盘)          │  │  │
│  │  └─────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────┘  │
│                       │                              │
│  ┌────────────────────┴───────────────────────────┐  │
│  │           样式层 (统一CSS变量)                   │  │
│  │                                                │  │
│  │  ┌──────────┐ ┌──────────┐ ┌───────────────┐  │  │
│  │  │variables │ │base.css  │ │components.css │  │  │
│  │  │.css      │ │(重置+基础)│ │(通用组件样式) │  │  │
│  │  │(设计Token)│ └──────────┘ └───────────────┘  │  │
│  │  └──────────┘                                  │  │
│  └────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────┘
```

**关键改进：**

| 改进点   | 当前          | 重构后                        |
| ----- | ----------- | -------------------------- |
| JS组织  | 单文件6300行    | ES Modules模块化(每模块200-500行) |
| 状态管理  | 全局变量        | 集中式Store(发布-订阅模式)          |
| 视图路由  | CSS类切换      | 轻量Router模块                 |
| API调用 | 分散的fetch    | 统一API封装(拦截器/错误处理)          |
| CSS   | 内联+外部混用     | CSS变量统一设计Token             |
| 主题    | 手动维护两套      | CSS变量切换(data-theme属性)      |
| 图表    | 直接调用ECharts | Chart模块封装(统一配置)            |
| 构建    | 无           | 可选Vite(开发热更新+生产压缩)         |

**目录结构规划：**

```
app/static/
├── index.html                  # 入口HTML
├── login.html
├── futures_analysis.html       # 主页面(精简HTML骨架)
├── css/
│   ├── variables.css           # 设计Token(颜色/字体/间距)
│   ├── base.css                # 重置+基础样式
│   ├── components.css          # 通用组件(按钮/卡片/模态框/表格)
│   ├── layout.css              # 布局(导航/侧边栏/网格)
│   └── views/
│       ├── list.css            # 品种列表页样式
│       ├── detail.css          # 详情页样式
│       ├── review.css          # 复盘页样式
│       └── trade-review.css    # 交易复盘页样式
├── js/
│   ├── app.js                  # 应用入口(初始化+路由)
│   ├── api.js                  # HTTP请求封装
│   ├── store.js                # 状态管理
│   ├── router.js               # 视图路由
│   ├── chart.js                # ECharts封装
│   ├── theme.js                # 主题管理
│   ├── components.js           # 通用组件(模态框/通知/加载)
│   ├── auth.js                 # 认证逻辑
│   └── views/
│       ├── list-view.js        # 品种列表视图
│       ├── detail-view.js      # 品种详情视图
│       ├── watched-view.js     # 自选视图
│       ├── review-view.js      # 复盘计划视图
│       └── trade-review.js     # 交易复盘视图
└── assets/
    └── (图标SVG等)
```

**Store状态管理示例：**

```javascript
// js/store.js - 轻量级状态管理
class Store {
    constructor() {
        this.state = {
            user: JSON.parse(localStorage.getItem('user_info') || 'null'),
            token: localStorage.getItem('auth_token'),
            theme: localStorage.getItem('futures-theme') || 'light',
            futures: { list: [], current: null, loading: false },
            watched: JSON.parse(localStorage.getItem('watched_symbols') || '[]'),
            review: { plans: [], current: null },
            trade: { records: [], batches: [], stats: null }
        };
        this.listeners = new Map();
    }

    on(key, callback) { /* 订阅状态变化 */ }
    set(key, value) { /* 更新状态 + 通知监听者 */ }
    get(key) { /* 获取状态 */ }
}

export const store = new Store();
```

***

## 第四部分：功能清单验证结果

### 4.1 验证方法

通过逐一阅读所有8个API路由文件源码，与前端JS代码中的API调用进行交叉比对，确认每个端点的存在性和完整性。

### 4.2 验证后的完整端点清单（共77个端点）

| 模块 | 前缀 | 端点数 | GET | POST | DELETE | PUT |
|------|------|--------|-----|------|--------|-----|
| 认证 | `/api/v1/auth` | 4 | 2 | 2 | 0 | 0 |
| 数据 | `/api/v1/data` | 5 | 4 | 1 | 0 | 0 |
| 任务 | `/api/v1/tasks` | 8 | 2 | 4 | 1 | 0 |
| 配置 | `/api/v1/config` | 4 | 1 | 3 | 0 | 0 |
| 期货分析 | `/api/v1/futures` | 19 | 10 | 6 | 1 | 1 |
| AI配置 | `/api/v1/ai-config` | 4 | 2 | 2 | 0 | 0 |
| 复盘计划 | `/api/v1/review` | 14 | 7 | 5 | 2 | 0 |
| 交易复盘 | `/api/v1/trade-review` | 12 | 9 | 2 | 2 | 0 |
| 页面路由 | `/` | 7 | 7 | 0 | 0 | 0 |
| **合计** | | **77** | **44** | **25** | **6** | **1** |

### 4.3 验证中发现的问题

| 编号 | 严重度 | 问题描述 | 影响 |
|------|--------|---------|------|
| V1 | **高** | 大部分API端点无认证保护：路由注册时未全局应用认证依赖，所有70个API端点可无认证访问 | 安全风险 |
| V2 | **高** | AI模型配置存在两套重复系统：`/api/v1/ai-config`（JSON文件存储）与 `/api/v1/futures/ai-models`（数据库存储）互不同步 | 数据不一致 |
| V3 | **中** | 前端调用了不存在的端点 `/api/v1/config/symbols`（index.html 第2047行），后端返回404 | 功能异常 |
| V4 | **中** | `review_plan.html` 页面无入口路由：main.py中未注册 `/review-plan` 路由，只能通过 `/static/review_plan.html` 访问且绕过认证 | 安全+可访问性 |
| V5 | **中** | `trade_review.py` 第394行引用 `from app.services.ai_analysis import AIAnalysisService`，但该类不存在（只有 `AIFuturesAnalyzer`），运行时报 ImportError | 功能异常 |
| V6 | **低** | 无速率限制：数据刷新和AI分析接口可能被频繁调用导致资源耗尽 | 稳定性风险 |
| V7 | **低** | CORS配置完全开放（`allow_origins=["*"]`） | 安全风险 |

### 4.4 与初版文档的差异

| 项目 | 初版 | 验证后 | 差异说明 |
|------|------|--------|--------|
| API端点总数 | 55+ | **70个API + 7个页面路由 = 77** | 逐一核实后数量更精确 |
| 期货分析模块端点 | 18 | **19** | 遗漏了 `POST /api/v1/futures/analysis/save` |
| 复盘计划模块端点 | 12 | **14** | 遗漏了 `POST /api/v1/review/plans/batch` 和 `GET /api/v1/review/summary/{id}` |
| 已知Bug | 0 | **5个(V1-V5)** | 深度验证发现 |

---

## 第五部分：编码规范

### 5.1 Python 编码规范

#### 基础规范
- **Python版本**：3.11+
- **代码格式化工具**：Ruff（替代 black + isort + flake8）
- **行宽**：最大 120 字符
- **缩进**：4 空格
- **编码**：UTF-8
- **类型注解**：所有函数签名必须包含类型注解

#### 命名规范
| 类型 | 规范 | 示例 |
|------|------|------|
| 文件名 | snake_case | `ai_analysis.py` |
| 类名 | PascalCase | `AIFuturesAnalyzer` |
| 函数/方法 | snake_case | `fetch_symbol_data()` |
| 常量 | UPPER_SNAKE_CASE | `CACHE_TTL_SECONDS` |
| 变量 | snake_case | `current_price` |
| 私有成员 | _前缀 | `_calc_macd()` |
| 模块级私有 | _前缀 | `_internal_helper()` |

#### 导入顺序（Ruff自动排序）
```python
# 1. 标准库
import json
import logging
from datetime import datetime
from typing import Dict, List, Optional

# 2. 第三方库
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session