Metadata-Version: 2.4
Name: tp-quant
Version: 1.6.8
Summary: Trading Pattern Scanner Identifies complex patterns like head and shoulder, wedge and many more.
Author: Preetam Sharma
License: CC BY-NC-SA 4.0
Requires-Python: ==3.12.*
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy>=2.0.0
Requires-Dist: pandas<4,>=3.0.0
Requires-Dist: kdata-quant>=2.2.6
Requires-Dist: TA-Lib>=0.4.32
Requires-Dist: pyyaml>=6.0
Requires-Dist: pyarrow>=25.0.1
Provides-Extra: backtest
Requires-Dist: backtrader>=1.9.78.123; extra == "backtest"
Dynamic: license-file

# Python API 接口参考文档 (API Reference)

本文档面向需要在下游系统（如 LLM AI Agent、量化自动化交易流水线、复盘看板）中直接集成 `tp-quant` 的开发者。

安装包：`pip install tp-quant`

> [!TIP]
> 🌟 **多周期协同与自适应契约 (Multi-Timeframe & Adaptation Guide)**  
> 核心引擎根据交易定位设计了严谨的周期输入契约与跨周期共振机制：
> - **全域机会雷达与趋势跟踪 (Opportunity Radar / Kaufman)**：支持传入**日线 (Daily)** 或 **周线 (Weekly)** 数据（可通过 `timeframe="daily"|"weekly"` 指定或由引擎自适应推断），在日线分析时会自动结合周线大趋势进行跨周期共振确认。
> - **均值回归策略 (Mean Reversion / Engine 2)**：标准设计契约要求传入**日线 (Daily)** OHLCV 数据，引擎内部会自动将其动态聚合为周线以判定周线布林带超跌与底部反转形态，并在日线级别执行 T+1 开盘撮合与三阶段动态跟踪止损。

---

## 🎯 核心架构速查与对应关系 (Architecture & Quick Navigation)

`tp-quant` 的核心能力由 **全雷达体系 (Opportunity Radar)** 与 **交易执行双核体系 (Dual-Core Strategy Engines)** 组成，各自解决不同场景的需求：

| 体系 / 核心概念 | 解决什么问题 | 外部调用 Python API | 对应文档章节 |
| :--- | :--- | :--- | :--- |
| **🌐 全雷达体系**<br>(Opportunity Radar) | **全市场/全池选品与四栏异动扫描**<br>四栏式全域互斥去重归类（量化异动/预警观察/潜在机会/风险提示），计算动态防守线与双距离 | `analyze_opportunity_radar()`<br>`evaluate_opportunity_radar_item()`<br>`OpportunityRadarConfig` | [第 1 章 (1.2, 1.3)](#1-全域机会雷达综合引擎-combined-opportunity-radar) |
| **🧭 核心 1：右侧趋势突破**<br>(Engine 1 / Trend Breakout) | **交易执行：右侧主升浪做多**<br>抓放量结构突破 + EMA20 回踩确认 + EMA53 移动跟踪 | `get_strategy_signal(StrategyEngine.ENGINE1_TREND, df)` | [第 1 章 (1.1, 1.2)](#1-全域机会雷达综合引擎-combined-opportunity-radar) |
| **⚡ 核心 2：左侧均值回归**<br>(Engine 2 / Mean Reversion) | **交易执行：左侧大波段抄底**<br>抓周线布林超跌 + K线底部反转 + 3阶段跟踪止盈 (Stage 1/2/3) + 熊市冷却 | `get_mean_reversion_signal()`<br>或 `get_strategy_signal(StrategyEngine.ENGINE2_REVERSAL, df)` | [第 6 章 (6.1)](#6-均值回归与板块轮动引擎-mean_reversion--sector_rotation) |
| **🔄 超跌企稳独立引擎**<br>(Oversold & Stabilized，**不经 `get_strategy_signal` 分发**) | **周线超跌筑底质量评估与左侧早期埋伏**<br>波动率自适应回撤门禁 + TA-Lib 底部形态矩阵 + 周线筑底质量 0-10 分，输出 `OVERSOLD_ALERT` / `WAITING_DAILY` / `TRIGGERED` 三档 | `check_oversold_stabilized()`<br>`get_extreme_reversal_signal()` | [第 6 章 (6.8)](#68-超跌企稳独立引擎-oversold--stabilized) |
| **🌟 双核综合引擎**<br>(Combined Engine) | **双核同时运行 / 实盘仿真回测**<br>左侧 + 右侧信号一起抓，用于全历史实战回测与多策略综合调度 | `get_strategy_signal(StrategyEngine.COMBINED, df)`<br>`run_strategy_engine_simulation()` | [第 1 章 (1.1, 1.4)](#1-全域机会雷达综合引擎-combined-opportunity-radar) |
| **🔎 雷达辅助筛选层**<br>(Radar Selectors) | **从雷达结果中提纯目标清单**<br>通用筛选原语 + 超跌族/买点族/观察族/风险族共 20 个纯函数，不重算引擎 | `filter_radar_items()`<br>`get_high_quality_oversold_stabilized()`<br>`get_oversold_watchlist()`<br>`get_golden_pullback_second_buys()` | [第 1 章 (1.6)](#16-雷达辅助筛选层-radar-selectors) |
| **📊 截面板块轮动**<br>(Sector Rotation) | **多标的资产配置与强弱轮动**<br>以沪深300为基准，计算 RS 相对强弱与 4 象限分布 (领涨/复苏/衰退/滞后) | `SectorRotationEngine`<br>`run_sector_rotation_backtest()` | [第 6 章 (6.4~6.7)](#6-均值回归与板块轮动引擎-mean_reversion--sector_rotation) |
| **🗽 美股专属量化双核**<br>(US Quantitative System) | **美股自适应超级趋势与截面双动量**<br>宏观 SPY SMA200/10月动量体制判别、KAMA 吊灯超级趋势、截面行业轮动、0-10 分 5 大态机会雷达（支持统一门面 `timeframe="D"/"W"`） | `run_us_strategy()`<br>`compute_us_rotation()`<br>`analyze_us_radar()` | [第 7 章 (7.1~7.5)](#7-美股专属量化系统与机会雷达-us-etf-quantitative-system--radar) |
| **🌏 跨境溢价共振**<br>(Overseas Premium) | **跨境 QDII ETF 溢价风控与套利**<br>盘后时差对齐 (国内T日锚定美股T-1日)，60日比价偏离度 Z-Score 门禁 + 美股周线强趋势共振 + 全池机会雷达 | `evaluate_overseas_opportunity_item()`<br>`analyze_overseas_radar()`<br>`run_overseas_premium_strategy()` | [第 8 章 (8.1~8.5)](#8-跨境-qdii-etf-溢价套利与趋势共振引擎-overseas_premium) |
| **🛡️ 交易撮合与执行生命周期**<br>(Execution Matcher) | **A 股实盘仿真与未成交追踪**<br>开盘一字涨跌停拦截、停牌检测、滑点佣金仿真、未成交信号生命周期归档与成交率统计 | `ExecutionMatcher`<br>`compute_execution_summary()`<br>`get_a_share_price_limit_ratio()` | [第 9 章 (9.1~9.3)](#9-实盘撮合与信号全生命周期追踪-execution) |
| **🗓️ 机会生命周期跟踪**<br>(Opportunity Lifecycle) | **纵向时间演变跟踪与滚动回放**<br>雷达标的入池双门禁（质量 Top-N + 看涨形态确认）、5 阶段推进、主动止盈 / 破位双确认出池、逐日进池出池流转日志 | `select_trackable_opportunities()`<br>`confirm_bullish_formation()`<br>`track_opportunity_lifecycle()`<br>`track_radar_report()` | [第 11 章 (11.1~11.6)](#11-机会生命周期跟踪与滚动回放-opportunity_lifecycle) |
| **📈 统一行情获取与标准化**<br>(Unified Market Data) | **股票/ETF/指数/美股统一行情拉取**<br>标的类型自动路由、前缀规整自愈（如 `000300` 自动规整为 `sh.000300`）、异常自愈重试与标准化全小写 DatetimeIndex OHLCV 数据输出 | `get_any_ohlc()`<br>`is_likely_index()`<br>`normalize_index_symbol()` | [第 12 章 (12.1~12.4)](#12-统一行情数据获取与标准化接口-get_any_ohlc) |

---

## 目录索引 (Table of Contents)

1. [全域机会雷达综合引擎 (Combined Opportunity Radar)](#1-全域机会雷达综合引擎-combined-opportunity-radar)
   - 1.1 [统一策略枚举与事件契约 (`StrategyEngine`)](#11-统一策略枚举与事件契约)
   - 1.2 [单标的雷达信号调用 (`get_strategy_signal` / `evaluate_opportunity_radar_item`)](#12-单标的雷达信号调用)
   - 1.3 [全市场多周期雷达批量扫描 (`analyze_opportunity_radar`)](#13-全市场多周期雷达批量扫描-analyze_opportunity_radar)
   - 1.4 [技术信号层与实盘执行层的核心区别 (`get_strategy_signal` vs `run_strategy_engine_simulation`)](#14-技术信号层与实盘执行层的核心区别)
   - 1.5 [全景回测与实战验证 CLI](#15-全景回测与实战验证-cli)
   - 1.6 [雷达辅助筛选层 (Radar Selectors)](#16-雷达辅助筛选层-radar-selectors)
   - 1.7 [机会雷达战法专题看板体系 (3+1 实战击球与 11 大战法)](#17-机会雷达战法专题看板体系-31-实战击球与-11-大战法)
3. [技术形态扫描与预筛选管道 (`pre_screen_and_scan`)](#3-技术形态扫描与预筛选管道-pre_screen_and_scan)
   - 3.1 [预筛选与扫描主接口](#31-预筛选与扫描主接口)
   - 3.2 [Context Package 上下文数据包全字段解析](#32-context-package-上下文数据包全字段解析)
   - 3.3 [威科夫量价供需分析 (`detect_wyckoff_context`)](#33-威科夫量价供需分析-detect_wyckoff_context)
4. [市场状态机与多周期趋势评估](#4-市场状态机与多周期趋势评估)
   - 4.1 [综合唯一主状态机 (`detect_side_state`)](#41-综合唯一主状态机-detect_side_state)
   - 4.2 [做多右侧状态机 (`detect_right_side_state`)](#42-做多右侧状态机-detect_right_side_state)
   - 4.3 [底部结构跟踪状态机 (`detect_bottom_tracking_state`)](#43-底部结构跟踪状态机-detect_bottom_tracking_state)
   - 4.4 [独立周线中期趋势质量评分 (`evaluate_weekly_trend`)](#44-独立周线中期趋势质量评分-evaluate_weekly_trend)
5. [市场环境与辅助分析工具](#5-市场环境与辅助分析工具)
   - 5.1 [市场情绪温度计 (`sentiment_thermometer`)](#51-市场情绪温度计-sentiment_thermometer)
   - 5.2 [动态支撑阻力计算 (`calculate_support_resistance`)](#52-动态支撑阻力计算-calculate_support_resistance)
   - 5.3 [组合风险平权与相关性去重](#53-组合风险平权与相关性去重)
6. [均值回归与板块轮动引擎 (`mean_reversion` & `sector_rotation`)](#6-均值回归与板块轮动引擎-mean_reversion--sector_rotation)
   - 6.1 [A 股周线均值回归与三阶段跟踪 (`get_mean_reversion_signal` / `MeanReversionSignal`)](#61-a-股周线均值回归与三阶段跟踪-get_mean_reversion_signal)
   - 6.2 [TA-Lib 底部反转形态扫描与权重 (`scan_talib_patterns`)](#62-ta-lib-底部反转形态扫描与权重-scan_talib_patterns)
   - 6.3 [均值回归事件驱动回测 (`run_mean_reversion_simulation`)](#63-均值回归事件驱动回测-run_mean_reversion_simulation)
   - 6.4 [全池截面轮动评估与纯趋势研判 (`evaluate_universe`)](#64-全池截面轮动评估与纯趋势研判-evaluate_universe)
   - 6.5 [四象限坐标体系与动能研判逻辑](#65-四象限坐标体系与动能研判逻辑)
   - 6.6 [截面状态指标 (`SectorMetric` / `RotationQuadrant`)](#66-截面状态指标-sectormetric--rotationquadrant)
   - 6.7 [截面组合历史回测 (`run_sector_rotation_backtest`)](#67-截面组合历史回测-run_sector_rotation_backtest)
   - 6.8 [超跌企稳独立引擎 (Oversold & Stabilized)](#68-超跌企稳独立引擎-oversold--stabilized)
7. [美股专属量化系统与机会雷达 (`us_macro` / `us_strategy` / `us_opportunity_radar`)](#7-美股专属量化系统与机会雷达-us-etf-quantitative-system--radar)
   - 7.1 [宏观绝对动量与体制判别 (`us_macro`)](#71-宏观绝对动量与体制判别-us_macro)
   - 7.2 [自适应超级趋势与截面双动量策略 (`us_strategy` / `us_weekly_strategy`)](#72-自适应超级趋势与截面双动量策略-us_strategy)
   - 7.3 [美股专属 0-10 分机会雷达与 5 大状态机 (`us_opportunity_radar` / `us_weekly_opportunity_radar`)](#73-美股专属-0-10-分机会雷达与-5-大状态机-us_opportunity_radar)
   - 7.4 [多周期统一门面入口 (`run_us_strategy` / `compute_us_rotation` / `analyze_us_radar`)](#74-多周期统一门面入口)
   - 7.5 [美股专属大类资产均值回归引擎 (`us_mean_reversion`)](#75-美股专属大类资产均值回归引擎-us_mean_reversion)
   - 7.6 [美股全景回测与雷达扫描 CLI](#76-美股全景回测与雷达扫描-cli)
8. [跨境 QDII ETF 溢价套利与趋势共振引擎 (`overseas_premium`)](#8-跨境-qdii-etf-溢价套利与趋势共振引擎-overseas_premium)
   - 8.1 [底层资产映射与盘后时差对齐 (`OVERSEAS_UNDERLYING_MAP` / `align_cn_us_series`)](#81-底层资产映射与盘后时差对齐)
   - 8.2 [60日相对比价偏离度计算 (`calculate_premium_zscore`)](#82-60日相对比价偏离度计算)
   - 8.3 [单标的实时机会与信号评估 (`evaluate_overseas_opportunity_item` / `get_overseas_premium_signal`)](#83-单标的实时机会与信号评估)
   - 8.4 [跨境全池机会雷达批量扫描 (`analyze_overseas_radar` / `OverseasRadarSummary`)](#84-跨境全池机会雷达批量扫描)
   - 8.5 [双核共振策略回测与绩效寻优 (`run_overseas_premium_strategy`)](#85-双核共振策略回测与绩效寻优)
9. [实盘撮合与信号全生命周期追踪 (`execution`)](#9-实盘撮合与信号全生命周期追踪-execution)
   - 9.1 [交易所物理约束与涨跌停比例 (`get_a_share_price_limit_ratio` / `ExecutionStatus`)](#91-交易所物理约束与涨跌停比例)
   - 9.2 [次日开盘撮合可行性仿真 (`ExecutionMatcher`)](#92-次日开盘撮合可行性仿真-executionmatcher)
   - 9.3 [未成交信号追踪与生命周期汇总 (`UnfilledSignal` / `compute_execution_summary`)](#93-未成交信号追踪与生命周期汇总)
10. [四大经典战术买点与全生命周期形态识别 (`tactical_patterns`)](#10-四大经典战术买点与全生命周期形态识别-tactical_patterns)
   - 10.1 [威科夫量化生命周期四大战术形态契约 (`TacticalPatternType` / `TacticalPatternSignal`)](#101-威科夫量化生命周期四大战术形态契约)
   - 10.2 [单买点独立判定函数 (`detect_bottom_reversal` / `detect_ma_startup` / `detect_volume_breakout` / `detect_pullback_low_absorb`)](#102-单买点独立判定函数)
   - 10.3 [全量战术买点扫描与自适应仓位建议 (`scan_tactical_patterns`)](#103-全量战术买点扫描与自适应仓位建议)
11. [机会生命周期跟踪与滚动回放 (`opportunity_lifecycle`)](#11-机会生命周期跟踪与滚动回放-opportunity_lifecycle)
   - 11.1 [生命周期阶段与准入/退出枚举 (`LifecycleStage` / `EntryChannel` / `ExitReason` / `PoolEventType`)](#111-生命周期阶段与准入退出枚举)
   - 11.2 [入池双门禁 (`confirm_bullish_formation` / `select_trackable_opportunities`)](#112-入池双门禁)
   - 11.3 [出池三通道与阈值 (主动止盈 + 破位双确认)](#113-出池三通道与阈值)
   - 11.4 [单标的生命周期推导 (`track_opportunity_lifecycle`)](#114-单标的生命周期推导)
   - 11.5 [全池跟踪账本与逐日滚动回放 (`replay_opportunity_pool` / `OpportunityTrackingBook` / `OpportunityFlowEvent`)](#115-全池跟踪账本与逐日滚动回放)
   - 11.6 [逐日滚动回放实战范式与窗口调优](#116-逐日滚动回放实战范式与窗口调优)
12. [统一行情数据获取与标准化接口 (`get_any_ohlc`)](#12-统一行情数据获取与标准化接口-get_any_ohlc)
   - 12.1 [设计背景与数据源规整原则](#121-设计背景与数据源规整原则)
   - 12.2 [标的代码智能路由与格式规整 (`is_likely_index` / `normalize_index_symbol`)](#122-标的代码智能路由与格式规整)
   - 12.3 [核心统一获取函数 (`get_any_ohlc`)](#123-核心统一获取函数-get_any_ohlc)
   - 12.4 [标准化 OHLCV 输出结构与实战调用范式](#124-标准化-ohlcv-输出结构与实战调用范式)

---

## 1. 全域机会雷达综合引擎 (Combined Opportunity Radar)

**全域机会雷达综合引擎 (`Combined Radar`) 采用“交易执行双核 (Dual Cores) + 选品形态雷达 (Pattern Radar) + 截面板块轮动 (Sector Rotation)”分层架构**。

它将复杂的形态发现、宏观截面与严谨的量化执行解耦：
1. **📊 经典形态雷达层 (Pattern Radar)**：负责 10+ 经典几何形态（头肩底、双底、杯柄、三角形突破）识别、0-10 综合技术评分与自媒体图文可视化；
2. **⚡ 左侧均值回归核 (Left-Side Core - Engine 2 / Mean Reversion)**：周线布林超跌 + TA-Lib K 线底部形态 + 三阶段跟踪止盈 (Stage 1/2/3) + 熊市止损冷却与假摔快速重入保护；
3. **🧭 右侧趋势突破核 (Right-Side Core - Engine 1 / Trend Breakout)**：右侧放量突破结构 + EMA20 回踩确认 + EMA53 防守跟踪主升浪；
4. **🌐 截面板块轮动与全天候自适应**：四象限相对强度软打分赋能雷达；同时独立提供 Kaufman KAMA 自适应趋势引擎 (Engine 3)。

```
                  ┌────────────────────────────────────────────────────────────┐
                  │              StrategySignalEvent 统一信号契约              │
                  │  (buy_signal, sell_signal, stop_loss, take_profit, reason) │
                  └─────────────────────────────┬──────────────────────────────┘
                                                │
                          【Combined Opportunity Radar 综合雷达】
                       StrategyEngine.COMBINED / analyze_opportunity_radar
                                                │
         ┌──────────────────────────────────────┴──────────────────────────────────────┐
         ▼                                                                             ▼
【⚡ 左侧均值回归核 (Engine 2 / MR)】                          【🧭 右侧趋势突破核 (Engine 1 / Trend)】
  周线布林超跌 + TA-Lib底部形态 + 三阶段止盈                      右侧放量突破 + EMA20回踩 + EMA53动态跟踪
         ▲                                                                             ▲
         └──────────────────────────────┬──────────────────────────────────────────────┘
                                        │ 选品形态赋能 & 截面轮动加权
              【📊 经典形态雷达 (Pattern Radar) & 🌐 板块轮动四象限 (Sector Rotation)】
                       头肩底 / 双底 / 杯柄 / 三角形 / 0-10综合评分 / 领涨-复苏-衰退-滞后
```

---

### 1.1 统一策略枚举与事件契约

```python
from tradingpatterns import (
    StrategyEngine,                 # 核心策略枚举类 (COMBINED, MEAN_REVERSION, ENGINE1_TREND, ENGINE2_REVERSAL, ENGINE3_KAUFMAN)
    EngineType,                     # StrategyEngine 别名
    get_strategy_signal,            # 顶层统一单策略信号分发器 (E1/E2/E3/MR)
    evaluate_opportunity_radar_item,# 单标的全维度雷达评估
    analyze_opportunity_radar,      # 全池多周期雷达批量扫描 (内嵌板块轮动)
    OpportunityRadarConfig,         # 雷达扫描配置类 (门槛、钝化周期、防追高、技术面 cutoff)
    StrategySignalEvent,            # 统一信号事件基类
    deduce_exit_metadata,           # 标准化平仓元数据与标签推断
    run_strategy_engine_simulation, # 单标的纯量化撮合回测仿真
)
```

#### 策略引擎枚举 (`StrategyEngine`)：
- **`ENGINE1_TREND` / `ENGINE1`**: 右侧趋势突破引擎 (放量突破 + EMA20 回踩 + EMA53 移动跟踪)。
- **`ENGINE2_REVERSAL` / `MEAN_REVERSION`**: A 股周线均值回归与三阶段跟踪引擎 (周线布林超跌 + TA-Lib K 线底部形态 + 3-Stage 跟踪止盈 + 熊市止损冷却与假摔快速重入)。
- **`ENGINE3_KAUFMAN` / `ENGINE3`**: Kaufman KAMA 全天候自适应趋势引擎。
- **`COMBINED`**: 全域机会雷达双核综合引擎 (Engine 1 + Engine 2，用于全池雷达与组合回测)。

#### 统一返回对象 (`StrategySignalEvent` 标准契约)：
支持属性访问（`sig.buy_signal`）与字典键访问（`sig["buy_signal"]`）：

| 字段/属性 | 类型 | 说明 |
| :--- | :--- | :--- |
| **`buy_signal`** | `bool` | 是否触发次日开盘买入信号。 |
| **`sell_signal`** | `bool` | 是否触发次日开盘卖出/离场信号。 |
| **`stop_loss`** | `float` | 建议的量化止损防守线（破位即走；具体保护幅度按策略与周期自适应）。 |
| **`take_profit`** | `float` | 建议的目标止盈价/关键阻力位（到达考虑减仓止盈）。 |
| **`signal_tier`** | `str \| None` | 信号确定性分级 (`"L3"` 强信号 \| `"L2"` 中等/接力 \| `"L1"` 预警关注 \| `None`)。 |
| **`reason`** | `str` | 信号触发的详细原因说明。 |
| **`state`** | `str` | 策略内部状态机状态 / 体制（如 `"RIGHT_CONFIRMED"`, `"TREND_BULL"`, `"TRIGGERED"`, `"COOLDOWN"`）。 |
| **`symbol`** | `str` | 标的代码。 |
| **`date`** | `str` | 信号产生的 K 线日期 (`YYYY-MM-DD`)。 |
| **`details`** | `dict` | 包含底层指标、KAMA 生命线、周线宏观状态与形态元数据的完整字典。 |

---

### 1.2 单标的雷达信号调用

#### 方式一：调用单策略引擎信号接口 (`get_strategy_signal`)
`get_strategy_signal` 用于提取具体单一策略引擎在第 T 日收盘后的执行决策：

```python
import tradingpatterns as tp
import kdata

# 抓取日线 OHLCV 数据
df = kdata.get_ohlc("513120", "2024-01-01", "2026-08-19")

# 1. 获取左侧均值回归信号 (Engine 2 / Mean Reversion)
sig_mr = tp.get_strategy_signal(
    tp.StrategyEngine.MEAN_REVERSION, # 或 tp.StrategyEngine.ENGINE2_REVERSAL
    df, 
    symbol="513120"
)

# 2. 获取右侧趋势突破信号 (Engine 1)
sig_trend = tp.get_strategy_signal(
    tp.StrategyEngine.ENGINE1_TREND,
    df,
    symbol="513120"
)

# 3. 获取 Kaufman 自适应趋势信号 (Engine 3)
sig_kaufman = tp.get_strategy_signal(
    tp.StrategyEngine.ENGINE3_KAUFMAN,
    df,
    symbol="513120",
    use_multitimeframe=True
)

if sig_mr.buy_signal:
    print(f"【🔥均值回归买入】({sig_mr.signal_tier}) | 建议止损: {sig_mr.stop_loss:.3f} | 原因: {sig_mr.reason}")
```

#### 方式二：调用单标的全维度雷达评估 (`evaluate_opportunity_radar_item`)
一站式计算形态扫描、状态机、多引擎信号、截面板块轮动属性与防追高过滤：

```python
from tradingpatterns import evaluate_opportunity_radar_item

item_res = evaluate_opportunity_radar_item(
    df=df,
    symbol="515880",
    name="通信ETF",
    frequency="weekly",      # "weekly" (周频) 或 "daily" (日频)
    min_amount_ea=None,      # 异动成交额门槛 (亿)，None 时自动取默认
    min_vol_ratio=1.5,       # 放量倍数门槛 (默认 1.5 倍)
    min_pct_change=1.5,      # 涨跌幅门槛 (默认 1.5%)
    weekly_mode="early",     # 周线模式
)

print(f"机会来源: {item_res['primary_opp_source']}")
print(f"状态变迁: {item_res['prev_state_cn']} ━━➔ {item_res['curr_state_cn']}")
print(f"建议防守线: {item_res['stop_loss']}")
print(f"板块轮动象限: {item_res['quadrant_cn']} (分位数: {item_res['rs_percentile']}%, 斜率: {item_res['rs_slope']})")
```

**核心输出字段**：
- `has_buy_signal` (bool): 是否触发任一核心买点。
- `has_sell_signal` (bool): 是否触发离场/移动止损/止盈信号。
- `frequency` (str): 评估周期（`"weekly"` 或 `"daily"`）。
- `vol_ratio` (float): 当前指定 `frequency` 下的主控放量倍数（实际周期成交量 / 基准均量）。
- `change_pct` (float): 当前指定 `frequency` 下的主控周期涨跌幅（%）。
- `amount_ea` (float): 当前指定 `frequency` 下的主控周期成交额（亿元）。
- `daily_vol_ratio` (float): **日频放量倍数**（当日成交量 / 近 20 日成交量均值）。
- `daily_change_pct` (float): **日频涨跌幅**（当日收盘价相对前一日变动百分比，%）。
- `daily_amount_ea` (float): **日频成交额**（当日成交金额，单位：亿元）。
- `weekly_vol_ratio` (float): **周频放量倍数**（近 5 日累计成交量 / 过去 20 周周均成交量基准）。
- `weekly_change_pct` (float): **周频涨跌幅**（近 5 日累计涨跌幅百分比，%）。
- `weekly_amount_ea` (float): **周频成交额**（近 5 日累计成交金额，单位：亿元）。
- `opp_sources` (List[str]): 机会来源组合（包含 `"ENGINE2"` 左侧均值回归, `"ENGINE1"` 右侧趋势突破, `"ENGINE3"` Kaufman 趋势）。
- `primary_opp_source` (str): 主导机会来源中文说明。
- `signal_tier`: 最高信号级别 (`"L3"` 强信号 \| `"L2"` 中等/接力 \| `"L1"` 预警关注)。
- `is_opportunity` (bool): 是否归入【潜在机会】。
- `is_vol_abnormal` (bool): 是否归入【量化异动】。
- `vol_anomaly_type` (str): 量化异动微观结构分类枚举。取值：
  - `"BREAKOUT_EXPANSION"`: 突破推进放量（大阳线 + 实体比例高 + 空间 ATR 扩张）。
  - `"STOPPING_VOLUME"`: 底部恐慌承接（超跌区域暴量 + 长下影线/探底大长腿，机构接盘）。
  - `"CHURNING_STAGNATION"`: 高位巨量滞涨（高位暴量但涨幅极小或长上影，努力无结果）。
  - `"PANIC_BREAKDOWN"`: 破位恐慌杀跌（大阴线跌幅深 + 暴量光脚破位）。
  - `"VOLUME_DRY_UP"`: 极致地量变盘（成交量深度缩水达 55% 以上且处于历史低分位，筹码锁仓）。
  - `"REGULAR_SURGE"`: 常规放量（满足基础放量门槛，非极端结构）。
  - `"NONE"`: 正常量能。
- `vol_anomaly_cn` (str): 异动微观结构标准纯文本中文标签（如 `"突破推进放量"`, `"底部恐慌承接"`, `"高位巨量滞涨"`, `"破位恐慌杀跌"`, `"极致地量变盘"`）。
- `vol_zscore` (float): 成交量对数标准分（Log-Volume Z-Score，反映相对 20 日历史均量的统计显著度）。
- `vol_percentile` (float): 成交量在近 120 日中的历史百分位分位数（0.0 ~ 100.0%）。
- `range_atr_ratio` (float): 当日真实波幅相对于前 20 日 ATR 的扩张倍数（$TR / ATR_{20}$）。
- `body_ratio` (float): K 线实体高度占全日总振幅的比例（0.0 ~ 1.0）。
- `is_risk` (bool): 是否归入【风险提示】。
- `quadrant` / `quadrant_cn` (str): 所属板块轮动四象限（`LEADING` 领涨区 / `RECOVERING` 复苏区 / `WEAKENING` 衰退区 / `LAGGING` 滞后区）。
- `rs_percentile` (float): 相对基准的 60 日历史分位数 (0~100%)。
- `rs_slope` (float): 相对基准的 10 日线性回归斜率。
- `oversold_status` (str): **超跌企稳独立引擎的真实状态**。取值 `"NONE"` / `"OVERSOLD_ALERT"` / `"WAITING_DAILY"` / `"TRIGGERED"`，以及覆盖态 `"WAITING_BEAR_MARKET_DIP"` / `"WAITING_MARKET_STABILIZATION"` / `"EXTENDED_WAITING_PULLBACK"` / `"REJECTED_BY_BEARISH"`（三档状态与覆盖态的语义见 6.8 节）。
- `oversold_drawdown` (float): 距周线近 52 周最高点的回撤（小数，负值，如 `-0.42` 表示跌 42%）。
- `oversold_bottom_score` (float): 周线筑底质量评分 `0.0 ~ 10.0`。
- `oversold_rebound_from_low` (float): 距近期筑底低点的反弹幅度（小数正值，如 `0.058` 表示自低点仅反弹 5.8%，用于防追高与真实底部验证）。
- `oversold_tier` (str \| None): 超跌引擎自身的信号层级（`"L1"` 超跌预警 / `"L2"` 企稳观察 / `"L3"` 右侧确认）。**注意**：它不参与 `signal_tier` 的合成，需单独读取。
- `oversold_entry_mode` (str): `"EARLY_BIRD"`（左侧早鸟抢跑通道）/ `"STANDARD"`。
- `oversold_weekly_signals` / `oversold_daily_signals` (List[str]): 周线 / 执行级别的命中原语（如 `"BOTTOM_CONSOLIDATION"`, `"TALIB_HAMMER_PINBAR"`, `"BREAK_EMA20"`）。
- `sig_oversold_stabilized` (bool): 超跌企稳引擎是否已触发买入（等价 `oversold_status == "TRIGGERED"`）。
  > ⚠️ **勿混淆**：`sig_oversold` / `has_oversold_buy_signal` 两字段由 **Engine 2（周线均值回归）** 驱动，语义与上表不同。

---

### 1.3 全市场多周期雷达批量扫描 (`analyze_opportunity_radar`)

`analyze_opportunity_radar` 是面向标的池（ETF 或股票池）的全域多周期雷达批量扫描入口。它集成了**多策略引擎聚合 (Engine 1/2/3)**、**截面板块轮动计算 (4 象限加权)**、**经典形态与状态机识别**、**防追高与时效性钝化过滤 (Staleness Check)**，并按照**全域四栏互斥去重规则**将标的归类到强类型报表对象 `OpportunityRadarReport`（别名 `RadarReport`）中。

#### 1. 函数签名与参数说明

```python
def analyze_opportunity_radar(
    etf_pool: Dict[str, Tuple[str, pd.DataFrame]],
    frequency: str = "weekly",
    market: str = "auto",
    min_amount_ea: Optional[float] = None,
    min_vol_ratio: Optional[float] = None,
    min_pct_change: Optional[float] = None,
    weekly_mode: Optional[str] = None,
    market_context_df: Optional[pd.DataFrame] = None,
    include_alerts: bool = True,
    config: Optional[OpportunityRadarConfig] = None,
) -> OpportunityRadarReport:
```

| 参数 | 类型 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| **`etf_pool`** | `Dict[str, Tuple[str, pd.DataFrame]]` | **必填** | 标的池字典，格式为 `{"标的代码": ("标的名称", df), ...}`，其中 `df` 为包含 `open, high, low, close, volume` 的 K 线 DataFrame。 |
| **`frequency`** | `str` | `"weekly"` | 扫描频率。`"weekly"`（周频：以近 5 日为当周、近 100 日为 20 周均额基准）或 `"daily"`（日频：以当日为窗口、近 20 日为均量基准）。状态机与评分基于日 K 粒度计算，量额窗口随之切换。 |
| **`market`** | `str` | `"auto"` | 市场模式。`"auto"`（默认，根据标的代码自适应推断：纯数字如 `510050` 为 A 股，英文如 `SPY` 为美股）、`"CN"`（强制 A 股超跌反转与二买白名单，突破防追高）或 `"US"`（美股顺势双动量）。 |
| **`min_amount_ea`** | `Optional[float]` | `None` | 异动成交额门槛（亿元）。为 `None` 时根据 `config`/`frequency` 自动取默认值（周频 2.5 亿 / 日频 0.5 亿）。 |
| **`min_vol_ratio`** | `Optional[float]` | `None` | 异动放量倍数门槛（实际成交量 / 基准均量）。为 `None` 时从 `config` 获取（默认 1.5 倍）。 |
| **`min_pct_change`** | `Optional[float]` | `None` | 异动涨跌幅绝对值门槛 (%)。为 `None` 时从 `config` 获取（默认 1.5%）。 |
| **`weekly_mode`** | `Optional[str]` | `None` | 周线筛选模式（`"early"` / `"balanced"` / `"strict"`）。为 `None` 时日频默认为 `"early"`，周频默认为 `"balanced"`。 |
| **`market_context_df`** | `Optional[pd.DataFrame]` | `None` | 市场大盘/基准指数日 K 数据（可选）。若未提供且标的池中包含 `510300` / `SPY` / `QQQ`，会自动提取作为基准进行大盘环境与截面板块轮动计算。 |
| **`include_alerts`** | `bool` | `True` | 是否开启四栏输出模式。设为 `True` 时报告包含预警观察池 `alert_list`（并自动细分为高质量蓄势与常规观察），元组解包兼容 4 元组与 3 元组。 |
| **`config`** | `Optional[OpportunityRadarConfig]` | `None` | 雷达配置对象（可选，为 `None` 时使用全局默认配置 `DEFAULT_RADAR_CONFIG`）。 |

---

#### 2. 雷达配置对象 (`OpportunityRadarConfig`)

可以通过传入自定义 `OpportunityRadarConfig` 精细调优雷达的门槛参数：

```python
from tradingpatterns import OpportunityRadarConfig, analyze_opportunity_radar

# 自定义雷达门槛配置
custom_config = OpportunityRadarConfig(
    min_amount_ea_daily=0.8,       # 日频成交额门槛 (0.8亿)
    min_amount_ea_weekly=3.0,      # 周频成交额门槛 (3.0亿)
    min_vol_ratio=2.0,             # 放量倍数门槛 (2.0倍)
    min_pct_change=2.0,            # 涨跌幅门槛 (2.0%)
    stale_breakout_max_bars=3,     # 突破信号最大有效天数 (>3天判定为钝化)
    stale_ema20_atr_dist_max=2.5,  # 偏离 EMA20 最大 ATR 倍数 (>2.5倍判定为发散)
    chasing_ema20_dist_max=0.05,   # 距 EMA20 偏离度上限 (+5% 判定为追高)
    tech_score_cutoff=-5.0,        # 技术评分准入门槛
    anomaly_zscore_threshold=1.8,  # 触发放量统计异常的对数 Z-Score 门槛 (约超 96.4% 分位)
    anomaly_dry_up_zscore=-1.8,    # 触发极致地量的对数 Z-Score 门槛 (约低于 3.6% 分位)
    anomaly_dry_up_ratio=0.45,     # 极致地量与基准均量比率上限 (成交量萎缩 55% 以上)
    anomaly_atr_expansion_min=1.3, # 突破推进时真实波幅扩张倍数门槛 (TR / ATR20 >= 1.3)
)
```

---

#### 3. 返回数据结构 (`OpportunityRadarReport` 与 `OpportunityRadarItem`)

`analyze_opportunity_radar` 返回强类型报表对象 **`OpportunityRadarReport`**（可简写为 `RadarReport`），包含完整的列表、分流指标与 DataFrame 导出支持，同时 **100% 向后兼容元组解包**。

##### 3.1 `OpportunityRadarReport` 属性与方法

```python
report = analyze_opportunity_radar(etf_pool, frequency="weekly", include_alerts=True)

# 1. 强类型属性访问
print(report.vol_list)           # 一、量化异动 (List[OpportunityRadarItem])
print(report.alert_list)         # 二、预警观察池全量 (List[OpportunityRadarItem])
print(report.hq_alert_list)      # 2.1 🌟 高质量蓄势机会 (非钝化/高分/领涨复苏象限)
print(report.routine_alert_list) # 2.2 ⚠️ 常规跟踪与钝化观察 (钝化/追高/弱势初选)
print(report.opp_list)           # 三、潜在机会池 (L3 确定性策略机会)
print(report.risk_list)          # 四、风险提示池 (破位失效/卖出信号)
print(report.all_items)          # 全池扫描标的清单

# 2. 智能提纯 Top-N 核心先锋机会 (基于复合优先级打分模型)
top_picks = report.get_top_actionable(top_n=3, from_pool="hq_alerts")
for pick in top_picks:
    print(f"🔥 先锋标的: {pick.name}({pick.symbol}) | 动作: {pick.action_advice}")

# 3. 导出为 Pandas DataFrame
df_opps = report.to_df("opportunities") # 导出机会池表格
df_alerts = report.to_df("alerts")      # 导出预警池表格
df_all = report.to_df("all")            # 导出全池扫描总表

# 4. 100% 兼容传统元组解包
vol_list, alert_list, opp_list, risk_list = report
```

##### 3.2 `OpportunityRadarItem` 标的条目核心字段

列表中的元素均为强类型 **`OpportunityRadarItem`**（别名 `RadarItem`），同时支持属性访问与字典键访问（`item.tech_score` 与 `item["tech_score"]`）：

| 字段/属性名 | 类型 | 说明 | 适用列表 |
| :--- | :--- | :--- | :--- |
| **`symbol`** | `str` | 标的代码。 | 全列表通用 |
| **`name`** | `str` | 标的中文名称。 | 全列表通用 |
| **`frequency`** | `str` | 扫描频率（`"weekly"` / `"daily"`）。 | 全列表通用 |
| **`tech_score`** | `float` | 0-10 综合技术评分（量价、均线、动量、形态综合得分）。 | 全列表通用 |
| **`curr_state`** | `str` | **当前状态机中文名称**（如 `"右侧确认"`, `"筑底成熟"`, `"超跌企稳"` 等；**字典访问亦兼容 `curr_state_cn`**）。 | 全列表通用 |
| **`prev_state`** | `str` | **前序状态推演中文名称**（如 `"筑底成熟"`, `"超跌观察"` 等；**字典访问亦兼容 `prev_state_cn`**）。 | 全列表通用 |
| **`vol_ratio`** | `float` | 放量倍数（实际周期成交量 / 基准均量）。 | 全列表通用 |
| **`change_pct`** | `float` | 周期涨跌幅（%）。 | 全列表通用 |
| **`market`** | `str` | 市场归属（`"CN"` A股防御与反转哲学 / `"US"` 美股顺势双动量哲学）。 | 全列表通用 |
| **`priority_score`** | `float` | **池内专属优先级评分 (0.0 ~ 10.0)**：机会池衡量可操作性 (actionability)、预警池衡量蓄势质量 (quality)、风险池衡量健康程度 (severity，分越低越危险)、异动池衡量异动显著度 (significance)。 | 全列表通用 |
| **`grade`** | `str` | **标准化综合评级 (`"A"` / `"B"` / `"C"` / `"D"`)**：全池统一方向映射（A 级最优，D 级最弱/最危险）。 | 全列表通用 |
| **`grade_dimension`** | `str` | 评级所依托的业务语义维度（`"actionability"` / `"quality"` / `"severity"` / `"significance"`）。 | 全列表通用 |
| **`has_buy_signal`** | `bool` | 是否触发任一核心策略买入信号。 | 全列表通用 |
| **`has_sell_signal`** | `bool` | 是否触发任一核心策略卖出/离场信号（由 Engine 1 趋势突破与 Engine 3 Kaufman 合成）。 | 全列表通用 |
| **`is_pullback`** | `bool` | 是否属于缩量回踩 EMA20 支撑买点（$-1.5\% \le \text{dist\_to\_ema20} \le +1.5\%$ 且量比 $\le 1.25$）。 | 全列表通用 |
| **`is_chasing`** | `bool` | 是否属于均线过度发散/连阳形态的追高标的。 | 全列表通用 |
| **`action_advice`** | `str` | **详细实操动作建议**（约 30~40 字，结合均线乖离、轮动象限与买点生成的交易动作，适合控制台表格、图卡及自媒体文案）。 | 全列表通用 |
| **`action_tag`** | `str` | **简明动作标签**（10 字以内，如 `🟢 首发突破买点`, `🌟 回踩企稳买点`, `⏳ 趋势在途·等回踩`, `👀 领涨蓄势·等突破`, `⏳ 弱势磨底·多观望`, `🛑 风险破位·坚决避`）。 | 全列表通用 |
| **`cash_advice`** | `str` | **面向空仓视角的实操指引文案**（防追高提示、挂单买入目标价、持股待涨说明）。 | 全列表通用 |
| **`ema20_price`** | `float` | 当前 EMA20 价格参考线。 | 全列表通用 |
| **`dist_to_ema20`** | `float` | 距 EMA20 偏离度比例（收盘价 / EMA20 - 1）。 | 全列表通用 |
| **`signal_tier`** | `str \| None` | 信号确定性分级（`"L3"` 强信号 / `"L2"` 企稳突破观察 / `"L1"` 超跌预警 / `None`）。 | 全列表通用 |
| **`signal_tier_cn`** | `str` | 信号分级中文描述（`"右侧/策略确认"`, `"企稳/突破观察"`, `"超跌/候选预警"`, `"无信号"`）。 | 全列表通用 |
| **`opp_sources`** | `List[str]` | 机会来源策略列表（如 `["ENGINE1"]`, `["ENGINE2"]`, `["ENGINE3"]`）。 | `vol_abnormal_list` |
| **`primary_opp_source`** | `str` | 主导机会来源中文说明（如 `"Engine 1 (右侧突破)"` / `"Engine 2 (周线均值回归)"` / `"Engine 3 (Kaufman趋势)"`）。 | `vol_abnormal_list` |
| **`oversold_status`** | `str` | **超跌企稳独立引擎状态**（取值与三档语义见 6.8 节；注意 `sig_oversold` 属于 Engine 2 均值回归，二者不同）。 | 全列表通用 |
| **`oversold_drawdown`** | `float` | 距周线近 52 周最高点回撤（小数负值）。 | 全列表通用 |
| **`oversold_bottom_score`** | `float` | 周线筑底质量评分 0.0 ~ 10.0。 | 全列表通用 |
| **`oversold_rebound_from_low`** | `float` | 距近期筑底低点反弹幅度（小数正值，如 0.058 表示反弹 5.8%）。 | 全列表通用 |
| **`oversold_tier`** | `str \| None` | 超跌引擎自身层级（`"L1"` / `"L2"` / `"L3"` / `None`），不参与 `signal_tier` 合成。 | 全列表通用 |
| **`oversold_entry_mode`** | `str` | `"EARLY_BIRD"` 左侧早鸟抢跑 / `"STANDARD"`。 | 全列表通用 |
| **`sig_oversold_stabilized`** | `bool` | 超跌企稳引擎是否触发买入（等价 `oversold_status == "TRIGGERED"`）。 | 全列表通用 |
| **`stop_loss`** | `float` | 建议的量化防守止损价。 | `vol_abnormal_list` |
| **`dist_to_support`** | `float` | 距下方支撑位的偏离比例。 | 全列表通用 |
| **`dist_to_anchor`** | `float` | 距底部/突破启动锚点的涨幅比例。 | 全列表通用 |
| **`quadrant`** | `str` | 板块轮动四象限编码（`"LEADING"` / `"RECOVERING"` / `"WEAKENING"` / `"LAGGING"` / `"UNKNOWN"`）。 | 全列表通用 |
| **`quadrant_cn`** | `str` | 板块轮动四象限中文标签（`"领涨象限"` / `"改善象限"` / `"衰退象限"` / `"落后象限"` / `"未分类"`）。 | 全列表通用 |
| **`rs_percentile`** | `float` | 相对基准的 60 日历史相对强弱分位数 (0.0 ~ 100.0%)。 | 全列表通用 |
| **`rs_slope`** | `float` | 相对基准的 10 日线性回归斜率。 | 全列表通用 |
| **`risk_reason`** | `str` | 风险触发原因（如 `"触发卖出信号"`, `"结构失效/破位"`）。 | `risk_list` |
| **`observation_reason`** | `str` | 观察原因（如 `"右侧候选，等待突破确认"`, `"趋势过度延伸，避免追高"`）。 | `vol_abnormal_list` / `alert_list` |
| **`is_stale` / `stale_reason`** | `bool` / `str` | 信号是否钝化及钝化原因（如突破已超 3 天、ATR 偏离过大等）。 | `alert_list` |
| **`vol_anomaly_type`** | `str` | **量价微观异动行为枚举**（`"BREAKOUT_EXPANSION"` 突破推进 / `"STOPPING_VOLUME"` 底部恐慌承接 / `"CHURNING_STAGNATION"` 高位巨量滞涨 / `"PANIC_BREAKDOWN"` 破位杀跌 / `"VOLUME_DRY_UP"` 极致地量变盘 / `"REGULAR_SURGE"` 常规放量 / `"NONE"` 正常量能）。 | 全列表通用 |
| **`vol_anomaly_cn`** | `str` | **量价微观异动纯中文定性标签**（如 `"突破推进放量"`, `"底部恐慌承接"`, `"高位巨量滞涨"`, `"破位恐慌杀跌"`, `"极致地量变盘"`, `"常规放量"`, `"正常量能"`，不含 Emoji）。 | 全列表通用 |
| **`vol_zscore`** | `float` | **成交量对数 Z-Score**（基于 $x_t = \ln(V_t + 1)$，对比前 20 期对数均值与波动标准差计算偏离度，超越 $\pm 1.8$ 具有极强统计显著性）。 | 全列表通用 |
| **`vol_percentile`** | `float` | **120 日历史成交量分位数百分比**（$0.0\% \sim 100.0\%$，标准化刻画历史相对量能位置）。 | 全列表通用 |
| **`range_atr_ratio`** | `float` | **真实波幅空间扩张倍数**（$\text{TR} / \text{ATR}_{20}$，$> 1.3$ 表明突破或异动伴随价格空间有效推进）。 | 全列表通用 |
| **`body_ratio`** | `float` | **K 线实体占全日振幅比例**（$0.0 \sim 1.0$，刻画多空推进纯度与阻力大小）。 | 全列表通用 |

##### 3.3 Top-N 核心先锋机会智能提纯 (`select_top_actionable_opportunities`)

在多达数十只标的的高质量蓄势池或全池中，为帮助下游系统或自媒体读者一键获取最具爆发力、盈亏比最优的 Top-3 核心买入先锋标的，系统提供了**复合优先级打分提纯算法**：

```python
from tradingpatterns import (
    select_top_actionable_opportunities,
    filter_top_actionable_candidates,  # 别名
)

# 方式一：直接从 OpportunityRadarReport 对象中一键提纯 (推荐)
# from_pool="auto" (默认值) 开启两阶段瀑布流：优先取 opp_list，不足 top_n 从 hq_alerts 补齐
top_3_hq = report.get_top_actionable(top_n=3)

# 方式二：传入任意 OpportunityRadarItem 列表或字典列表进行过滤
top_3 = select_top_actionable_opportunities(
    items=report.hq_alert_list,
    top_n=3,
    min_tech_score=4.5,
    allow_stale=False,
    allow_chasing=False,
)
```

> **💡 API 设计说明 (别名说明)**
> `filter_top_actionable_candidates` 是 `select_top_actionable_opportunities` 的**完全等价别名**，两者底层指向同一块逻辑。
> 之所以导出两个名字，是为了满足下游调用方在不同场景下的语义偏好：
> - 当调用侧重于“排除劣质/破位/钝化标的”时，可以使用 `filter_`；
> - 当调用侧重于“截取排名前 N 位的高分标的”时，可以使用 `select_`。请根据自身代码可读性习惯任选其一。

**优先级打分模型设计 (Actionable Priority Scoring)**：
1. **硬性排除**：自动过滤结构破位 (`is_risk`)、信号钝化 (`is_stale`)、追高过热 (`is_chasing`) 及低于门槛 (`tech_score < min_tech_score`) 的标的；
2. **单日/当期动能奖惩 (防追高机制)**：
   - **A 股**：追高重罚——单日涨幅 `> 5.0%` 扣除 `6.0` 分（严禁接盘）；追高轻罚——`> 3.0%` 扣除 `3.5` 分；温和奖励——`0.0% ~ 3.0%` 奖励 `+1.0` 分；超跌机会逆势下跌 `> 2.0%` 时额外扣除 `1.5` 分；
   - **美股**：`> 6.0%` 扣除 `3.0` 分；`0.0% ~ 4.0%` 奖励 `+1.0` 分；超跌机会逆势下跌 `> 3.0%` 时扣除 `1.5` 分；
3. **动能象限加权**：`LEADING (领涨)` +2.0 分、`RECOVERING (改善)` +1.5 分、`WEAKENING (衰退)` -1.0 分、`LAGGING (滞后)` -2.0 分；
4. **买点与层级加权**：
   - A 股双核心买点加成：**超跌企稳买点**（`sig_oversold_stabilized == True`，即 `oversold_status == "TRIGGERED"`）或右侧黄金二买 (`is_pullback`) 享满额 `+3.0` 分；普通顺势突破克制加 `+1.5` 分；
   - 美股模式：顺势突破与回踩均享满额加成，且多头排列额外 `+2.0` 分、相对强度分位 $\ge 80$ 额外 `+1.5` 分；
   - `L2` 临界观察 +1.5 分，`L1` 初选预警 +0.5 分；
5. **均线偏离安全垫与防追高硬门禁**：
   - **A 股**：$-1.0\% \le \text{dist\_to\_ema20} \le +1.5\%$ (支撑位附近) +1.0 分；$\text{dist\_to\_ema20} > 2.5\%$ (过度偏离) 扣除 `2.0` 分；
   - **美股**：$-1.5\% \le \text{dist\_to\_ema20} \le +2.0\%$ +1.0 分；$\text{dist\_to\_ema20} > 4.5\%$ 扣除 `2.0` 分；
   - **A 股先锋硬门禁**：A 股模式下若非缩量回踩或超跌企稳反转，单日涨幅 `> 2.5%` 或偏离 EMA20 `> 2.5%` 的标的一票否决、严禁入选 Top-N 核心买入先锋！
   - **美股趋势门禁**：单日涨幅 `> 6.5%` 或偏离 EMA20 `> 5.5%` 的标的直接排除。
   > **⚠️ 已知差异**：该门禁还包含 `is_above_sma200 == False` 则排除的条件，但通用雷达条目 `OpportunityRadarItem` 并不携带 `is_above_sma200` / `is_bull_align` / `er_val` / `adx_val` 字段，因此这几个字段在通用雷达中恒取默认值（`is_above_sma200=True`、其余 `False` / `0.0`），对应的加分与排除分支实际不生效。美股 200 日均线多空防线由**美股专属机会雷达**独立实现（其条目自带 `is_above_sma200`，见 7.3 节）。

---

#### 4. 四栏全域互斥去重与排序规则

雷达采用严格的**单标的全域唯一归类机制**，优先级如下：
1. **风险提示 (`risk_list`)**：准入标准为**“结构破位/持仓卖出防守”**。若触发核心策略卖出信号或结构破位失效（`FAILED`、`BOTTOM_FAILED`，`is_risk == True`），优先归入风险提示池，防止放量下跌掩盖离场信号。按 `tech_score` 升序排列（最弱破位标的置顶）。
   > **⚠️ 重要边界区分（防守风险 vs 追高风险）**：  
   > 右侧过度延伸（`RIGHT_EXTENDED`，即乖离透支/极致过热）虽然属于“高风险区间”，但其做多大趋势依然完好（`in_right_side == True`），持仓者应依托移动止盈跟踪利润；它属于针对**买方的“追高风险”**，因此**绝不归入 `risk_list`**（避免误导持仓者恐慌清仓），而是严格分流至 **`alert_list`（预警观察栏）** 并标注 `observation_reason="趋势过度延伸，避免追高"`。
2. **量化异动 (`vol_abnormal_list`)**：非风险标的中满足放量与涨跌幅门槛的标的（`is_vol_abnormal == True`）。按异动显著度 `priority_score` 降序、放量倍数 `vol_ratio` 降序、涨跌幅绝对值降序排列。
3. **潜在机会 (`opportunity_list`)**：
   - **A 股市场 (`market="CN"`) 实施“双核心白名单机制”**：进入机会池需命中 ① **右侧缩量回踩二买**（EMA20 附近缩量企稳 `is_pullback`）或 ② **左侧均值回归买点**（Engine 2 周线布林超跌底分型，即 `sig_oversold` / `has_oversold_buy_signal`）。若当天出现放量大阳线突破（即使触发 L3），一律安全降级踢入【预警观察池】（2.1 高质量蓄势），贴上 `⏳ 突破确立·等回踩` 标签，坚决杜绝任何诱导空仓追高。
     > **⚠️ 与 Top-N 阶段的差异（有意为之）**：本白名单认的是 **Engine 2 均值回归**买点；而 Top-N 精选阶段的"防追高硬门禁豁免"认的是 **超跌企稳独立引擎**买点（`sig_oversold_stabilized` / `oversold_status == "TRIGGERED"`，见 6.8 节）。因此一只"超跌企稳已 `TRIGGERED`、但均值回归未触发"的标的会落在 `alert_list` 而非 `opp_list`——这不影响使用：`report.all_items` 与 `alert_list` 均携带完整超跌字段，辅助筛选层（见 1.6 节）可正常选取。
   - **美股市场 (`market="US"`) 保持“顺势超级趋势特权”**：保留大阳线放量突破直接进机会池、鼓励顺势骑浪（Super Trend）。
   - 按可操作性 `priority_score` 降序 ➔ 信号分层 (L3) ➔ 策略买点 ➔ 放量倍数降序排列。
4. **预警观察 (`alert_list`)**：承接 L1/L2 预警、观察态以及钝化标的（包含 A 股大阳线突破确立重点自选标的、`CANDIDATE` 候选观察、`RIGHT_EXTENDED` 避免追高预警、技术面偏弱待修复等）。按蓄势质量 `priority_score` 降序 ➔ L2 优先于 L1 ➔ 放量倍数降序排列。
   - 自动细分为 **2.1 🌟 高质量蓄势机会 (`hq_alert_list`)**（包含 A 股突破确立优质自选、高分/强势象限非钝化标的）与 **2.2 ⚠️ 常规跟踪与钝化观察 (`routine_alert_list`)**（钝化防追、追高过热、弱势初选）。

---

#### 5. 完整代码调用示例

```python
from tradingpatterns import analyze_opportunity_radar, OpportunityRadarConfig

# 1. 批量扫描标的池（四栏输出）
vol_list, alert_list, opp_list, risk_list = analyze_opportunity_radar(
    etf_pool={
        "515880": ("通信ETF", df_comm),
        "512880": ("证券ETF", df_sec),
        "513120": ("港股创新药", df_hk),
    },
    frequency="weekly",      # "weekly" (周频) 或 "daily" (日频)
    include_alerts=True,     # 开启四栏模式 (默认开启)
    min_amount_ea=None,      # None 时周频默认 2.5 亿 / 日频默认 0.5 亿
    min_vol_ratio=1.5,
    min_pct_change=1.5,
)

print(f"📊 【量化机会雷达 | 全市场四栏扫描复盘】\n")

# 栏目一：潜在机会池 (L3 确定性策略机会)
print("🎯 【潜在机会池 (L3 策略确认)】")
for item in opp_list:
    print(
        f"• {item['symbol']} {item['name']}: "
        f"状态【{item['curr_state']}】 | 评分: {item['tech_score']:.1f} | "
        f"板块象限: {item['quadrant_cn']} | 动作: {item['action_advice']}"
    )

# 栏目二：预警与蓄势观察池 (L1/L2 观察与超跌企稳)
print("\n👀 【预警观察池 (L1/L2 蓄势/超跌)】")
for item in alert_list:
    obs_info = f" | 观察: {item['observation_reason']}" if item.get("observation_reason") else ""
    stale_info = f" | 钝化: {item['stale_reason']}" if item.get("is_stale") else ""
    print(
        f"• [{item['signal_tier_cn']}] {item['symbol']} {item['name']}: "
        f"状态【{item['curr_state']}】 | 评分: {item['tech_score']:.1f} | 动作: {item['action_advice']}{obs_info}{stale_info}"
    )

# 栏目三：量化异动池 (放量/异动)
print("\n🌊 【量化异动池】")
for item in vol_list:
    print(
        f"• {item['symbol']} {item['name']}: "
        f"放量 {item['vol_ratio']:.2f} 倍 | 涨跌幅 {item['change_pct']:+.2f}% | "
        f"状态【{item['curr_state']}】 | 动作: {item['action_advice']}"
    )

# 栏目四：风险提示池 (破位/卖出)
print("\n⚠️ 【风险预警池】")
for item in risk_list:
    print(
        f"• {item['symbol']} {item['name']}: "
        f"状态【{item['curr_state']}】 | 评分: {item['tech_score']:.1f} | "
        f"风险原因: {item['risk_reason']} | 动作: {item['action_advice']}"
    )
```

---

### 1.4 技术信号层与实盘执行层的核心区别 (`get_strategy_signal` vs `run_strategy_engine_simulation`)

在量化交易系统设计中，**“技术形态/指标满足触发条件”（Signal）并不等同于“真实交易账户可执行买卖”（Execution）**。

`tp-quant` 提供了两套定位鲜明、相互协同的核心接口：

```
┌────────────────────────────────────────────────────────────────────────┐
│                   【技术信号层】 get_strategy_signal                   │
│   • 无状态计算 (Stateless) | 依赖数据: 截至目标日的历史 K 线序列       │
│   • 核心关注: "当天技术指标、均线与形态是否符合开仓/平仓触发标准？"   │
│   • 输出产物: 当日信号事件 (buy_signal / sell_signal / 静态止损位)     │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ 驱动并输入
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│               【实盘执行层】 run_strategy_engine_simulation             │
│   • 有状态仿真 (Stateful)  | 依赖数据: 账户资金、真实持仓与历史交易流水 │
│   • 核心关注: "当前账户是否已有持仓？实际成本是多少？浮盈是否激活移动锁利？"│
│   • 输出产物: 仿真持仓状态、实际撮合成交单、3阶段移动止损、历史累计收益│
└────────────────────────────────────────────────────────────────────────┘
```

#### 1. 核心差异对照矩阵

| 对比维度 | `get_strategy_signal` (技术信号层) | `run_strategy_engine_simulation` (实盘执行层) |
| :--- | :--- | :--- |
| **状态机机制** | **无状态 (Stateless)**：单次独立纯函数运算，无外部账户记忆。 | **有状态 (Stateful)**：维护连续运行的资金、持仓成本与成交流水。 |
| **持仓排他性** | **不考虑已有持仓**：若行情持续走强，连续多日均会输出 `buy_signal = True`。 | **严格排他过滤**：若已建仓，后续重复买点会被标记为 `SKIPPED_ALREADY_IN_POSITION` 跳过。 |
| **出场/止损机制** | **静态规则防守**：输出初始锚定止损价（如跌破前低或跌破 EMA53）。 | **3阶段动态跟踪**：根据实际持仓浮盈自动切换 Stage 1 硬止损 $\rightarrow$ Stage 2 保本/KAMA 生命线 $\rightarrow$ Stage 3 EMA10 紧锁利润。 |
| **防飞刀与纠错** | **无历史记忆**：无法感知前几日是否刚被止损。 | **全闭环风控**：熊市止损后触发 **10~20 根 K 线强制禁买冷却期**；止损后 6 根 K 线内大阳线收复触发**假摔洗盘快速纠错重入**。 |
| **主要应用场景** | **全池机会雷达扫描、盘后自媒体选品初筛、单日技术形态全息诊断**。 | **策略回测验证、实盘账户盯盘、头寸管理与动态止盈止损跟踪**。 |

#### 2. 代码调用与协同示例

```python
import kdata
from tradingpatterns import StrategyEngine, get_strategy_signal, run_strategy_engine_simulation

symbol = "510050"
target_date = "2024-05-20"

# 获取历史数据 (建议预热 300+ 交易日)
df = kdata.get_ohlc(symbol, "2023-01-01", target_date)

# 1. 诊断当天形态信号 (技术信号层)
sig_today = get_strategy_signal(StrategyEngine.COMBINED, df, symbol=symbol)
print(f"当天技术买入信号: {sig_today.buy_signal}, 建议初始止损: {sig_today.stop_loss:.3f}")

# 2. 仿真账户执行与持仓状态 (实盘执行层)
sim_res = run_strategy_engine_simulation(
    engine_type=StrategyEngine.COMBINED,
    df=df,
    symbol=symbol,
    start_date="2023-01-01",
    initial_capital=100000.0,
)

# 查看截至当天的账户真实状态
last_trade = sim_res.trades[-1] if sim_res.trades else None
if last_trade and not last_trade.get("exit_date"):
    print(f"账户状态: 【持仓中】 开仓价: {last_trade['entry_price']:.3f}, 移动止损: {last_trade['stop_loss']:.3f}")
else:
    print(f"账户状态: 【空仓观望】 累计策略收益: {sim_res.total_return_pct:+.2f}%")
```

---

### 1.5 全景回测与实战验证 CLI

包内置了多周期与多策略批量回测命令行工具与 Python 标准调用接口：

```bash
# 1. 单标的策略回测 (支持 pattern / sma / combined)
tp backtest -s 510050 --engine combined --start 2024-01-01

# 2. 标的池文件批量快速扫描
tp scan -f pool.yaml --json-simple
```

对于需要在 Python 代码中执行纯量化仿真回测的开发者，推荐直接调用顶层回测 API：
- `run_strategy_engine_simulation(...)`: 单标的策略引擎（双核 Combined / 趋势突破 Engine 1 / Kaufman Engine 3）标准撮合回测；
- `run_mean_reversion_simulation(...)`: 单标的周线均值回归与三阶段跟踪专用撮合回测；
- `run_sector_rotation_backtest(...)`: 多标的截面板块轮动与 Top-K 动态换仓组合回测。

---

### 1.6 雷达辅助筛选层 (Radar Selectors)

> **设计定位**：`analyze_opportunity_radar` 只负责**产出完整结果**；所有"挑选/提纯"逻辑下沉到**雷达辅助筛选层**的一组纯函数。这些函数**只读**已有条目字段，**不重算任何引擎**，因此可对同一份 `report` 反复组合筛选。

所有函数首个参数统一为 `source`，接受三种形态：`OpportunityRadarReport`（自动合并各池并去重）、`List[OpportunityRadarItem]`、`List[dict]`。返回值一律为 `List[OpportunityRadarItem]`（未命中返回空列表）。

#### 1. 通用原语

| 函数 | 说明 |
| :--- | :--- |
| `iter_radar_items(source)` | 归一化输入：`Report` → 各池合并去重；`list` → 原样；`None` → `[]` |
| `filter_radar_items(items, **criteria)` | **唯一通用筛选实现**，见下方参数表 |
| `sort_radar_items(items, by=("priority_score","tech_score"), reverse=True)` | 多键排序，键缺失时回退默认值 |
| `take_top_n(items, n)` | 截断前 N 个 |
| `to_symbols(items)` | 提取代码列表 |

`filter_radar_items` 支持的筛选条件：

| 参数 | 说明 |
| :--- | :--- |
| `symbols` / `markets` | 代码白名单 / 市场（`"CN"`、`"US"`） |
| `oversold_stages` | 超跌状态白名单（如 `("WAITING_DAILY",)`） |
| `tiers` | `signal_tier` 白名单（`"L1"/"L2"/"L3"`） |
| `quadrants` | 板块轮动象限白名单 |
| `sources` | `opp_sources` 引擎来源白名单（如 `("ENGINE2",)`） |
| `min_tech_score` / `max_tech_score` | 技术评分区间 |
| `min_vol_ratio` | 最小放量倍数 |
| `min_change_pct` / `max_change_pct` | 涨跌幅区间（%） |
| `dist_to_ema20_range` | EMA20 偏离区间（如 `(-0.015, 0.015)`） |
| `min_bottom_score` / `min_drawdown` | 超跌筑底分下限 / 回撤深度要求（传负数，如 `-0.30` 表示只保留回撤不浅于 30% 的标的） |
| `entry_modes` | `oversold_entry_mode` 白名单（如 `("EARLY_BIRD",)`） |
| `min_rs_percentile` | 相对强度分位下限 |
| `exclude_risk` / `exclude_stale` / `exclude_chasing` | 默认**全部为 False**（通用原语保持宽容，严格口径请用下方领域选择器） |
| `require_buy` | 仅保留 `has_buy_signal == True` |

#### 2. 领域选择器（按族划分）

**超跌族**
| 函数 | 语义 |
| :--- | :--- |
| `filter_oversold(items, *, oversold_stages=("OVERSOLD_ALERT","WAITING_DAILY","TRIGGERED"), min_bottom_score=None, min_drawdown=None, entry_modes=None, **kw)` | 超跌基础筛选 |
| `get_high_quality_oversold_stabilized(items, top_n=None, min_bottom_score=4.0, min_drawdown=None, exclude_risk=False)` | `TRIGGERED` 优质超跌企稳机会，按 (筑底分, `tech_score`, 回撤深度) 降序 |
| `get_oversold_watchlist(items, top_n=None, min_bottom_score=None, min_drawdown=None, max_rebound_from_low=0.12, exclude_risk=False)` | `WAITING_DAILY` 早鸟清单（周线已企稳，距低点反弹 $\le 12\%$，防追高且排除死猫跳） |
| `get_oversold_alerts(items, top_n=None, min_drawdown=None, exclude_risk=False)` | `OVERSOLD_ALERT` 最早预警（胜率最低） |
| `get_oversold_early_birds(items, top_n=None, exclude_risk=False)` | `oversold_entry_mode == "EARLY_BIRD"` 左侧抢跑 |

> **🔎 为什么超跌族默认 `exclude_risk=False`？**
> 实测 51 只 A 股 ETF：19 只 `WAITING_DAILY` 中有 10 只 `is_risk=True`，`risk_reason` 全部是"触发卖出信号"——而那是**趋势引擎**（Engine 1 / Kaufman）的卖出，深跌品种本就位于 EMA53 下方，卖压是结构性必然，与左侧抄底的前提并不矛盾。若默认剔除，会把筑底分最高的几只一并藏掉。超跌引擎本身已内置**熊市回撤门禁 / 大盘企稳门禁 / 防追高**三重风控。需要严格口径时显式传 `exclude_risk=True`。
> 对比：`get_golden_pullback_second_buys` 与 `get_launch_breakouts` 属**右侧**买点，上升趋势中出现卖出信号是真否决，故它们默认 `exclude_risk=True`。

**买点族**
| 函数 | 语义 |
| :--- | :--- |
| `get_oversold_early_birds(items, top_n=None)` | `oversold_entry_mode == "EARLY_BIRD"` 左侧抢跑 |
| `get_golden_pullback_second_buys(items, top_n=None)` | `is_pullback` 缩量回踩 EMA20 二买 |
| `get_launch_breakouts(items, top_n=None, market=None)` | L3 + `has_buy_signal` + 非 stale/chasing 首发突破 |
| `get_engine_opportunities(items, sources=("ENGINE1","ENGINE2","ENGINE3"), top_n=None)` | 按 `opp_sources` 指定引擎来源 |
| `get_actionable_watchlist(items, top_n=None)` | 潜在机会 + 高质量蓄势合并去重（对齐生命周期入池口径） |

**观察族**
| 函数 | 语义 |
| :--- | :--- |
| `get_high_quality_setups(items, top_n=None, min_tech_score=4.5)` | L1/L2 蓄势 + 强势象限（LEADING/RECOVERING）+ 非钝化非追高 |
| `get_relative_strength_leaders(items, min_rs_percentile=75.0, top_n=None)` | 截面相对强度领涨（主线领涨/复苏象限） |
| `get_volume_surges(items, min_vol_ratio=1.5, top_n=None)` | 放量异动榜，按 (量比, 涨幅绝对值) 降序 |

**风险族**
| 函数 | 语义 |
| :--- | :--- |
| `get_breakdown_risks(items, top_n=None)` | `is_risk` 或 `has_sell_signal` 的结构破位清单 |
| `get_overextended_warnings(items, dist_threshold=0.05)` | `is_chasing` 或乖离超阈值的追高过热清单 |
| `get_stale_signals(items)` | `is_stale` 信号钝化清单 |

**量化异动微观结构族**
| 函数 | 语义 |
| :--- | :--- |
| `select_breakout_anomalies(items, top_n=None)` | 突破推进放量 (`BREAKOUT_EXPANSION`)：带量大阳线 + 创 10 日新高 + 真实波幅显著扩张 |
| `select_stopping_volume_candidates(items, top_n=None)` | 底部恐慌承接 (`STOPPING_VOLUME`)：超跌深幅回撤位置暴量释放 + 探底长下影 (Selling Climax) |
| `select_churning_risk_items(items, top_n=None)` | 高位巨量滞涨 (`CHURNING_STAGNATION`)：高位大发散 + 暴量涨幅极小/长上影 (努力无结果排雷) |
| `select_dry_up_coiling_items(items, top_n=None)` | 极致地量变盘 (`VOLUME_DRY_UP`)：对数 Z-score 深度负向 + 成交量极端萎缩 + 筹码沉淀变盘前夜 |
| `filter_actionable_anomalies(items, top_n=None)` | 可操作多头异动池：仅包含突破推进与底部承接，并排除滞涨与破位风险 |

```python
from tradingpatterns import analyze_opportunity_radar
from tradingpatterns.radar_selectors import (
    get_high_quality_oversold_stabilized, get_oversold_watchlist,
    get_golden_pullback_second_buys, get_launch_breakouts,
    get_relative_strength_leaders, get_breakdown_risks,
    select_breakout_anomalies, select_stopping_volume_candidates,
    select_churning_risk_items, select_dry_up_coiling_items,
    filter_actionable_anomalies,
)

report = analyze_opportunity_radar(pool, frequency="daily", include_alerts=True)

print([i.symbol for i in get_high_quality_oversold_stabilized(report, top_n=5)])
print([i.symbol for i in get_oversold_watchlist(report)])
print([i.symbol for i in get_golden_pullback_second_buys(report)])
print([i.symbol for i in get_launch_breakouts(report, market="US")])
print([i.symbol for i in get_breakdown_risks(report)])
print([i.symbol for i in select_breakout_anomalies(report)])
print([i.symbol for i in select_churning_risk_items(report)])
```

---

### 1.7 机会雷达战法专题看板体系 (3+1 实战击球与 11 大战法)

全域机会雷达经过引擎计算后，会产出包含海量量化特征的 `OpportunityRadarReport`。在面对繁杂技术数据（如评分、乖离率、象限、状态机、多空信号、对数 Z-Score 等）时，交易员容易产生**“认知过载”与“难以快速决策”**的痛点。

为此，系统构建了**战法专题提纯体系**，基于 `tradingpatterns.radar_selectors` 纯函数层，形成了**“3+1 实战击球决策看板”（精简实操版）**与**“四大族群 11 大战法看板”（全景诊断版）**，并已在 **CLI 控制台终端** 和 **独立 Web 前端 (`/radar`)** 中完整工程化落地。

```
┌──────────────────────────────────────────────────────────────────────────────────┐
│              底座：全域机会雷达 OpportunityRadarReport (全量数据源)                  │
└────────────────────────────────────────┬─────────────────────────────────────────┘
                                         │ 纯函数只读提纯 (0 毫秒级开销)
                                         ▼
┌──────────────────────────────────────────────────────────────────────────────────┐
│               【3+1 实战击球决策框架】 (Radar Selectors 3+1 Decision)              │
│                                                                                  │
│  🔥 1. 今日核心先锋 (Top-3) ──► 复合打分 + 瀑布流 + 严惩 A 股盲目追高             │
│  🎯 2. 核心战法击球点       ──► 稳健二买 (右侧低吸) vs 精品抄底 (左侧反转) vs 顺势突破│
│  👀 3. 强势跟踪与自选       ──► 领涨龙头 + 临界蓄势 + 筑底潜伏 (WAITING_DAILY) + 微观异动│
│  🛑 4. 风险排雷与避险       ──► 结构破位 + 巨量滞涨 (防出货) + 均线发散 (防追高)    │
└────────────────────────────────────────┬─────────────────────────────────────────┘
                                         │ 业务分发与渲染
                    ┌────────────────────┴────────────────────┐
                    ▼                                         ▼
   【终端一：CLI 控制台终端】                 【终端二：独立量化 Web 控制台 (/radar)】
    • 默认 3+1 实战看板 (compact)             • /api/radar_selectors_scan 结构化输出
    • --full-selectors 展开 11 大战法         • ECharts 5 K 线图 (EMA20/MA60/支撑/买卖点)
    • 支持灵活日期与生命周期按需滚动回放       • 下方 3+1 决策看板点击秒级联动
```

#### 1. 3+1 实战击球决策框架设计

该框架按照**“先锋决策 ➔ 核心击球 ➔ 强势自选 ➔ 避险排雷”**的实盘推演动线组织信息，拒绝杂乱平铺：

| 板块名称 | 实战核心逻辑 | 底层驱动函数 | 核心准入条件 / 特征 |
| :--- | :--- | :--- | :--- |
| **🔥 1. 今日核心先锋**<br>(Today's Top Picks) | **买入可行性最高决策**：复合优先级打分，结合自动瀑布流；**A 股模式下对大阳线及过度偏离均线实施重罚与一票否决**，唯有真正具备低吸安全垫或确定性突破标的方可入选。 | `select_top_actionable_opportunities(report, top_n=3)` | 排除破位、钝化与追高；A 股单日涨幅 > 2.5% 或偏离 EMA20 > 2.5% 直接排除（非回踩/抄底不可入选）。 |
| **🎯 2. 核心战法击球点**<br>(Actionable Entry Points) | **立刻可落地的击球动作**：<br>• **🌟 稳健二买**：右侧上升趋势中缩量回踩 EMA20 支撑企稳，A 股胜率最高战法；<br>• **🧊 精品抄底**：深跌后周线筑底高分 + 日线底分型确立触发 (`TRIGGERED`)；<br>• **🚀 顺势突破**：放量突破重要颈线或中枢（美股首发买入，A 股提示确立等回踩）。 | • `get_golden_pullback_second_buys`<br>• `get_high_quality_oversold_stabilized`<br>• `get_launch_breakouts` | • 偏离 EMA20 处于 $[-1.5\%, +1.5\%]$ 且量比 $\le 1.25$x；<br>• 筑底评分 $\ge 4.0$ 且状态为 `TRIGGERED`；<br>• `L3` 突破且排除过热与钝化。 |
| **👀 3. 强势跟踪与自选**<br>(Strong Watchlist & Setups) | **机构主线抱团与临界变盘储备**：<br>• **🏆 领涨龙头**：相对大盘走势极其强劲的抱团核心；<br>• **💎 临界蓄势**：排除钝化与追高的高分蓄势品种，处于变盘前夜；<br>• **⏳ 筑底潜伏**：周线高分企稳（`WAITING_DAILY` 且筑底评分 $\ge 5.0$），耐心等待日线右侧放量信号点火；<br>• **🔬 微观量价异动**：突破推进放量 ($Z_{vol} > 1.8$)、极致地量变盘沉淀 ($Z_{vol} < -1.2$) 与底部恐慌承接 (Selling Climax)。 | • `get_relative_strength_leaders`<br>• `get_high_quality_setups`<br>• `get_oversold_watchlist`<br>• `select_breakout_anomalies`<br>• `select_dry_up_coiling_items`<br>• `select_stopping_volume_candidates` | • 截面 RS 分位数 $\ge 75\%$ 且位于领涨/复苏象限；<br>• $L1/L2$ 状态且技术分 $\ge 4.5$，非钝化非追高；<br>• 周线筑底评分 $\ge 5.0$ 且状态为 `WAITING_DAILY`；<br>• 微观量价对数 $Z$-Score 结合振幅 ATR 扩张/萎缩定性。 |
| **🛑 4. 风险排雷与避险**<br>(Risk Defense & Warnings) | **坚决不接飞刀与保护利润**：<br>• **🛑 结构破位**：触发卖出信号或跌破关键防守位（排除周线良性高分筑底标的，避免左侧与右侧认知冲突）；<br>• **⚠️ 巨量滞涨**：高位暴量滞涨（努力无结果），警惕主力派发出货；<br>• **♨️ 均线发散**：偏离 EMA20 过远（乖离率 $> 5\%$），超温过热严禁追高。 | • `get_breakdown_risks`<br>• `select_churning_risk_items`<br>• `get_overextended_warnings` | • 命中核心卖点或 `is_risk == True`（已排除高分良性筑底标的）；<br>• 高位发散且量比高但涨幅极小或长上影；<br>• $\text{dist\_to\_ema20} > 5\%$ 且处于连阳过热区间。 |

---

#### 2. 四大族群 11 大量化战法全景架构

对于需要更精细化投研分类的场景，系统支持全量展开**四大族群 11 大战法清单**：

| 族群分类 | 战法编号与名称 | 核心接口函数 | 核心量化逻辑与特征 |
| :--- | :--- | :--- | :--- |
| **🧊 左侧超跌族**<br>(Oversold Family) | **战法 ①：优质超跌企稳** | `get_high_quality_oversold_stabilized` | 52 周深跌后，筑底评分 $\ge 4.0$，日线底分型确立触发 `TRIGGERED`。 |
| | **战法 ②：超跌早鸟清单** | `get_oversold_watchlist` | 周线级别筑底良好，处于 `WAITING_DAILY` 阶段，等待日线点火确认。 |
| | **战法 ③：左侧抢跑通道** | `get_oversold_early_birds` | 极度深跌后首次止跌企稳的早鸟抢跑标的 (`EARLY_BIRD`)。 |
| **🎯 买点执行族**<br>(Actionable Family) | **战法 ④：黄金第二买点** | `get_golden_pullback_second_buys` | 稳健低吸之王：右侧均线上方缩量回踩 EMA20（偏离在 $\pm 1.5\%$ 且量比 $\le 1.25$）。 |
| | **战法 ⑤：顺势首发突破** | `get_launch_breakouts` | $L3$ 状态且 `has_buy_signal`，放量大阳线突破中枢或防守线。 |
| | **战法 ⑥：核心先锋精选** | `select_top_actionable_opportunities` | 融合自动瀑布流，自适应 A 股/美股哲学排名的买入先锋 (Top-3 / Top-5)。 |
| **👀 观察蓄势族**<br>(Watch Family) | **战法 ⑦：RS 领涨龙头** | `get_relative_strength_leaders` | 截面相对大盘强弱分位数 $\ge 75\%$，主线板块领涨。 |
| | **战法 ⑧：高质量临界蓄势** | `get_high_quality_setups` | $L1/L2$ 状态，技术评分 $\ge 4.5$，排除钝化和追高，即将点火。 |
| | **战法 ⑨：量价微观异动** | `select_breakout_anomalies`<br>`select_stopping_volume_candidates`<br>`select_dry_up_coiling_items` | 突破放量推进、底部恐慌承接 (Selling Climax)、极致地量沉淀变盘。 |
| **⚠️ 风险排雷族**<br>(Risk Family) | **战法 ⑩：巨量滞涨排雷** | `select_churning_risk_items` | 暴量但实体极小或长上影，努力无结果，警惕派发。 |
| | **战法 ⑪：结构破位离场** | `get_breakdown_risks` | 跌破动态支撑线或触发策略离场，坚决不接下坠飞刀。 |

---

#### 3. 数据源准备与调度流程 (How Data Sources Flow In)

战法专题看板是纯函数只读提纯层，其上游依赖标准化的标的行情与大盘基准：

```
┌────────────────────────────────────────────────────────────────────────┐
│                        【1. 标的池输入数据准备】                        │
│   pool_data: Dict[str, Tuple[str, pd.DataFrame]]                       │
│   - key: 标的代码 (如 "510300", "SPY")                                 │
│   - value: (标的中文名, OHLCV DataFrame)                                │
│   - DataFrame 要求: 包含 open, high, low, close, volume; 时间升序排列   │
│   - 数据长度: 建议至少 60 根 K 线 (预热 EMA20, MA60, ATR 等指标)         │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        【2. 大盘基准上下文】                            │
│   market_context_df: pd.DataFrame (可选但强烈推荐)                       │
│   - A 股: 沪深300指数 / ETF (510300) 行情                              │
│   - 美股: 标普500 ETF (SPY) 行情                                       │
│   - 作用: 驱动截面相对强弱 (RS 分位数/斜率) 及大盘顺逆势风控            │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                 【3. 全域雷达批量分析 (调度核心入口)】                 │
│   report = analyze_opportunity_radar(                                  │
│       pool=pool_data,                                                  │
│       frequency="daily" | "weekly",                                    │
│       market_context_df=market_context_df,                             │
│       include_alerts=True,                                             │
│   )                                                                    │
│   - 产物: OpportunityRadarReport 强类型报表对象                        │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│             【4. 战法提取与多维分类 (纯函数零开销提纯)】               │
│   直接消费 report 对象，调用 tradingpatterns.radar_selectors 函数:    │
│   - select_top_actionable_opportunities(report, top_n=3)               │
│   - get_golden_pullback_second_buys(report)                            │
│   - get_high_quality_oversold_stabilized(report)                       │
│   - get_launch_breakouts(report)                                       │
│   - get_relative_strength_leaders(report)                              │
│   - get_high_quality_setups(report)                                    │
│   - select_breakout_anomalies(report) / select_dry_up_coiling_items    │
│   - get_breakdown_risks(report) / select_churning_risk_items           │
└────────────────────────────────────────────────────────────────────────┘
```

---

#### 4. 下游消费规范与输出数据结构契约 (How Results Are Structured)

所有战法筛选函数均返回 `List[OpportunityRadarItem]`。当需要将战法分类结果序列化（如提供给 REST API、CLI 工具、LLM Agent 或数据推送管道）时，推荐采用标准字典转换方法 `item.to_dict()`。

##### 4.1 标准输出数据字典规范

```python
def extract_radar_showcase_payload(report: OpportunityRadarReport) -> dict:
    """提取 3+1 实战决策与战法专题结构化数据包（供任何下游服务消费）"""
    from tradingpatterns.radar_selectors import (
        select_top_actionable_opportunities,
        get_golden_pullback_second_buys,
        get_high_quality_oversold_stabilized,
        get_launch_breakouts,
        get_relative_strength_leaders,
        get_high_quality_setups,
        get_oversold_watchlist,
        select_breakout_anomalies,
        select_dry_up_coiling_items,
        select_stopping_volume_candidates,
        get_breakdown_risks,
        select_churning_risk_items,
        get_overextended_warnings,
        get_stale_signals,
    )

    def _to_dicts(items):
        return [item.to_dict() if hasattr(item, "to_dict") else item for item in items]

    return {
        "as_of_date": report.as_of_date,
        "frequency": report.frequency,
        "total_scanned": len(report.all_items),
        "selectors_3plus1": {
            # 1. 🔥 今日核心先锋 (Top-3 击球决策 - 优先级复合模型 & 防追高重罚)
            "top_picks": _to_dicts(select_top_actionable_opportunities(report, top_n=3)),

            # 2. 🎯 核心战法击球点 (右侧低吸 vs 左侧抄底)
            "pullbacks": _to_dicts(get_golden_pullback_second_buys(report, top_n=5)),
            "oversold_triggered": _to_dicts(get_high_quality_oversold_stabilized(report, top_n=5)),
            "breakouts": _to_dicts(get_launch_breakouts(report, top_n=5)),

            # 3. 👀 强势跟踪与自选 (临界蓄势变盘与底部储备)
            "rs_leaders": _to_dicts(get_relative_strength_leaders(report, min_rs_percentile=75.0, top_n=5)),
            "hq_setups": _to_dicts(get_high_quality_setups(report, top_n=5)),
            "bottom_watchlist": _to_dicts(get_oversold_watchlist(report, top_n=5, min_bottom_score=5.0)),
            "breakout_anomalies": _to_dicts(select_breakout_anomalies(report, top_n=5)),
            "dry_up_anomalies": _to_dicts(select_dry_up_coiling_items(report, top_n=5)),
            "stopping_anomalies": _to_dicts(select_stopping_volume_candidates(report, top_n=5)),

            # 4. 🛑 风险排雷与避险预警 (坚决不接飞刀 / 严禁盲目追高)
            "breakdowns": _to_dicts(get_breakdown_risks(report, top_n=5)),
            "churning_anomalies": _to_dicts(select_churning_risk_items(report, top_n=5)),
            "overextended": _to_dicts(get_overextended_warnings(report, dist_threshold=0.05)),
            "stale_items": _to_dicts(get_stale_signals(report)),
        },
    }
```

##### 4.2 四大族群 11 大量化战法全景看板数据包规范与函数用法

当业务需要展示**全景量化战法矩阵**（例如投研报表导出、看板聚合服务或自动化任务）时，可直接通过 `tradingpatterns` 顶层导出的纯函数，将 `OpportunityRadarReport` 归类聚合为四大族群 11 大战法结构化数据包：

```python
from tradingpatterns import (
    analyze_opportunity_radar,
    # 族群一：核心击球
    get_golden_pullback_second_buys,
    get_high_quality_oversold_stabilized,
    get_launch_breakouts,
    get_engine_opportunities,
    # 族群二：超跌博弈
    get_oversold_watchlist,
    get_oversold_alerts,
    get_oversold_early_birds,
    # 族群三：强势跟踪
    get_relative_strength_leaders,
    get_high_quality_setups,
    # 族群四：风险排雷
    get_breakdown_risks,
    get_overextended_warnings,
    get_stale_signals,
)

def extract_full_11_tactics_dashboard_payload(report: OpportunityRadarReport) -> dict:
    """提取四大族群 11 大量化战法全景看板数据包（只读纯函数提纯，零副作用）"""
    def _to_dicts(items):
        return [item.to_dict() if hasattr(item, "to_dict") else item for item in items]

    return {
        "as_of_date": report.as_of_date,
        "market": report.market,
        "tactical_matrix": {
            # 族群一：🎯 核心击球族群 (立刻执行/击球点)
            "actionable_family": {
                "golden_pullback_second_buys": _to_dicts(get_golden_pullback_second_buys(report)),
                "high_quality_oversold_stabilized": _to_dicts(get_high_quality_oversold_stabilized(report)),
                "launch_breakouts": _to_dicts(get_launch_breakouts(report)),
                "engine_opportunities": _to_dicts(get_engine_opportunities(report)),
            },
            # 族群二：🧊 超跌博弈族群 (左侧潜伏/逆向观察)
            "oversold_family": {
                "oversold_watchlist": _to_dicts(get_oversold_watchlist(report)),
                "oversold_alerts": _to_dicts(get_oversold_alerts(report)),
                "oversold_early_birds": _to_dicts(get_oversold_early_birds(report)),
            },
            # 族群三：👀 强势跟踪族群 (主线抱团/蓄势储备)
            "watch_family": {
                "relative_strength_leaders": _to_dicts(get_relative_strength_leaders(report, min_rs_percentile=75.0)),
                "high_quality_setups": _to_dicts(get_high_quality_setups(report)),
            },
            # 族群四：🛑 风险排雷族群 (避险减防/严禁追高)
            "risk_family": {
                "breakdown_risks": _to_dicts(get_breakdown_risks(report)),
                "overextended_warnings": _to_dicts(get_overextended_warnings(report, dist_threshold=0.05)),
                "stale_signals": _to_dicts(get_stale_signals(report)),
            },
        },
    }
```

##### 4.3 下游消费场景说明
- **CLI 终端展示**：直接遍历 `selectors_3plus1` 各列表，格式化输出对齐表格；
- **HTTP/REST API 接口**：将上述字典作为 JSON 直接响应返回，如 Web 服务的 `GET /api/radar_selectors_scan`；
- **AI Agent / 交易机器人**：仅读取 `top_picks` 与 `breakdowns`，由 Agent 针对买入先锋评估执行条件，针对破位标的生成防守提示。

---

## 3. 技术形态扫描与预筛选管道 (`pre_screen_and_scan`)

> [!TIP]
> 🧭 **架构定位与最佳实践指引 (Architecture & Best Practice Guide)**  
> - **L1 基础初筛层 (形态与静态特征漏斗)**：`pre_screen_and_scan` 属于**静态截面漏斗工具**，专注于对全市场海量标的进行硬门禁过滤（流动性/数据长度）与多维度形态特征打分（0~10 分），输出无状态的特征上下文数据包 (Context Package)。它不包含账户资金买卖点与止损止盈生命周期管理。
> - **L2 战法执行层 (双核策略引擎 - 强烈推荐)**：如果您在下游系统（如自动化交易流水线、LLM AI Agent、量化实盘）中需要捕获**左侧底部反转战法**或**右侧趋势主升浪**，**强烈推荐直接调用工业级双核策略引擎**：
>   - **左侧底部反转/大波段抄底**：调用 `get_mean_reversion_signal()`（或 `StrategyEngine.ENGINE2_REVERSAL`），具备**周线布林带极限通道超跌 + TA-Lib K线底反转共振确认**，并内置**三阶段阶梯跟踪止盈 (Stage 1/2/3)** 与 **熊市止损冷却熔断**，彻底杜绝单点形态在单边阴跌行情中“盲目接飞刀”；
>   - **右侧主升突破**：调用 `get_strategy_signal(StrategyEngine.ENGINE1_TREND, df)`，具备唐奇安结构突破、EMA20 缩量回踩第二买点与动态吊灯跟踪；
>   - **全域选品与分类**：调用 `analyze_opportunity_radar()`，原生集成四栏互斥去重、空仓防追高契约与动态防守线计算。

### 3.1 预筛选与扫描主接口

一体化的预筛选与形态扫描管道 (v2.4)，结合生命周期、趋势环境与量价配合度，对标的进行严格漏斗过滤并生成详尽的 **Context Package**。

```python
from tradingpatterns import pre_screen_and_scan

# 单标的诊断/扫描
result = pre_screen_and_scan(df, symbol="sh.600519", min_score=6.0)

# 批量扫描
results = pre_screen_and_scan(jobs, min_score=6.0, max_workers=8)
```

---

### 3.2 Context Package 上下文数据包全字段解析

`pre_screen_and_scan` 返回的数据结构遵循分层契约：

#### 1. 完整扫描数据包 (预筛选通过 `pre_screen_passed == True`)

```json
{
  "symbol": "sh.600519",
  "name": "贵州茅台",
  "total_score": 8.5,
  "pre_screen_passed": true,
  "rejection_reason": null,
  "pre_screen": {
    "strategy_hint": "趋势跟随",
    "priority_score": 0.88,
    "urgency": "MEDIUM",
    "signal_age_days": 2,
    "stale": false,
    "stop_infeasible": false
  },
  "trend_structure": {
    "ema_alignment": "bullish_aligned",
    "adx": 28.5
  },
  "volume": {
    "vr": 1.1,
    "vr_type": "正常",
    "obv_accumulation": true
  },
  "wyckoff": {
    "phase": "accumulation",
    "event": "spring",
    "bias": "demand"
  },
  "weekly_context": {
    "weekly_trend_direction": "bullish"
  },
  "calculated_constraints": {
    "max_position_pct": 30,
    "min_rrr": 1.2
  }
}
```

#### 2. 早期硬过滤拦截返回 (早期阻断 `pre_screen_passed == False`)

当标的在数据长度校验（< 60 根 K 线）、流动性硬门禁（20日均成交额/换手率不足）或价格结构门禁（异常停牌/价格过低）被物理拦截时，系统将提前快速返回轻量字典，避免无效计算：

```json
{
  "symbol": "sh.600519",
  "pre_screen_passed": false,
  "pre_screen_summary": "流动性拦截: 20日日均成交额不足5000万",
  "rejection_reason": "流动性不足"
}
```

> [!TIP]
> **集成安全建议**：下游消费端解析返回结果时，建议先检查 `if result.get("pre_screen_passed"):` 或使用 `.get()` 进行字段安全读取，避免直接索引深层嵌套字段引发 `KeyError`。

| 字段路径 | 说明 |
| :--- | :--- |
| **`pre_screen_passed`** | 是否通过预筛选硬门禁与基础过滤 (`bool`)。 |
| **`pre_screen_summary`** | 预筛选诊断摘要或拦截归因描述。 |
| **`rejection_reason`** | 若被硬过滤拦截，记录具体阻断原因（如 `流动性不足`、`价格结构异常`、`数据不足` 等）；通过时为 `null`。 |
| **`total_score`** | 日线预筛选 0~10 排序总分（仅在通过预筛选时生成）。 |
| **`pre_screen.strategy_hint`** | 建议策略框架（`趋势跟随`, `底部反转`, `区间震荡`, `等待突破`, `观望`）。 |
| **`pre_screen.stop_infeasible`** | 止损不可行硬标记（价格偏离技术位超过允许的 ATR 上限）。 |
| **`wyckoff`** | 威科夫供需分析结果 (`phase`, `event`, `bias`, `score`)。 |
| **`calculated_constraints`** | 系统预计算的风控约束（建议最大仓位比例、最小盈亏比、最大止损宽容度）。 |

---

### 3.3 威科夫量价供需分析：`detect_wyckoff_context`

```python
from tradingpatterns import detect_wyckoff_context

wyckoff = detect_wyckoff_context(df)
print(wyckoff["phase"], wyckoff["event"], wyckoff["bias"])
```

---

## 4. 市场状态机与多周期趋势评估

### 4.1 综合唯一主状态机：`detect_side_state`

将左侧筑底状态机（`BottomTrackingState`）与右侧做多状态机（`RightSideState`）合并为全局唯一的单一主状态，并输出标准化的筑底观察阶段、右侧交易计划与风控防守线：

```python
from tradingpatterns import (
    detect_side_state,
    SideState,
    STATE_LABELS,
    BOTTOM_OBSERVATION_LABELS,
    RIGHT_SIDE_PLAN_LABELS,
    STATE_EMOJIS,
    get_state_label_cn,
    get_bottom_observation_cn,
    get_right_side_plan_cn,
    get_state_emoji,
)

res = detect_side_state(df, weekly_mode="balanced")

print(f"主状态编码: {res['state']}")
print(f"主状态中文: {get_state_label_cn(res['state'])} ({get_state_emoji(res['state'])})")
print(f"筑底观察: {get_bottom_observation_cn(res['bottom_observation'])}")
print(f"右侧计划: {get_right_side_plan_cn(res['right_side_plan'])}")
print(f"刚跨入右侧: {res['entered_right_side']} | 处于右侧趋势: {res['in_right_side']}")
```

#### 标准中文状态映射表 (`STATE_LABELS`)：
| 英文枚举值 (`State`) | 标准中文标签 (`STATE_LABELS`) | 视觉图标 | 业务语义与交易指导 |
| :--- | :--- | :--- | :--- |
| `BASE` | **底部蓄势** | ⚪ | 下跌/回撤/底部构筑阶段，尚未形成有效反转 |
| `CANDIDATE` | **右侧候选** | 🟡 | 出现止跌回升证据，正等待关键结构突破 |
| `RIGHT_CONFIRMED` | **右侧确认** | 🟢 | **突破确认成立**（收盘突破前高阻力 + 辅助确认成立，`entered_right_side=True`） |
| `RIGHT_ACTIVE` | **右侧延续** | 🔵 | 突破后趋势持续有效，守在防守失效线上方（`HOLD_AND_TRACK`） |
| `RIGHT_EXTENDED` | **右侧过度延伸** | 🟠 | 趋势仍有效但乖离过大，极致过热追高风险（`AVOID_CHASING`，雷达分流归入 `alert_list`） |
| `FAILED` | **结构失效** | 🔴 | 候选或已确认结构跌破防守线，结构破坏（`STAND_ASIDE`） |
| `DECLINING` | **左侧下跌** | ⚪ | 处于左侧单边下行通道中，未见止跌迹象 |
| `BOTTOM_WATCH` | **筑底观察** | 🟡 | 初步探底，开始跟踪底部锚点 |
| `BOTTOM_BUILDING` | **筑底构建** | 🟠 | 在底部箱体内反复震荡夯实底部（Higher Lows 形成中） |
| `BOTTOM_MATURE` | **筑底成熟** | 🟠 | 底部构筑充分（持续超 20 根 K 线），蓄势待发 |
| `STARTUP_PREHEAT` | **启动预热** | 🟢 | 均线与 MACD 出现向上拐头共振，准备向右侧突破 |
| `BOTTOM_FAILED` | **筑底失败** | 🔴 | 跌破前期底部支撑锚点，底部形态破坏 |

#### 筑底观察与右侧计划映射表：
* **`BOTTOM_OBSERVATION_LABELS`**：
  - `"RIGHT_SIDE_ACTIVE"`: `已转入右侧，不再跟踪筑底`
  - `"BOTTOM_READY"`: `底部结构就绪，等待右侧突破`
  - `"BOTTOM_TRACKING"`: `底部观察中`
  - `"BOTTOM_FAILED"`: `当前底部结构失效`
  - `"NO_BOTTOM_SETUP"`: `暂无有效筑底结构`
* **`RIGHT_SIDE_PLAN_LABELS`**：
  - `"WAIT_BREAKOUT"`: `等待结构突破`
  - `"HOLD_AND_TRACK"`: `持有并跟踪失效位`
  - `"AVOID_CHASING"`: `避免追高，等待回撤`
  - `"STAND_ASIDE"`: `观望，等待新结构`
  - `"NONE"`: `暂无右侧计划`

#### 状态生命周期流转轨迹（Lifecycle Flow）：
```
【左侧下跌】(DECLINING) 
     │ (触底企稳)
     ▼
【筑底构建】(BOTTOM_BUILDING) ➔ 【筑底成熟】(BOTTOM_MATURE) ➔ 【启动预热】(STARTUP_PREHEAT) / 【右侧候选】(CANDIDATE)
     │ (收盘突破前20日高点阻力位 + 周线共振)
     ▼
【右侧确认】(RIGHT_CONFIRMED, 触发入场信号 entered_right_side=True)
     │ (次日及后续站稳突破位)
     ▼
【右侧延续】(RIGHT_ACTIVE, 跟踪持有 HOLD_AND_TRACK)
     ├── (涨幅过大 / 偏离EMA20过大) ──➔ 【右侧过度延伸】(RIGHT_EXTENDED)
     └── (跌破动态失效防守位) ────────➔ 【结构失效】(FAILED) ──➔ 【底部蓄势】(BASE)
```

---

### 4.2 做多右侧状态机：`detect_right_side_state`

```python
from tradingpatterns import detect_right_side_state, RightSideState

rs = detect_right_side_state(df, weekly_mode="balanced")
# 输出字典包含: state, entered_right_side, in_right_side, is_tradeable, breakout_level, invalidation_level, confidence_score
```

---

### 4.3 底部结构跟踪状态机：`detect_bottom_tracking_state`

> [!NOTE]
> `detect_bottom_tracking_state` 专注于单标的 K 线几何结构上的筑底阶段演进（`BOTTOM_WATCH` 探底 ➔ `BOTTOM_BUILDING` 夯实 ➔ `BOTTOM_MATURE` 成熟），属于纯结构状态机观察工具。  
> 若需要在实战中执行左侧底部反转交易，请直接调用 **[第 6 章 均值回归引擎 `get_mean_reversion_signal()`](#61-a-股周线均值回归与三阶段跟踪-get_mean_reversion_signal)**，其具备周线级别超跌过滤、三阶段移动止盈与熊市止损冷却保护。

```python
from tradingpatterns import detect_bottom_tracking_state, BottomTrackingState

bt = detect_bottom_tracking_state(df)
# 输出字典包含: state, in_bottom_tracking, bottom_mature, ready_for_right_side, anchor_low, support_level, resistance_level
```

---

### 4.4 独立周线中期趋势质量评分：`evaluate_weekly_trend`

独立的中期周线质量评分系统（0~100 分），不参与日线预筛选总分合成：

```python
from tradingpatterns import evaluate_weekly_trend, evaluate_weekly_trends

res = evaluate_weekly_trend(df, symbol="512880")
print(f"周线评分: {res['weekly_trend_score']} | 评级: {res['rating']}")
```

---

### 4.5 终端宽字符排版对齐工具 (`wc_len` / `wc_pad`)

用于在开发命令行 CLI、控制台对齐输出包含中文、Emoji 等宽字符的 Markdown 表格与报告：

```python
from tradingpatterns import wc_len, wc_pad

# 中文字符占 2 个显示宽度，英文占 1 个
print(wc_len("右侧确认"))  # 输出 8

# 对齐排版
header = f"{wc_pad('标的代码', 10)} | {wc_pad('标的名称', 12)} | {wc_pad('当前主状态', 14)}"
print(header)
```

---

## 5. 市场环境与辅助分析工具

### 5.1 市场情绪温度计：`sentiment_thermometer`

提供 A 股市场整体情绪温度（0~100）的计算、自适应历史分位数归一化、情绪状态分级与 5 大温区操作总方针：

```python
from tradingpatterns import (
    compute_sentiment_snapshot,
    compute_sentiment_series,
    DEFAULT_CONFIG,
    SentimentConfig,
    SENTIMENT_ZONES,
    get_sentiment_zone_desc,
    CORE_BENCHMARK_ETFS,
)

# 1. 单日情绪快照 (推荐使用周频 freq="W" 进行波段择时，日频 freq="D" 进行短线监控)
snapshot = compute_sentiment_snapshot(date="2026-08-19", config=SentimentConfig(freq="W"))
temp = snapshot["temperature"]

# 2. 获取当前温度的标准战术操作建议
zone_title, action_advice, full_desc = get_sentiment_zone_desc(temp)

print(f"情绪温度: {temp:.1f} / 100.0 | 状态: {snapshot['state']} | 趋势: {snapshot['direction']}")
print(f"当前温区: {zone_title}")
print(f"战术总方针: {action_advice}")
print(f"底层因子分位: {snapshot['factors']}")
# 输出示例: {'breadth': 88.0, 'momentum': 94.0, 'turnover': 5.0, 'volatility': 50.0, 'positioning': 96.0}
```

#### 情绪温区划分与战术指南 (`SENTIMENT_ZONES`)：
| 温度区间 | 状态代码 | 温区标识 | 市场特征与战术操作方针 |
| :--- | :--- | :--- | :--- |
| $\le 20.0$ | `ICE_COLD` | **🥶 极寒冰点区 (恐慌极值)** | 【左侧分批布局】市场处于极限非理性杀跌，风险出清彻底。严禁恐慌割肉，可按网格/定投逢低分批吸筹优质核心资产。 |
| $20.0 \sim 40.0$ | `COLD` | **❄️ 筑底蓄势区 (左侧探底)** | 【轻仓防守观察】底部结构酝酿中，主跌浪趋缓但尚未放量。维持2~3成底仓，多看少动，耐心等待右侧突破信号。 |
| $40.0 \sim 60.0$ | `NEUTRAL` | **☁️ 中性平衡区 (结构轮动)** | 【聚焦结构个股】宏观多空相对平衡，指数大概率宽幅震荡。重个股与细分板块轮动，遵循“缩量低吸、放量冲高不追”。 |
| $60.0 \sim 80.0$ | `HOT` | **🔥 趋势主升区 (右侧强势)** | 【顺势持筹待涨】市场处于明确右侧主升浪，增量资金进场。坚定跟随均线趋势，回踩生命线（MA20）视为良性买点。 |
| $\ge 80.0$ | `OVERHEAT` | **🌋 极度过热区 (盛极而衰)** | **最高级别风控预警**：【逢高分批兑现】短期情绪严重透支，乖离率过大，均值回归压力剧增。严禁盘中追高，主动分批止盈，破位坚决离场。 |

#### 核心机制与量化解读要点：
1. **高温度与极度过热（$\ge 80.0$）是“逆向风控预警”，绝非追高做多信号**：
   - 情绪温度计衡量的是全市场的拥挤度与透支程度。实证显示，处于 `OVERHEAT` 时未来一季度的平均收益极低、胜率不足 46%，面临强烈的均值回归回撤压力。
2. **大盘缩量时温度为何依然可能走高（量价背离与虚热机制）**：
   - **量能因子如实归零**：缩量时，`turnover`（量能因子，权重 20%）单项分会跌至接近 0 分，如实反映增量资金枯竭；
   - **价格因子绝对主导**：若全市场普涨（广度 F1 占 35%）、动量向上（动量 F2 占 25%）且持仓均处于近期高位无套牢盘（位置 F5 占 20%），合占 80% 权重的价格因子会合力拉高初始加权分；
   - **二次分位数拉伸**：在历史 1 年参照系下，加权分排在前 5% 以内，直接触发 80+ 度的 `OVERHEAT` 警报；
   - **实战意义**：缩量上涨反映的是“筹码锁仓、下方无买盘承接”的脆弱形态（空中楼阁）。系统打出极高温度，正是精确量化出这种“量价背离的极端脆弱性”，提示必须启动防守减仓。
3. **温度方向（`direction`）语义消歧**：
   - **低位 `warming`（$\le 40$ 度）**：**【良性企稳 / 冰点回暖】**。恐慌出清后的右侧高胜率进场点。
   - **中位 `warming`（$40 \sim 80$ 度）**：**【动量升温 / 趋势延续】**。
   - **高位 `warming`（$\ge 80$ 度）**：**【加速发烧 / 冲顶透支】**。如同人体体温升至 40.5℃，属于极度危险的危险脉冲，切忌误读为“行情转好继续追高”。

#### 4. 周频与日频温度计实战选型与平滑参数指南 (`freq` & `smooth_span`)

针对实战中不同维度的择时需求（如大波段定投抄底 vs 短线突发催化脉冲追踪），必须根据**周期尺度与滤波平滑参数**进行针对性配置：

| 应用场景 | 推荐周期 (`freq`) | 平滑参数 (`smooth_span`) | 战术定位与核心价值 | 适用时机与实战案例 |
| :--- | :---: | :---: | :--- | :--- |
| **大周期定乾坤<br>(中长线底顶/定投)** | **周频 `W`** | 默认 **`2`** | **过滤日线级所有高频杂波与假突破**。<br>直接反映周线级别宏观流动性与筹码沉淀结构。 | **熊市大底探底**：如 2024 年 8~9 月漫长阴跌磨底期间，周线温度连续数周被压制在 20~30°C 极限蓄势区，出现显著底背离，是指数大波段建仓的核心定性锚。 |
| **短线趋势顺势跟踪<br>(持仓防守/防追高)** | **日频 `D`** | 推荐 **`3 ~ 5`** | **兼顾趋势平滑性与抗噪能力**。<br>过滤单日上影线或偶发脉冲，保持均线与温度方向的连续性。 | **右侧波段持筹**：适合右侧主升浪中的动态持仓观察与回踩生命线（MA20）判定，防止频繁假信号干扰交易节奏。 |
| **突发脉冲与拐点探测<br>(重大政策/突变预警)** | **日频 `D`** | 强制设为 **`1`<br>(关闭滤波)** | **零滞后纯单日原始加权脉冲**。<br>彻底消除 EWMA 历史权重滞后，捕捉由强外部催化导致的单日跳空跃迁。 | **历史级突变捕捉**：面对类似 2024-09-19（降息异动）与 2024-09-24（国新办史诗级政策落地）等突发事件，平滑温度会被前序阴跌拖累；而 `smooth=1` 时单日温度可瞬间跳涨超 +30°C，第一时间触发点火警报。 |

> [!TIP]
> 💡 **实战选型心法**：
> 1. **“大盘定调看周频 (`--freq W`)，微观脉冲看日频原始值 (`--freq D --smooth 1`)，波段持仓跟踪看日频平滑 (`--freq D --smooth 3`)”**；
> 2. 当日频原始温度（`smooth=1`）在低位连续阴跌区间突然出现 **单日跳空跃迁 $\ge +25^\circ\text{C}$ 且放量** 时，往往是市场拐点首发异动信号，应立即结合《机会雷达》的 `vol_list (量化异动池)` 进行个券狙击。

#### 常用核心基准标的池 (`CORE_BENCHMARK_ETFS`)：
包含 A 股主流宽基与大行业 ETF 代码字典（`"510300": "沪深300ETF"`, `"510500": "中证500ETF"`, `"512100": "中证1000ETF"`, `"159915": "创业板ETF"`, `"512880": "证券ETF"`, `"512800": "银行ETF"`, `"518880": "黄金ETF"`, `"513100": "纳指ETF"`）。

---

### 5.2 动态支撑阻力计算：`calculate_support_resistance`

```python
from tradingpatterns import calculate_support_resistance

sr_df = calculate_support_resistance(df, window=3)
current_support = sr_df["support"].dropna().iloc[-1]
```

---

### 5.3 组合风险平权与相关性去重

```python
from tradingpatterns import filter_correlated_assets, volatility_adjusted_position_sizing

# 1. 过滤高相关性同质化标的 (相关系数 > 0.8)
kept_symbols = filter_correlated_assets(returns_df, scores_dict, threshold=0.80)

# 2. 基于 ATR 倒数的风险平权资金分配 (Risk Parity)
weights = volatility_adjusted_position_sizing(atr_dict, total_capital=100000.0)
```

---

## 6. 均值回归与板块轮动引擎 (`mean_reversion` & `sector_rotation`)

该模块针对 A 股高波动、易超跌反弹与板块快速轮动的特征，提供 **A 股周线均值回归与三阶段跟踪引擎** 与 **截面相对强度四象限板块轮动引擎**。

### 6.1 A 股周线均值回归与三阶段跟踪 (`get_mean_reversion_signal`)

专门针对 A 股市场设计的周线大级别均值回归策略（Engine 2 核心）。采用“周线定大方向环境，日线形态/动量抓精准买点，三阶段移动止盈让利润奔跑”的设计：

```python
from tradingpatterns import (
    get_mean_reversion_signal,
    MeanReversionSignal,
    BOTTOM_PATTERNS
)

# 计算日线收盘后的均值回归信号 (供次日开盘执行)
sig = get_mean_reversion_signal(
    df_daily=df,
    symbol="510050",
    is_holding=False,             # 是否处于持仓状态
    entry_price=0.0,              # 若持仓，传入成本价
    holding_stage=1,              # 若持仓，传入当前跟踪阶段 (1, 2, 3)
    holding_weeks=0,              # 若持仓，传入已持仓周数
    current_stop_loss=0.0,        # 当前动态止损价
    trade_history=[]              # 传入历史交易记录用于单边熊市止损冷却判断
)

if sig.buy_signal:
    print(f"触发均值回归买入: 止损价={sig.stop_loss:.3f}, 原因={sig.reason}")
elif sig.sell_signal:
    print(f"触发平仓离场: 原因={sig.reason}")
```

#### 核心机制与三阶段动态跟踪止盈：
1. **周线超跌门禁**：周线触及布林下轨 (BBANDS 20, 2.0)、周线 RSI(14) $\le 38$、周线 CCI(14) $\le -90$ 多重共振。
2. **日线精准触发**：
   - 组合 A: TA-Lib 底部 K 线反转形态加权分 $\ge 0.8$ 且日 RSI $< 48$；
   - 组合 B: 日 RSI $< 35$ 拐头回升且 KD 低位金叉；
   - 组合 C: 资金流向 MFI $< 25$ 回升且收实体真阳线；
   - 周线 MACD 底背离（额外提供强信号加权）。
3. **三阶段跟踪止盈 (3-Stage Trailing Stop)**：
   - **Stage 1 (回归等待期)**：建仓后等待价格向周线中轨 (SMA20) 回归。执行近 3 周最低点 $\times 0.985$ 与日线 ATR 止损；若超 16 周未回归中轨触发时间止损。
   - **Stage 2 (回归确认期)**：价格有效突破周线中轨后，自动升级至 Stage 2，切换为 **Weekly EMA10 动态跟踪止盈**。
   - **Stage 3 (趋势延续期)**：价格突破周线布林上轨后，自动升级至 Stage 3，切换为 **Weekly EMA20 动态跟踪止盈**，全程护航大牛浪。
4. **风控保护机制**：
   - **单边熊市止损冷却 (Bear Market Cooldown)**：在价格低于 EMA53 的弱势格局下，若发生止损，触发 10 根 K 线（连续止损为 20 根）冷却期，禁止在同一深跌浪中频繁抄底，除非价格创出新低（$< 0.97 \times \text{前次止损价}$）或收复 EMA53。
   - **假摔快速重入 (Shakeout Re-entry)**：若止损后 6 根 K 线内快速以实体阳线收复 EMA20，判定为主力诱空假摔，触发快速纠错重入。
5. **状态出口**：`WAITING_WEEKLY_OVERSOLD`（周线超跌等待）/ `WAITING_DAILY_TRIGGER`（日线等待触发）/ `TRIGGERED_BUY`（已触发买入）/ `HOLDING_STAGE_N`（持仓第 N 阶段）/ `COOLDOWN`（熊市冷却中）/ `NO_DATA` / `NO_WEEKLY_DATA`。
   > ⚠️ **边界提醒**：上述状态名与**超跌企稳独立引擎**的 `OVERSOLD_ALERT` / `WAITING_DAILY` / `TRIGGERED` **形似而不同，不可互相匹配**。关于"信号延迟特性、早鸟通道、防追高硬限、中间态提前布局"，均属于超跌企稳引擎的行为，请见 [6.8 超跌企稳独立引擎](#68-超跌企稳独立引擎-oversold--stabilized)。

---

### 6.2 TA-Lib 底部与顶部反转形态扫描 (`scan_talib_patterns` / `BOTTOM_PATTERNS`)

> [!NOTE]
> `scan_talib_patterns` 属于**底层纯向量化形态识别算子**，仅负责识别单根或多根局部 K 线是否符合日本蜡烛图反转模式并输出加权得分。  
> 实战中单凭局部 K 线形态容易在下跌主浪中被诱多接飞刀，因此它仅作为 `get_mean_reversion_signal` 内部日线确认的子规则之一。对于真实的策略买入与出场跟踪，请直接使用上文 [6.1 节均值回归引擎](#61-a-股周线均值回归与三阶段跟踪-get_mean_reversion_signal)。

内置 11 种经典 TA-Lib 底部反转形态与 7 种顶部形态的向量化扫描与置信度权重评分：

```python
from tradingpatterns import scan_talib_patterns, BOTTOM_PATTERNS

# 方式一：传入 OHLC numpy 数组 (float64) 进行高速形态扫描
bottom_hits, bottom_weight, top_severe, top_warning = scan_talib_patterns(
    open_p=df_daily["open"].to_numpy(dtype=float),
    high_p=df_daily["high"].to_numpy(dtype=float),
    low_p=df_daily["low"].to_numpy(dtype=float),
    close_p=df_daily["close"].to_numpy(dtype=float)
)

# 方式二：直接传入包含 open/high/low/close 列的 DataFrame
# bottom_hits, bottom_weight, top_severe, top_warning = scan_talib_patterns(df_daily)

print("命中底部形态:", bottom_hits)       # 如 ['CDLMORNINGSTAR', 'CDLENGULFING_BULL']
print("综合底部形态得分:", bottom_weight) # 权重加权分
print("命中严重顶部形态:", top_severe)
print("命中预警顶部形态:", top_warning)
```

- **形态权重表 (`BOTTOM_PATTERNS`)**：包含晨星 (`CDLMORNINGSTAR`: 1.5)、看涨吞没 (`CDLENGULFING_BULL`: 1.5)、三白兵 (`CDL3WHITESOLDIERS`: 1.5)、看涨弃婴 (`CDLABANDONEDBABY_BULL`: 1.2)、十字晨星 (`CDLMORNINGDOJISTAR`: 1.2)、锤头线 (`CDLHAMMER`: 1.0)、刺透形态 (`CDLPIERCING`: 1.0)、倒锤头线 (`CDLINVERTEDHAMMER`: 0.8)、看涨孕线 (`CDLHARAMI_BULL`: 0.8)、蜻蜓十字 (`CDLDRAGONFLYDOJI`: 0.8)、看涨踢脚 (`CDLKICKING_BULL`: 1.0)。

---

### 6.3 均值回归事件驱动回测 (`run_mean_reversion_simulation`)

```python
from tradingpatterns import run_mean_reversion_simulation

res = run_mean_reversion_simulation(
    df=df_daily,
    symbol="510050",
    name="上证50ETF",
    initial_capital=100000.0,
    start_date="2024-01-01",
    min_window=40
)

print(f"累计收益率: {res.total_return_pct:.2f}%")
print(f"最大回撤: {res.max_drawdown_pct:.2f}%")
print(f"胜率: {res.win_rate_pct:.2f}% | 盈亏比: {res.profit_loss_ratio:.2f}")
```

---

### 6.4 全池截面轮动评估与纯趋势研判 (`evaluate_universe`)

`SectorRotationEngine` 的核心截面评级计算器。**如果仅用于日常盯盘、自媒体复盘、板块热点研判而不进行自动化交易与回测**，只需传入全池标的截至当天的历史 K 线数据，即可一次性计算出所有标的当前所属的轮动四象限、相对大盘强度 (RS) 历史分位数以及 10 日动能斜率。

```python
import kdata
from tradingpatterns import SectorRotationEngine

# 1. 准备待观察的板块/ETF 列表与对标基准 (默认 510300 沪深300ETF)
symbols = ["515880", "512800", "512690", "588000", "516160"]
names = {"515880": "通信", "512800": "银行", "512690": "酒", "588000": "科创50", "516160": "新能源"}
bench_sym = "510300"

# 2. 抓取近期 OHLCV 数据 (建议包含最近 >=60 根 K 线用于计算分位数与斜率)
dfs = {s: kdata.get_ohlc(s, "2025-01-01", "2026-08-22") for s in symbols}
bench_df = kdata.get_ohlc(bench_sym, "2025-01-01", "2026-08-22")

# 3. 初始化轮动引擎并计算最新截面
engine = SectorRotationEngine(
    symbols=symbols,
    names=names,
    benchmark_symbol=bench_sym
)

# current_date_idx 指定目标评估日在 DataFrame 中的索引 (最新一天取 len-1)
metrics = engine.evaluate_universe(
    universe_dfs=dfs,
    benchmark_df=bench_df,
    current_date_idx=len(bench_df) - 1,
    prev_quadrants={}          # 用于迟滞防抖 (单点截面快照可置空)
)

# 4. 打印板块趋势与动能分布
for m in metrics:
    print(f"[{m.quadrant.value:<10}] {m.symbol} {m.name:<6} | "
          f"相对强度分位数: {m.rs_percentile:>5.1f}% | "
          f"10日动能斜率: {m.rs_slope:>+7.4f} | "
          f"综合评分: {m.composite_score:.1f}")
```

---

### 6.5 四象限坐标体系与动能研判逻辑

板块轮动模型构建在 **“相对强弱 (RS Percentile) - 动能方向 (RS Slope)”** 二维坐标系上，用于定性识别资金在不同行业间的宏观转移规律：

```
                    RS 斜率向上 (资金持续流入 / 走强)
                                   ▲
                                   │
           【🌱 潜伏复苏区】        │      【🚀 强势领涨区】
             (RECOVERING)          │        (LEADING)
        • RS 分位 < 30%            │   • RS 分位 >= 30%
        • 斜率 > 0 (左侧拐头向上)   │   • 斜率 > 0 (顺势主升浪)
                                   │
 ──────────────────────────────────┼──────────────────────────────────► RS 相对强度历史分位数
                                   │                                    (基准线 30% 区分强弱)
           【❄️ 弱势持续区】        │      【🍂 高位衰退区】
             (LAGGING)             │        (WEAKENING)
        • RS 分位 < 30%            │   • RS 分位 >= 30%
        • 斜率 <= 0 (持续阴跌)     │   • 斜率 <= 0 (高位动能衰竭)
                                   │
                    RS 斜率向下 (资金持续抽离 / 走弱)
```

#### 纯趋势研判实操准则：
1. **🚀 寻找主线主升浪 (LEADING)**：处于领跑区，相对大盘走强且动能加速，代表当前全市场最确定的强势主线。
2. **🌱 捕捉低位反转潜伏 (RECOVERING)**：处于超跌复苏区，虽然过去 60 天表现弱于大盘，但 10 日回归斜率已向上拐头，通常对应主力左侧建仓的超跌修复期。
3. **🍂 识别高位出货风险 (WEAKENING)**：虽然过去强势（RS 高位），但动能斜率已掉头向下，表明资金开始分歧流出，警惕补跌风险。
4. **❄️ 规避弱势下行深坑 (LAGGING)**：低位且动能继续下行，资金持续抽离，坚决规避。

---

### 6.6 截面状态指标 (`SectorMetric` / `RotationQuadrant` / `QUADRANT_META`)

`evaluate_universe` 返回的 `List[SectorMetric]` 包含完整的量化截面指标与标准化象限元数据：

```python
from tradingpatterns import (
    SectorMetric,
    RotationQuadrant,
    QUADRANT_META,
    get_quadrant_meta,
)

# 获取任一象限的标准元数据
meta = get_quadrant_meta(RotationQuadrant.LEADING)
print(meta["title"])  # 输出: 🔥 领涨区 (LEADING)
print(meta["desc"])   # 输出: 强势上涨，强者恒强，建议持仓或顺势加仓
```

#### 四象限标准元数据与操作建议 (`QUADRANT_META`)：
| 象限枚举 (`RotationQuadrant`) | 象限名称 | 标识 | 业务语义与实战建议 |
| :--- | :--- | :--- | :--- |
| `LEADING` | **领涨区** | 🔥 | 强势上涨，强者恒强，建议持仓或顺势加仓 |
| `RECOVERING` | **复苏区** | 🌱 | 低位拐头向上，动能正在积聚，建议关注或潜伏 |
| `WEAKENING` | **衰退区** | ⚠️ | 高位动能衰竭，相对走弱，建议减仓或防守 |
| `LAGGING` | **滞后区** | ❄️ | 弱势下行通道，未见企稳，建议规避 |

#### `SectorMetric` 核心字段：
- **`quadrant`** (Enum: `RotationQuadrant`): 标的当前所属的轮动四象限（`LEADING`, `RECOVERING`, `WEAKENING`, `LAGGING`）。
- **`rs_value` / `rs_smooth`**: 标的相对基准的 20 日收益比率及经 EMA(5) 平滑后的相对强度序列。
- **`rs_percentile`**: 相对强度 (RS) 在过去 60 个交易日内的历史分位数排名（100% 代表当前处于 60 日最强极点，0% 为最弱极点）。
- **`rs_slope`**: RS 近 10 日的线性回归斜率（`talib.LINEARREG_SLOPE`）。大于 0 代表动能正在走强向上。
- **`composite_score`**: 0~10 的软加权综合打分（包含象限基础加权分与均值回归底背离加分）。
- **`reversion_signal`**: 若当天同时触发了日周双级别均值回归买点，携带对应的 `MeanReversionSignal` 信号事件。

---

### 6.7 截面组合历史回测 (`run_sector_rotation_backtest`)

将上述横截面评估能力放入时间轴，自动撮合多标的换仓，生成宏观资产组合的回测报告。

```python
from tradingpatterns import run_sector_rotation_backtest

portfolio_res = run_sector_rotation_backtest(
    universe_dfs=universe_dfs,
    benchmark_df=bench_df,
    symbols=symbols,
    names=names,
    benchmark_symbol="510300",
    start_date="2024-01-01",
    initial_capital=1000000.0,
    max_positions=4,           # 动态组合最大同时持仓数 (Top K)
    min_window=60              # 历史指标预热期
)

# 打印宏观绩效
print("组合累计收益率:", portfolio_res["total_return_pct"])
print("组合最大回撤:", portfolio_res["max_drawdown_pct"])
print("调仓明细:", portfolio_res["trades"]) # 返回详尽的买卖时间线
```

---

### 6.8 超跌企稳独立引擎 (Oversold & Stabilized)

> **🔑 与 Engine 2 的关系**：本引擎是**独立于执行双核**的左侧引擎。核心函数为 `check_oversold_stabilized`（底层检测）与 `get_extreme_reversal_signal`（策略信号包装）。
> **它不经 `get_strategy_signal` 分发** —— `get_strategy_signal(StrategyEngine.ENGINE2_REVERSAL)` 路由到的是**周线均值回归**（见 6.1 节）。因此 `ENGINE2_REVERSAL` / `"engine2"` / `"oversold"` / `"reversal"` 这些 key **取不到本引擎的状态**，必须直接调用 `get_extreme_reversal_signal`。

#### 1. 三档状态出口（真值语义）

| 状态 | 含义 | 可否买入 |
| :--- | :--- | :--- |
| `OVERSOLD_ALERT` | 周线超跌条件成立，但尚未企稳（L1） | 否（仅预警） |
| `WAITING_DAILY` | 周线已完成企稳确认，等待日线精确触发（L2） | 否（观察，**可提前布局**） |
| `TRIGGERED` | 右侧确认完成，买入信号成立（L3） | 是 |
| `NONE` | 未满足超跌条件 | 否 |

#### 2. 状态覆盖态（风控降级，均不可买入）
`get_extreme_reversal_signal` 会在原始 status 之上覆盖出：`WAITING_BEAR_MARKET_DIP`（标的自身上方 EMA53 且回撤未达 -25%，拒绝左侧抄底）、`WAITING_MARKET_STABILIZATION`（大盘跌破 EMA20 × 0.985）、`EXTENDED_WAITING_PULLBACK`（距 EMA20 > 12% 或距结构低点 > 18%，防追高）、`REJECTED_BY_BEARISH`（日线看跌拒绝形态）、`NO_DATA`（K 线不足）。

#### 3. 超跌门槛（L1 判定）
- **默认**：`-coef × annual_vol`，ETF `coef = 0.8`、个股 `coef = 1.0`；区间夹紧——ETF $[-35\%, -12\%]$、个股 $[-50\%, -20\%]$。
- **固定标的池覆盖**：按标的分档覆盖——高弹性科技/半导体/医药 ETF `-30%`、红利/价值 ETF `-15%`、宽基指数 `-22%`。
- **替代通路**：周线 BIAS20 ≤ $-12\%$(ETF)/$-20\%$(个股) **且** 周线 RSI 最低 ≤ 35。
- **硬约束**：须位于周线 EMA60 下方（5% 容差）。

#### 4. 信号延迟特性与中间态预警（纯信号观察者指南）
- 超跌企稳属于**左侧偏确认型信号**，从价格见底到最终 `buy_signal=True`（`TRIGGERED`），典型延迟 **2~3 周**（10~20 个交易日），距底部涨幅约 5%~15%。**早鸟通道**（`oversold_entry_mode == "EARLY_BIRD"`：强反转形态或底背离 + 放量真阳线）可把延迟缩短至约 **1 周**（6~8 个交易日），距底部涨幅约 3%~8%。
- **防追高硬限**：信号触发时价格距近期低点涨幅不得超过 $\max(10\%, \min(18\%, 0.5 \times annual\_vol))$，超出则阻断（当日放量 $\ge 1.8\times$ MA20 可豁免）。
- **提前布局建议**：若不希望等待 `TRIGGERED`，可关注中间态 `WAITING_DAILY`（周线已完成超跌企稳确认）——它比最终买入信号早出现 **1~5 个交易日**。

#### 5. 在机会雷达中的取值方式
雷达以**旁路**方式单独调用一次 `get_extreme_reversal_signal`，把本引擎结果挂到每个标的上，对应字段为 `oversold_status` / `oversold_drawdown` / `oversold_bottom_score` / `oversold_tier` / `oversold_entry_mode` / `sig_oversold_stabilized` / `oversold_weekly_signals` / `oversold_daily_signals`（见 1.3 节的返回字段表）。

```python
from tradingpatterns import analyze_opportunity_radar
from tradingpatterns.radar_selectors import (
    get_oversold_watchlist,                 # WAITING_DAILY：早鸟，比 TRIGGERED 早一步
    get_high_quality_oversold_stabilized,   # TRIGGERED：优质超跌企稳机会
    get_oversold_alerts,                    # OVERSOLD_ALERT：最早、胜率最低
)

report = analyze_opportunity_radar(pool, frequency="daily", include_alerts=True)

for it in get_oversold_watchlist(report, min_bottom_score=3.0):
    print(it.symbol, it.oversold_status, f"{it.oversold_drawdown:.1%}",
          f"筑底分={it.oversold_bottom_score:.1f}", it.oversold_tier, it.curr_state)
```

> **⚠️ 修正说明**：早期版本文档曾写"雷达 `alert_list` 中该中间态为 `signal_tier="L1"`"。实际上超跌引擎自身的层级是 `oversold_tier`（`WAITING_DAILY` 对应 `"L2"`），它**不参与** `signal_tier`（该字段由均值回归/趋势突破/Kaufman 三引擎取最高层级合成）。中间态可通过 `oversold_status="WAITING_DAILY"` + `curr_state="超跌观察"` 可靠识别。

---

## 7. 美股专属量化系统与机会雷达 (US ETF Quantitative System & Radar)

为了适配美股市场的长牛强趋势（High Efficiency Ratio）、T+0 交易机制、行业动量效应与宏观利率敏感性，系统提供了独立于 A 股体系的美股专属量化层。

```
                          【SPY 宏观绝对动量与体制判别 (us_macro)】
                            (SMA200 / 10月绝对动量 / 建议总仓位)
                                              │
                     ┌────────────────────────┴────────────────────────┐
                     ▼                                                 ▼
        【自适应超级趋势策略 (us_strategy)】               【美股机会雷达 5 大状态机 (us_opportunity_radar)】
         - KAMA 自适应均线 + Donchian 通道突破              - SUPER_TREND / MOMENTUM_LEADER
         - EMA20 / SMA50 缩量回踩优质低吸                    - PULLBACK_BUY / DEFENSIVE_HOLD / LAGGING
         - 动态 Chandelier ATR 吊灯止损                     - 0-10 分多维加权技术评分
```

### 7.1 宏观绝对动量与体制判别 (`us_macro`)

```python
from tradingpatterns import (
    USMarketRegime,
    USMacroSnapshot,
    compute_us_macro_series,
    get_latest_us_macro_snapshot,
)

# 1. 计算 SPY 宏观体制时间序列
macro_df = compute_us_macro_series(spy_df, cash_df=shy_df)

# 2. 获取最新宏观快照
snapshot: USMacroSnapshot = get_latest_us_macro_snapshot(spy_df, cash_df=shy_df)

print("市场体制:", snapshot.regime.value)               # RISK_ON / RISK_OFF / VOL_PANIC
print("站上200日均线:", snapshot.is_above_sma200)      # True / False
print("10月绝对动量:", snapshot.momentum_10m)          # float
print("宏观安全得分 (0-10):", snapshot.risk_score)     # 0.0 ~ 10.0
print("建议股票总仓位:", snapshot.suggested_equity_ratio) # 0.0 ~ 1.0 (例如 0.2 或 1.0)
```

---

### 7.2 自适应超级趋势与截面双动量策略 (`us_strategy`)

```python
from tradingpatterns import (
    calculate_kama,
    calculate_er,
    run_us_super_trend_strategy,
    compute_us_rotation_metrics,
    USTrendBacktestResult,
    USRotationMetric,
    USRotationQuadrant,
)

# 1. Kaufman 自适应均线与效率比 (ER) 计算
er_series = calculate_er(df["close"], period=10)
kama_series = calculate_kama(df["close"], timeperiod=10)

# 2. 单标的美股超级趋势策略回测 (内嵌宏观风控与动态吊灯止损)
result: USTrendBacktestResult = run_us_super_trend_strategy(
    df=qqq_df,
    symbol="QQQ",
    macro_series=macro_df,
    initial_capital=100000.0,
    # 可选显式参数配置 (USTrendParams 杜绝硬编码魔法数字，可配置 enable_rs_filter 相对强度过滤)
    # params=USTrendParams(donchian_period=20, trailing_atr_mult=3.0, cooldown_bars_tier1=8, enable_rs_filter=False)
)

print(f"累计收益: {result.total_return_pct:+.2f}% | 年化CAGR: {result.cagr:+.2f}%")
print(f"夏普比率: {result.sharpe_ratio:.2f} | 最大回撤: {result.max_drawdown_pct:.2f}%")
print(f"胜率: {result.win_rate:.1f}% | 盈亏比: {result.profit_factor:.2f}")

# 3. 截面双动量与行业相对强度 (RS) 轮动评估
rotation_metrics = compute_us_rotation_metrics(
    target_dfs={"XLK": xlk_df, "XLE": xle_df, "SMH": smh_df},
    benchmark_df=spy_df
)
for sym, metric in rotation_metrics.items():
    print(f"{sym}: 象限={metric.quadrant.value}, 复合动量={metric.composite_momentum:.3f}, RS百分位={metric.rs_percentile:.1f}%")
```

---

### 7.3 美股截面双动量机会雷达 (`us_opportunity_radar`)

美股机会雷达是顶层的**“全池选品与板块强弱体检引擎”**，与底层的“双核买卖执行引擎”协同分工：
- **双核策略 (Dual-Core)** 解决微观买卖点执行：哪一天该挂单建仓、加减仓、止盈或止损；
- **机会雷达 (Opportunity Radar)** 解决宏观与中观选品：每天盘后全自动扫描全美股池，识别**当前资金主线、哪类资产处于领头羊强势象限、谁出现黄金低吸回踩**。

#### 核心原理：“双动量 (Dual Momentum)”模型：
1. **绝对动量 (Absolute Momentum / 宏观守门员)**：以 SPY 200 日线与 10 个月动量过滤牛熊大势。若大盘处于 `RISK_OFF` 破位或 `VOL_PANIC` 恐慌踩踏，系统压低股票 ETF 评级并激活防守资产提示；
2. **截面相对动量 (Cross-Sectional Relative Momentum)**：计算各行业相对 SPY 的相对强度（$RS = P_{\text{ETF}} / P_{\text{SPY}}$），在四象限（领头羊 Leading、衰退区 Weakening、滞后区 Lagging、修复区 Recovering）中定位资金流向；
3. **0-10 分多维加权评分体系**：
   - 趋势强度 (4.0 分)：均线多头排列 + KAMA 效率比 ER + ADX(14)；
   - 相对动量 (3.0 分)：相对 SPY 的 RS 象限与全池复合动量百分位；
   - 回踩结构 (2.0 分)：EMA20/SMA50 支撑位缩量企稳与反转形态；
   - 宏观安全 (1.0 分)：大盘体制与波动率健康度；
4. **5 大美股专属雷达机会状态机**：
   - `SUPER_TREND`：超级主升浪狂飙；
   - `MOMENTUM_LEADER`：全市场领跑领头羊 ETF；
   - `PULLBACK_BUY`：强势趋势下缩量回踩 EMA20 优质低吸点；
   - `DEFENSIVE_HOLD`：大盘震荡时的债券/黄金独立避险状态；
   - `LAGGING`：走弱跑输大盘，提示观望。

```python
from tradingpatterns import (
    USRadarState,
    USRadarItem,
    USRadarSummary,
    evaluate_us_opportunity_item,
    analyze_us_opportunity_radar,
)

# 1. 单标的雷达打分与状态评估
item: USRadarItem = evaluate_us_opportunity_item(
    symbol="NVDA",
    df=nvda_df,
    benchmark_df=spy_df,
    name="NVIDIA Corp",
    rank_percentile=95.0
)
print("雷达状态:", item.radar_state.value)       # SUPER_TREND / MOMENTUM_LEADER / PULLBACK_BUY / DEFENSIVE_HOLD / LAGGING
print("综合得分:", item.composite_score)        # 0.0 ~ 10.0 (趋势40% + 动量30% + 回踩20% + 宏观10%)
print("关键支撑位:", item.key_support)          # float
print("操作建议:", item.action_suggestion)     # 专家行动指南

# 2. 全池批量机会雷达分析
summary: USRadarSummary = analyze_us_opportunity_radar(
    target_dfs=target_dfs,
    benchmark_df=spy_df,
    cash_df=shy_df
)
print(f"扫描标的数: {summary.total_scanned}")
print("超级主升标的:", [x.symbol for x in summary.super_trend_items])
print("动量领跑标的:", [x.symbol for x in summary.momentum_leaders])
print("优质回踩低吸:", [x.symbol for x in summary.pullback_buys])
print("避险防守标的:", [x.symbol for x in summary.defensive_holds])
```

---

### 7.4 多周期统一门面入口 (`run_us_strategy` / `compute_us_rotation` / `analyze_us_radar`)

系统提供了支持日线 (`'D'`) 与周线 (`'W'`) 自动调度的统一顶层门面 API，内置自适应降采样 (`auto_resample=True` 时自动将日线转为 `'W-FRI'` 周线)：

```python
from tradingpatterns import (
    run_us_strategy,
    compute_us_rotation,
    analyze_us_radar,
    run_us_weekly_super_trend_strategy,
    compute_us_weekly_rotation_metrics,
    analyze_us_weekly_opportunity_radar,
    USWeeklyTrendSignalType,
    USWeeklyRotationQuadrant,
    USWeeklyTrendTrade,
    USWeeklyTrendBacktestResult,
    USWeeklyRotationMetric,
)

# 1. 统一入口：运行美股趋势策略 (支持日频 'D' 或周频 'W'，内置自动重采样)
res_daily: USTrendBacktestResult = run_us_strategy(
    df=qqq_df,
    symbol="QQQ",
    macro_series=macro_df,
    initial_capital=100000.0,
    timeframe="D",
)

res_weekly: USWeeklyTrendBacktestResult = run_us_strategy(
    df=qqq_df,
    symbol="QQQ",
    macro_series=macro_df,
    initial_capital=100000.0,
    timeframe="W",
    auto_resample=True,
)

print(f"周线策略累计收益: {res_weekly.total_return_pct:+.2f}% | 夏普: {res_weekly.sharpe_ratio:.2f}")

# 2. 统一入口：计算截面行业双动量与相对强度 (支持 'D' / 'W')
rotation_daily = compute_us_rotation(
    target_dfs={"XLK": xlk_df, "XLE": xle_df, "SMH": smh_df},
    benchmark_df=spy_df,
    timeframe="D",
)

rotation_weekly = compute_us_rotation(
    target_dfs={"XLK": xlk_df, "XLE": xle_df, "SMH": smh_df},
    benchmark_df=spy_df,
    cash_df=shy_df,
    timeframe="W",
    auto_resample=True,
)

# 3. 统一入口：运行全池机会雷达批量扫描 (支持 'D' / 'W')
weekly_radar_summary = analyze_us_radar(
    target_dfs=target_dfs_dict,
    benchmark_df=spy_df,
    cash_df=shy_df,
    timeframe="W",
    auto_resample=True,
)
print(f"周线机会雷达扫描完成: 共 {weekly_radar_summary.total_scanned} 标的")
```

---

### 7.5 美股专属大类资产均值回归引擎 (`us_mean_reversion`)

专为美股 ETF 设计的左侧大波段均值回归策略（Engine 2），与右侧超级趋势（Engine 1）构成双核互补体系。

#### 核心特征与设计原则：
1. **大类资产超跌分级**：宽基指数（SPY/QQQ/IWM 等）触及 $\text{BBANDS}(20, 2.0)$ 下轨或 $\text{RSI}(14) \le 35$；科技高贝塔（XLK/SMH/SOXX/XBI 等）强制双重深度确认 $\text{BBANDS}(20, 2.2)$ 且 $\text{RSI}(14) \le 30$；防守固收/商品（TLT/GLD/XLU 等）触及 $\text{BBANDS}(20, 1.8)$ 或 $\text{RSI}(14) \le 40$。
2. **严格前向因果与 As-of 对齐**：周线指标基于上一周已完整闭合的周 K 线计算并 `shift(1)` 前向对齐，周中未闭合周不进入计算，杜绝未来数据泄露与 `.bfill()`。
3. **Next-Open 开盘撮合**：收盘判定信号，次日以开盘价挂单撮合入场与离场，支持跳空防穿仓保护。
4. **三阶段阶梯出场**：
   - **Stage 1（回归期）**：守初始硬止损，反弹触及周线中轨（SMA20）强制**平半仓（50%）**锁定确定性利润，并将剩余仓位止损平移抬升至保本价（Breakeven Stop）；
   - **Stage 2（动量期）**：有效突破中轨后，切换至日线 EMA10 动态单调递增跟踪止盈；
   - **Stage 3（趋势期）**：突破周线布林上轨后，升级为 EMA20/KAMA 趋势骑浪跟踪；
   - **时间止损**：Stage 1 潜伏期超过 40 个交易日（约 8 周）仍未回归中轨，强制 Next-Open 平仓。
5. **宏观与连亏风控**：大盘处于 `VOL_PANIC`（极度恐慌）时，股票类 ETF 强制禁开均值回归（防守类 TLT/GLD 豁免）；单次止损冷却 10 日，连续亏损 $\ge 2$ 次强制冷却 20 日。

```python
from tradingpatterns import (
    USAssetTier,
    USMeanReversionStage,
    USMeanReversionSignal,
    USMeanReversionTrade,
    USMeanReversionBacktestResult,
    generate_us_mean_reversion_signals,
    evaluate_us_mean_reversion_backtest,
    compute_us_macro_series,
)

# 1. 准备行情与宏观序列
macro_series = compute_us_macro_series(spy_df)

# 2. 生成均值回归信号与 Next-Open 撮合记录
signals, trades = generate_us_mean_reversion_signals(
    df=tlt_df,
    symbol="TLT",
    asset_tier=USAssetTier.DEFENSIVE_BOND,
    macro_series=macro_series,
    min_score_threshold=6.0,
)

# 3. 统计回测量化绩效
result: USMeanReversionBacktestResult = evaluate_us_mean_reversion_backtest(
    symbol="TLT",
    trades=trades,
    initial_capital=100000.0,
)

print(f"标的: {result.symbol} | 交易次数: {result.total_trades} | 胜率: {result.win_rate:.1f}%")
print(f"累计收益: {result.total_return_pct:+.2f}% | 盈亏比: {result.profit_factor:.2f} | 最大回撤: {result.max_drawdown_pct:.2f}%")
```

---

### 7.6 美股全景回测与雷达扫描 CLI

支持通过包自带的 CLI 命令行工具或 Python API 对美股全池或自定义标的进行批量回测与最新雷达扫描：

```bash
# 全池或多标的批量策略回测
tp backtest -s SPY,QQQ,SMH,XLK,XLE,GLD --engine combined --start 2024-01-01

# 标的池 YAML 文件批量快速扫描
tp scan -f us_pool.yaml --json-simple
```

---

## 8. 跨境 QDII ETF 溢价套利与趋势共振引擎 (`overseas_premium`)

**跨境 QDII ETF 溢价双核共振引擎 (`Overseas Premium Engine`) 专为国内挂牌的海外指数/行业 ETF（如标普500 ETF、纳指100 ETF、纳指科技 ETF、标普油气 ETF、日经225 ETF等）设计。**

它解决了跨境 ETF 常见的两大核心痛点：
1. **防范高位溢价泡沫接盘**：美股走牛或国内情绪过热时，国内 QDII ETF 溢价率经常飙升至 10%~20%。引擎通过**“盘后相对比价偏离度 (Z-Score)”**进行硬性阻断，并在溢价泡沫破裂时提前止盈；
2. **美股超级趋势与周线强共振**：仅在美股底层资产（SPY/QQQ/XOP/EWJ）确认周线及日线多头强趋势、且国内溢价健康时才触发买入；同时在极端恐慌错杀（折价率极深）时触发左侧套利。

```
                      【国内 QDII ETF 行情 + 美股底层资产行情】
                                         │
                                         ▼
                           【align_cn_us_series 盘后对齐】
                           (国内 T 日 锚定 美股 T-1 日收盘)
                                         │
                                         ▼
                       【calculate_premium_zscore 溢价偏离度】
                        (60日滚动比价偏离度 Z-Score 计算)
                                         │
                   ┌─────────────────────┴─────────────────────┐
                   ▼                                           ▼
       【底层美股趋势与动能判定】                       【溢价风控门禁与极值判别】
   • KAMA 上行 + Donchian 通道突破              • 正常安全区: Z < 1.0 (允许买入)
   • EMA20 强势回踩企稳 (Pullback)              • 追高阻断区: Z >= 1.0 (阻断开仓)
   • 周线 EMA20 多头强趋势共振                   • 泡沫风险区: Z > 2.5 (止盈预警)
                   │                                           │
                   └─────────────────────┬─────────────────────┘
                                         │
                                         ▼
          【evaluate_overseas_opportunity_item / analyze_overseas_radar】
      输出：TREND_BUY (趋势共振买点) / DISCOUNT_BUY (折价套利买点) /
            BLOCKED (高溢价阻断) / PREMIUM_BUBBLE_SELL (泡沫风险卖点) / WATCH (观望)
```

---

### 8.1 底层资产映射与盘后时差对齐

```python
from tradingpatterns import (
    OVERSEAS_UNDERLYING_MAP,
    get_underlying_for_symbol,
    align_cn_us_series,
)

# 1. 查询国内跨境 ETF 对应的底层海外代码
us_symbol = get_underlying_for_symbol("513100")  # 返回 "QQQ"
us_symbol_oil = get_underlying_for_symbol("159518")  # 返回 "XOP"

# 2. 盘后离线交易日时差严格对齐 (国内 T 日白盘收盘价锚定美股 T-1 日收盘价)
cn_aligned, us_aligned = align_cn_us_series(cn_df, us_df)
```

---

### 8.2 60日相对比价偏离度计算 (`calculate_premium_zscore`)

无需获取实时汇率或 IOPV，算法通过滚动统计比价的比值来规避长期汇率漂移：

$$Ratio_t = \frac{Close_{CN, t}}{Close_{US, t-1}}$$
$$Z_t = \frac{Ratio_t - Mean_{60}}{\max(Std_{60}, 1e-6)}$$

```python
from tradingpatterns import calculate_premium_zscore

# 计算 60 日相对比价、滚动均值及偏离度 Z-Score
ratio_arr, mean_arr, zscore_arr = calculate_premium_zscore(
    cn_close=cn_df["close"].to_numpy(),
    us_close_aligned=us_aligned["close"].to_numpy(),
    window=60
)
print("最新溢价偏离度 Z-Score:", zscore_arr[-1])
```

---

### 8.3 单标的实时机会与信号评估 (`evaluate_overseas_opportunity_item` / `get_overseas_premium_signal`)

用于每日收盘后对单个跨境 ETF 进行**实时机会发现与风控决策**（例如次日是否开仓、是否被高溢价阻断、是否需要止盈止损）：

```python
from tradingpatterns import evaluate_overseas_opportunity_item, compute_us_macro_series

# 1. 计算宏观背景序列 (以 SPY 为基准)
macro_df = compute_us_macro_series(spy_df)

# 2. 评估单标的最新机会与决策
item = evaluate_overseas_opportunity_item(
    cn_df=cn_df,                        # 国内 ETF 日线 (如 513100)
    us_df=qqq_df,                       # 对应底层美股日线 (如 QQQ)
    symbol="513100",
    name="纳指ETF",
    macro_series=macro_df,
    max_buy_zscore=1.0,                 # 溢价门禁 (Z-Score < 1.0 允许买入)
    bubble_sell_zscore=2.5,             # 泡沫止盈阈值 (Z-Score > 2.5)
    discount_buy_zscore=-2.5,           # 极端折价套利阈值 (Z-Score < -2.5)
    require_weekly_bull=True,           # 开启周线多头强趋势门禁
    is_holding=False,                   # 当前是否持仓
)

if item:
    print(f"标的: {item.name}({item.symbol}) -> 底层: {item.underlying_symbol}")
    print(f"最新收盘: 国内 {item.close_cn} | 底层美股 {item.close_us}")
    print(f"溢价偏离 Z-Score: {item.zscore:+.2f} (溢价安全={item.is_premium_safe}, 泡沫风险={item.is_bubble_risk})")
    print(f"美股动能: 突破={item.is_us_breakout}, 回踩={item.is_us_pullback}, 周线多头={item.is_weekly_bull}")
    print(f"执行行动: 【{item.action}】 (买入信号={item.buy_signal}, 卖出信号={item.sell_signal})")
    print(f"建议防守止损位: {item.stop_loss:.3f}")
    print(f"决策原因: {item.reason}")
```

#### 决策行动分类 (`item.action`)：
- **`BUY`**: 触发买点！底层美股趋势突破/回踩确认且溢价健康（`TREND_BUY`），或国内极端恐慌错杀折价（`DISCOUNT_BUY`）。
- **`BLOCKED`**: **高溢价风控阻断！** 底层美股虽然走牛，但国内 ETF 溢价偏离度过高（`Z-Score >= 1.0`），坚决禁止追高。
- **`SELL`**: 触发离场！包含高溢价泡沫破裂防范（`PREMIUM_BUBBLE_SELL`）、底层美股破位吊灯移动止损（`US_TRAILING_STOP`）或宏观极速恐慌（`US_MACRO_RISK_OFF`）。
- **`WATCH`**: 观望蓄势或处于无买点震荡区间。
- **`HOLD`**: 若传入 `is_holding=True` 且未触发卖点，处于正常持仓保护状态。

---

### 8.4 跨境全池机会雷达批量扫描 (`analyze_overseas_radar` / `OverseasRadarSummary`)

一键对全市场所有跨境 QDII ETF 进行批量扫描与分类归档，可直接作为**每日跨境机会复盘看板与自动化监控工具**：

```python
from tradingpatterns import analyze_overseas_radar, compute_us_macro_series

# 准备国内标的池字典与海外底层资产字典
# cn_pool: {"513100": cn_df1, "159518": cn_df2, "513880": cn_df3, ...}
# us_pool: {"QQQ": qqq_df, "XOP": xop_df, "EWJ": ewj_df, "SPY": spy_df}

macro_df = compute_us_macro_series(us_pool["SPY"])

# 批量扫描跨境全池机会雷达
radar: OverseasRadarSummary = analyze_overseas_radar(
    cn_dfs=cn_pool,
    us_dfs=us_pool,
    macro_series=macro_df,
    names={"513100": "纳指ETF", "159518": "油气ETF", "513880": "日经225ETF"},
    max_buy_zscore=1.0,
    bubble_sell_zscore=2.5,
    discount_buy_zscore=-2.5,
)

print(f"📊 【跨境 QDII ETF 机会雷达 | 日报】(共扫描 {radar.total_scanned} 只标的)\n")

print("🔥 【核心买入机会 (趋势共振 / 折价套利)】")
for opp in radar.opportunities:
    print(f"• [{opp.signal_type.value}] {opp.name}({opp.symbol}): Z-Score={opp.zscore:+.2f} | 建议防守位: {opp.stop_loss:.3f} | 原因: {opp.reason}")

print("\n🚫 【美股走强但高溢价阻断 (严禁追高)】")
for blk in radar.blocked_items:
    print(f"• {blk.name}({blk.symbol}): Z-Score={blk.zscore:+.2f} (偏离过大) | 底层美股: {blk.underlying_symbol}")

print("\n⚠️ 【高溢价泡沫风险预警】")
for risk in radar.bubble_risks:
    print(f"• {risk.name}({risk.symbol}): Z-Score={risk.zscore:+.2f} (高位滞涨/泡沫破裂风险)")

print("\n👀 【跟踪观察池】")
for w in radar.watches:
    print(f"• {w.name}({w.symbol}): Z-Score={w.zscore:+.2f} | 美股突破={w.is_us_breakout}")
```

---

### 8.5 双核共振策略回测与绩效寻优 (`run_overseas_premium_strategy`)

对特定标的或全池进行事件驱动历史回测，检验趋势共振与溢价风控的综合实战收益：

```python
from tradingpatterns import (
    OverseasSignalType,
    OverseasTrade,
    OverseasBacktestResult,
    run_overseas_premium_strategy,
    compute_us_macro_series,
)

# 1. 计算美股大盘宏观状态 (以 SPY 为基准)
macro_df = compute_us_macro_series(spy_df)

# 2. 运行单标的跨境 ETF 溢价双核共振策略回测
result: OverseasBacktestResult = run_overseas_premium_strategy(
    cn_df=cn_df,                        # 国内 ETF 日线行情 (如 513100)
    us_df=qqq_df,                       # 对应底层海外日线行情 (如 QQQ)
    symbol="513100",
    underlying_symbol="QQQ",
    macro_series=macro_df,
    initial_capital=100000.0,
    max_buy_zscore=1.0,                 # 买入溢价上限 (Z-Score < 1.0)
    bubble_sell_zscore=2.5,             # 溢价泡沫防范卖出阈值 (Z-Score > 2.5)
    discount_buy_zscore=-2.5,           # 极端折价错杀套利买入阈值 (Z-Score < -2.5)
    require_weekly_bull=True            # 启用底层周线强趋势过滤
)

print(f"累计收益: {result.total_return_pct:+.2f}% | 年化CAGR: {result.cagr:+.2f}%")
print(f"夏普比率: {result.sharpe_ratio:.2f} | 最大回撤: {result.max_drawdown_pct:.2f}%")
print(f"胜率: {result.win_rate:.1f}% | 盈亏比: {result.profit_factor:.2f}")
print(f"成功阻断高溢价接盘次数: {result.blocked_high_premium_buys} 次")

# 3. 遍历交易明细
for trade in result.trades:
    print(f"买入: {trade.entry_date} ({trade.entry_price:.3f}, Z={trade.entry_zscore:+.2f}) -> "
          f"卖出: {trade.exit_date} ({trade.exit_price:.3f}, Z={trade.exit_zscore:+.2f}) | "
          f"收益: {trade.return_pct:+.2f}% | 原因: {trade.exit_reason}")
```

---

## 9. 实盘撮合与信号全生命周期追踪 (`execution`)

**实盘撮合与执行模块遵循“策略信号触发 (Alpha Firing)”与“交易所物理执行约束 (Execution Constraints)”严格解耦的设计原则。**

策略引擎只根据量化形态与技术面输出纯粹的买卖信号，撮合层则负责在 T+1 开盘时判定信号的物理可行性（一字涨停/跌停拦截、停牌检测、滑点/费率损耗仿真、已有持仓去重），并精确记录所有未成交信号及其物理归因。

```
                          ┌────────────────────────┐
                          │   策略引擎输出纯买卖信号   │
                          │ (StrategySignalEvent)  │
                          └───────────┬────────────┘
                                      │
                                      ▼
                      【ExecutionMatcher 撮合仿真器】
             (次日开盘物理约束校验：一字涨跌停 / 停牌 / 滑点手续费)
                                      │
                 ┌────────────────────┴────────────────────┐
                 ▼                                         ▼
         【✅ 成功撮合成交】                        【❌ 物理阻断 / 未成交归档】
       (成交价 = 开盘价 ± 滑点)                  (LIMIT_UP_LOCKED, SUSPENDED...)
                 │                                         │
                 └────────────────────┬────────────────────┘
                                      │
                                      ▼
                        【compute_execution_summary】
                    (全生命周期执行汇总与成交率统计报表)
```

---

### 9.1 交易所物理约束与涨跌停比例 (`get_a_share_price_limit_ratio` / `ExecutionStatus`)

系统内置了各板块交易规则的涨跌停比例自适应解析函数 `get_a_share_price_limit_ratio`：

```python
from tradingpatterns import get_a_share_price_limit_ratio, ExecutionStatus

# 板块涨跌幅上限自动识别
limit_main = get_a_share_price_limit_ratio("600519")      # 主板 10% (0.10)
limit_cyb = get_a_share_price_limit_ratio("300750")       # 创业板 20% (0.20)
limit_kcb = get_a_share_price_limit_ratio("688981")       # 科创板 20% (0.20)
limit_bj = get_a_share_price_limit_ratio("832000")        # 北交所 30% (0.30)
limit_st = get_a_share_price_limit_ratio("600000", "ST浦发") # ST 股票 5% (0.05)
limit_us = get_a_share_price_limit_ratio("AAPL")          # 美股无涨跌停限制 (1.00)
```

#### 执行状态枚举 (`ExecutionStatus`)：
- **`FILLED`**: 正常撮合成交（按次日开盘价 + 滑点成交）。
- **`LIMIT_UP_LOCKED`**: 次日开盘一字涨停封死，买入挂单无法撮合。
- **`LIMIT_DOWN_LOCKED`**: 次日开盘一字跌停封死，卖出挂单无法撮合。
- **`SUSPENDED`**: 标的次日停牌或无成交量。
- **`SKIPPED_ALREADY_IN_POSITION`**: 已处于持仓状态，跳过重复开仓买点。
- **`INSUFFICIENT_LIQUIDITY`**: 流动性不足。
- **`EXPIRED`**: 信号超时失效。

---

### 9.2 次日开盘撮合可行性仿真 (`ExecutionMatcher`)

```python
from tradingpatterns import ExecutionMatcher, UnfilledSignal

matcher = ExecutionMatcher(
    slippage_rate=0.0005,      # 单边滑点率 (默认万 5)
    fee_rate=0.0002,           # 佣金/经手费费率 (默认万 2)
    strict_limit_check=True    # 启用严格涨跌停与停牌物理拦截
)

# 1. 评估次日买入信号撮合可行性
can_buy, buy_price, unfilled_buy = matcher.check_buy_feasibility(
    symbol="510050",
    signal_date="2026-08-20",
    engine="ENGINE2_REVERSAL",
    signal_close_price=2.850,
    next_open=2.855,
    next_high=2.870,
    next_low=2.845,
    next_close=2.860,
    next_volume=1500000.0,
    name="上证50ETF"
)

if can_buy:
    print(f"买入成功撮合，实际成交价 (含滑点): {buy_price:.3f}")
else:
    print(f"买入未能成交: [{unfilled_buy.status.value}] {unfilled_buy.reason}")

# 2. 评估次日卖出信号撮合可行性
can_sell, sell_price, unfilled_sell = matcher.check_sell_feasibility(
    symbol="510050",
    signal_date="2026-08-25",
    engine="ENGINE2_REVERSAL",
    signal_close_price=2.950,
    next_open=2.945,
    next_high=2.960,
    next_low=2.940,
    next_close=2.955,
    next_volume=1200000.0,
    name="上证50ETF"
)
```

---

### 9.3 未成交信号追踪与生命周期汇总 (`UnfilledSignal` / `compute_execution_summary`)

```python
from tradingpatterns import compute_execution_summary

# 模拟成交历史与未成交拦截记录
executed_trades = [
    {"entry_date": "2026-08-01", "exit_date": "2026-08-15", "symbol": "510050", "return_pct": 5.2}
]
unfilled_records = [unfilled_buy.to_dict()] if unfilled_buy else []

# 生成信号全生命周期统计分析报告
summary = compute_execution_summary(
    trades=executed_trades,
    unfilled_signals=unfilled_records
)

print(f"总触发信号数: {summary['total_signals']}")
print(f"实际成交笔数: {summary['filled_trades']}")
print(f"综合撮合成交率: {summary['fill_rate_pct']}%")
print(f"未成交物理归因分布: {summary['reason_stats']}")
```

---

## 10. 四大经典战术买点与全生命周期形态识别 (`tactical_patterns`)

该模块将经典的量化形态识别标准化为从 **跌透 $\to$ 筑底 $\to$ 点火 $\to$ 主升浪** 全生命周期的四大战术买点，并彻底打通雷达准入与策略引擎的分级赋权：

> [!TIP]
> 🌟 **经典战术买点标准命名与业务语义规范 (Tactical Archetype Naming Guide)**
> - **自媒体与实盘看板推荐命名 (方案 A)**：`集齐威科夫四大战术买点：抄底 · 启动 · 突破 · 回踩`  
>   *定位说明*：面向日常实操、投教科普与自媒体内容传播。以单字动词强化记忆，精准传达从左侧极值抄底到右侧主升接力的实操路径。
> - **量化系统与策略研报标准命名 (方案 B)**：`威科夫全生命周期四大战术买点（左侧抄底 / 箱体启动 / 放量突破 / 缩量二买）`  
>   *定位说明*：面向机构投研、量化API接口与专业策略研报。严格对齐威科夫经典结构阶段（Phase C Spring 震仓 $\to$ Phase D LPS 均线初动 $\to$ Phase D/E JAC 跨越小溪 $\to$ Phase E BUEC 回踩溪沿），兼具量化严谨性与结构生命周期边界。

| 战术买点类型 | 阶段定位 | 量化核心特征 | 止损逻辑 | 建议仓位 |
| :--- | :--- | :--- | :--- | :--- |
| **🧱 底部反转**<br>(`BOTTOM_REVERSAL`) | 恐慌末期<br>左侧抄底 | 超跌筑底打分 $\ge 3.0$ 或形态旁路触发，当日收出止跌反转 K 线（实体阳线或下影线 $\ge 40\%$） | 近 3 日最低点 $\times 0.99$ | 50% 试探底仓 |
| **✨ 均线启动**<br>(`MOVING_AVERAGE_STARTUP`) | 筑底完成<br>初动先行 | EMA10 与 EMA20 粘合度 $\le 1.5\%$ 且 EMA20 拐头向上，价格站上 EMA20，量比 $0.95 \sim 2.0$ | 启动平台近 5 日低点与 EMA20 $\times 0.985$ 较大者 | 30% 观察底仓 |
| **🚀 放量突破**<br>(`VOLUME_BREAKOUT`) | 箱体突破<br>主升点火 | 突破 Donchian 20 前高，实体涨幅 $\ge 2.0\%$，上影线 $\le 35\%$，成交量比 $\ge 1.45$ 爆发 | 突破大阳线实体中轴预警，跌破大阳线最低点止损 | 30% 突破防踏空 |
| **🎯 缩量回踩**<br>(`PULLBACK_LOW_ABSORB`) | 趋势确认<br>黄金二买 | 顺势站上 EMA53 生命线，回抽 EMA20 支撑区间 ($[-1.8\%, +1.8\%]$)，量比 $\le 1.05$ 极度地量萎缩，收十字星或企稳阳线 | 跌破 EMA20 $\times 0.985$ 窄止损 (试错成本通常 $\le 2.5\%$) | 70% 重仓加码 |

---

### 10.1 威科夫量化生命周期四大战术形态契约

```python
from tradingpatterns import (
    TacticalPatternType,
    TacticalPatternSignal,
    detect_bottom_reversal,
    detect_ma_startup,
    detect_volume_breakout,
    detect_pullback_low_absorb,
    scan_tactical_patterns,
)

# 查看支持的四大战术类型
for p_type in TacticalPatternType:
    print(p_type.value)
# 输出:
# BOTTOM_REVERSAL
# MOVING_AVERAGE_STARTUP
# VOLUME_BREAKOUT
# PULLBACK_LOW_ABSORB
```

---

### 10.2 单买点独立判定函数

每个战术形态均提供纯函数接口，输入单标的 OHLCV DataFrame，返回 `(is_triggered, entry_price, stop_loss, reasons)` 四元组：

```python
# 1. 🧱 底部反转识别 (超跌极值点)
is_btm, btm_price, btm_sl, btm_reasons = detect_bottom_reversal(df)

# 2. ✨ 均线启动识别 (均线粘合初动)
is_start, start_price, start_sl, start_reasons = detect_ma_startup(df)

# 3. 🚀 放量突破识别 (主升浪点火)
is_brk, brk_price, brk_sl, brk_reasons = detect_volume_breakout(df)

# 4. 🎯 缩量回踩识别 (黄金第二买点)
is_pb, pb_price, pb_sl, pb_reasons = detect_pullback_low_absorb(df)
```

---

### 10.3 全量战术买点扫描与自适应仓位建议 (`scan_tactical_patterns`)

支持一键扫描当前交易日前向触发的全部战术买点并输出标准信号列表：

```python
signals = scan_tactical_patterns(
    df=df,
    symbol="510050",
    oversold_score=0.0,       # 若外部已计算超跌分可直接传入，未传入时自动自驱计算
    has_pattern_bypass=False
)

for sig in signals:
    print(f"【{sig.label}】 触发级别: {sig.signal_tier}")
    print(f"推荐开仓价: {sig.entry_price:.3f} | 初始窄止损位: {sig.stop_loss:.3f}")
    print(f"建议战术仓位: {sig.suggested_weight_pct * 100:.0f}% | 技术综合打分: {sig.score}")
    print(f"形态判定依据: {sig.reasons}")
```



---

## 11. 机会生命周期跟踪与滚动回放 (`opportunity_lifecycle`)

该模块把雷达的「当日截面切片」升级为**纵向时间演变跟踪**：标的被雷达捕获后建档入池，逐日推进五阶段生命周期，触发主动止盈 / 破位止损 / 沉寂超时后淘汰出池，并输出结构化账本与「进池 / 出池」流转日志。

> [!IMPORTANT]
> **无状态纯函数契约 (Stateless Contract)**
> - `track_opportunity_lifecycle()` **不记忆任何历史**。入池档案（`first_spotted_date` / `spotted_bars_ago` / `spotted_price`）必须由调用方逐日传入并自行持久化。
> - 必须传入 **as-of 切片**（`df.iloc[:t+1]`）。传入含未来数据的全量 df 会引入未来函数。
> - 日更场景若不做台账持久化、而让引擎自行倒推入池点，同一标的每天的「入池价」会随数据窗口滑动而改变，`cumulative_return` 与 `spotted_bars_ago` 随之失真。

---

### 11.1 生命周期阶段与准入/退出枚举

**五阶段生命周期 (`LifecycleStage`)** —— 由 `tradingpatterns` 顶层直接导出：

| 阶段枚举 | 中文标签 | 业务含义 |
| :--- | :--- | :--- |
| `STAGE_0_SPROUT` | 🔥 异动萌芽 | 当日/当周出现放量异动（主力放量打桩） |
| `STAGE_1_SETUP` | 👀 蓄势磨底 | 缩量洗盘蓄势或前瞻潜伏 |
| `STAGE_2_BREAKOUT` | 🚀 突破击球 | 策略引擎确认的首发买点 |
| `STAGE_3_PULLBACK` | 🎯 黄金回踩 | 缩量回踩 EMA20 的第二买点 |
| `STAGE_4_RIDING` | 🌊 趋势延续 | 主升浪顺势持有（含防追高标记） |
| `STAGE_X_INVALID` | 🛑 退出出池 | 止盈结案 / 破位止损 / 沉寂超时 |

**准入通道 (`EntryChannel`)** 与**退出原因 (`ExitReason`)** —— 均由 `tradingpatterns` 顶层直接导出：

```python
from tradingpatterns import LifecycleStage, ExitReason, EntryChannel, PoolEventType

# 五级阶梯式准入通道
[e.value for e in EntryChannel]
# ['LEVEL_0_PRE_INCUBATION', 'LEVEL_1_VOLUME_SURGE', 'LEVEL_2_BREAKOUT',
#  'LEVEL_3_PULLBACK', 'LEVEL_4_TREND_RIDING']

# 四大退出原因
[e.value for e in ExitReason]
# ['NONE', 'PROFIT_TAKEN', 'BREAKDOWN_STOP', 'TIME_EXPIRED']

# 两大流转事件类型
[e.value for e in PoolEventType]
# ['ENTRY', 'EXIT']
```

| 退出原因 | 中文 | 说明 |
| :--- | :--- | :--- |
| `NONE` | 跟踪中 | 仍在活跃池内 |
| `PROFIT_TAKEN` | 止盈结案 | 主动止盈（硬目标或动态吊灯） |
| `BREAKDOWN_STOP` | 破位止损 | 价格真跌破结构防守线 / EMA53 |
| `TIME_EXPIRED` | 沉寂超时 | 横盘超期且资金退潮 |

---

### 11.2 入池双门禁

**为什么要门禁**：仅凭放量异动入池会把钝化、追高、纯放量标的全部纳入，导致跟踪名单噪声极大。入池需同时通过两道门禁——**质量提纯** 与 **看涨形态确认**。

#### `confirm_bullish_formation(df, lookback=5, min_strength=2) -> Tuple[bool, str]`

校验标的在最近 `lookback` 根 K 线内是否存在**经确认的看涨图表形态**。

| 参数 | 类型 | 默认 | 说明 |
| :--- | :--- | :--- | :--- |
| `df` | `pd.DataFrame` | — | **as-of 切片**后的 OHLCV，禁止传含未来数据的全量 df |
| `lookback` | `int` | `5` | 形态回溯 K 线根数 |
| `min_strength` | `int` | `2` | 形态确认最低强度门槛 |

**返回**：`(是否确认, 命中的看涨形态名)`；未确认时形态名为空串。

行为约定：

- 内部调用 `get_recent_bullish_patterns(..., enable_confirmation=True, min_strength=...)`；
- **对称三角形 (`SYMMETRICAL_TRIANGLE`) 被显式排除**——其突破方向待定，不属于看涨形态；
- 数据不足（`len(df) < 20`）或检测抛异常时**一律安全降级为 `(False, "")`**，不向上抛错。

#### `select_trackable_opportunities(radar_report, pool_dict, top_n=3, pattern_lookback=5, pattern_min_strength=2, min_tech_score=4.5)`

多轨差异化入池门禁与可操作性 Top-N 选拔：四大准入通道分轨驱动、差异化形态门禁校验与可操作性综合提纯。

四大准入通道与差异化门禁规范：
1. **🟣 黄金回踩轨 (`LEVEL_3_PULLBACK`)**：由 `get_golden_pullback_second_buys` 检出，必须通过 `confirm_bullish_formation` 看涨几何形态确认，初始阶段为 `STAGE_3_PULLBACK`；
2. **🔴 首发突破轨 (`LEVEL_2_BREAKOUT`)**：由 `get_launch_breakouts` 检出，必须通过 `confirm_bullish_formation` 看涨几何形态确认，初始阶段为 `STAGE_2_BREAKOUT`；
3. **🟡 放量异动轨 (`LEVEL_1_VOLUME_SURGE`)**：由 `get_volume_surges` 检出，**豁免几何形态强确认**，以均线健康底线（`close >= ema20 * 0.985` 且 `tech_score >= 4.0`）与非追高温和正向涨幅（`change_pct >= +1.5%`，`is_chasing=False`）为硬门禁，初始阶段为 `STAGE_0_SPROUT`；
4. **🟢 超跌企稳轨 (`LEVEL_0_PRE_INCUBATION`)**：由 `get_high_quality_oversold_stabilized` 检出，**豁免几何形态确认**，严守周线筑底质量评分门禁（`bottom_score >= 4.0` 且排除陷阱级），初始阶段为 `STAGE_1_SETUP`。

多轨冲突仲裁优先级：
$$\text{黄金回踩 (PULLBACK)} \succ \text{首发突破 (BREAKOUT)} \succ \text{放量异动 (VOLUME\_SURGE)} \succ \text{超跌企稳 (OVERSOLD)}$$

| 参数 | 类型 | 默认 | 说明 |
| :--- | :--- | :--- | :--- |
| `radar_report` | `OpportunityRadarReport` | — | `analyze_opportunity_radar()` 的返回报表 |
| `pool_dict` | `Dict[str, Tuple[str, pd.DataFrame]]` | — | `{"510050": ("上证50ETF", as_of_df), ...}`，**必须是 as-of 切片** |
| `top_n` | `int` | `3` | 每日最多入池标的数 |
| `pattern_lookback` | `int` | `5` | 形态回溯 K 线根数 |
| `pattern_min_strength` | `int` | `2` | 形态确认最低强度 |
| `min_tech_score` | `float` | `4.5` | 可操作性筛选的最低技术评分 |

**返回**：`List[Tuple[OpportunityRadarItem, str]]`，即 `[(雷达条目, 命中的形态名或准入描述), ...]`，按可操作性优先级降序，且条目上附加 `entry_channel`、`initial_stage` 与 `trigger_selector` 元数据。

```python
from tradingpatterns import analyze_opportunity_radar
from tradingpatterns.opportunity_lifecycle import (
    select_trackable_opportunities,
    confirm_bullish_formation,
)

radar = analyze_opportunity_radar(pool, frequency="daily", market_context_df=mctx)

# 单标的形态校验
is_bullish, pattern = confirm_bullish_formation(pool["510050"][1], lookback=5, min_strength=2)

# 当日入池名单（每日最多 3 只）
for item, pattern in select_trackable_opportunities(radar, pool, top_n=3):
    print(f"入池: {item.name}({item.symbol}) 形态={pattern} 技术分={item.tech_score:.1f}")
```

---

### 11.3 出池三通道与阈值

出池判定在 `track_opportunity_lifecycle()` 内部完成，三大通道语义如下：

| 通道 | `ExitReason` | 触发条件 | 需价格确认 |
| :--- | :--- | :--- | :---: |
| ① 主动止盈 | `PROFIT_TAKEN` | 累计涨幅 ≥ `3.0%` 硬目标；**或**持有期峰值浮盈 ≥ `2.0%` 后收盘跌破 `峰值 − 2.2 × ATR14` 动态吊灯线（且收盘仍高于入池价） | 是 |
| ② 破位止损 | `BREAKDOWN_STOP` | 收盘 < 防守位 × 0.985；**或**（收盘 < EMA53 且 EMA20 乖离 < −3%）；吊灯线击穿但已跌破入池价 | 是 |
| ③ 沉寂超时 | `TIME_EXPIRED` | `spotted_bars_ago ≥ max_setup_bars` 且未处右侧、无买点、量能萎缩至 ≤ 0.65x | 否 |

> [!WARNING]
> **破位双确认 (Price Confirmation)**：引擎的**卖出信号**与**结构失效状态 (`FAILED` / `BOTTOM_FAILED`) 单独不足以将标的移出跟踪池**，必须叠加价格跌破防守线的确认。
> 原因：单日噪声会把标的扫在局部最低点。实测案例——某标的在结构失效日被清仓于 −0.91%，随后 5 个交易日反弹至 +4.7%。
> 卖出信号不会被丢弃，而是写入 `invalidation_condition` 字段（标注「仅降级观察，不单独出池」）。

**可调阈值常量**（从子模块导入，修改前请确认与回测口径一致）：

```python
from tradingpatterns.opportunity_lifecycle import (
    PROFIT_TAKEN_HARD_TARGET_PCT,   # 3.0  主动止盈硬目标（累计涨幅 %）
    CHANDELIER_ACTIVATION_PCT,      # 2.0  吊灯跟踪止盈激活阈值（峰值浮盈 %）
    CHANDELIER_ATR_MULT,            # 2.2  吊灯跟踪回撤倍数（ATR）
    CHANDELIER_ATR_WINDOW,          # 14   吊灯 ATR 周期
    DEFAULT_ADMISSION_TOP_N,        # 3    每日入池上限
    DEFAULT_PATTERN_LOOKBACK,       # 5    形态回溯 K 线根数
    DEFAULT_PATTERN_MIN_STRENGTH,   # 2    形态确认最低强度
    VOLUME_SURGE_FAST_DECAY_BARS,   # 5    异动快速衰减检验窗口 (5 根 K 线)
    VOLUME_SURGE_DECAY_VOL_RATIO,   # 0.7  异动衰减量能阈值 (量比 <= 0.7)
)
```

出池增强三大机制：
1. **破位止损 (`BREAKDOWN_STOP`) 双重确认**：跌破防守线 0.985，或命中结构破位/卖出风险且跌破 EMA20；
2. **沉寂超时 (`TIME_EXPIRED`) 加速淘汰**：蓄势期达 `max_setup_bars` 超时，或钝化满 3 根 K 线加速超时，或**放量异动标的满 5 根 K 线未突破且量比萎缩至 0.7 以下快速衰减出池**；
3. **主动止盈 (`PROFIT_TAKEN`) 动态吊灯**：浮盈达 2.0% 激活 ATR 吊灯线，并在短线严重超买（偏离 EMA20 > 5.0%）时自适应收紧回撤容忍倍数至 1.5 ATR 锁定利润。

---

### 11.4 单标的生命周期推导

#### `track_opportunity_lifecycle(...) -> TrackedOpportunityItem`

对单只标的做完整的生命周期量化推导（纯函数、无状态）。

| 参数 | 类型 | 默认 | 说明 |
| :--- | :--- | :--- | :--- |
| `df` | `pd.DataFrame` | — | **as-of 切片**后的 OHLCV |
| `symbol` / `name` | `str` | `""` | 标的代码与名称 |
| `frequency` | `str` | `"daily"` | `"daily"` 或 `"weekly"` |
| `market` | `str` | `"auto"` | `"auto"` / `"CN"` / `"US"` |
| `lookback_bars` | `Optional[int]` | `None` | 回溯异动窗口；**仅在未传入入池档案时生效**（日频默认 30 / 周频默认 4） |
| `max_setup_bars` | `Optional[int]` | `None` | 蓄势超时出池阈值（日频默认 15 / 周频默认 4） |
| `config` | `Optional[OpportunityRadarConfig]` | `None` | 雷达配置，缺省用 `DEFAULT_RADAR_CONFIG` |
| `market_context_df` | `Optional[pd.DataFrame]` | `None` | 大盘基准上下文 |
| `first_spotted_date` | `Optional[str]` | `None` | **入池档案**：首次入池日期 |
| `spotted_bars_ago` | `Optional[int]` | `None` | **入池档案**：已跟踪 K 线根数 |
| `spotted_price` | `Optional[float]` | `None` | **入池档案**：入池价（`cumulative_return` 的基准） |
| `entry_channel` | `Optional[Union[str, EntryChannel]]` | `None` | **准入通道**：标的入池轨道 (如 `LEVEL_1_VOLUME_SURGE`) |

> [!NOTE]
> `first_spotted_date` / `spotted_bars_ago` / `spotted_price` **三者必须同时传入**才会被采用；
> 否则引擎会用 `_find_first_spotted_bar()` 从 df 倒推放量异动起点，此时 `lookback_bars` 生效。
> 日更场景应始终传入档案，避免入池点随数据窗口滑动。

**返回**：`TrackedOpportunityItem` 强类型数据对象，支持 `.to_dict()` 序列化。核心字段：

| 字段 | 说明 |
| :--- | :--- |
| `stage` / `stage_cn` / `stage_age_bars` | 当前生命周期阶段、中文标签、持续 K 线根数 |
| `first_spotted_date` / `spotted_bars_ago` | 首次入池日期、已跟踪 K 线根数 |
| `cumulative_return` | 自入池价以来的累计涨跌幅（%） |
| `exit_reason` / `exit_reason_cn` | 退出原因枚举与中文 |
| `support_price` / `ema20_price` / `dist_to_ema20` | 核心防守位、EMA20、乖离率 |
| `invalidation_condition` | 失效判定条件描述（含卖出信号降级提示） |
| `headline` / `media_tag` / `action_advice` | 一句话摘要、状态标签、大白话操作指引 |
| `is_radar_spotted` / `radar_type` / `has_execution_signal` / `signal_tier` | 雷达前哨与交易引擎信号的解耦标记 |

```python
from tradingpatterns import track_opportunity_lifecycle

item = track_opportunity_lifecycle(
    df=df.iloc[:t + 1],              # as-of 切片，杜绝未来函数
    symbol="510050",
    name="上证50ETF",
    frequency="daily",
    max_setup_bars=15,
    first_spotted_date="2026-08-31",
    spotted_bars_ago=3,
    spotted_price=3.041,
)

print(f"[{item.stage_cn}] {item.name} 累计 {item.cumulative_return:+.1f}% | 防守 {item.support_price:.3f}")
print(f"退出原因: {item.exit_reason_cn} | 提示: {item.media_tag}")
print(f"失效条件: {item.invalidation_condition}")
```

---

### 11.5 全池跟踪账本与逐日滚动回放

#### `replay_opportunity_pool(pool_dict, frequency="daily", track_days=7, top_n=3, ...) -> Tuple[OpportunityTrackingBook, List[OpportunityFlowEvent]]`

**核心滚动跟踪与回放引擎（纯函数、无状态、无未来函数）**。

该函数为全池标的执行逐日截面切片与五阶段生命周期流转推演：
1. **逐日推进**：在回放窗口内模拟时间流逝（每一步严格只切片到当日收盘 `iloc[:t+1]`）；
2. **入池双门禁**：当日触发的新机会经「形态确认 + 质量提纯 Top-N」双门禁审核后建档，生成 `ENTRY` 流转事件；
3. **在池演化**：对已在池标的按五阶段状态机推进，动态计算浮盈、核心防守位与移动吊灯止盈位；
4. **淘汰出池**：触发主动止盈、破位止损或沉寂超时后生成 `EXIT` 事件，移出活跃池并归入结案名单；
5. **纯数据输出**：返回最终的 `OpportunityTrackingBook` 结构化账本对象与 `List[OpportunityFlowEvent]` 流转事件列表，便于 API / Web / 外部管道直接消费。

| 参数 | 类型 | 默认 | 说明 |
| :--- | :--- | :--- | :--- |
| `pool_dict` | `Dict[str, Tuple[str, pd.DataFrame]]` | — | 全池标的字典：`{"代码": ("名称", full_df)}` |
| `frequency` | `str` | `"daily"` | 扫描频率：`"daily"` 或 `"weekly"` |
| `track_days` | `int` | `7` | 滚动回放窗口期（交易日根数） |
| `top_n` | `int` | `3` | 每日入池上限（入池质量门禁 Top-N） |
| `max_setup_bars` | `Optional[int]` | `None` | 横盘蓄势超时淘汰阈值（缺省跟随 `track_days`） |
| `market_context_df` | `Optional[pd.DataFrame]` | `None` | 大盘基准 K 线 DataFrame（可选） |
| `final_report` | `Optional[OpportunityRadarReport]` | `None` | 末步已算好的雷达报表（可选，省去末步重复计算） |
| `include_alerts` | `bool` | `True` | 是否允许高质量预警标的参与入池门禁 |

**返回**：`(OpportunityTrackingBook, List[OpportunityFlowEvent])`

```python
from tradingpatterns import (
    replay_opportunity_pool,
    OpportunityTrackingBook,
    OpportunityFlowEvent,
    PoolEventType,
)

# 1. 传入全池行情 DataFrame 字典进行多日滚动跟踪
book, events = replay_opportunity_pool(
    pool_dict=pool,
    frequency="daily",
    track_days=7,
    top_n=3,
)

# 2. 消费进出池流转事件 (纯结构化数据，无 print 侵入)
for evt in events:
    action = "入池" if evt.event_type == PoolEventType.ENTRY else "出池"
    print(f"[{evt.date}] {action}: {evt.name}({evt.symbol}) 现价 {evt.price:.3f} | {evt.message}")

# 3. 消费当前账本中的活跃跟踪池与结案名单
print(f"\n当前活跃标的 ({len(book.all_active_items())} 只):")
for it in book.all_active_items():
    print(f"  [{it.stage_cn}] {it.name}({it.symbol}) 累计 {it.cumulative_return:+.1f}% | 防守位: {it.support_price:.3f}")

print(f"\n本期结案退出 ({len(book.invalidated)} 只):")
for it in book.invalidated:
    print(f"  [{it.exit_reason_cn}] {it.name}({it.symbol}) 累计 {it.cumulative_return:+.1f}%")

# 4. 结构化 JSON 导出 (供下游 Web / API 服务直接使用)
payload = book.to_dict()
```

#### `track_radar_report(radar_report, pool_dict, ...) -> OpportunityTrackingBook`

接收单期雷达报表，对雷达发现的标的做纵向生命周期跟踪并归类汇总。

> [!NOTE]
> 该函数目前的入池口径为 `vol_list + alert_list + opp_list + risk_list`（全量），
> **尚未接入 11.2 的入池双门禁**。若需要门禁口径，请调用 `replay_opportunity_pool()` 或先调用 `select_trackable_opportunities()`。

#### `scan_and_track_opportunities(pool_dict, frequency="daily", market="auto", ...) -> OpportunityTrackingBook`

内部自动完成「雷达扫描发现 → 生命周期跟踪」全链路的便捷入口。

**返回**：`OpportunityTrackingBook` 账本对象，按阶段分桶存放：

| 属性 | 说明 |
| :--- | :--- |
| `sprouts` / `setups` / `breakouts` / `pullbacks` / `ridings` | 阶段 0~4 的活跃标的 |
| `invalidated` | 阶段 X：本期结案退出名单 |
| `newly_admitted` / `current_exited` | 本期新纳入 / 本期移出 |
| `active_pre_incubations()` | 活跃中的前瞻潜伏池（激进/耐心读者） |
| `active_right_side_confirmations()` | 活跃中的右侧确认池（稳健读者） |
| `all_active_items()` | 全部活跃标的（排除已出池） |
| `total_count()` | 活跃 + 已出池总数 |
| `to_dict()` | 序列化为字典（含各分桶计数 `counts`） |

---

### 11.6 逐日滚动回放实战范式与窗口调优

逐日滚动回放基于公有顶层 API `replay_opportunity_pool()`，对目标标的池进行纵向时间推演：从窗口起点起逐交易日推演全池雷达切片，当日通过质量与形态双门禁的机会首次入池建档；已在池中的标的按五阶段状态机推进并动态计算浮盈与防守线；触发主动止盈、破位止损或沉寂超时的标的淘汰出池，最终输出结构化账本 `OpportunityTrackingBook` 与全量流转日志 `List[OpportunityFlowEvent]`。

#### 核心调优参数与行为约定

| 参数 | 类型 | 默认 | 说明 |
| :--- | :--- | :--- | :--- |
| `pool_dict` | `Dict[str, Tuple[str, pd.DataFrame]]` | — | 全池标的行情字典：`{"代码": ("名称", df)}` |
| `frequency` | `str` | `"daily"` | 扫描频率：`"daily"` 或 `"weekly"` |
| `track_days` | `int` | `7` | **回放窗口交易日数**：往回推演几个交易日（日频推荐 `10~20`，周频推荐 `20`） |
| `top_n` | `int` | `3` | 每日入池上限（入池质量门禁 Top-N） |
| `max_setup_bars` | `Optional[int]` | `None` | 横盘蓄势超时淘汰阈值（缺省跟随 `track_days`；建议独立设为 15~20） |
| `market_context_df` | `Optional[pd.DataFrame]` | `None` | 大盘基准行情，提供宏观择时上下文 |
| `include_alerts` | `bool` | `True` | 是否允许高质量预警标的参与入池门禁 |

#### 快速推演代码范式

```python
from tradingpatterns import (
    replay_opportunity_pool,
    PoolEventType,
    OpportunityTrackingBook,
)

# 1. 启动逐日滚动回放推演 (以日频 15 个交易日窗口、每日最多入池 3 只为例)
book, events = replay_opportunity_pool(
    pool_dict=pool_dict,
    frequency="daily",
    track_days=15,
    top_n=3,
    max_setup_bars=15,
)

# 2. 消费逐日流转日志
for evt in events:
    action = "入池" if evt.event_type == PoolEventType.ENTRY else "出池"
    print(f"[{evt.date}] {action}: {evt.name}({evt.symbol}) 现价 {evt.price:.3f} | {evt.message}")

# 3. 统计最终账本
print(f"累计活跃标的: {len(book.all_active_items())} 只，已结案标的: {len(book.invalidated)} 只")
```

> [!IMPORTANT]
> **`track_days` 是回放窗口，不是持仓上限**。它决定「回放哪几天」，同时也把最长跟踪天数隐式限制在 `track_days − 1` 天。
> 窗口过短会有两个副作用：
> 1. `max_setup_bars` 默认跟随窗口，导致 `TIME_EXPIRED`（沉寂超时）通道可能永不触发；
> 2. 若窗口恰逢下跌行情，样本内可能没有任何标的能走出盈利，出现「0 胜」的假象。
>
> 依据实证结论：**最佳持有周期为 10~20 个交易日**（T+20 胜率 65%）。生产环境的日更跟踪没有窗口截断，表现不应以短窗口推演为准。

---

## 12. 统一行情数据获取与标准化接口 (`get_any_ohlc`)

### 12.1 设计背景与数据源规整原则

在量化策略与机会雷达系统中，标的代码涵盖股票、A 股 ETF、大盘指数、行业指数以及美股 ETF 等多种异构类型。底层数据源 `kdata-quant` 2.0 规范对不同标的设有明确的接口分流与代码校验规则：
1. **股票与 ETF 接口 (`kdata.get_ohlc`)**：用于常规股票、ETF、LOF 及美股标的，若误传大盘指数会抛出 `ValueError`；
2. **大盘指数接口 (`kdata.get_index_ohlc`)**：专用于大盘指数，强制要求指数代码包含交易所市场前缀（如 `sh.000300`、`sz.399001`）或传入 `MarketIndex` 枚举，若传入无前缀的纯数字（如 `000300`）会抛出参数错误；
3. **输出标准化要求**：不同接口返回的数据在列名大小写、时间索引类型及空值格式上存在细微差异。

为消除调用方的认知负担与代码冗余，`tradingpatterns` 提供了高内聚的统一行情获取函数 `get_any_ohlc`：
- **智能自动路由**：根据代码特征前缀及指数清单，自动识别股票/ETF 与大盘指数并分流调用相应底层接口；
- **前缀自动规整**：自动将纯数字指数代码规整为标准带前缀格式，同时支持 `MarketIndex` 枚举直接穿透；
- **双向自愈降级**：捕获接口因标的类型误判产生的异常并自动切换回退重试，保障数据流水线健壮不中断；
- **输出格式标准化**：统一输出全小写列名 `['open', 'high', 'low', 'close', 'volume']`，索引强制转为 `pd.DatetimeIndex` 且按时间升序排列，空数据安全返回标准空 DataFrame。

---

### 12.2 标的代码智能路由与格式规整

#### `is_likely_index(symbol_or_index: Union[str, MarketIndex]) -> bool`

判断传入的代码是否为大盘或行业指数标的。

- **判定规则**：
  1. 若传入 `MarketIndex` 枚举实例，直接返回 `True`；
  2. 明确匹配已知核心大盘指数（如 `000001`, `000300`, `399001`, `000905`, `932000`, `000688`, `us.GSPC` 等）；
  3. 属于 A 股 ETF/LOF 专属号段（`51`, `56`, `58`, `15`, `16` 开头）时，必定返回 `False`（确保进入个股/ETF 通道）；
  4. 具备典型指数前缀特征（`399`、`sh.000`、`sz.399` 等）或包含 `index` 关键词时，返回 `True`。

#### `normalize_index_symbol(symbol_or_index: Union[str, MarketIndex]) -> Union[str, MarketIndex]`

将纯数字指数代码自动规整为带交易所前缀的标准代码格式，支持枚举类型直接穿透。

- **映射规整范例**：
  - `'000300'` $\to$ `'sh.000300'`
  - `'000001'` $\to$ `'sh.000001'`
  - `'399001'` $\to$ `'sz.399001'`
  - `'399006'` $\to$ `'sz.399006'`
  - `'sh000300'` $\to$ `'sh.000300'`
  - `MarketIndex.HS300` $\to$ `MarketIndex.HS300`（保持枚举对象不变）

---

### 12.3 核心统一获取函数 (`get_any_ohlc`)

#### `get_any_ohlc(...) -> pd.DataFrame`

统一获取股票、ETF 或大盘指数的标准化 OHLCV K 线数据。

```python
def get_any_ohlc(
    symbol: Union[str, MarketIndex],
    start_date: Optional[Union[str, pd.Timestamp, datetime]] = None,
    end_date: Optional[Union[str, pd.Timestamp, datetime]] = None,
    period: Optional[object] = None,
    **extra_parameters: object,
) -> pd.DataFrame:
```

| 参数 | 类型 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| `symbol` | `Union[str, MarketIndex]` | — | 标的代码或指数枚举（如 `'510300'`, `'sh.000300'`, `'000300'`, `'600519'`, `'us.SPY'`, `MarketIndex.SH`） |
| `start_date` | `Optional[Union[str, pd.Timestamp, datetime]]` | `None` | 起始日期，支持字符串 `'YYYY-MM-DD'` 或时间对象 |
| `end_date` | `Optional[Union[str, pd.Timestamp, datetime]]` | `None` | 结束日期，支持字符串 `'YYYY-MM-DD'` 或时间对象 |
| `period` | `Optional[object]` | `None` | K 线周期，默认为日线（如 `Period.DAILY`） |
| `**extra_parameters`| `object` | — | 透传给底层行情驱动的可选参数 |

**返回值**：
- `pd.DataFrame`：清洗规范化后的标准 OHLCV 数据，列名小写，时间升序，索引为 `pd.DatetimeIndex`。标的无数据或为空时，返回包含标准列名的空 DataFrame。

---

### 12.4 标准化 OHLCV 输出结构与实战调用范式

#### 标准数据结构

无论调用何种标的，返回的 DataFrame 均具备以下一致的形态：
- **索引**：`pd.DatetimeIndex`，按时间由远及近严格升序排序；
- **标准列**：`['open', 'high', 'low', 'close', 'volume']`，全小写字母，数值类型统一。若存在成交额字段则标准化为 `'amount'`。

#### 实战调用范式

```python
from tradingpatterns import get_any_ohlc
from kdata.markets import MarketIndex

# 1. 获取 A 股行业 ETF 数据 (自动路由至 get_ohlc)
df_etf = get_any_ohlc("510300", start_date="2024-01-01", end_date="2024-12-31")
print("ETF 数据尾部:")
print(df_etf.tail(2))

# 2. 获取大盘指数数据 (带前缀代码，自动路由至 get_index_ohlc)
df_index = get_any_ohlc("sh.000300", start_date="2024-01-01", end_date="2024-12-31")
print("指数数据尾部:")
print(df_index.tail(2))

# 3. 获取大盘指数数据 (纯数字代码，自动规整补齐前缀 sh.000300)
df_auto_norm = get_any_ohlc("000300", start_date="2024-01-01", end_date="2024-12-31")

# 4. 使用官方 MarketIndex 枚举获取
df_enum = get_any_ohlc(MarketIndex.SH, start_date="2024-01-01", end_date="2024-12-31")

# 5. 获取美股 ETF 数据 (自动路由至 get_ohlc)
df_us = get_any_ohlc("us.SPY", start_date="2024-01-01", end_date="2024-12-31")
```

