# 设计方案调整
## 20260402
1. WeightBacktest 中的 dfw 参数名称改成 data，同时支持三种类型的输入
- pd.DataFrame
- pl.DataFrame / pl.LazyFrame
- file 路径（csv/feather/parquet/xlsx 四种常见格式）
2. 评估指标的优化（三大类：收益、风险、特质）
收益指标：
- 绝对收益
- 年化收益
- 夏普比率
- 卡玛比率
- 新高占比
- 单笔盈亏比 - 用pairs计算
- 单笔收益 - 用pairs计算
- 日胜率
- 周胜率
- 月胜率
- 季胜率
- 年胜率 - 细节：当年交易天数不到 yearly days 的一半，不计算这一年
风险指标：
- 最大回撤
- 年化波动率
- 下行波动率
- 新高间隔
特质指标：
- 交易次数 - 用pairs计算
- 年化交易次数 - 用pairs计算
- 持仓K线数 - 用pairs计算
- 交易胜率 - 用pairs计算
- 多头占比 - 用weight计算
- 空头占比 - 用weight计算
stats - 多空综合的评估指标
long_stats - 只看多头部分的评估指标
short_stats - 只看空头部分的评估指标
3. 新增 segment_stats 函数
s = segment_stats(sdt="20170101", edt="20190101", kind="多头/空头/多空")
按 sdt 和 edt 分别过滤 dailys 和 pairs，然后计算出 2 种的所有指标
4. 新增 long_alpha_stats 函数
将多头的日收益和基准的日收益，按目标年化波动率20%调整后，多头累计 - 基准累计 = 多头超额；
用 daily_performance 在多头超额上面计算指标
5. python/wbt 下面新增 plotting 模块，根据 weight backtest 的输出数据格式，绘制各种可视化图表
画图仅依赖 plotly
参考 czsc 库下面的 svc 模块和 utils/plotting 模块，需要仔细甑别哪些绘图函数是针对回测场景有效的。
可以先统一数据格式，然后根据统一的格式来绘制图表
## 20260403
1. 所有涉及到 stats 输出的函数，输出的字段顺序都按照以下方式（包括字段名称），这样人工可读性强
{'绝对收益': -8.9528,
'年化收益': -0.4117,
'夏普比率': -2.9296,
'卡玛比率': -0.0455,
'新高占比': 0.0011,
'单笔盈亏比': 0.927,
'单笔收益': -1.98,
'日胜率': 0.4226,
'周胜率': 0.3406,
'月胜率': 0.2541,
'季胜率': 0.0984,
'年胜率': 0.0,
'最大回撤': 9.0425,
'年化波动率': 0.1405,
'下行波动率': 0.0907,
'新高间隔': 2.0,
'交易次数': 7497492,
'年化交易次数': 344775.18,
'持仓K线数': 3.77,
'交易胜率': 0.5078,
'多头占比': 0.1575,
'空头占比': 0.84,
'品种数量': 5,
'开始日期': '2010-01-01',
'结束日期': '2025-01-01'}
2. segment_stats 中 sdt 和 edt 参数应该以 str 为主，兼容 timestamp 之类的格式，不要用 int
3. 在 wbt\python\scripts\quick_start.ipynb 中提供 plotting 函数的使用案例，并直接运行出来
## 20260517
从 czsc 库迁移 5 个常用函数到 wbt，并把可发布行为保持一致。
1. 业务逻辑全部下沉到 Rust（针对 Rust 核心 + Python 适配的两个函数），Python 侧只做 pandas ↔ Arrow IPC 格式适配；Rust 端的 warning 通过 `log` + `pyo3-log` 桥接到 Python `logging`，loguru 用户配一次 `InterceptHandler` 即可接管。
2. 模块组织：每个函数在 `python/wbt/utils/` 下独立一个 `.py` 文件，由 `utils/__init__.py` 汇总后再由顶层 `wbt/__init__.py` 透传。
3. 新增 API 清单：
| API | 来源 | 实现层 | 说明 |
|---|---|---|---|
| `cal_yearly_days(dts)` | `czsc.eda` | Rust core + Python adapter | 年度交易日数，跨度 <365 天时回退 252 并发 warning |
| `rolling_daily_performance(df, ret_col, window, min_periods, yearly_days)` | `czsc.utils.analysis.stats` | Rust core + Python adapter | 滚动窗口日度绩效；自动排序、NaN→0、自动推断 yearly_days |
| `weights_simple_ensemble(df, weight_cols, method, only_long)` | `czsc.eda` | 纯 Python | 多策略权重集成（mean / vote / sum_clip） |
| `cal_trade_price(df, digits, windows)` | `czsc.eda` | 纯 Python | TWAP / VWAP 与下根 K 线交易价表 |
| `log_strategy_info(strategy, df)` | `czsc.utils.log` | 纯 Python | 用 loguru 打印每个品种的权重摘要 |
4. 依赖变更：Rust 端新增 `log = "0.4"` + `pyo3-log = "0.13"`（兼容 pyo3 0.28）；Python 端新增 `loguru`。
5. 关键质量门：cargo test 142 / cargo clippy clean / pytest 230 / ruff clean / basedpyright clean。
6. 兼容性：所有改动是 additive，没有移除或重命名既有 API。
实施计划与逐 task review 记录见 `docs/superpowers/plans/2026-05-17-czsc-functions-migration.md`。