From 28925063d4aca18058e9b957914f31d664c12b34 Mon Sep 17 00:00:00 2001
From: GitHub <action@github.com>
Date: Tue, 9 Jun 2026 16:17:02 +0800
Subject: [PATCH] docs: finalize backtest spec with minor clarifications (rev
 2.1)

- DSL identifier rules: letters/digits/underscores
- reduce mode: min(requested, max_affordable) formula
- Chanlun time alignment: nearest K-line <= timestamp
- GridResult/run_many return types documented

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../specs/2026-06-09-backtest-engine-design.md  | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/docs/superpowers/specs/2026-06-09-backtest-engine-design.md b/docs/superpowers/specs/2026-06-09-backtest-engine-design.md
index 49fe62d..73b0ab2 100644
--- a/docs/superpowers/specs/2026-06-09-backtest-engine-design.md
+++ b/docs/superpowers/specs/2026-06-09-backtest-engine-design.md
@@ -326,7 +326,7 @@ def dual_ma(df):
 easy-tdx backtest SH 600519 --strategy "CROSS(MA(close,5),MA(close,20))" --cash 100000 --table
 ```
 
-编译器内部将 `close` 映射到 DataFrame 的 `close` 列。支持的列名：`open`, `close`, `high`, `low`, `vol`, `amount`，以及预计算的指标列名（如 `MACD_DIF`, `BOLL_UPPER`）。
+编译器内部将 `close` 映射到 DataFrame 的 `close` 列。标识符规则：字母/数字/下划线，首字符不为数字。支持的列名：`open`, `close`, `high`, `low`, `vol`, `amount`，以及预计算的指标列名（如 `MACD_DIF`, `BOLL_UPPER`）。
 
 ### 5.3 内置 DSL 函数
 
@@ -380,7 +380,9 @@ class BacktestEngine:
 
     def run(self, df: pd.DataFrame, chanlun_result: Any | None = None) -> BacktestResult:
         """执行回测。df 是 easy_tdx 标准 K 线 DataFrame（可含额外指标列）。
-        chanlun_result 可选注入缠论分析结果，策略通过 self.chanlun 访问。"""
+        chanlun_result 可选注入缠论分析结果，策略通过 self.chanlun 访问。
+        注意：缠论结果中的时间戳按最近 K 线 datetime 匹配对齐（笔确认需后续K线，
+        买卖点时间戳可能与 K 线不完全一致，引擎取 <= 该时间戳的最后一根 K 线）。"""
         ...
 ```
 
@@ -418,7 +420,7 @@ Step 2 是唯一需要逐行处理的步骤（仓位依赖前一 Bar 状态）
 
 | 模式 | 说明 |
 |------|------|
-| `reduce`（默认） | 自动减到最大可买/可卖量，记录成交 |
+| `reduce`（默认） | 自动减到最大可买/可卖量：买入量 = min(请求量, 最大可买量)；卖出量 = min(请求量, 当前持仓量)。记录实际成交 |
 | `skip` | 跳过该信号，记录一条 `rejected=True` 的 Trade |
 
 ### 6.6 费用模型
@@ -437,19 +439,22 @@ Step 2 是唯一需要逐行处理的步骤（仓位依赖前一 Bar 状态）
 ### 6.8 多策略批量回测 (P1)
 
 ```python
-# 多只股票
+# 多只股票（顺序独立回测，非组合）
 results = engine.run_many({
     "SH600519": df_519,
     "SZ000858": df_858,
 })
-# → dict[str, BacktestResult]
+# → dict[str, BacktestResult]，每个 key 对应一只股票的回测结果
 
 # 参数扫描
 results = engine.run_grid(df, params={
     "short": [5, 10, 15],
     "long": [20, 30, 60],
 })
-# → list[GridResult]，支持 .sort_by("sharpe").to_table()
+# → list[GridResult]
+# GridResult.params: dict[str, Any]  # 使用的参数组合
+# GridResult.result: BacktestResult   # 该参数组合的回测结果
+# GridResult 支持 .sort_by("sharpe").to_table()
 ```
 
 ---