# EPCMBot 项目进度看板

最后核对时间：`2026-03-18`

## 1、文档目的与维护规则

这份文档是协作者的项目进度面板，不是尚未执行的实现草案。核心目标是让任何协作者在 3 分钟内看清三件事：

1. 我们已经交付了什么
2. 当前存在哪些限制
3. 下一步最该做什么

维护规则：

- 更新时机：功能合并后、接口发生变化后、测试/覆盖率显著变化后。
- 「**已完成**」定义：代码中可定位到实现路径，且至少有自动化验证（测试或静态检查）支撑。
- 「**待优化扩展**」定义：和当前架构直接相关、可在后续版本落地的增强项，不写空泛愿景。

## 2、项目现状快照

### 2.1、能力矩阵

| 子系统 | 状态 | 现状 |
|---|---|---|
| 本地数据加载与协议校验 | ✅ 已完成 | 支持 CSV/Parquet，校验字段、时间顺序、秒级粒度、价格合法性。 |
| 特征工程与目标构造 | ✅ 已完成 | 已实现盘口失衡、订单流、VWAP 偏离、3 秒前瞻收益目标。 |
| 滚动训练与调参 | ✅ 已完成 | 带 purge 的 walk-forward；CatBoost + Optuna；GMADL 与 R²双轨评估。 |
| SHAP 可解释性 | ✅ 已完成 | 输出重要性表与 top feature 依赖数据。 |
| 回测引擎 | ✅ 已完成 | Taker/Maker/Combined 三套回测逻辑可执行。 |
| 风险报告 | ⚠️ 部分完成 | 风险条目输出已完成，但缺少风险模块专项自动化测试。 |
| CLI 与结果落盘 | ✅ 已完成 | `epcmbot` 支持摘要输出与 artifacts 落盘。 |
| 离线构数工具 | ✅ 已完成 | `epcmbot-build-dataset` 可从 Binance 历史数据生成协议化 1 秒数据。 |
| 测试夹具与主测试集 | ✅ 已完成 | 固定 Binance 夹具已落库，主流程测试可稳定复现。 |
| 测试与质量门禁 | ⚠️ 部分完成 | 主流程可测，但覆盖率分布不均，仍有补强空间。 |

### 2.2、关键验证结果（本次核对）

- `pytest --cov=epcmbot`：`17 passed`，总覆盖率 `75%`。
- `ruff check .`：通过（`All checks passed!`）。
- `ruff format . --check`：通过（`28 files already formatted`）。

### 2.3、✅ 已完成详情

本小节与 `2.1` 中状态为 `✅ 已完成` 的能力一一对应。

- **本地数据加载与协议校验**
  - 已实现 `load_market_frame`，覆盖本地文件读取、字段完整性、时间有序性、秒级对齐与价格关系校验。
  - 实现位置：`epcmbot/data.py`。
  - 验证：`tests/test_data.py`。

- **特征工程与目标构造**
  - 已实现 `build_feature_frame`，包含 `mid_price`、`relative_spread`、`depth_imbalance`、`order_flow_imbalance`、`buy/sell_vwap_deviation`、`vwap_pressure`、`target_log_return`。
  - 已显式避免未来泄露：特征基于当前/历史，目标通过 horizon 前移生成。
  - 实现位置：`epcmbot/features.py`。
  - 验证：`tests/test_features.py`。

- **滚动训练与调参**
  - 已实现 `run_walk_forward_training`：外层滚动切分 + 内层调参，主模型按 GMADL、基线按 R²。
  - 已实现 purge window 切分器 `RollingTimeSeriesSplitter`。
  - 实现位置：`epcmbot/modeling.py`、`epcmbot/validation.py`。
  - 验证：`tests/test_pipeline.py`（含端到端训练流程）。

- **SHAP 可解释性**
  - 已实现 `run_shap_analysis(model, feature_df, feature_columns)`，输出全局重要性和 top feature dependence 数据。
  - 实现位置：`epcmbot/explain.py`。
  - 验证：`tests/test_pipeline.py`。

- **回测引擎**
  - 已实现 `TakerBacktester`、`MakerBacktester`、`CombinedBacktester`。
  - 已实现绩效指标：`ARC`、`ASD`、`Sharpe/IR*`、`MDD`、`MLD`、`IR**`、`t-test`。
  - 实现位置：`epcmbot/backtest.py`、`epcmbot/metrics.py`。
  - 验证：`tests/test_backtest.py`、`tests/test_metrics.py`。

- **CLI 与结果落盘**
  - `epcmbot`：已支持本地输入的一键流水线（特征 -> 训练 -> 回测 -> 指标 -> 摘要/落盘）。
  - 实现位置：`epcmbot/main.py`。
  - 验证：`tests/test_main.py`。

- **离线构数工具**
  - 已实现 `epcmbot-build-dataset`，支持从 Binance 历史 zip 自动聚合生成 1 秒协议化数据。
  - 实现位置：`epcmbot/binance_dataset.py`。
  - 验证：`tests/test_binance_dataset.py`。

- **测试夹具与主测试集**
  - 已沉淀固定 Binance 夹具：`tests/fixtures/binance/roseusdt_20240115_1s.csv`。
  - 已覆盖数据、特征、训练流水线、回测、指标、CLI 持久化、构数工具核心路径。
  - 验证：`tests/test_data.py`、`tests/test_features.py`、`tests/test_pipeline.py`、`tests/test_backtest.py`、`tests/test_metrics.py`、`tests/test_main.py`、`tests/test_binance_dataset.py`。

### 2.4、⚠️ 部分完成详情

本小节与 `2.1` 中状态为 `⚠️ 部分完成` 的能力一一对应。

- **风险报告**
  - 已实现结构化风险输出（过拟合、延迟滑点、流动性蒸发、逆向选择、同质化、诱导操纵）。
  - 实现位置：`epcmbot/risk.py`。
  - 当前缺口：缺少风险模块专项自动化测试，需补齐后再升级为“已完成”。

- **测试与质量门禁**
  - 已实现主流程测试覆盖：`pytest --cov=epcmbot`。
  - 实现位置：`tests/test_*.py`。
  - 验证：`pytest --cov=epcmbot`。

## 2.5、公共接口与边界

核心接口：

- `load_market_frame(path, schema_config=None) -> pd.DataFrame`
- `build_feature_frame(market_df, horizon_seconds=3) -> pd.DataFrame`
- `run_walk_forward_training(feature_df, config) -> TrainingArtifacts`
- `run_shap_analysis(model, feature_df, feature_columns) -> ShapSummary`
- `run_taker_backtest(feature_df, predictions, config) -> BacktestResult`
- `run_maker_backtest(feature_df, predictions, config) -> BacktestResult`
- `compute_performance_metrics(equity_curve, periods_per_year=31_536_000) -> MetricsReport`

CLI：

- `epcmbot`：核心研究流水线入口，默认消费本地协议化输入表（CSV/Parquet）。
- `epcmbot-build-dataset`：可选离线构数工具，用于从 Binance 公共历史数据生成输入表。

### 2.6、 ⚠️ 已知限制

- Maker 回测是工程保守近似，不是逐笔排队仿真；无法覆盖真实队列位置与撮合细节。
- 覆盖率分布不均：`epcmbot/binance_dataset.py` 约 `51%`、`epcmbot/main.py` 约 `58%`、`epcmbot/risk.py` 约 `44%`。
- 主流程仍以本地输入文件为前提；若输入质量不足，结果稳定性会直接受影响。

### 2.7、 🚧 待优化扩展（按优先级）

- P1（优先落地）
  - 补齐低覆盖模块边界测试。
    - 目标：总覆盖率从 `75%` 提升到 `>=85%`。
    - 重点：`binance_dataset/main/risk` 的异常路径、边界参数、失败分支。
  - 增强回测摩擦建模。
    - 方向：延迟、额外滑点、成交约束、不同流动性状态下的成交条件。
    - 目标：提升回测结果对实盘摩擦的鲁棒性。

- P2（扩展能力）
  - 多标的联合训练与稳健性评估。
    - 方向：跨 `symbol`、跨窗口的泛化检验与配置化实验。
  - 更完整的 artifacts 与监控输出。
    - 方向：参数版本对比、分折稳定性面板、关键风险指标追踪。

## 3、 近期里程碑（下一版本）

### Milestone A：质量补强（最小可交付）

- 交付内容：
  - 为 `binance_dataset/main/risk` 新增高价值边界测试。
  - 把覆盖率拉升到 `>=85%`。
- 验收标准：
  - `pytest --cov=epcmbot` 通过，覆盖率达标。
  - `ruff check .` 与 `ruff format . --check` 均通过。

### Milestone B：回测可信度增强

- 交付内容：
  - 在回测中引入至少一类显式摩擦建模（如延迟或分段滑点）。
  - 输出可复核的参数与影响摘要。
- 验收标准：
  - 新增测试覆盖摩擦参数生效路径。
  - 文档能说明“与旧模型相比改变了什么、影响了什么”。