财务报告自动化工具

生成季度股票表现报告，包含股息调整后的总回报率。

功能说明

• 解析 CSV 格式的价格数据（Yahoo Finance 导出格式）
• 计算价格回报率（基于原始收盘价）和总回报率（基于经股息调整的收盘价）
• 生成结构化季度报告：起始/结束价格、回报率、最高/最低价、平均成交量、已支付股息

关键修复（v1.0.1）

此前版本使用原始收盘价计算回报率，导致对 AAPL 等派息股票的回报率估算偏低。v1.0.1 引入以下改进：

1. 列名标准化 — 自动适配大小写混合的 CSV 表头（例如将 Date 统一为 date）
2. 调整后收盘价计算 — 基于股息进行历史价格反向调整，使总回报率准确反映股息再投资效果
3. 区分 price_return 与 total_return — 同时输出两项指标，确保透明性
4. 股息追踪支持 — dividend 列为可选；若缺失则默认为 0

使用方法

作为 Python 模块使用

from scripts.stock_analyzer import StockAnalyzer

analyzer = StockAnalyzer(data_path="finance/AAPL.csv")

# 30 日总回报率（含股息调整）
print(analyzer.calculate_returns(30))

# 仅 30 日价格回报率（不含股息）
print(analyzer.calculate_returns(30, use_adj=False))

# 生成完整季度报告
report = analyzer.generate_quarterly_report(quarter=2, year=2026)
print(report)

命令行接口（CLI）

python3 scripts/stock_analyzer.py

预期 CSV 格式

Date,Close,Volume,Open,High,Low
01/02/2026,$269.77,21755774,$272.05,$277.82,$269.11

可选列：

• dividend — 除息日每股派息金额
• adj_close — 预先计算好的调整后收盘价（若存在，则覆盖内部计算结果）

报告输出示例

{
  "quarter": "Q2 2026",
  "start_date": "2026-04-01",
  "end_date": "2026-06-30",
  "start_price": 223.0,
  "end_price": 235.5,
  "price_return_pct": 5.61,
  "total_return_pct": 6.12,
  "dividends_per_share": 0.25,
  "highest_price": 240.0,
  "lowest_price": 218.5,
  "average_volume": 35000000
}

依赖要求

• Python 3.10+
• pandas