本项目是一个灵活、可扩展的投资分析工具集，旨在利用模块化的设计，为不同的投资分析策略提供支持。当前版本实现了股债利差分析的核心功能。
- 数据自动更新:
updater_stock.py: 从网络获取并更新指定股票的历史股价、股息率等信息。updater_treasury.py: 获取并更新中国国债收益率曲线数据。
- 核心分析计算:
calculator_spread.py: 基于最新的股票和国债数据，计算二者之间的利差（风险溢价）。
- 数据可视化:
visualizer_spread.py: 将计算出的利差、股价等信息生成清晰的可视化图表。
确保您的电脑已安装 Python 3 和 pip 包管理工具。
# 1. 克隆本项目到本地
git clone <your_repository_url>
cd investment_analysis
# 2. 安装项目所需的依赖库
pip install -r requirements.txt项目的所有配置项都集中在 common/config.py 文件中。在运行前，请务必进行以下配置：
-
设置API Token: 打开
common/config.py文件，找到TUSHARE_TOKEN配置项，并替换为您自己的 Tushare Pro 的真实 Token。Tushare 用于获取准确的股票股息率数据。# common/config.py # [updater_stock] tushare Pro 的 API token，用于获取分红等数据。请替换为自己的真实token。 TUSHARE_TOKEN = 'YOUR_REAL_TOKEN_HERE'
-
修改分析对象 (可选): 您可以修改
STOCK_CODE和STOCK_NAME来分析不同的股票。# common/config.py STOCK_CODE = "002807" # 要分析的股票代码 (例如: "600519" 对应贵州茅台) STOCK_NAME = "江阴银行" # 股票中文名 (用于图表标题)
-
其他配置:
FORCE_FULL_DATA_REFRESH: 默认为False，使用增量更 8000 模式，高效地获取最新数据。如果发现本地数据有损坏或缺失，可以将其设置为True，程序将强制从网络下载全量历史数据并与本地合并。DATA_START_DATE: 数据获取的起始日期，默认为 "1998-01-01"。
完成配置后，直接运行主程序即可：
python main/main_spread_analysis.py程序会自动执行数据更新、分析计算和图表生成的全过程。
分析完成后，所有的产出文件都保存在 visualizer/results/ 目录下：
{stock_code}_spread_analysis.csv: 详细的股债利差计算数据。{stock_code}_spread_plot_with_price.png: 包含股价走势和股债利差的综合图表。{stock_code}_spread_plot_standalone.png: 独立的股债利差走势图。
updater_stock.py 脚本不仅是自动化流程的一部分，也是一个功能强大的独立工具，负责获取和处理个股的各项历史数据。
为了确保股息率计算的准确性，脚本在处理 Tushare 返回的分红数据时采用了一套严谨的整合逻辑：
- 方案优选：对于同一财报期（
end_date）可能存在的多个分红方案（如"预案"、"股东大会通过"、"实施"），脚本会按照实施 > 股东大会通过 > 预案的优先级，自动筛选出唯一有效的方案。 - 年度汇总：在筛选出各期最有效的方案后，脚本会按 自然年份 进行加总，从而准确地将公司的中期分红和年度分红合并，得出年度总分红。
脚本会计算一个自定义的 "股息率(%)"，其核心逻辑是基于上一年度的总分红来计算当前股价下的回报率。
-
计算公式: 脚本依据以下公式计算股息率，其中考虑了送转股对分红的稀释效应。
静态股息率(%) = (调整后的每股分红 / 当前股价) * 100其中：
调整后的每股分红 = (每10股分红 / 10) / (1 + 每10股送转股数 / 10)当前股价：根据当前代码实现，采用的是每日的 开盘价。每10股分红: 根据当前代码实现，直接采用cash_div_tax字段。
-
严格的分红数据检查：脚本会严格检查上一年度是否有分红数据，如果没有，则将该交易日的股息率计为0，确保计算结果的可靠性。
您可以独立运行此脚本，来为指定的任意一支股票更新或生成历史数据文件。
# 例如，单独更新 招商银行(600036) 的数据
python updater/updater_stock.py --code 600036--code: 指定需要更新的股票代码。
运行成功后，最新的数据文件会保存在 data/auto/{股票代码}_history.csv。
在 common/config.py 文件中，您可以将 DEBUG_LOG_ENABLED 设置为 True。
# common/config.py
DEBUG_LOG_ENABLED = True开启后，在运行 updater_stock.py 时，脚本会在处理 最新一条 历史数据时，打印出详细的股息率计算步骤，方便您进行核对和调试。
investment_analysis/
│
├── main/
│ └── main_spread_analysis.py # <--- 股债利差分析的总入口
│
├── updater/
│ ├── updater_treasury.py # <--- 负责更新国债数据
│ └── updater_stock.py # <--- 负责更新股票数据
│
├── data/
│ ├── auto/ # <--- 存放由 updater 脚本自动下载和更新的数据
│ │ ├── treasury_bond_rates.csv
│ │ └── 002807_history.csv
│ └── hand/ # <--- 用于存放需要手动添加的原始数据 (当前为空)
│
├── visualizer/
│ ├── calculator_spread.py # <--- 股债利差计算器
│ ├── visualizer_spread.py # <--- 股债利差可视化工具
│ └── results/ # <--- 存放所有分析和可视化的结果
│ ├── 002807_spread_analysis.csv
│ └── 002807_spread_plot_with_price.png
│
├── common/
│ ├── config.py # <--- 所有模块的统一配置文件
│ └── utils.py # <--- 通用工具函数
│
├── requirements.txt # <--- 项目依赖
└── README.md # <--- 项目说明书 (本文件)
- 数据获取:
main脚本首先调用updater/中的脚本。这些脚本会从网络（如akshare,tushare）获取最新的国债和股票数据，并将其保存到data/auto/目录中。 - 数据读取:
visualizer/calculator_spread.py从data/auto/读取上一步生成的数据文件。 - 分析计算: 计算器完成利差分析后，将结果（一个
.csv文件）保存到visualizer/results/目录。 - 可视化:
visualizer/visualizer_spread.py读取visualizer/results/中的分析数据，生成图表（.png文件），并再次保存到该目录。
本项目的设计鼓励进行功能扩展。例如，要新增一个 "市盈率（PE）分析" 功能，您可以遵循以下步骤：
- 创建执行入口: 在
main/目录下创建main_pe_analysis.py。 - 创建数据获取器: 如果需要新的数据源（例如获取PE数据），在
updater/下创建对应的updater_pe_data.py。 - 创建分析器与可视化工具: 在
visualizer/目录下创建calculator_pe_analysis.py和visualizer_pe.py。 - 更新配置: 在
common/config.py中为新功能添加所需的所有配置项（如文件路径、参数等），并写好注释。 - 编写调度逻辑: 在
main_pe_analysis.py中，按顺序调用您新创建的updater,calculator和visualizer模块。 - 运行:
python main/main_pe_analysis.py。