Merge pull request #47 from akfamily/dev

feat(plot): 新增专业级可视化模块与交互式回测报告

Author: albertandking

.pre-commit-config.yaml

@@ -7,6 +7,7 @@ repos:
       - id: check-yaml
         args: [--unsafe]
       - id: check-added-large-files
+        args: ['--maxkb=1000']
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.14.14

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "akquant"
-version = "0.1.27"
+version = "0.1.28"
 edition = "2024"
 description = "High-performance quantitative trading framework based on Rust and Python"
 license = "MIT"

Cargo.toml

@@ -145,6 +145,25 @@ sqn                                     -0.743693
 kelly_criterion                         -0.080763
 ```
 
+## 可视化 (Visualization)
+
+AKQuant 内置了基于 **Plotly** 的强大可视化模块，仅需一行代码即可生成包含权益曲线、回撤分析、月度热力图等详细指标的交互式 HTML 报告。
+
+```python
+# 生成交互式 HTML 报告，自动在浏览器中打开
+result.report(title="我的策略报告", show=True)
+
+# 或者单独绘制仪表盘
+import akquant.plot as aqp
+aqp.plot_dashboard(result)
+```
+
+<p align="center">
+  <img src="assets/dashboard_preview.png" alt="Strategy Dashboard" width="800">
+  <br>
+  👉 <a href="https://akquant.akfamily.xyz/report_demo/">点击查看交互式报表示例 (Interactive Demo)</a>
+</p>
+
 ## 文档索引
 
 *   📖 **[核心特性与架构](docs/zh/index.md#核心特性)**: 了解 AKQuant 的设计理念与性能优势。

README.md

@@ -1,6 +1,53 @@
 # Backtest Results & Metrics
 
-This document details the performance metrics in AKQuant backtest results (`metrics_df`), including their meanings, units, and calculation methods.
+This document details the performance metrics in AKQuant backtest results (`metrics_df`), including their meanings, units, and calculation methods. It also covers the visualization capabilities for analyzing these results.
+
+## Visualization (Plotting)
+
+AKQuant provides a comprehensive visualization module to analyze backtest results. You can generate professional-grade interactive HTML reports or individual plots directly from the `BacktestResult` object.
+
+### Quick Start
+
+The easiest way to visualize your backtest results is using the `report()` method:
+
+```python
+# Generate a full HTML report
+result.report(
+    title="My Strategy Report",
+    filename="report.html",
+    show=True  # Set to True to open in browser automatically (default is False)
+)
+```
+
+This generates a consolidated dashboard including:
+- **Equity Curve**: Interactive chart of account equity over time.
+- **Drawdown**: Historical drawdown analysis.
+- **Monthly Heatmap**: Monthly return performance grid.
+- **Key Metrics**: A summary of important performance statistics.
+
+### Intraday Support (New)
+
+The plotting module automatically detects and adapts to intraday (minute-level) backtests:
+- **Smart Downsampling**: For large datasets (>10k points), it switches to WebGL rendering (`Scattergl`) for high performance.
+- **Adaptive X-Axis**: Automatically formats time labels (e.g., `%Y-%m-%d %H:%M`) and prevents label overlap.
+- **Adaptive Duration Units**: Trade duration analysis automatically switches units (Days, Hours, or Minutes) based on the strategy's average holding period.
+
+### Advanced Plotting
+
+You can also access individual plotting functions for more granular control:
+
+```python
+import akquant.plot as aqp
+
+# 1. Plot Dashboard (Equity, Drawdown, Heatmap)
+aqp.plot_dashboard(result)
+
+# 2. Analyze Trade Distribution (PnL vs Duration)
+aqp.plot_trades_distribution(result.trades_df)
+
+# 3. Analyze PnL vs Duration
+aqp.plot_pnl_vs_duration(result.trades_df)
+```
 
 ## Metrics Overview
 

assets/dashboard_preview.png

@@ -0,0 +1,5 @@
+# Interactive Backtest Report Demo
+
+Below is an interactive backtest report generated by AKQuant. You can interact directly with the charts on this page to view detailed backtest data.
+
+<iframe src="../../assets/reports/akquant_report.html" width="100%" height="1000px" frameborder="0" style="border: 1px solid #eee; border-radius: 4px;"></iframe>

docs/assets/reports/akquant_report.html

@@ -205,7 +205,7 @@ Instrument(
 
 **绩效指标详解 (Performance Metrics):**
 
-详细的绩效指标说明、单位及计算公式，请参考 **[绩效指标详解](metrics.md)**。
+详细的绩效指标说明、单位及计算公式，请参考 **[绩效指标详解](backtest_result.md)**。
 
 
 ## 6. 内置指标 (Indicators)

docs/en/backtest_result.md

@@ -156,3 +156,62 @@
 | `margin` | 占用保证金 | Float | 当前持仓占用的保证金。 |
 | `unrealized_pnl` | 未实现盈亏 | Float | 持仓浮动盈亏。 |
 | `entry_price` | 持仓均价 | Float | 当前持仓的平均成本价格。 |
+
+## 可视化 (Visualization)
+
+AKQuant 提供了强大的可视化工具，帮助用户直观地分析策略表现。
+
+### 快速开始 (Quick Start)
+
+最简单的方法是直接调用 `BacktestResult` 对象的 `report` 方法，它会生成一个包含所有关键图表的交互式 HTML 报告。
+
+```python
+# 生成完整的 HTML 报告
+result.report(
+    title="我的策略报告",
+    filename="report.html",
+    show=True  # 设为 True 以自动在浏览器中打开 (默认为 False)
+)
+```
+
+或者使用 `plot` 方法快速预览特定图表：
+
+```python
+# 绘制权益曲线
+result.plot(kind="equity")
+
+# 绘制月度热力图
+result.plot(kind="heatmap")
+```
+
+### 进阶绘图 (Advanced Plotting)
+
+对于更细粒度的控制，可以直接使用 `akquant.plot` 模块。
+
+```python
+import akquant.plot as aqp
+
+# 1. 绘制仪表盘 (权益, 回撤, 热力图)
+aqp.plot_dashboard(result)
+
+# 2. 分析交易分布 (盈亏 vs 持仓时间)
+aqp.plot_trades_distribution(result.trades_df)
+
+# 3. 绘制滚动指标 (夏普比率, 波动率)
+aqp.plot_rolling_metrics(result)
+
+# 4. 绘制年度回报
+aqp.plot_yearly_returns(result)
+
+# 5. 绘制每日回报分布
+aqp.plot_daily_returns_distribution(result)
+```
+
+### 日内回测支持 (Intraday Support)
+
+AKQuant 的绘图引擎会自动检测日内数据（如分钟级数据）并进行优化：
+
+*   **自适应 X 轴**: 自动调整时间刻度格式，避免标签重叠。
+*   **WebGL 加速**: 对于超过 10,000 个数据点的图表，自动切换到 WebGL 渲染以保证流畅度。
+*   **智能布局**: 动态调整子图间距，防止高频数据的标签遮挡。
+*   **自适应单位**: 交易分布图会自动根据平均持仓时间切换单位（天/小时/分钟）。