DESIGN.md
# AI Quant 项目设计文档
## 1. 项目概述
### 1.1 项目背景
随着量化交易的快速发展，越来越多的投资者开始使用量化策略进行股票交易。然而，传统的量化交易平台往往过于复杂，需要专业的编程技能和金融知识，限制了普通投资者的使用。
AI Quant 项目旨在开发一个简单易用、功能强大的 A 股量化交易框架，帮助投资者快速构建和测试量化策略，并提供模拟交易和实盘交易功能。
### 1.2 项目目标
- 开发一个基于 VNpy 4.3.0 的 A 股量化交易框架
- 保留 A 股核心功能并优化架构
- 构建工业化可用的 A 股量化交易程序
- 实现自我测试、模拟测试、数据本地缓存和离线运行
- 全面优化架构、代码、文档，确保工业级稳定性
### 1.3 项目特色
- **三层架构设计**：核心接口层、服务引擎层、应用策略层
- **招商证券对接**：单独封装招商证券专属配置模板，简化配置参数
- **单票量化策略**：单独抽离，标准化入参/出参，仅负责单票分析
- **大模型推理**：独立插件式设计，预留 Ollama/FinGPT 接口
- **双模式运行**：支持控制台模式和图形界面模式
- **依赖管理优化**：添加依赖检查功能，自动检测并提示缺失的依赖包
- **模拟数据生成**：使用几何布朗运动模型生成更真实的股票价格序列
- **交易信号优化**：调整了交易信号的判断逻辑，降低了买入信号的门槛
## 2. 需求分析
### 2.1 功能需求
#### 2.1.1 核心功能
1. **招商证券对接**：提供招商证券接口配置和交易功能
2. **单票量化策略**：实现单只股票的量化分析和交易信号生成
3. **大模型推理**：提供大模型推理服务，用于股票分析和策略生成
4. **数据管理**：提供数据缓存和管理功能，支持离线运行
5. **模拟测试**：提供模拟交易功能，用于策略测试和验证
6. **实盘交易**：提供实盘交易功能，支持自动化交易
#### 2.1.2 辅助功能
1. **控制台模式**：提供控制台界面，支持命令行操作
2. **图形界面模式**：提供图形界面，支持可视化操作
3. **日志管理**：提供日志管理功能，记录程序运行过程
4. **配置管理**：提供配置管理功能，支持参数化配置
5. **依赖检查**：提供依赖检查功能，自动检测并提示缺失的依赖包
### 2.2 非功能需求
1. **可靠性**：确保程序运行稳定，避免崩溃和数据丢失
2. **性能**：确保程序运行高效，处理大量数据时不卡顿
3. **可维护性**：确保代码结构清晰，注释详细，便于维护和扩展
4. **可扩展性**：提供插件式架构，支持功能扩展和定制
5. **安全性**：确保程序安全运行，防止恶意攻击和数据泄露
## 3. 系统架构
### 3.1 三层架构设计
AI Quant 项目采用三层架构设计，各模块间通过统一接口通信，无跨模块强依赖。
#### 3.1.1 核心接口层 (core/)
核心接口层负责与外部系统对接，包括：
- **招商证券接口**：core/api/zs_sec.py，提供招商证券接口配置和交易功能
- **市场数据接口**：core/api/market.py，提供市场数据获取功能
- **交易接口**：core/api/trade.py，提供交易功能
- **工具模块**：core/utils/，提供通用工具函数
#### 3.1.2 服务引擎层 (service/)
服务引擎层负责业务逻辑处理，包括：
- **回测引擎**：service/backtest/，提供回测功能
- **风险控制引擎**：service/risk/，提供风险控制功能
- **数据管理引擎**：service/data/，提供数据缓存和管理功能
- **大模型推理引擎**：service/llm/，提供大模型推理功能
#### 3.1.3 应用策略层 (app/)
应用策略层负责策略实现和用户交互，包括：
- **单票量化策略**：app/strategy/single_stock.py，实现单只股票的量化分析和交易信号生成
- **控制台模式**：app/console/console.py，提供控制台界面
- **图形界面模式**：app/main/mainwindow.py，提供图形界面
- **策略配置**：app/config/，提供策略参数配置
### 3.2 模块依赖关系
各模块间通过统一接口通信，无跨模块强依赖。核心接口层为服务引擎层提供基础接口，服务引擎层为应用策略层提供业务逻辑支持。
## 4. 详细设计
### 4.1 核心接口层设计
#### 4.1.1 招商证券接口
**文件路径**：core/api/zs_sec.py
**功能描述**：提供招商证券接口配置和交易功能。
**核心类**：
1. **ZSSecConfig**：招商证券接口配置类，包含服务器地址、端口、账号、密码、经纪商代码等配置参数。
2. **ZSSecApi**：招商证券交易接口类，提供连接、登录、断开连接、发送订单、撤销订单、获取账户信息和持仓信息等功能。
**核心方法**：
```python
def connect(self) -> bool:
"""
连接服务器
Returns:
连接是否成功的布尔值
"""
def login(self) -> bool:
"""
登录账户
Returns:
登录是否成功的布尔值
"""
def disconnect(self) -> bool:
"""
断开连接
Returns:
断开连接是否成功的布尔值
"""
def send_order(
self,
symbol: str,
exchange: Exchange,
price: float,
volume: int,
direction: Direction,
offset: Offset,
order_type: OrderType = OrderType.LIMIT
) -> Optional[str]:
"""
发送订单
Args:
symbol: 股票代码
exchange: 交易所
price: 价格
volume: 数量
direction: 方向
offset: 开平类型
order_type: 订单类型
Returns:
订单 ID（如果成功），否则 None
"""
def cancel_order(self, order_id: str) -> bool:
"""
撤销订单
Args:
order_id: 订单 ID
Returns:
撤销是否成功的布尔值
"""
def get_account(self) -> Optional[Dict[str, Any]]:
"""
获取账户信息
Returns:
账户信息字典（如果成功），否则 None
"""
def get_positions(self) -> Optional[Dict[str, Any]]:
"""
获取持仓信息
Returns:
持仓信息字典（如果成功），否则 None
"""
```
#### 4.1.2 市场数据接口
**文件路径**：core/api/market.py
**功能描述**：提供市场数据获取功能。
**核心类**：
1. **MarketDataApi**：市场数据接口类，提供行情数据获取功能。
**核心方法**：
```python
def get_kline_data(
self,
symbol: str,
frequency: str = "d",
start_date: str = None,
end_date: str = None
) -> pd.DataFrame:
"""
获取 K 线数据
Args:
symbol: 股票代码
frequency: 频率
start_date: 起始日期
end_date: 结束日期
Returns:
K 线数据 DataFrame
"""
def get_tick_data(
self,
symbol: str,
start_date: str = None,
end_date: str = None
) -> pd.DataFrame:
"""
获取 tick 数据
Args:
symbol: 股票代码
start_date: 起始日期
end_date: 结束日期
Returns:
tick 数据 DataFrame
"""
```
#### 4.1.3 交易接口
**文件路径**：core/api/trade.py
**功能描述**：提供交易功能。
**核心类**：
1. **TradeApi**：交易接口类，提供交易功能。
**核心方法**：
```python
def send_order(
self,
symbol: str,
exchange: Exchange,
price: float,
volume: int,
direction: Direction,
offset: Offset,
order_type: OrderType = OrderType.LIMIT
) -> Optional[str]:
"""
发送订单
Args:
symbol: 股票代码
exchange: 交易所
price: 价格
volume: 数量
direction: 方向
offset: 开平类型
order_type: 订单类型
Returns:
订单 ID（如果成功），否则 None
"""
def cancel_order(self, order_id: str) -> bool:
"""
撤销订单
Args:
order_id: 订单 ID
Returns:
撤销是否成功的布尔值
"""
```
### 4.2 服务引擎层设计
#### 4.2.1 回测引擎
**文件路径**：service/backtest/
**功能描述**：提供回测功能。
**核心类**：
1. **BacktestEngine**：回测引擎类，提供回测功能。
**核心方法**：
```python
def run_backtest(
self,
strategy: str,
symbol: str,
start_date: str,
end_date: str,
initial_capital: float = 1000000.0
) -> Dict[str, Any]:
"""
运行回测
Args:
strategy: 策略名称
symbol: 股票代码
start_date: 起始日期
end_date: 结束日期
initial_capital: 初始资金
Returns:
回测结果字典
"""
```
#### 4.2.2 风险控制引擎
**文件路径**：service/risk/
**功能描述**：提供风险控制功能。
**核心类**：
1. **RiskControlEngine**：风险控制引擎类，提供风险控制功能。
**核心方法**：
```python
def check_risk(self, order: Dict[str, Any]) -> bool:
"""
检查风险
Args:
order: 订单信息
Returns:
风险检查是否通过的布尔值
"""
```
#### 4.2.3 数据管理引擎
**文件路径**：service/data/
**功能描述**：提供数据缓存和管理功能。
**核心类**：
1. **DataCache**：数据缓存管理器类，提供数据缓存和管理功能。
**核心方法**：
```python
def save(self,
symbol: str,
data: pd.DataFrame,
frequency: str = "d",
start_date: str = None,
end_date: str = None) -> str:
"""
保存数据到缓存
Args:
symbol: 股票代码
data: 数据
frequency: 频率
start_date: 起始日期
end_date: 结束日期
Returns:
缓存文件路径
"""
def load(self,
symbol: str,
frequency: str = "d",
start_date: str = None,
end_date: str = None) -> pd.DataFrame:
"""
从缓存加载数据
Args:
symbol: 股票代码
frequency: 频率
start_date: 起始日期
end_date: 结束日期
Returns:
加载的数据
"""
def exists(self,
symbol: str,
frequency: str = "d",
start_date: str = None,
end_date: str = None) -> bool:
"""
检查缓存是否存在
Args:
symbol: 股票代码
frequency: 频率
start_date: 起始日期
end_date: 结束日期
Returns:
缓存是否存在
"""
def delete(self,
symbol: str,
frequency: str = "d",
start_date: str = None,
end_date: str = None) -> bool:
"""
删除缓存
Args:
symbol: 股票代码
frequency: 频率
start_date: 起始日期
end_date: 结束日期
Returns:
删除是否成功
"""
```
2. **MockDataGenerator**：模拟数据生成器类，提供模拟数据生成功能。
**核心方法**：
```python
def generate_random_kline_data(
symbol: str,
start_date: str = "2023-01-01",
end_date: str = "2023-12-31",
frequency: str = "d",
volatility: float = 0.01,
trend: float = 0.0015
) -> pd.DataFrame:
"""
生成随机 K 线数据
Args:
symbol: 股票代码
start_date: 起始日期
end_date: 结束日期
frequency: 频率（d: 日线，h: 小时线，m: 分钟线）
volatility: 波动率
trend: 趋势强度
Returns:
生成的 K 线数据 DataFrame
"""
```
#### 4.2.4 大模型推理引擎
**文件路径**：service/llm/
**功能描述**：提供大模型推理功能。
**核心类**：
1. **LLMInferenceService**：大模型推理服务类，提供大模型推理功能。
**核心方法**：
```python
def infer(self, prompt: str, temperature: float = 0.7, max_tokens: int = 512) -> Optional[str]:
"""
执行大模型推理
Args:
prompt: 推理提示
temperature: 推理温度
max_tokens: 最大生成 tokens 数
Returns:
推理结果字符串（如果成功），否则 None
"""
def analyze_stock_data(self, symbol: str, data: Dict[str, Any]) -> Optional[str]:
"""
分析股票数据（专业方法）
Args:
symbol: 股票代码
data: 股票数据
Returns:
分析结果字符串（如果成功），否则 None
"""
def generate_strategy(self, conditions: Dict[str, Any]) -> Optional[str]:
"""
生成交易策略（专业方法）
Args:
conditions: 策略条件
Returns:
策略代码字符串（如果成功），否则 None
"""
```
### 4.3 应用策略层设计
#### 4.3.1 单票量化策略
**文件路径**：app/strategy/single_stock.py
**功能描述**：实现单只股票的量化分析和交易信号生成。
**核心类**：
1. **SingleStockAnalyzer**：单票量化分析器类，提供单只股票的量化分析功能。
**核心方法**：
```python
def analyze(self, symbol: str, kline_data: pd.DataFrame) -> "StockAnalysisResult":
"""
分析股票数据
Args:
symbol: 股票代码
kline_data: K 线数据
Returns:
股票分析结果
"""
```
2. **StockAnalysisResult**：股票分析结果类，包含股票代码、综合评分、标的等级、交易信号和关键指标等信息。
#### 4.3.2 控制台模式
**文件路径**：app/console/console.py
**功能描述**：提供控制台界面，支持命令行操作。
**核心类**：
1. **ConsoleMode**：控制台模式类，提供控制台界面。
**核心方法**：
```python
def run(self):
"""
运行控制台模式
"""
```
#### 4.3.3 图形界面模式
**文件路径**：app/main/mainwindow.py
**功能描述**：提供图形界面，支持可视化操作。
**核心类**：
1. **MainWindow**：图形界面主窗口类，提供图形界面。
## 5. 测试计划
### 5.1 测试目标
- 验证项目核心功能是否正常运行
- 验证项目架构是否稳定
- 验证项目代码是否符合规范
- 验证项目性能是否满足要求
### 5.2 测试内容
#### 5.2.1 单元测试
- 测试核心接口层的接口是否正常工作
- 测试服务引擎层的业务逻辑是否正确
- 测试应用策略层的策略是否有效
#### 5.2.2 集成测试
- 测试各模块间的交互是否正常
- 测试系统整体功能是否满足需求
#### 5.2.3 性能测试
- 测试系统处理大量数据时的性能
- 测试系统响应时间是否满足要求
#### 5.2.4 安全测试
- 测试系统是否存在安全漏洞
- 测试系统是否符合安全标准
### 5.3 测试方法
- **手动测试**：通过控制台模式和图形界面模式进行测试
- **自动化测试**：使用 pytest 进行自动化测试
- **性能测试**：使用 locust 进行性能测试
### 5.4 测试工具
- **pytest**：用于单元测试和集成测试
- **locust**：用于性能测试
- **flake8**：用于代码质量检查
### 5.5 测试报告
测试报告将包含以下内容：
- 测试目的
- 测试环境
- 测试内容
- 测试结果
- 测试结论
- 建议
## 6. 部署计划
### 6.1 部署环境
- **操作系统**：Linux（推荐 CentOS 7 或 Ubuntu 18.04）
- **Python 版本**：Python 3.8+
- **依赖包**：参考 requirements.txt
### 6.2 部署步骤
1. 克隆项目代码
2. 安装依赖包
3. 配置招商证券接口参数
4. 启动程序
### 6.3 部署方式
- **控制台模式**：使用命令行启动
- **图形界面模式**：使用桌面环境启动
## 7. 维护计划
### 7.1 维护目标
- 确保项目持续稳定运行
- 及时修复 bug 和安全漏洞
- 定期更新项目功能
- 提供技术支持
### 7.2 维护内容
- 代码维护：修复 bug 和安全漏洞
- 功能更新：添加新功能和优化现有功能
- 文档更新：更新项目文档
- 技术支持：提供技术支持和培训
### 7.3 维护流程
- 问题报告：用户提交问题报告
- 问题分析：分析问题原因
- 问题修复：修复问题
- 测试验证：测试修复后的功能
- 发布更新：发布更新版本
## 8. 总结
AI Quant 项目是一个基于 VNpy 4.3.0 的 A 股量化交易框架，采用三层架构设计，保留了 A 股核心功能并优化了架构。项目提供了招商证券对接、单票量化策略、大模型推理、数据管理、模拟测试和实盘交易等功能，支持控制台模式和图形界面模式。
项目架构清晰，代码质量高，所有模块都添加了详细的中文注释，确保了工业级的稳定性。项目还提供了完整的测试计划和部署计划，便于项目的维护和扩展。