etf/archive/visualization/report_generator/README.md

# ETF轮动策略报告生成器

生成精美的 HTML 策略报告，展示回测结果和关键指标。

## 功能特性

- ✅ **策略 KPI** - 累计收益、年化收益、胜率、夏普比率等
- ✅ **净值曲线** - 交互式折线图，支持缩放和悬停
- ✅ **月度收益** - 柱状图展示每月收益分布
- ✅ **盈亏分布** - 饼图展示盈利/亏损比例
- ✅ **品种排行** - 横向条形图展示各品种表现
- ✅ **调仓记录** - 可按日期和品种筛选的交易明细表格
- ✅ **现代化 UI** - 渐变色头部、卡片布局、响应式设计
- ✅ **打印友好** - 支持直接打印为 PDF

## 使用方法

### 基础用法

```bash
# 生成完整报告
python visualization/report_generator/generate_report.py

# 指定时间区间
python visualization/report_generator/generate_report.py --start 2024-01-01 --end 2024-12-31

# 指定输出目录
python visualization/report_generator/generate_report.py --output my_reports
```

### Python API 调用

```python
from visualization.report_generator.generate_report import ReportGenerator

# 创建生成器
generator = ReportGenerator(results_dir='results')

# 生成报告
output_file = generator.generate(
    start_date='2024-01-01',
    end_date='2024-12-31',
    output_dir='reports'
)

print(f"报告已生成: {output_file}")
```

### 定时生成（可选）

```bash
# 添加到 crontab，每天生成一次
0 9 * * * cd /path/to/etf && python visualization/report_generator/generate_report.py
```

## 依赖

```bash
pip install pandas numpy jinja2
```

## 文件结构

```
visualization/report_generator/
├── template.html          # HTML 模板
├── generate_report.py     # 报告生成脚本
└── README.md             # 说明文档
```

## 输出示例

生成的报告包含：

1. **头部区域** - 报告标题和数据区间
2. **KPI 卡片** - 8 个关键指标（收益、胜率、夏普比等）
3. **净值曲线** - 带渐变填充的折线图
4. **月度收益** - 红绿柱状图
5. **盈亏分布** - 环形饼图
6. **品种排行** - 横向条形图
7. **调仓表格** - 支持筛选和打印

## 自定义

### 修改配色方案

编辑 `template.html` 中的 CSS 变量：

```css
:root {
    --primary-color: #1890ff;
    --success-color: #52c41a;
    --danger-color: #ff4d4f;
}
```

### 添加新指标

在 `generate_report.py` 的 `calculate_kpis()` 方法中添加：

```python
def calculate_kpis(self, trades_filtered):
    # ... 现有代码 ...
    
    # 添加新指标
    new_metric = ...
    
    return {
        'total_return': ...,
        'new_metric': new_metric,  # 新增
        ...
    }
```

然后在模板中使用：

```html
<div class="kpi-value">{{ new_metric }}</div>
```

## 技术栈

- **模板引擎**: Jinja2
- **图表库**: ECharts 5.4
- **样式框架**: Bootstrap 5.3
- **图标**: Bootstrap Icons

## 注意事项

1. 确保 `results/report_summary.csv` 和 `results/report_trades.csv` 存在
2. 数据格式需符合预期（参考现有 CSV 文件）
3. 生成的 HTML 文件可离线查看（ECharts 使用 CDN）
4. 打印时筛选栏会自动隐藏

## 示例输出

```
🚀 开始生成策略报告...
✅ 数据加载成功: 1233 条交易记录
📊 筛选后数据: 1233 条记录
✅ 报告已生成: reports/strategy_report_20260508_210000.html
📁 文件大小: 125.3 KB
🌐 在浏览器中打开: file:///Users/aszer/Documents/vscode/etf/reports/strategy_report_20260508_210000.html
```