关键位箱体突破调整

crypto_monitor_gate/关键位自动下单说明.md

@@ -1,98 +1,142 @@
-# 关键位自动下单说明
-
-**适用仓库：`crypto_monitor_gate`｜交易所：Gate.io USDT 永续**（Binance 版见同名的 `crypto_monitor_binance` 目录。）
-
-本文档与 `.env`、`app.check_key_monitors`、`app.add_key`、`_market_open_for_key_monitor` 的实现一致。
-
----
-
-## 结构与是否自动开仓
-
-| `key_monitors.monitor_type`（录入类型） | 自动下单 | 触发后处置 |
-|---------------------------------------|----------|------------|
-| **箱体突破** | 是（满足全部条件） | **一次性结案**：写 `key_monitor_history` → 从 `key_monitors` **删除** |
-| **收敛突破** | 是（同上） | 同上 |
-| **关键阻力位** | 否 | 企业微信 **1 次** → `close_reason=key_level_alert_only` → **失效** |
-| **关键支撑位** | 否 | 同上 |
-
-触发条件：**5m 收线硬门控** `_key_hard_checks`（量能、突破幅度、第二根收盘确认、日成交量前 30 等）。
-
----
-
-## 录入限制（`/add_key`）
-
-- 存在 **`order_monitors.status='active'`** 时：**禁止添加** 「箱体突破」「收敛突破」。
-- **关键阻力位 / 关键支撑位**：不受上条限制；触发后 **仅单次微信提醒**，然后结案。
-- **4h EMA55 与所选方向逆势**：**不拦截**；添加成功后 **Flash** 提示。
-- 上下沿入库前经 **`round_price_to_exchange`** 按合约 **价格精度** 取整。
-
----
-
-## 环境与参数（`.env`）
-
-| 变量 | 含义 | 默认 |
-|------|------|------|
-| `KEY_AUTO_MIN_PLANNED_RR` | 计划 RR 阈值：**仅当严格大于该值** 才自动开仓（按下方 `E` 计算） | `1.5` |
-| `KEY_STOP_OUTSIDE_BREAKOUT_PCT` | 止损：突破 K 极值向外 **百分比**（多：`低×(1−p/100)`；空：`高×(1+p/100)`） | `0.5` |
-
-**其余与本仓库手动实盘一致：** `KLINE_TIMEFRAME`、`RISK_PERCENT`、`LIVE_TRADING_ENABLED`、`BREAKEVEN_*`、`DAILY_OPEN_ALERT_THRESHOLD`，以及 **`GATE_*`**（密钥、止盈止损触发、`GATE_TPSL_*` 等）。
-
----
-
-## 计价与下单口径
-
-| 用途 | 价格 |
-|------|------|
-| 企业微信展示、**与 RR 门槛比较的计划 RR** | 确认 K（第二根闭合 5m）收盘 **`E`** |
-| **实际开仓** | **市价**（`place_exchange_order`，与 `/add_order` 一致）；成交价可能与 `E` **滑点** |
-| **以损定仓** | `calc_risk_fraction(direction, 当前市价, 止损)` + `RISK_PERCENT`（与 `/add_order` 一致） |
-
-- 开仓成功后：`order_monitors.monitor_type` 为 **关键位监控**；持仓卡片「来源」显示之。手动开仓为 **下单监控**。
-- 持仓列表中的 **盈亏比**：按 **实际成交价** 相对 SL/TP 重算，可与「按 `E` 算的计划 RR」略有偏差。
-- **本仓库止盈止损挂单**：开仓后由 **`_gate_place_tp_sl_orders`** 挂载（仓位类 `price_orders` 或备选条件路径，逻辑与手动一致）；细节受 `GATE_TPSL_USE_POSITION_ORDER`、`GATE_TPSL_PRICE_TYPE` 等影响。
-
----
-
-## 自动单止盈 / 止损（仅箱体突破、收敛突破）
-
-设箱体高度 **`H = |upper − lower|`**（录入上下沿）。
-
-| 方向 | 止损 SL | 止盈 TP |
-|------|---------|---------|
-| 多 | 突破 K **最低价** × (1 − `KEY_STOP_OUTSIDE_BREAKOUT_PCT`/100) | **`E + 1×H`** |
-| 空 | 突破 K **最高价** × (1 + `KEY_STOP_OUTSIDE_BREAKOUT_PCT`/100) | **`E − 1×H`** |
-
-计划 **`RR = calc_rr_ratio(direction, E, SL, TP)`**。若为 `None` 或 **RR ≤ `KEY_AUTO_MIN_PLANNED_RR`** → **不下单**，走 `rr_insufficient` 结案。
-
----
-
-## 一次性结案（`close_reason`）
-
-以下任一发生：**按需发微信** → **`key_monitor_history`** → **从 `key_monitors` 删除**；**不会对同一条关键位重复轮询重试开仓**。
-
-| `close_reason` | 含义 |
-|----------------|------|
-| `rr_insufficient` | 门控通过，但计划 RR 未达标或 SL/TP / RR **几何无效** |
-| `exchange_failed` | 计划 RR 达标，但未开实盘、`LIVE_TRADING_ENABLED=false`、风控、保证金或 **交易所报错** 等导致 **开仓失败** |
-| `auto_opened` | 计划 RR 达标且 **市价开仓成功**（已写 `order_monitors`，并已挂止盈止损） |
-| `key_level_alert_only` | 阻力/支撑位 **仅推送**结案 |
-
----
-
-## 与企业微信推送
-
-每种结案路径 **至多一条**主业务推送（RR 不足 / 下单失败 / 开仓成功 / 阻力支撑仅提醒）。
-
-旧版「满 `KEY_ALERT_MAX_TIMES` 次再归档」对已触发结案的路径 **不再适用**；表中 `notification_count`、`max_notify` 等字段仍可能存在，以 **导出、兼容** 为主。
-
----
-
-## 相关代码位置（通用）
-
-| 说明 | 符号 |
-|------|------|
-| 门控与主循环 | `check_key_monitors` |
-| 录入、有仓拦截、4h Flash | `add_key` |
-| 市价开仓 + 写 `order_monitors` | `_market_open_for_key_monitor` |
-| 计划 RR | `calc_rr_ratio(direction, E, SL, TP)` |
-| 价格精度 | `round_price_to_exchange` |
+# 关键位监控说明（自动开仓 + 人工盯盘）
+
+**适用：`crypto_monitor_gate`（Gate U 本位永续）**  
+Binance / OKX 见各自目录下同名文档；共享逻辑在仓库根目录 `key_monitor_lib.py`。
+
+本文档与 `.env`、`check_key_monitors`、`add_key`、`_key_hard_checks`、`_process_key_rs_level_alert` 一致。
+
+---
+
+## 一、监控类型总览
+
+| 录入类型 | 录入时选方向 | 自动市价开仓 | 触发与结案 |
+|----------|--------------|--------------|------------|
+| **箱体突破** | **必选** 多/空 | **是**（门控 + RR） | 条件满足 → 开仓或 `rr_insufficient` / `exchange_failed` → **一次性删除** |
+| **收敛突破** | **必选** 多/空 | **是**（同上） | 同上 |
+| **关键阻力位** | **不选**（`direction=watch`） | **否** | 5m 收盘突破上/下沿 → 微信 **3 次** → `key_level_alert_done` |
+| **关键支撑位** | **不选** | **否** | 同上（与阻力位**相同规则**：填上沿+下沿，程序双向监控） |
+| 斐波回调 0.618 / 0.786 | 必选 | 限价挂单逻辑 | 见斐波说明（**不在下文展开**） |
+
+**添加时（所有类型）：** 品种须 **日成交量排名前 `KEY_DAILY_VOLUME_RANK_MAX`（默认 30）**；上沿 **>** 下沿。
+
+---
+
+## 二、关键阻力位 / 关键支撑位（人工盯盘）
+
+### 2.1 录入
+
+- 填写 **上沿 `upper`** 与 **下沿 `lower`**（程序同时监控两侧，**无法预先判定**做多还是做空）。
+- 页面 **不显示、不要求** 方向；库中 `direction` 初始为 `watch`，**首次突破后** 写入 `long`（向上突破上沿）或 `short`（向下突破下沿）。
+
+### 2.2 触发（极简）
+
+- 周期：**`KLINE_TIMEFRAME`（默认 5m）最近一根已闭合 K** 的 **收盘价**（非影线）。
+- **向上突破上沿：** `收盘 > upper` → 推断方向 **多 / 向上**，本次监控任务开始按节奏提醒。
+- **向下突破下沿：** `收盘 < lower` → 推断方向 **空 / 向下**，本次任务同样开始提醒。
+- **任一侧突破即结束本条监控周期**（不会在突破后再等待另一侧；上沿、下沿谁先满足用谁，同根 K 仅可能满足一侧）。
+
+**不参与：** 量能、二确 K、越过幅度下限、日成交排名（运行时）、计划 RR、自动开仓。
+
+### 2.3 微信提醒次数
+
+| 配置 | 默认 | 含义 |
+|------|------|------|
+| `KEY_ALERT_MAX_TIMES` | `3` | 突破后最多推送 3 次 |
+| `KEY_ALERT_INTERVAL_MINUTES` | `5` | 相邻两次推送至少间隔 5 分钟 |
+
+- 第 1 次：首次检测到突破的当次轮询（若已闭合 5m 满足条件）。
+- 第 2、3 次：仅按间隔推送（**不要求**价格仍在箱外）。
+- 第 3 次推送后：写入 `key_monitor_history`，`close_reason=**key_level_alert_done**`，从 `key_monitors` **删除**。
+
+### 2.4 与箱体/收敛的区别
+
+| 项目 | 阻力/支撑 | 箱体/收敛 |
+|------|-----------|-----------|
+| 方向 | 程序推断 | 人工选择 |
+| K 线根数 | 1 根闭合 5m | 2 根（突破 K + 确认 K） |
+| 提醒次数 | 3 次后结案 | 自动单：触发后 1 次业务推送并结案 |
+
+---
+
+## 三、箱体突破 / 收敛突破（自动开仓）
+
+### 3.1 K 线结构（默认索引）
+
+| 角色 | 环境变量 | 默认 | 含义 |
+|------|----------|------|------|
+| 突破 K | `KEY_CONFIRM_BREAKOUT_BAR` | `-2` | 倒数第 2 根闭合 K |
+| 确认 K | `KEY_CONFIRM_BAR` | `-1` | 倒数第 1 根闭合 K |
+
+### 3.2 硬门控（须全部通过）
+
+1. **有效突破（收盘越界）**  
+   - 多：`突破 K 收盘 > upper`  
+   - 空：`突破 K 收盘 < lower`
+
+2. **突破越过幅度（仅下限）**  
+   - 多：`(突破 K 收盘 − upper) / upper × 100 > KEY_BREAKOUT_AMP_MIN_PCT`（默认 **0.03%**）  
+   - 空：`(lower − 突破 K 收盘) / lower × 100 >` 同上  
+   - **无上限**；突破过猛由 **计划 RR** 过滤。  
+   - **不再**使用 K 线实体占开盘价比例；`KEY_BREAKOUT_AMP_MAX_PCT` **已不参与门控**。
+
+3. **确认 K 不进箱体**  
+   - 多：确认 K 收盘 **`> upper`**（不得在 `[lower, upper]` 内）  
+   - 空：确认 K 收盘 **`< lower`**
+
+4. **量能：** 突破 K 成交量 > 前 `KEY_VOLUME_MA_BARS`（默认 20）根均量 × `KEY_VOLUME_RATIO_MIN`（默认 1.3）
+
+5. **日成交量排名：** 运行时仍须前 `KEY_DAILY_VOLUME_RANK_MAX`（默认 30）
+
+6. **计划 RR（最后经济门控）：** 按确认 K 收盘 **E** 计算 SL/TP 后，`RR` **严格大于** `KEY_AUTO_MIN_PLANNED_RR`（默认 1.5）才市价开仓
+
+### 3.3 止损 / 止盈（确认 K 收盘为 E）
+
+箱体高 **H = |upper − lower|**。止损锚在 **突破 K 极值** 外侧：
+
+| 方向 | 止损（标准/趋势方案） |
+|------|------------------------|
+| 多 | 突破 K **最低价** × (1 − `KEY_STOP_OUTSIDE_BREAKOUT_PCT`%) |
+| 空 | 突破 K **最高价** × (1 + `KEY_STOP_OUTSIDE_BREAKOUT_PCT`%) |
+
+止盈方案见下表（与改版前一致）：
+
+| 方案 | `sl_tp_mode` | 多：SL / TP | 空：SL / TP |
+|------|--------------|-------------|-------------|
+| 标准突破 | `standard` | 突破 K 低外侧% / **E+H** | 突破 K 高外侧% / **E−H** |
+| 箱体 1R·止盈 1.5H | `box_1p5` | **E−H** / **E+1.5×H** | **E+H** / **E−1.5×H** |
+| 趋势单·自填止盈 | `trend_manual` | 突破 K 低 × (1−`KEY_TREND_STOP_OUTSIDE_PCT`%) / **录入止盈** | 突破 K 高外侧% / **录入止盈** |
+
+### 3.4 一次性结案（`close_reason`）
+
+| `close_reason` | 含义 |
+|----------------|------|
+| `rr_insufficient` | 门控通过但 RR 不达标或 SL/TP 几何无效 |
+| `exchange_failed` | RR 达标但实盘/交易所等原因未开仓 |
+| `auto_opened` | RR 达标且市价开仓成功 |
+| `key_level_alert_done` | 阻力/支撑 **3 次提醒** 完成 |
+
+---
+
+## 四、环境与参数（`.env` 摘要）
+
+| 变量 | 箱体/收敛 | 阻力/支撑 |
+|------|-----------|-----------|
+| `KEY_BREAKOUT_AMP_MIN_PCT` | 突破越过下限（默认 0.03） | 不用 |
+| `KEY_BREAKOUT_AMP_MAX_PCT` | **已废弃门控** | 不用 |
+| `KEY_VOLUME_*` / `KEY_CONFIRM_*` | 用 | 不用 |
+| `KEY_AUTO_MIN_PLANNED_RR` | 用 | 不用 |
+| `KEY_ALERT_MAX_TIMES` / `KEY_ALERT_INTERVAL_MINUTES` | 不用 | 用（默认 3 次 / 5 分钟） |
+| `KEY_DAILY_VOLUME_RANK_MAX` | 添加时 + 运行时 | **仅添加时** |
+
+---
+
+## 五、相关代码
+
+| 说明 | 位置 |
+|------|------|
+| 共享判定 | `key_monitor_lib.py` |
+| 主循环 | `check_key_monitors` |
+| 自动门控 | `_key_hard_checks` |
+| 阻力/支撑提醒 | `_process_key_rs_level_alert` |
+| 录入 | `add_key` |
+| 开仓 | `_market_open_for_key_monitor` |