docs: expand v5.3 weight model and refactor implementation checklist

docs/arbitrage-engine/v53-design.md

@@ -40,32 +40,111 @@ Market Data -> Feature Snapshot -> Track Router -> Signal Decision -> Execution
 ## 4.1 ALT 轨（ETH/XRP/SOL）
 
 - 目标：保留 V5.1 有效微观结构 Alpha，去除冗余。
-- 分层结构（100分）：
-  - Direction: 55
-  - Crowding: 25
-  - Environment: 15
-  - Auxiliary: 5
 - 关键变更：取消独立 Confirmation 层（避免与 Direction 共线性重复计分）。
-- 初始开仓阈值：75（先稳态，不一次改太多）。
+- 决策机制：线性加权评分（总分 100）+ 门控 + 阈值。
-- 翻转阈值：85（高于开仓阈值，减少震荡内耗）。
+
+### 4.1.1 ALT 权重总表（V5.3 初版）
+
+| 层级 | 权重 | 子特征 | 子特征权重 | 说明 |
+|------|------|--------|------------|------|
+| Direction | 55 | `cvd_resonance` | 30 | `cvd_fast` 与 `cvd_mid` 同向共振 |
+| Direction | 55 | `p99_flow_alignment` | 20 | P99 大单方向与主方向一致 |
+| Direction | 55 | `cvd_accel_bonus` | 5 | CVD 加速度同向奖励 |
+| Crowding | 25 | `lsr_contrarian` | 15 | 多空比反向拥挤 |
+| Crowding | 25 | `top_trader_position` | 10 | 大户持仓方向确认 |
+| Environment | 15 | `oi_delta_regime` | 15 | OI 变化状态 |
+| Auxiliary | 5 | `coinbase_premium` | 5 | 美系现货溢价辅助 |
+
+### 4.1.2 ALT 子特征评分函数（标准化）
+
+- `cvd_resonance`（0/30）：
+  - LONG：`cvd_fast > 0 && cvd_mid > 0`
+  - SHORT：`cvd_fast < 0 && cvd_mid < 0`
+  - 否则 `0` 且 `gate_no_direction=true`
+- `p99_flow_alignment`（0/10/20）：
+  - 强同向净流：20
+  - 无明显反向压制：10
+  - 明显反向：0
+- `cvd_accel_bonus`（0/5）：
+  - 加速度方向与主方向一致：5
+- `lsr_contrarian`（0~15）：
+  - LONG：`lsr<=0.5` 高分，`0.5<lsr<1.0` 线性递减
+  - SHORT：`lsr>=2.0` 高分，`1.0<lsr<2.0` 线性递减
+- `top_trader_position`（0~10）：
+  - 与方向一致比例越高分越高
+- `oi_delta_regime`（0/7.5/15）：
+  - 资金显著流入：15
+  - 平稳：7.5
+  - 显著流出：0
+- `coinbase_premium`（0/2/5）：
+  - 顺向溢价：5
+  - 中性：2
+  - 反向：0
+
+### 4.1.3 ALT 决策阈值
+
+- `open_threshold = 75`
+- `flip_threshold = 85`
+- `max_positions_per_track = 4`
+- `cooldown_seconds = 300`
+
+### 4.1.4 ALT 信号总分公式
+
+```text
+score_alt = direction(55) + crowding(25) + environment(15) + auxiliary(5)
+open if score_alt >= 75 and no veto
+flip if reverse_score_alt >= 85 and no veto
+```
 
 ## 4.2 BTC 轨（独立模型）
 
 - 目标：针对机构主导盘口，提升信号有效性。
-- 首批核心特征：
+- 决策方式：先用“条件门控 + 否决条件”，不与 ALT 共用线性总分。
-  - `tiered_cvd_whale`：按成交额分层后的大单净流（如 >100k）。
+
-  - `obi_depth_10`：前 10 档订单簿失衡。
+### 4.2.1 BTC 核心特征
-  - `spot_perp_divergence`：现货与永续的价量背离。
+
-  - `atr_percent_1h`：1小时 ATR 占当前价格百分比（波动率状态门控）。
+- `atr_percent_1h`：1小时 ATR 占当前价格百分比（波动率门控）
-- 决策方式：先用“条件门控 + 否决条件”，暂不强行做线性总分。
+- `tiered_cvd_whale`：按成交额分层的大单净流（建议主桶 `>100k`）
-- 波动率门控：当 `atr_percent_1h` 低于阈值时，直接否决 BTC 开仓（低波动噪音阶段保护）。
+- `obi_depth_10`：盘口前 10 档失衡
-- 原则：BTC 轨独立评估，不与 ALT 汇总后做统一结论。
+- `spot_perp_divergence`：现货与永续价量背离
+
+### 4.2.2 BTC 门控与否决逻辑
+
+- 波动率门控：`atr_percent_1h < min_vol_threshold` -> veto
+- 方向门控：巨鲸净流未达阈值 -> veto
+- 挂单墙否决：方向与 OBI 显著冲突 -> veto
+- 期现背离否决：perp 强多但 spot 弱（或反向）-> veto
+
+### 4.2.3 BTC 参数（初始值，可配置）
+
+- `min_vol_threshold = 0.002`（0.2%）
+- `obi_veto_threshold = 0.30`
+- `whale_flow_threshold`：按币价与流动性分档配置
+- 以上参数均定义为配置项，禁止散落硬编码。
+
+### 4.2.4 BTC 决策伪代码
+
+```text
+if missing_any_feature:
+  block("missing_feature")
+if atr_percent_1h < min_vol_threshold:
+  block("low_vol_regime")
+if abs(tiered_cvd_whale) < whale_flow_threshold:
+  block("weak_whale_flow")
+if direction_conflict_with_obi:
+  block("obi_imbalance_veto")
+if spot_perp_divergence_is_trap:
+  block("spot_perp_divergence_veto")
+otherwise:
+  allow_open
+```
 
 ## 5. 数据基建（ML Ready）
 
 ## 5.1 表设计
 
 ### `signal_feature_events`
+
 - 用途：每次信号评估快照（无论是否开仓）。
 - 关键字段：
   - 元数据：`event_id, ts, symbol, track, side`
@@ -74,31 +153,33 @@ Market Data -> Feature Snapshot -> Track Router -> Signal Decision -> Execution
   - 决策：`score_total, score_direction, score_crowding, score_environment, score_aux, gate_passed, block_reason`
 
 ### `signal_label_events`
+
 - 用途：延迟回填标签，评估信号纯预测能力。
 - 字段：`event_id, y_binary_30m, y_binary_60m, y_return_15m, y_return_30m, y_return_60m, mfe_r_60m, mae_r_60m`
 
 ### `execution_cost_events`
+
 - 用途：独立归因执行成本。
-- 字段：`trade_id, entry_type, exit_type, fee_bps, slippage_bps, maker_ratio, flip_flag, hold_seconds`
+- 字段：`trade_id, entry_type, exit_type, fee_bps, slippage_bps, maker_ratio, flip_flag, hold_seconds, friction_cost_r`
 
 ## 5.2 标签定义
 
-- `Y_binary_60m`（严格定义）：从信号触发时间 `ts` 起 60 分钟内，使用 `Mark Price` 序列判定，若价格先触及 `+2.0 ATR`，且在该触发时刻之前从未触及 `-1.0 ATR`，则记为 `1`，否则记为 `0`。
+- `Y_binary_60m`（严格定义）：从信号触发时间 `ts` 起 60 分钟内，使用 `Mark Price` 序列判定，若价格先触及 `+2.0 * atr_value`，且在该触发时刻之前从未触及 `-1.0 * atr_value`，则记为 `1`，否则记为 `0`。
-- 时间顺序要求（Chronological Order）：若 60 分钟窗口内先触及 `-1.0 ATR`，即使后续再触及 `+2.0 ATR`，也必须记为 `0`。
+- 时间顺序要求（Chronological Order）：若 60 分钟窗口内先触及 `-1.0 * atr_value`，即使后续再触及 `+2.0 * atr_value`，也必须记为 `0`。
 - `Y_return_t`：固定时间窗（15m/30m/60m）净收益率（含成本估计）。
 
 说明：
 - 标签优先评价“信号有效性”，而不是被具体 TP/SL 参数污染的最终交易结果。
-- 统一使用 `Mark Price`，避免最新成交价插针导致的假标签。
+- 统一使用 `Mark Price` + `atr_value` 快照，避免插针和重算偏差。
 
 ## 6. 执行引擎改造
 
 1. **TP 优先 Maker + Taker 兜底**：入场后预挂 TP1/TP2 限价单；若价格已越过 TP 触发价且挂单在超时窗口（如 2 秒）内仍未成交，立即撤单并用 Taker 市价平仓兜底。
-2. **Break-Even 费用感知**：BE 触发价需覆盖手续费与滑点缓冲，避免“名义保本、账户实亏”。
+2. **部分成交分支**：兜底前查询成交量，仅对剩余仓位执行 `Cancel -> Taker Close`。
-3. **Flip 双门槛**：
+3. **Break-Even 费用感知**：BE 触发价需覆盖手续费与滑点缓冲，避免“名义保本、账户实亏”。
-   - 开仓阈值：75
+4. **Flip 双门槛**：开仓阈值 `75`，翻转阈值 `85`。
-   - 翻转阈值：85
+5. **并发和幂等**：`Cancel -> Market` 需要状态锁和幂等键，防止重复平仓。
-4. **执行质量指标化**：持续监控 `maker_ratio / avg_fee_r / flip_loss_r`。
+6. **执行质量指标化**：持续监控 `maker_ratio / avg_friction_cost_r / flip_loss_r`。
 
 ## 7. 反过拟合协议（强制）
 
@@ -108,20 +189,50 @@ Market Data -> Feature Snapshot -> Track Router -> Signal Decision -> Execution
 4. **升级门槛**：样本外结果不达标不得进入下一阶段。
 5. **可解释性检查**：无金融逻辑支撑的“高胜率规则”禁止上线。
 
-## 8. 发布与回滚机制
+## 8. 模型权重训练与更新机制（新增）
+
+## 8.1 参数分层
+
+- `static_params`：交易风控硬约束（如最大仓位、最大回撤阈值）
+- `tunable_params`：可训练参数（ALT 子特征权重、阈值、BTC 门控阈值）
+- `release_params`：版本发布参数（`strategy_version`, `config_hash`）
+
+## 8.2 ALT 权重训练流程
+
+1. 用 `signal_feature_events + signal_label_events` 生成训练集。
+2. 先做单变量稳定性审计（IC、分箱胜率、PSI）。
+3. 再做有约束优化：
+   - 权重非负
+   - 总和固定为 100
+   - 单层权重变化设上限（如不超过上版的 30%）
+4. 在 OOS 上评估，未达标不发布。
+
+## 8.3 BTC 阈值训练流程
+
+1. 针对每个门控特征做阈值网格搜索。
+2. 以 OOS `net_r + drawdown` 共同评分。
+3. 选择 Pareto 最优点，不追单一胜率最优。
+
+## 8.4 参数更新节奏
+
+- 建议频率：每 1-2 周滚动一次。
+- 每次仅允许小步更新，避免参数跳变。
+- 每次更新必须附带变更记录：`old -> new`、样本窗口、验证结果。
+
+## 9. 发布与回滚机制
 
 - 每次策略升级必须生成新 `strategy_version` 和 `config_hash`。
 - 发版前必须附带：训练窗结果 + 验证窗（OOS）结果 + 执行成本变化。
 - 任一核心指标触发阈值告警（如净R断崖、回撤超限）立即回滚到上一稳定版本。
 
-## 9. 版本验收标准（V5.3）
+## 10. 版本验收标准（V5.3）
 
 - ALT 轨：样本外连续两个窗口净R为正。
 - BTC 轨：样本外净R非负，且胜率不低于随机基线。
 - 执行层：`maker_ratio >= 40%`，且 `avg_friction_cost_r`（滑点+手续费）较 V5.1 基线下降 >= 30%。
 - 稳定性：最大回撤不显著劣化。
 
-## 10. 里程碑
+## 11. 里程碑
 
 - M1：完成三张新表与事件落库。
 - M2：完成 ALT/BTC 路由与首版决策逻辑。

docs/arbitrage-engine/v53-implementation-checklist.md

@@ -6,34 +6,47 @@ updated: 2026-03-03
 
 # V5.3 实施清单
 
-## P0（必须先完成）
+## Phase 0 - 数据与追溯基建（P0）
 
 - [ ] 新增 `signal_feature_events` 表（含索引）
 - [ ] 新增 `signal_label_events` 表（含索引）
 - [ ] 新增 `execution_cost_events` 表（含索引）
-- [ ] 在信号评估循环中落库 feature snapshot（每次评估都写）
 - [ ] `signal_feature_events` 增加 `atr_value` 字段（信号触发时 ATR 绝对值快照）
+- [ ] 在信号评估循环中落库 feature snapshot（每次评估都写）
 - [ ] 打通统一追溯字段：`strategy_version/config_hash/engine_instance`
+- [ ] 标签回填任务上线（15m/30m/60m）
+- [ ] 标签回填强制使用 Mark Price，并按时间顺序判定先触发条件
+- [ ] 标签计算强制使用快照 `atr_value`（禁止回填时重算 ATR）
+
+## Phase 1 - 决策引擎重构（P0）
+
 - [ ] 实现 ALT/BTC 路由器（按 symbol 分流）
 - [ ] ALT 轨移除独立 confirmation 层，改为四层结构
-- [ ] 增加 flip 双门槛：`open=75`, `flip=85`
+- [ ] ALT 轨实现权重分配：`55/25/15/5`
+- [ ] ALT 轨实现阈值：`open=75`, `flip=85`
+- [ ] BTC 轨首版特征：`tiered_cvd_whale`, `obi_depth_10`, `spot_perp_divergence`, `atr_percent_1h`
+- [ ] BTC 轨门控逻辑上线（含 veto 条件）
+- [ ] BTC 轨缺失特征默认 `BLOCK_SIGNAL`，并写入 `block_reason`
+- [ ] BTC 轨阈值配置化：`min_vol_threshold`, `obi_veto_threshold`, `whale_flow_threshold`
+
+## Phase 2 - 执行层与摩擦成本优化（P0）
+
 - [ ] 执行层支持 TP 预挂单（maker 优先）
 - [ ] 增加 TP 未成交兜底：越价+超时后撤 maker 改 taker 强平
+- [ ] 增加“部分成交”分支：仅对剩余仓位执行兜底
 - [ ] Break-Even 改为费用感知（含手续费+滑点缓冲）
-- [ ] 新增标签回填任务（15m/30m/60m）
+- [ ] `Cancel -> Market` 增加状态锁与幂等键
-- [ ] 标签回填强制使用 Mark Price，并按时间顺序判定先触发条件
+- [ ] 新增执行成本统计任务（fee/slippage/maker_ratio/friction_cost_r）
 
-## P1（强烈建议本期完成）
+## Phase 3 - 评估与发布闸门（P1）
 
-- [ ] BTC 轨首版特征：`tiered_cvd_whale`, `obi_depth_10`, `spot_perp_divergence`, `atr_percent_1h`
-- [ ] BTC 轨采用门控逻辑（含 veto 条件）
-- [ ] 新增执行成本统计任务（fee/slippage/maker_ratio）
 - [ ] 新增按 `config_hash` 分组报表接口
 - [ ] 新增按 `track` 分组报表接口（ALT/BTC 分开看）
 - [ ] 建立 Walk-Forward 评估脚本（训练窗+验证窗）
 - [ ] 产出首版 V5.3 OOS 报告模板
+- [ ] 新增参数变更记录模板（`old -> new` + 样本窗口 + OOS结果）
 
-## P2（优化项）
+## Phase 4 - 持续优化（P2）
 
 - [ ] 特征 shadow 机制（新因子先记录不参与决策）
 - [ ] 自动化回滚钩子（核心KPI超阈值触发）
@@ -44,6 +57,7 @@ updated: 2026-03-03
 ## 数据库建议（草案）
 
 ## `signal_feature_events`
+
 - 主键：`event_id`
 - 必要索引：
   - `(ts)`
@@ -52,33 +66,38 @@ updated: 2026-03-03
   - `(strategy_version, config_hash, ts DESC)`
 
 ## `signal_label_events`
+
 - 主键：`event_id`
 - 必要索引：
   - `(y_binary_60m, ts)`
   - `(symbol, ts DESC)`
 
 ## `execution_cost_events`
+
 - 主键：`trade_id`
 - 必要索引：
   - `(ts)`
   - `(symbol, ts DESC)`
   - `(entry_type, exit_type, ts DESC)`
 
-## 验证清单（上线前）
+## 上线前验证清单
 
 - [ ] feature 事件写入无丢失，延迟可接受
 - [ ] label 回填任务无时间错位
 - [ ] ALT/BTC 路由正确（BTC 不落入 ALT）
+- [ ] BTC 缺失特征不会静默放行
 - [ ] maker 优先在真实成交中可观测
+- [ ] TP 兜底分支含部分成交路径可复现
 - [ ] BE 逻辑覆盖成本后，不再出现“保本但净亏”异常
 - [ ] flip 频次和 flip 损耗下降
 - [ ] OOS 报告通过预设阈值
 
-## 发布闸门（建议）
+## 发布闸门（量化指标）
 
 - [ ] ALT：连续两个 OOS 窗口净R > 0
 - [ ] BTC：OOS 净R >= 0 且胜率 >= 随机基线
-- [ ] `maker_ratio >= 40%`，且 `avg_friction_cost_r`（滑点+手续费）较 V5.1 下降 >= 30%
+- [ ] `maker_ratio >= 40%`
+- [ ] `avg_friction_cost_r`（滑点+手续费）较 V5.1 下降 >= 30%
 - [ ] 最大回撤不高于风险红线
 
 ## 任务分配建议