系统设计与开发者文档

本文档为量化交易系统的核心开发者提供全面的技术参考，涵盖了系统架构、核心模块、API接口、部署运维以及未来的发展规划。

1. 系统架构

本系统采用模块化设计，主要由数据层、分析层、策略层和应用层组成。

1.1. 核心模块

main.py: 自选股分析流程的入口。
recommendation_system.py: AI智能推荐流程的入口。
health_check.py: Flask应用的入口，提供 /health 和 /run API端点。
src/: 包含所有核心逻辑的目录。
- config.py: 集中管理所有配置。
- data_loader.py (DataLoader): 负责从akshare获取数据并存入数据库。
- db.py (DatabaseManager): 管理SQLite数据库。
- analysis_engine.py (AnalysisEngine): 负责计算技术指标。
- gemini_analyzer.py (GeminiAnalyzer): 与Gemini API交互，进行AI分析。
- strategy_engine.py (StrategyEngine): 核心策略模块，汇总分析并生成信号。
- market_regime.py (MarketRegime): 判断市场宏观状态（牛/熊/震荡）。
- logger.py: 提供统一的日志服务。
send_email.py: 生成HTML邮件报告并发送。

1.2. 数据流

数据获取: DataLoader 从 akshare 获取数据。
数据存储: DatabaseManager 将数据存入SQLite数据库 (data/stock_data.db)。
市场状态判断: MarketRegime 分析市场指数，确定宏观环境。
技术分析: AnalysisEngine 基于历史数据计算技术指标。
AI分析: GeminiAnalyzer 调用Gemini API获取基本面和消息面分析。
策略决策: StrategyEngine 结合所有分析结果，并根据市场状态动态调整权重，生成最终决策。
结果输出: 通过日志、邮件 (send_email.py) 和API (health_check.py) 输出。

2. 策略、评分与决策体系 (V3)

本量化交易系统的核心决策逻辑，通过对技术面、基本面和AI市场情绪面三个维度进行独立的量化评分，并结合市场状态动态加权，最终生成交易信号。

2.0. A股总分计算逻辑

对于A股，系统采用动态加权模型计算总分，取代了旧版的简单分数相加。

分数归一化: 将技术面（满分50）、基本面（满分35）、情绪面（满分25）的原始得分，分别归一化到 [-1, 1] 的区间内。
应用动态权重: 根据当前市场状态（波动率、成交量）计算出动态权重（例如，趋势行情下技术面权重更高），然后对归一化后的分数进行加权求和。
映射回百分制: 将加权后的分数重新映射回 [-100, 100] 的范围，作为最终总分。

动态权重调整

系统会根据市场的微观状态（通过ATR判断的波动率和通过均量线判断的成交量）对基础权重进行动态微调：

高波动 & 放量 (趋势行情): 提升技术面权重，降低基本面和情绪面权重。
低波动 & 缩量 (盘整行情): 降低技术面权重，提升基本面权重。

最终决策阈值

坚定买入: 总分 >= 40
推荐买入: 总分 >= 30
维持仓位: 总分 >= 20
谨慎持有: 总分 > -5
推荐卖出: 总分 > -20
坚定卖出: 总分 <= -20

2.1. ETF评分体系（指数基金/ETF专用）

技术面：50分（均线、成交量、波动率等为主，弱化KDJ等短线指标）
AI消息面：50分（重点关注资金流向、申购赎回、行业轮动、指数调整等）
基本面：恒为0分（ETF不参与基本面打分）

总分 = 技术面得分（归一化到50分） + AI消息面得分（归一化到50分）

归一化方法：技术面满分已更新为50分，因此不再需要额外乘区。AI消息面原始得分(满分10) / 10 * 50。
ETF决策流程与A股一致，但分数分布和信号解释更侧重资金流和行业轮动。

2.2. 技术面分析 (V3, 总分: 50分)

技术面分析旨在捕捉市场的短期趋势和动量。它由五个核心指标构成，各自有独立的评分和权重。

指标	权重	触发条件 (优先级由上到下)	得分
MACD趋势	15分	看涨金叉 (DIF上穿DEA，且DIF>0)	+15
		看跌死叉 (DIF下穿DEA，且DIF<0)	-15
		多头排列 (DIF>DEA)	+8
		空头排列 (DIF<DEA)	-8
RSI动量	10分	RSI上穿50中轴 (强动量信号)	+10
		RSI下穿50中轴 (强动量信号)	-10
		RSI < 30 (超卖区)	+8
		RSI > 70 (超买区)	-8
		RSI < 40 (偏弱)	+4
		RSI > 60 (偏强)	-4
布林带	8分	价格触及下轨	+8
		价格触及上轨	-8
		价格在中轨下方	+3
		价格在中轨上方	-3
KDJ指标	7分	KDJ超卖 (K<20, D<20)	+7
		KDJ超买 (K>80, D>80)	-7
		KDJ金叉 (K>D)	+3
		KDJ死叉 (K<D)	-3
成交量	10分	趋势显著放量 (MA5 > MA20*1.2)	+5
		趋势温和放量 (MA5 > MA20)	+2
		趋势显著缩量 (MA5 < MA20*0.8)	-5
		当日巨量 (Vol > MA20*2.0)	+5
		当日放量 (Vol > MA20*1.5)	+2

最终报告形式: 技术面得分: [总分] | 原因: [综合原因] (MACD: [得分], RSI: [得分], 布林带: [得分], KDJ: [得分], 成交量: [得分])

2.3. 基本面分析 (总权重: 35分)

基本面分析旨在评估资产的内在价值。它由三个核心估值指标构成，以适应不同类型的投资标的。

1. 市盈率 (PE) - (权重: 15分)

数据来源: Akshare实时接口。对于ETF，则自动获取其跟踪指数的PE。
评分标准:
- PE < 15: +15分 (估值低)
- 15 <= PE < 30: +8分 (估值合理)
- 30 <= PE < 50: -8分 (估值偏高)
- PE >= 50: -15分 (估值过高)

2. 市净率 (PB) - (权重: 12分)

数据来源: Akshare实时接口。对于ETF，则自动获取其跟踪指数的PB。
评分标准:
- PB < 1.5: +12分 (估值低)
- 1.5 <= PB < 3: +6分 (估值合理)
- 3 <= PB < 5: -6分 (估值偏高)
- PB >= 5: -12分 (估值过高)

3. 股息率 (Dividend Yield) - (权重: 8分)

数据来源: Akshare实时接口。
评分标准:
- 股息率 > 4%: +8分 (高股息)
- 2% < 股息率 <= 4%: +4分 (股息尚可)
- 股息率 <= 2%: -8分 (股息较低)

评分平衡性: 正向分数总和 = 负向分数总和 = 35分

正向: 15 + 12 + 8 = 35分
负向: (-15) + (-12) + (-8) = -35分

最终报告形式: 基本面得分: [总分] | 原因: [综合原因] (PE: [得分], PB: [得分], DY: [得分])

2.4. AI市场情绪面分析 (总权重: 25分)

本部分利用Gemini的联网搜索和分析能力，对最新的市场新闻和公告进行情绪量化。

执行方式: 向Gemini API发送一个包含股票名称和代码的Prompt。
返回格式: 要求Gemini返回一个包含以下字段的JSON对象：
- sentiment_score: 一个从 -10 (极度利空) 到 +10 (极度利好) 的量化分数。
- sentiment_reason: 一句话总结的核心判断原因。
- key_factors: 1-3个影响判断的关键事件列表。
- data_date: 关键信息的最新日期。
分数换算: Gemini返回的 sentiment_score将乘以 2.5，以匹配本项 25分 的总权重。

最终报告形式: AI消息面得分: [总分] | 原因: [AI总结的原因] (数据更新至: [日期]) 关键因素: [AI识别的关键事件]

2.7. 实现状态与验证

状态: 已完成 (As of 2025-08-17)

技术面评分 (V3, 2.2节): strategy_engine.py 中的逻辑已通过 _calculate_technical_score 函数完全实现，并通过 tests/test_scoring_logic.py 中的 test_technical_scoring_detailed 单元测试验证。V3版更新了RSI趋势判断和成交量评分体系。
动态权重与总分计算: A股的动态加权和总分计算逻辑已在 _get_dynamic_weights 和 _calculate_score 中实现，并通过 test_dynamic_weight_adjustment 和 test_calculate_score_with_dynamic_weights 验证。
基本面评分 (2.3节): strategy_engine.py 中的逻辑已通过 _calculate_fundamental_score 函数完全实现，并通过 tests/test_fundamental_scoring.py 单元测试验证。

核心评分逻辑已实现模块化，与本文档描述的设计完全对齐。

2.5. 新增技术指标

系统现已支持更多A股常用的技术指标：

1. 布林带 (Bollinger Bands)

计算方式: 20日移动平均线 ± 2倍标准差
应用: 判断价格波动区间和超买超卖状态

2. KDJ指标

计算方式: 基于9日RSV的随机指标
应用: 判断超买超卖和买卖时机

3. 成交量指标

计算方式: 5日和10日成交量移动平均
应用: 分析量价关系和资金流向

4. ATR (平均真实波幅)

计算方式: 14日真实波幅移动平均
应用: 衡量市场波动性和设置止损位

5. 威廉指标 (Williams %R)

计算方式: 基于14日最高最低价的动量指标
应用: 判断超买超卖状态

2.6. 最终决策报告与日志

系统在完成对所有股票的分析后，会生成一份聚合的决策报告表格，清晰地展示所有目标的分析结果。

1. 单只股票分析过程输出

在分析过程中，系统会为每只股票打印一行简要的完成信息，如下所示：

--- 正在分析股票: 贵州茅台 (600519.SH) ---
  分析完成: 贵州茅台 (600519.SH) - 总分:  65 | 最终信号: 【买入】
----------------------------------------

2. 最终聚合报告

所有股票分析完成后，系统会打印一个统一的表格，汇总所有决策报告，方便横向对比。

聚合报告表示例:

股票名称     | 代码       |   技术面得分 |   基本面得分 |   AI消息面得分 |  总分 | 最终决策 | 类型
------------------------------------------------------------------------------------------------------------------
贵州茅台     | 600519.SH  |          -5 |           17 |             -8 |    4 | 【谨慎持有】 | A股
平安银行     | 000001.SZ  |           25 |           15 |             12 |   52 | 【买入】     | A股
沪深300ETF  | 510300.SH  |           32 |            0 |             30 |   62 | 【买入】     | ETF

3. 决策等级说明

重仓买入 (紫色): 总分 >= 80，强烈推荐买入信号
买入 (绿色): 总分 >= 60，推荐买入信号
持有 (黄色): 总分 >= 20，建议持有观望
谨慎持有 (青色): 总分 >= -10，建议谨慎持有或减仓
卖出 (红色): 总分 < -10，建议卖出信号

ETF决策等级说明

重仓买入：总分 ≥ 80
买入：总分 ≥ 50
持有：总分 ≥ 30
谨慎持有：总分 ≥ 10
卖出：总分 < 10

注：ETF波动性低，建议结合资金流向和行业轮动信号综合判断。

4. 日志文件

对于有明确 买入/重仓买入 或卖出信号的股票，详细的决策依据会被记录在 logs/trade_signals_YYYY-MM-DD.log 文件中，供后续复盘。

日志格式示例:

Signal for 贵州茅台 (600519.SH) on 2025-01-13: 【买入】
  - Tech: 15 (MACD看涨金叉, RSI(45.2)偏弱) (MACD: 15, RSI: 5, 布林带: 3, KDJ: -3)
  - Fundamentals: 17 (PE: PE=25.30, 估值合理, PB: PB=8.50, 估值过高, 股息率: 股息率=1.20%, 股息较低) (PE: 8, PB: -8, DY: 0)
  - AI Sentiment: -8 (市场情绪偏谨慎) (Data until: 2025-01-13) 关键因素: 白酒行业政策调整, 消费需求变化
  - TOTAL SCORE: 24

ETF决策报告示例

--- 正在分析ETF: 沪深300ETF (510300.SH) ---
  分析完成: 沪深300ETF (510300.SH) - 总分:  62 | 最终信号: 【买入】
  - 技术面: 32（均线多头排列，成交量放大）
  - 基本面: 0（ETF不参与基本面打分）
  - AI消息面: 30（资金净流入，行业轮动利好）
----------------------------------------

3. API接口说明

服务启动后，可以通过HTTP请求与系统交互。

3.1. 健康检查

Endpoint: GET /health
功能: 检查服务是否正常运行。
返回: {"status": "ok", "msg": "service is healthy"}

3.2. 触发分析任务

Endpoint: GET /run
功能: 触发一次完整的分析流程。
查询参数:
- codes (可选, string): 指定一个或多个股票代码（用逗号分隔），仅分析这些股票。如果未提供，则执行“自选股+AI推荐”的完整流程。
请求示例:
- 触发完整流程: curl "http://127.0.0.1:5000/run"
- 分析指定股票: curl "http://127.0.0.1:5000/run?codes=600519.SH,000001.SZ"
返回:
- 成功时返回分析结果的JSON。
- 失败时返回 {"status": "fail", "msg": "错误信息"}。

4. 配置说明

所有配置项均位于 src/config.py，并支持通过环境变量覆盖。

核心配置:
- GEMINI_API_KEY: Gemini的API密钥。
- STOCK_POOL: 自选股股票池。
- ETF_TO_INDEX_MAP: ETF与对应指数的映射。
邮件配置:
- ENABLE_EMAIL_SENDING: 邮件发送总开关。
- SMTP_SERVER, EMAIL_ADDRESS, EMAIL_PASSWORD, RECIPIENT_EMAIL: 邮箱参数。
评分权重:
- TECHNICAL_WEIGHTS, FUNDAMENTAL_WEIGHTS, SENTIMENT_WEIGHT: 各维度权重。
- MARKET_REGIME_WEIGHTS: 不同市场状态下的权重动态调整配置。
决策阈值:
- DECISION_THRESHOLDS: 定义买入、卖出、持有等决策的分数线。

5. 部署与运维

5.1. Docker部署 (推荐)

创建 .env 文件: 在项目根目录创建 .env 文件，并填入环境变量（如 GEMINI_API_KEY）。
构建镜像:
```
docker build -t quant-trading .
```

运行容器:

docker run -d -p 5000:5000 --env-file .env quant-trading

5.2. 本地直接运行

安装依赖:
```
pip install -r requirements.txt
```
配置环境变量 或直接修改 src/config.py。
启动服务:
```
python health_check.py
```

5.3. 自动化任务

Linux: 使用 crontab 定时调用 /run 接口。
Windows: 使用“任务计划程序”定时执行curl命令或Python脚本。

6. 项目路线图 (Roadmap)

本文档规划了系统未来的主要开发方向，旨在将其从一个选股分析工具，演进为一个功能完备的综合性量化平台。

第一阶段：技术架构优化 (已完成)

性能优化: 引入并发处理，并行获取和分析股票。
成本与效率优化: 增加基于缓存的AI分析结果复用。
架构优化: 改造API为异步模式，提供任务状态查询接口。
数据管理优化: 实现股票数据的增量更新和数据库索引。

第二阶段：功能与策略优化 (已完成)

功能完备性增强:
- 引入回测框架 (BacktestingEngine)。
- 引入投资组合与风险管理 (PortfolioManager)。
量化策略深度优化:
- 引入市场状态机 (MarketRegime)，实现权重动态调整。
- 深化AI模型应用（情绪时序分析、AI因子挖掘、因果推断）。

第三阶段：平台化与智能化 (规划中)

实盘交易集成: 对接主流券商（如华泰、同花顺）的实盘交易API，实现从信号生成到自动下单的交易闭环。
策略市场与回测平台:
- 开发一个可视化的策略回测界面。
- 允许用户通过Web界面创建、修改和回测自己的量化策略。
交互式Web仪表盘:
- 使用Streamlit或Dash/Plotly创建一个丰富的Web界面。
- 展示持仓分析、收益曲线、风险指标、市场状态等。
深度学习模型引入:
- 探索使用LSTM、Transformer等模型进行股价短期趋势预测。
- 将预测结果作为一个新的评分因子整合进StrategyEngine。
事件驱动策略:
- 监控新闻、公告、财报发布等事件。
- 开发基于特定事件（如业绩预增、高管增持）的交易策略。

系统设计与开发者文档#

1. 系统架构#

1.1. 核心模块#

1.2. 数据流#

2. 策略、评分与决策体系 (V3)#

2.0. A股总分计算逻辑#

动态权重调整#

最终决策阈值#

2.1. ETF评分体系（指数基金/ETF专用）#

2.2. 技术面分析 (V3, 总分: 50分)#

2.3. 基本面分析 (总权重: 35分)#

1. 市盈率 (PE) - (权重: 15分)#

2. 市净率 (PB) - (权重: 12分)#

3. 股息率 (Dividend Yield) - (权重: 8分)#

2.4. AI市场情绪面分析 (总权重: 25分)#

2.7. 实现状态与验证#

2.5. 新增技术指标#

1. 布林带 (Bollinger Bands)#

2. KDJ指标#

3. 成交量指标#

4. ATR (平均真实波幅)#

5. 威廉指标 (Williams %R)#

2.6. 最终决策报告与日志#

1. 单只股票分析过程输出#

2. 最终聚合报告#

3. 决策等级说明#

ETF决策等级说明#

4. 日志文件#

ETF决策报告示例#

3. API接口说明#

3.1. 健康检查#

3.2. 触发分析任务#

4. 配置说明#

5. 部署与运维#

5.1. Docker部署 (推荐)#

5.2. 本地直接运行#

5.3. 自动化任务#

6. 项目路线图 (Roadmap)#

第一阶段：技术架构优化 (已完成)#

第二阶段：功能与策略优化 (已完成)#

第三阶段：平台化与智能化 (规划中)#