# 关键位自动下单说明

**适用仓库：`crypto_monitor_binance`｜交易所：Binance U 本位永续**（Gate 版见同名的 `crypto_monitor_gate` 目录。）

本文档与 `.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`，以及 **`BINANCE_*`**（密钥、`BINANCE_MARGIN_MODE`、`BINANCE_POSITION_MODE`、`BINANCE_TRIGGER_WORKING_TYPE` 等）。资金字段舍入端口径与 **`FUNDS_DECIMALS`** 一致。

---

## 计价与下单口径

| 用途 | 价格 |
|------|------|
| 企业微信展示、**与 RR 门槛比较的计划 RR** | 确认 K（第二根闭合 5m）收盘 **`E`** |
| **实际开仓** | **市价**（`place_exchange_order`，与 `/add_order` 一致）；成交价可能与 `E` **滑点** |
| **以损定仓** | `calc_risk_fraction(direction, 当前市价, 止损)` + `RISK_PERCENT`（保证金等 **`FUNDS_DECIMALS`** 舍入，与 `/add_order` 一致） |

- 开仓成功后：`order_monitors.monitor_type` 为 **关键位监控**；持仓卡片「来源」显示之。手动开仓为 **下单监控**。
- 持仓列表中的 **盈亏比**：按 **实际成交价** 相对 SL/TP 重算，可与「按 `E` 算的计划 RR」略有偏差。
- **本仓库止盈止损挂单**：开仓后由 **`_binance_place_tp_sl_orders`** 挂载（与手动一致：U 本位条件/Algo 类触发单；具体类型以 ccxt / 交易所为准）。

---

## 自动单止盈 / 止损（仅箱体突破、收敛突破）

添加关键位时在页面选择 **止盈止损方案**（写入 `key_monitors.sl_tp_mode`）。确认 K 收盘 **E**，箱体高 **H = |upper − lower|`**。

| 方案 | `sl_tp_mode` | 多：SL / TP | 空：SL / TP |
|------|--------------|-------------|-------------|
| 标准突破（默认） | `standard` | 突破 K 低 × (1−`KEY_STOP_OUTSIDE_BREAKOUT_PCT`%) / **E+H** | 突破 K 高 × (1+外侧%) / **E−H** |
| 箱体1R·止盈1.5H | `box_1p5` | **E−H** / **E+1.5×H**（RR≈1.5） | **E+H** / **E−1.5×H** |
| 趋势单·自填止盈 | `trend_manual` | 突破 K 低 × (1−`KEY_TREND_STOP_OUTSIDE_PCT`%) / **录入止盈** | 突破 K 高 × (1+外侧%) / **录入止盈** |

计划 **`RR = calc_rr_ratio(direction, E, SL, TP)`**。若为 `None` 或 **RR ≤ `KEY_AUTO_MIN_PLANNED_RR`** → **不下单**，走 `rr_insufficient` 结案。

**移动保本：** 添加时可勾选（默认关）；开仓写入 `order_monitors.breakeven_enabled` 与勾选一致。详见仓库根目录 `关键位止盈止损与移动保本更新说明.md`。

---

## 一次性结案（`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` |