|
|
# 期货智析系统 - 架构分析与重构方案
|
|
|
|
|
|
> 文档版本：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
|
|
|
|
|
|
|
