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线数据表设计（核心优化）：

-- 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分析异步化：

# 当前（阻塞）
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状态管理示例：

// 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自动排序）

# 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