arbitrage-engine/docs/STRATEGY_FACTORY_VALIDATION.md

# 策略工厂与信号引擎验证清单（Strategy Factory & Signal Engine Validation）

> 目的：把需要“逐项验证”的点全部列清楚，变成可打勾的 checklist。  
> 范围：`backend/signal_engine.py`（single-engine 数据发射源） + V5.4 策略工厂（`strategies` 表 → 信号 / 模拟盘）。  
> 权威规格仍以 `docs/arbitrage-engine-full-spec.md` 为准，本文件只列“需要检验的点”。

---

## 1. 背景与角色划分（人话版）

- single-engine（`backend/signal_engine.py`）在本系统里扮演的是：
  - 从 `agg_trades` + `market_indicators` 等数据源，滚动算出各种指标；
  - 每 15 秒左右，对每个运行中策略打分、判断是否开仓；
  - 把结果写入：
    - `signal_indicators`（信号与指标快照）；
    - `paper_trades`（模拟盘开仓记录）；
    - 并通过 NOTIFY 推送给其他进程。

- V5.4 策略工厂的职责是：
  - 把 `strategies` 表中 `status='running'` 的每一行，当成一个“策略实例”；
  - 对每个实例，组合：
    - 多窗口 CVD（5m / 15m / 30m / 1h / 4h）；
    - ALT 四层评分（Direction / Crowding / Environment / Auxiliary）；
    - 5 个否决 Gate（vol / cvd / whale / obi / spot_perp）的阈值与开关；
  - 在统一的信号模型上，跑出不同风格的策略。

当前假设：

- 你只对 **aggTrades 数据流** 有信心，其他所有东西（指标/门控/评分/策略映射/落库）都需要重新审计；
- 我们需要一个尽可能完整的“验证清单”，后续可以按照这份清单逐条打勾。

下面把需要检查的点分成 3 层：

- A. 数据与指标层：所有输入信号是不是对的（基础指标本身）  
- B. 策略配置与工厂层：DB 字段是否正确映射成策略参数  
- C. 决策与落库层：评分 / 门控 / 开仓 / 写库 / 冷却 / 方向限制等是否符合规则

---

## 2. 总体结构视图（先有个地图）

- **数据来源**
  - `agg_trades`：逐笔成交 → 多窗口 CVD / ATR / VWAP / 大单 P95/P99 / 巨鲸成交；
  - `market_indicators`：OI、多空比、Top Trader、资金费率、Coinbase Premium、OBI、期现背离等；
  - 实时 WebSocket：OBI 实时值、spot-perp divergence 实时值（如果有）。

- **策略配置**
  - `strategies` 表：策略实例的参数（symbol、方向、CVD 窗口、四层权重、五门阈值、TP/SL、timeout、flip_threshold 等）；
  - `load_strategy_configs_from_db()`：把这些行映射成内部配置 dict。

- **决策 / 落库**
  - `evaluate_factory_strategy()`（原 `_evaluate_v53`）：统一的评分与 Gates 逻辑；
  - `save_indicator()`：写 `signal_indicators`；
  - `paper_open_trade()`：写 `paper_trades`；
  - `NOTIFY new_signal`：推送给 live_executor 等其他进程。

这 3 层每一处的小错误，都可能直接导致“赚钱 / 亏钱”的行为偏差，所以需要逐项验证。

---

## 3. A 层：数据与指标验证（single-engine 基础指标）

### A1. 时间线与窗口基础

- ✅ `agg_trades.time_ms` 的语义是否统一为 **毫秒时间戳**，无混用秒/毫秒的情况。  
- ✅ 冷启动加载历史时，时间范围是否覆盖至少 `24h+`，足够支持所有窗口（5m/15m/30m/1h/4h/24h）。  
      - 当前实现：冷启动预载 4h（WINDOW_MID），之后由实时数据自然填充到 24h。此行为已知且暂视为接受的设计，不视为 bug。  
- ✅ 滚动窗口裁剪规则是否一致（例如统一使用 `t >= now_ms - window_ms`），避免 off-by-one。  
- ✅ 历史回补或乱序插入时，是否会导致窗口内时间回跳，进而影响 CVD/ATR 等指标。  
      - 当前实现：agg_trades_collector 通过 REST 补洞 + 连续性巡检，配合按 agg_id/time_ms 有序读取，认为不会产生系统性时间回跳问题。

### A2. CVD 多窗口计算

目标：确认 5m / 15m / 30m / 1h / 4h 所有 CVD 计算都符合“主动买入量 - 主动卖出量”的定义。

- ✅ 对 is_buyer_maker 的解释是否正确：  
      - 实现：采集时 `is_buyer_maker = 1 if t["m"] else 0`，CVD 里 `is_buyer_maker == 0` 计为买量（taker 买），`==1` 计为卖量（taker 卖）；  
      - 结论：与 Binance aggTrade 语义一致，CVD = taker 买入量 - taker 卖出量，符合预期。
- ✅ 基础 30m / 4h 窗口（`win_fast` / `win_mid`）中，新增/裁剪 trade 时 buy/sell 累计是否严格同步更新。  
      - 实现：所有 trade 通过 `TradeWindow.add()` 进入窗口，`trim()` 时同步回退 buy/sell 累计，CVD 始终等于当前窗口内的买减卖。  
- ✅ 其他窗口（5m/15m/1h）的 CVD 是否通过对已有窗口（win_fast/win_mid）的列表按时间切片重算，而不是重新查库。  
      - 实现：通过 `_window_ms()` 把窗口字符串转毫秒，从 `win_fast`/`win_mid` 的 `trades` 列表按 `t_ms >= now_ms - window_ms` 切片重算，未重复查库。  
- ✅ 所有窗口的截止时间点是否都使用当前 `now_ms`，不会出现“5m 用旧 now_ms，30m 用新 now_ms”的错位。  
      - 实现：`build_evaluation_snapshot(now_ms)` 与 `evaluate_factory_strategy(now_ms, ...)` 使用同一个 `now_ms`，动态切片和快照在同一时间基准上计算。
- ⚠️ 斜率与加速度：
  - ✅ 定义：`cvd_fast_slope = cvd_fast(now) - prev_cvd_fast`，`cvd_fast_accel = cvd_fast_slope(now) - prev_cvd_fast_slope`，在持续运行时语义正确；  
  - ⚠️ 冷启动第一帧使用 `prev_* = 0` 计算，未做专门回退为 0 的处理，可能使第一帧 slope/accel 数值偏大；目前视为需要后续评估/是否调整的注意点。

### A3. ATR 与 ATR 百分位

- ✅ 5m K 线 bucket 是否按 `bar_ms = (time_ms // period_ms) * period_ms` 计算，保证时间对齐。  
      - 实现：`ATRCalculator.update()` 中按 `time_ms // period_ms` 对齐 5m bar，符合预期。  
- ✅ Candle 的 open/high/low/close 更新逻辑是否正确，所有 trade 都被处理到。  
      - 实现：新 bar 时写入旧 bar 到队列，当前 bar 逐笔更新 high/low/close。  
- ✅ TR（True Range）计算是否符合标准定义：  
      - 实现：`max(high - low, |high - prev_close|, |low - prev_close|)`，与标准 TR 定义一致。  
- ✅ ATR 是按何种算法计算（简单平均 / Wilder EMA），与 full-spec 中的期望是否一致。  
      - 实现：先取第一根 TR 作为初始值，再用 `(atr_val*(length-1)+tr)/length` 逐步平滑，为 Wilder 风格 EMA，符合设计。  
- ✅ 当 candle 数量不足（小于 2 或小于 ATR length）时，ATR 返回 0 或合理默认值。  
      - 实现：`len(candles) < 2` 时直接返回 0.0，避免未成熟 ATR 参与决策。  
- ✅ `atr_percentile`：  
  - ✅ 历史 ATR 样本长度、维护方式（队列长度）是否合理；  
  - ✅ 百分位算法（<= current / count）是否正确；  
  - ✅ 样本太少时是否返回 50.0，避免无意义的极端值。  
      - 实现：`atr_history` 长度上限 288，少于 10 条或当前 ATR=0 时返回 50.0，其余按 rank 百分位计算。

### A4. P95 / P99 大单阈值

- ✅ 使用的样本是否来自 24h 窗口（`win_day`），并且只取 qty（不乘 price）。  
      - 实现：`compute_p95_p99()` 直接遍历 `win_day.trades`，取 `t[1]`（qty）构造样本数组，窗口长度即 24h。  
- ✅ 样本数 < 100 时是否使用保底常数（BTC: p95>=5, p99>=10；ALT: p95>=50, p99>=100），是否与策略设计一致。  
      - 实现：少于 100 条时直接返回 `(5.0, 10.0)`；样本足够时再按 symbol 区分 BTC/ALT 保底。  
- ✅ 排序和索引算法：`sorted(qtys)` 后，`int(n * 0.95)` / `int(n * 0.99)` 是否符合预期的分位点定义。  
      - 实现：对 qtys 排序后按整数下标取 95% / 99% 位置，属于合理的分位点近似。  
- ✅ ALT 的分类逻辑是否只是“非 BTC 即 ALT”，以及这是否满足未来新增 symbol 的需求。  
      - 实现：判断条件为 `"BTC" in self.symbol`，否则按 ALT 处理；目前支持的 symbol 集合有限（BTC/ETH/XRP/SOL），该简化规则可接受，如未来扩展再细化。

### A5. 巨鲸成交与 `whale_cvd_ratio`

- ✅ 巨鲸交易过滤条件是否为 `price * qty >= 100_000`（100k USD），阈值可配置或硬编码？  
      - 实现：`usd_val = price * qty`，`usd_val >= 100_000` 视为巨鲸成交，阈值目前硬编码为 100k。  
- ✅ `_whale_trades` 窗口长度是否为 15 分钟，裁剪逻辑是否正确（按 time_ms）。  
      - 实现：窗口长度 `WHALE_WINDOW_MS = 15min`，按 trade 的 `time_ms` 滑动裁剪。  
- ✅ `whale_cvd_ratio` 计算：  
  - ✅ buy_usd = 所有巨鲸买单金额之和；  
  - ✅ sell_usd = 所有巨鲸卖单金额之和；  
  - ✅ ratio = (buy_usd - sell_usd) / (buy_usd + sell_usd)；  
  - ✅ 无数据时返回 0.0 是否符合预期。  
- ✅ BTC 与 ALT 对巨鲸数据的使用差异是否符合设计：  
  - 实现：BTC 用 `whale_cvd_ratio`（或 DB 中 `tiered_cvd_whale`）做 Gate；ALT 使用 `recent_large_trades` 中的对立/同向大单判断。  
  - 备注：鲸鱼 Gate 的“占比阈值”在 C2 中有一个缩放 bug（`whale_flow_pct` 被多除以 100），已在 Gate 小节标记为问题点。

### A6. `market_indicators` 中的 JSON 指标

需要逐个核对字段名称与意义（对照实际 JSON）：

- ✅ `long_short_ratio`：  
  - 实现：从 `market_indicators` 读取 JSON `value`，使用 key `longShortRatio` 转为 float；默认 1.0。  
- ✅ `top_trader_position`：  
  - 实现：使用 key `longAccount`，代表 top trader 多头占比（0~1）。  
- ✅ `open_interest_hist`：  
  - 实现：使用 key `sumOpenInterestValue` 作为 OI 数值，后续只用来计算相对变化率。  
- ✅ `coinbase_premium`：  
  - 实现：使用 key `premium_pct`，并统一除以 100 转成小数，避免量纲混乱。  
- ✅ `funding_rate`：  
  - 实现：优先使用 `fundingRate`，否则 fallback `lastFundingRate`。  
- ✅ `obi_depth_10`：  
  - 实现：使用 key `obi`，作为 [-1,1] 区间内的订单簿不平衡（正=买压，负=卖压），与 Gate4 逻辑一致。  
- ✅ `spot_perp_divergence`：  
  - 实现：使用 key `divergence`，注释中定义为 `(spot - mark) / mark`，与 Gate5 使用方式一致。

### A7. OI 环境指标

- ✅ OI 读取：`open_interest_hist` 是否转换为 float；  
      - 实现：通过 `to_float(self.market_indicators.get("open_interest_hist"))` 转为 float。  
- ✅ OI 变化率定义：`oi_change = (oi_now - oi_prev) / oi_prev`，oi_prev>0 的保护是否到位。  
      - 实现：仅在 `prev_oi_value > 0` 时计算变化率，否则 oi_change=0.0。  
- ✅ environment_score_raw 的区间划分（例如 >=3%、0~3%、<0）对应基础分是否与 full-spec 一致。  
      - 实现：oi_change >=3% → 15 分；>0 → 10 分；<=0 → 5 分，符合设计。  
- ✅ `prev_oi_value` 的更新时机：只在 oi_value>0 时更新是否会导致长时间停留在 0。  
      - 实现：oi_value>0 时才覆盖 prev，启动后首帧用默认 10 分，后续随 OI 变化更新，行为符合预期。

### A8. 其他环境与拥挤指标

- ✅ `long_short_ratio` 的逻辑：>1 多头拥挤，<1 空头拥挤，这个假设需要与真实数据验证。  
      - 实现：LONG 方向时 lsr 较低（<1,<0.7,<0.5）给更高分，SHORT 方向时 lsr 较高（>1,>1.5,>2）给更高分，符合“多空占比”直觉。  
- ✅ crowding 层中对 LONG / SHORT 的条件：  
      - 实现与上述区间一致，并在 V5.1 路径中用 crowding_score=ls_score+top_trader_score；V5.3 路径中 crowding_score capped 为 25 分。  
- ✅ `top_trader_position` 映射：  
      - 实现：LONG：>=0.55 给 10 分、<=0.45 给 0 分、其他给 5 分；SHORT 反向，对应“top trader 站在我们这一边时加分”的逻辑。  
- ✅ `coinbase_premium` 阈值：  
      - 实现：>0.0005 / <-0.0005 视为强信号得 5 分；|premium|<=0.0005 得 2 分；其他情况 0 分，与 full-spec 描述一致。  
      - 备注：精确阈值是否需要微调属于策略优化问题，暂不视为实现 bug。

### A9. 时间与时区统一

- ✅ `agg_trades.time_ms`、`market_indicators.timestamp_ms`、`signal_indicators.ts` 是否全部为 UTC 毫秒。  
      - 实现：agg_trades 来自 Binance aggTrade `T`（毫秒），market_indicators 查询按 `timestamp_ms` 排序，signal_indicators.ts 由 `int(time.time()*1000)` 生成，语义统一为毫秒。  
- ✅ signal_engine 的 `now_ms` 是否与最新成交的时间差在可接受范围内（比如 <5 秒）。  
      - 实现：每轮循环用当前 `time.time()` 作为 now_ms，立刻用 `fetch_new_trades` 拉取自上次 agg_id 之后的 tick 并入窗口，逻辑上不会积累大延迟。  
- ✅ 所有窗口、冷却时间、timeout 等是否都用毫秒表达，避免混用秒/分钟。  
      - 实现：窗口常量、冷却时间、timeout 以及 liquidations 窗口等全部以毫秒表示。

---

## 4. B 层：策略配置与工厂验证（DB → 内存策略）

### B1. 行筛选与顺序

- ✅ `load_strategy_configs_from_db()` 是否只选择 `status='running'` 的行。  
      - 实现：SQL 显式 `WHERE status = 'running'`。  
- ⚠️ 是否有必要基于 `schema_version` 做过滤（未来版本升级时）。  
      - 实现：当前未按 `schema_version` 过滤，所有 running 策略视为同一版本；如未来引入多版本策略，需要补充。  
- ✅ ORDER BY created_at 是否会在行为上产生影响（一般无关，但需要意识到）。  
      - 实现：仅影响策略评估与写入的顺序，对行为影响有限。

### B2. 字段映射完整性

逐字段确认 DB → cfg 的映射：

- ✅ `strategy_id`（uuid）是否被转为 string，并赋值到 `cfg["strategy_id"]`。  
      - 实现：SQL 中 `strategy_id::text`，后续直接写入 cfg。  
- ✅ `display_name` 是否写入 `cfg["strategy_name_snapshot"]`。  
- ✅ `symbol` / `direction` 是否原样保留，大小写约定是否固定。  
      - 实现：直接从 DB 取值赋入 cfg，不做大小写转换。  
- ✅ `cvd_fast_window` / `cvd_slow_window` 是否直接映射到 cfg。  
- ✅ `weight_direction` / `weight_env` / `weight_aux` / `weight_momentum` 是否正确组成 `cfg["weights"]`。  
- ✅ `entry_score` / `flip_threshold` 是否正确映射到 `cfg["threshold"]` / `cfg["flip_threshold"]`。  
- ✅ `gate_obi_enabled` / `gate_whale_enabled` / `gate_vol_enabled` / `gate_spot_perp_enabled` / `gate_cvd_enabled` 是否被正确翻译成 bool。  
      - 实现：直接使用 DB 中的 boolean 字段。  
- ✅ 所有 Gate 相关 float 字段（`obi_threshold`、`whale_usd_threshold`、`whale_flow_pct`、`vol_atr_pct_min`、`spot_perp_threshold`）  
      在 None 时有合理默认（与 full-spec 匹配）。  
      - 实现：在转入 cfg 时对 None 做 `or 默认值` 处理，默认值来源于迁移脚本/旧 symbol_gates。  
- ✅ `sl_atr_multiplier` / `tp1_ratio` / `tp2_ratio` 是否正确映射到 `cfg["tp_sl"]`。  
- ✅ `timeout_minutes` 是否正确映射到 `cfg["timeout_minutes"]`。

### B3. legacy 策略兼容逻辑

- [ ] 固定 UUID：  
  - `...000053` → `"v53"`；  
  - `...000054` → `"v53_middle"`；  
  - `...000055` → `"v53_fast"`；  
  是否只对 deprecated legacy 策略生效。  
- [ ] 其他策略是否统一命名为 `custom_<uuid前8位>`，与历史 `strategy` 字段约定一致。  
- [ ] 当 DB 无策略时，是否 fallback 到 JSON 文件配置；当 DB 有策略时是否会重复加载 JSON。

更新：

- ✅ 固定 UUID 的映射逻辑正确，且只通过 `LEGACY_UUID_MAP` 在内存层生效，不会修改 DB 中的 strategy_id。  
- ✅ 其他策略统一命名为 `custom_<uuid前8位>`，与历史 `strategy` 字段兼容。  
- ✅ main() 中当 DB 读不到策略（异常）时才 fallback 到 JSON，正常情况下不会 DB+JSON 混用。

### B4. CVD 窗口参数

- ✅ `cvd_fast_window` / `cvd_slow_window` 的合法取值集合：是否只支持 {5m,15m,30m,1h,4h}。  
      - 实现：`_window_ms()` 支持任意 m/h，策略层目前只用上述几种组合。  
- ✅ 非法值时行为：抛出异常还是回退到默认 30m/4h。  
      - 实现：未匹配 "m"/"h" 后缀时回退到 30m，对异常配置有兜底。  
- ✅ `_window_ms()` 的实现是否覆盖所有这些枚举值。  
- ✅ `evaluate_factory_strategy()` 中选择 trade 源时，fast/slow 窗口与 win_fast/win_mid 的映射是否一致。  
      - 实现：fast 窗口长度 <=30m 用 win_fast，否则用 win_mid；slow 总是用 win_mid，与 full-spec 描述一致。

### B5. 四层权重与 entry/flip

- ✅ `weights` 是否已真实参与 scoring（direction/env/aux/momentum 四层权重）。  
      - 现状：V5.4 `strategies` 中的权重字段被映射到 cfg["weights"]（direction/env/aux/momentum），`evaluate_factory_strategy()` 会将四个权重归一化到 100 分，并把 direction+momentum 总权重按 55:25 的比例拆分给 direction/crowding，再按各层原始得分比例缩放，真实影响 total_score。  
- ✅ `entry_score` 是否只用于“达到该分数即可考虑开仓”，不会在别处被重载。  
      - 实现：在 `evaluate_factory_strategy()` 中作为标准开仓阈值（total_score < entry_score 时不会产生 signal），signal_engine 通过是否有 signal 决定是否尝试开仓。  
- ✅ `flip_threshold` 是否用于“重仓 / 反向强平”逻辑，阈值关系是否是 `flip_threshold >= entry_score`。  
      - 实现：在 `evaluate_factory_strategy()` 中，total_score >= flip_threshold 时记为重仓 tier="heavy"；在 `signal_engine` 中，当反向信号的 `score >= flip_threshold` 时触发 signal_flip 平仓。代码允许设置任意数值，上层应保证配置关系。  
- ⚠️ 当 `flip_threshold < entry_score` 时，系统行为是否有定义或需要禁止。  
      - 现状：代码未禁止这种配置，会导致实际行为变成“更容易触发 heavy 仓”；需要在策略配置侧约束，暂不视为实现错误。

### B6. Gate 参数与开关

逐 Gate 检查 DB → cfg 的映射：

- [ ] Gate vol：  
  - `gate_vol_enabled` → `gates["vol"]["enabled"]`；  
  - `vol_atr_pct_min` → `gates["vol"]["vol_atr_pct_min"]`，默认值与 full-spec 一致。  
- [ ] Gate cvd：  
  - `gate_cvd_enabled` → `gates["cvd"]["enabled"]`；  
  - 默认是否为 True，并与 full-spec 一致。  
- ✅ Gate whale：  
  - `gate_whale_enabled` → `gates["whale"]["enabled"]`；  
  - `whale_usd_threshold` → `gates["whale"]["whale_usd_threshold"]`；  
  - ✅ `whale_flow_pct` → `gates["whale"]["whale_flow_pct"]`（注意是否有 /100 的处理）。  
      - 更新：`evaluate_factory_strategy()` 中已去掉多余的 `/100` 缩放，现使用 0~1 的比例值与 DB/迁移脚本一致，鲸鱼 Gate 灵敏度恢复到设计水平。  
- [ ] Gate obi：  
  - `gate_obi_enabled` → `gates["obi"]["enabled"]`；  
  - `obi_threshold` → `gates["obi"]["threshold"]`。  
- [ ] Gate spot_perp：  
  - `gate_spot_perp_enabled` → `gates["spot_perp"]["enabled"]`；  
  - `spot_perp_threshold` → `gates["spot_perp"]["threshold"]`。

### B7. 策略方向限制

- ⚠️ DB 中的 `direction` 字段枚举是否固定为 `"long" | "short" | "both"`（大小写统一）。  
      - 现状：代码层直接使用 DB 文本，不验证枚举/大小写；依赖上游迁移与 API 保证有效值。  
- ✅ `evaluate_factory_strategy()` 或上层逻辑中是否有对该字段的应用：  
  - 预期：direction=long → 禁止 SHORT 信号开仓；direction=short → 禁止 LONG 信号开仓；direction=both → 不限制。  
  - 现状：已在 `evaluate_factory_strategy()` 内增加 per-strategy 方向约束：  
    - long 策略在方向判定为 SHORT 时不会产生 signal（但仍计算评分与指标快照）；  
    - short 策略在方向判定为 LONG 时不会产生 signal；  
    - both 不做限制。  
- ⚠️ 若当前实现未对 strategy direction 做约束，需要在此记为一个重点检查项。  
      - 更新：方向约束已在信号生成阶段生效，但反向 signal_flip 平仓仍按“环境方向”判断，是否也需要 direction 约束留待后续决策。

---

## 5. C 层：决策与落库验证（评分 + 门控 + 开仓 + 写库）

### C1. 逐 symbol / 逐策略评估流程

- ✅ 评估循环是否为：先按 symbol 分组，再对每个 symbol 内的所有策略依次评估。  
- ⚠️ 对于每个策略，是否在评估前检查 `cfg["symbol"] == state.symbol`，确保不会在错误币种上开仓。  
      - 现状：评估阶段对所有策略都计算分数，但在开/平仓阶段才按 `strategy_cfg["symbol"]` 过滤，因此不会在错误币种上实际开仓，只是多算了一些“无用分”。  
- ✅ 是否存在“一个策略在多个 symbol 上同时运行”的预期场景，如果有，需要明确规则。  
      - 现状：当前配置一条策略只绑定一个 symbol，引擎逻辑允许同一策略在多个 symbol 开仓，但上层 API 不这么用。

### C2. 五个 Gate 的逻辑

对于每一门，需要验证条件与 full-spec 一致：

- Gate1：波动率门（ATR/price 下限）
  - ✅ `atr_pct_price = atr / price` 的计算是否正确；  
  - ✅ 阈值 `min_vol` 是否来自 DB 的 `vol_atr_pct_min` 或 JSON fallback；  
  - ✅ 条件：`atr_pct_price < min_vol` 时，gate_block = `"low_vol(...)"`，并且后续直接视为不通过。

- Gate2：CVD 共振门
  - ✅ 快慢 CVD 同向时方向判断是否为：  
        fast>0 且 mid>0 → LONG；fast<0 且 mid<0 → SHORT；  
  - ✅ 不同向时，若 gate_cvd_enabled=True，则设置 `no_direction=True` 且 `gate_block="no_direction_consensus"`；  
  - ✅ 当 Gate2 关闭（enabled=False）时，是否允许仅根据 fast CVD 决定方向。

- Gate3：鲸鱼否决门
  - BTC：
    - ✅ 使用 `whale_cvd_ratio` 或 fallback 到 `market_indicators["tiered_cvd_whale"]`；  
    - ✅ 条件：  
      - LONG 且 whale_cvd_ratio < -阈值 → 否决；  
      - SHORT 且 whale_cvd_ratio > 阈值 → 否决。  
  - ALT：
    - ✅ `recent_large_trades` 中，对立大单与同向大单的判定逻辑是否正确；  
    - ✅ 只有“有对立大单且无同向大单”时才否决，且金额阈值是否为 whale_usd_threshold × price。

- Gate4：OBI 否决门
  - ✅ OBI 采样顺序是否为：先用实时 `rt_obi`，否则用 DB 中 `obi_depth_10`；  
  - ✅ 条件：  
    - LONG 且 obi_raw < -obi_veto → Gate 拒绝；  
    - SHORT 且 obi_raw >  obi_veto → Gate 拒绝。

- Gate5：期现背离否决门
  - ✅ 采样顺序：先用实时 `rt_spot_perp_div`，否则用 DB 中 `spot_perp_divergence`；  
  - ✅ 条件：  
    - LONG 且 divergence < -spd_veto → Gate 拒绝；  
    - SHORT 且 divergence >  spd_veto → Gate 拒绝。

### C3. gate_block / gate_passed 对评分和信号的影响

- ✅ 任意一门触发后，`gate_block` 是否被设置为对应字符串，`gate_passed=False`。  
- ✅ 评分计算完后，如果 `gate_passed=False`，是否将 `total_score` 强制置为 0。  
- ✅ `result["signal"]` 在 gate_passed=False 或 no_direction=True 时是否总是 None。  
- ✅ `factors` 中是否仍然保留原始四层分数和 Gate 细节，方便事后分析。

### C4. 四层评分计算细节

- Direction Layer：
  - ✅ CVD 共振基础分数（例如 30 分）是否与 full-spec 一致；  
  - ✅ p99_flow：有同向大单 / 无大单 / 有对立大单 三种情况的得分是否符合预期；  
  - ✅ accel_bonus：cvd_fast_accel 与方向同向时报 5 分；  
  - ✅ v53_fast 的独立加速路径（不要求双线共振）是否正确实现。  

- Crowding Layer：
  - ✅ long_short_ratio 与 top_trader_position 的区间划分与得分是否符合 full-spec；  
  - ✅ crowding_score capped 到 25 分。  

- Environment Layer：
  - ✅ ALT（或默认）路径：只用 OI 变化率映射出 environment_score_raw；  
  - ✅ v53_fast 额外的 OBI bonus：强/弱阈值与得分 5/3 是否正确；  
  - ✅ 总分 capped 到 15。  

- Auxiliary Layer：
  - ✅ coinbase_premium 的区间与得分（5/2/0）是否正确实施。  

- 汇总：
  - ✅ total_score = 四层得分之和 capped 到 100，并四舍五入到 0.1；  
  - ✅ 如果 `gate_passed=False`，最终 total_score 是否强制为 0。

### C5. 权重的实际使用情况

- ✅ 当前实现已经使用 `weights` 来调整各层最大分/权重（direction/env/aux/momentum），需要确认缩放规则是否符合预期；  
- ✅ future：如要进一步调整权重逻辑，需要设计迁移/验证方案，并评估对历史统计的影响。

### C6. signal 生成与冷却（entry / flip / cooldown）

- ✅ 条件逻辑：  
  - total_score >= flip_threshold → `tier="heavy"`；  
  - entry_score <= total_score < flip_threshold → `tier="standard"`；  
  - total_score < entry_score → 不开仓。  
- ✅ 冷却：  
  - COOLDOWN_MS = 10 分钟；  
  - 以 `strategy_name` 为 key 的 last_signal_ts 是否正确记录；  
  - 冷却期内不再生成新 signal。  
- ✅ `direction` 限制：  
  - 策略 direction=long/short/both 是否在最终生成 signal 和 signal_flip 时被应用：  
    - 只多策略：不会生成空头 signal，也不会因为空头评估方向触发 signal_flip 平仓；  
    - 只空策略：反之同理；  
    - both：行为与原来一致。

### C7. `signal_indicators` 落库字段映射

- ✅ ts：是否使用当前 `now_ms`，单位为毫秒。  
- ✅ symbol：与当前 `SymbolState.symbol` 一致。  
- ✅ strategy：写入 `cfg["name"]`（legacy 名称）。  
- ✅ strategy_id：写入 `cfg["strategy_id"]`（uuid string）。  
- ✅ strategy_name_snapshot：写入 `cfg["strategy_name_snapshot"]`。  
- ✅ 所有指标字段：  
  - cvd_fast / cvd_mid / cvd_day / cvd_fast_slope；  
  - atr_5m / atr_percentile / atr_value；  
  - vwap_30m / price；  
  - p95_qty / p99_qty；  
  - cvd_fast_5m（仅 v53_fast 有值）；  
  是否与 `snapshot` / 重新计算的一致。  
- ✅ factors（JSON）：  
  - 是否包含 gate_passed / gate_block / atr_pct_price / obi_raw / spot_perp_div / whale_cvd_ratio；  
  - direction / crowding / environment / auxiliary 四个子对象的 score/max 等字段是否齐全。

### C8. `signal_feature_events`（如仍在使用）

- ✅ 只对 v53 系列策略写入（策略名以 "v53" 开头）。  
- ✅ 原始字段（cvd_fast_raw 等）是否与 `result` 中的一致。  
- ✅ score_direction / score_crowding / score_environment / score_aux 是否与 factors 中一致。  
- ✅ gate_passed / block_reason 是否正确记录，便于后期分析。

### C9. `paper_open_trade` 模拟盘开仓逻辑

- ✅ ATR <= 0 时是否直接拒绝开仓，避免无意义 SL/TP。  
- ✅ SL/TP 价格计算：  
  - LONG：`SL = price - risk_distance`，`TP1 = price + tp1_ratio × risk_distance`，`TP2 = price + tp2_ratio × risk_distance`；  
  - SHORT：`SL = price + risk_distance`，`TP1 = price - tp1_ratio × risk_distance`，`TP2 = price - tp2_ratio × risk_distance`；  
  - 旧版 JSON 策略仍按 `tp*_mult × ATR` 方式计算，属于兼容分支；  
  是否与 full-spec 中“以 R 计目标”的定义一致。  
- ✅ risk_distance = sl_multiplier × ATR 是否正确计算并写入。  
- ✅ SL 合理性校验：  
  - 实际 SL 距离是否在 [0.8, 1.2] × risk_distance 之间；  
  - 不满足时是否拒绝开仓并打日志（避免奇怪配置）。  
- ✅ 模拟盘全局开关：  
  - `PAPER_TRADING_ENABLED` / `PAPER_ENABLED_STRATEGIES` / `PAPER_MAX_POSITIONS` 是否生效；  
  - 同一策略是否有 per-strategy 的最大持仓控制（如无，需要记录）。  
- ✅ 写库字段：  
  - symbol / direction / score / tier / entry_price / entry_ts；  
  - tp1_price / tp2_price / sl_price / atr_at_entry；  
  - score_factors = factors JSON；  
  - strategy = `cfg["name"]`；  
  - strategy_id / strategy_name_snapshot；  
  - risk_distance；  
  是否全部正确写入，对应字段类型与含义与 full-spec 一致。

### C10. 重复开仓与持仓交互

- ✅ 当前设计是否允许“同一策略在同一 symbol 上同时有多笔持仓”（分批进场）。  
- ✅ 是否存在逻辑限制“同一策略同方向仅允许一笔活动持仓”，如果没有，需要明确这一点。  
- ✅ 与 `paper_monitor` 的交互：  
  - 反向 signal 是否会触发 signal_flip 平仓；  
  - 平仓后冷却和再开仓的行为是否符合预期。

### C11. 通知与其他 side-effect

- ✅ 当 `result["signal"]` 非空时，是否总是触发 `NOTIFY new_signal`，payload 格式是否是：  
  `"symbol:strategy:signal:score"`。  
- ✅ 当 gate_block 不为空（gate_passed=False）或 no_direction=True 时，是否绝不会发 NOTIFY。  
- ✅ 如果 live_executor 等进程依赖该 payload，是否已经约定好格式且长期不变。

---

## 6. 验证优先级建议

后续可以按下面优先顺序逐项打勾：

**P0（必须最先验证的）**

- A2：CVD 多窗口计算（5m/15m/30m/1h/4h 全链路）。  
- A3+A9：ATR / ATR 百分位 / 波动率门。  
- A5+A6：巨鲸、OBI、期现背离的数据源与符号方向。  
- C2+C3+C4+C6：五个 Gate + 四层评分 + entry/flip + cooldown 的交互。  
- C7+C9：`signal_indicators` / `paper_trades` 落库字段，特别是 strategy_id / strategy_name_snapshot 与 SL/TP/risk_distance。

**P1（中优先级）**

- B2~B7：`strategies` 表字段映射完整性、CVD 窗口、Gate 参数、方向限制。  
- C1：per-symbol 遍历逻辑与 symbol 过滤。  
- C8：`signal_feature_events` 的字段映射（如还在使用）。

**P2（相对低优先级）**

- 对权重缩放逻辑的长期行为做验证（C5），确保与预期一致；  
- 日志/监控是否足够支撑线上排查；  
- 未来如需长期在线学习，可在此基础上加更多验证点。

---

## 7. 使用方式（给人类 / AI 的操作建议）

- 把本文件当作 **审计 checklist**：  
  - 每次改动前，先在这里找相关条目，确认“期望行为”是什么；  
  - 审计现有代码时，对照这些条目逐项比对，实现与期望不一致的地方要记录为 bug。  
- 对于 P0 条目，建议配合：
  - 真实历史数据回放（从数据库抽样一段时间）；  
  - 针对单一策略 / 单一 symbol 的离线重算脚本（对比 signal_indicators / paper_trades）。  
- 改动任何 C 层（评分/开仓/落库）逻辑时，必须同时：  
  - 更新 `docs/arbitrage-engine-full-spec.md` 中对应章节；  
  - 在本验证清单中勾选/更新受影响的条目；  
  - 附上简短的“为什么这样改 + 对历史行为的影响”说明。

> 一句话：  
> 以后任何人（包括 AI）想动 signal_engine / 策略工厂，都应该先看 full-spec，再看这份验证清单，  
> 确保“为什么这么算”和“有没有算对”都在一个有记录的地方。