crypto_monitor/docs/对冲计划开发方案.md

# OKX 对冲计划 — 开发方案

> 状态:**方案冻结**(实现前对照本页;改需求先改本文).  
> 范围:**仅 `crypto_monitor_okx` 实例**;中控不做对冲开平.  
> 相关策略说明:[期权对冲方案分析.md](./期权对冲方案分析.md)

---

## 1. 目标与命名

在 OKX 实例增加独立模块 **「对冲计划」**,把「行情选腿 → 情景测算 →(条件满足时)自动开仓 → 规则退出 → 独立复盘统计」串成一套可状态跟踪的计划.

| 产品名 | 英文键 | 含义 |
|--------|--------|------|
| **永期对冲** | `perp_options` | 同账户永续 + 买方期权 |
| **期期对冲** | `options_options` | 同账户内两条买方期权腿 |

页面/导航展示用中文名;API/DB 用英文键.

**不做(本方案外):**

- 卖方期权、组合单原子成交
- 中控代下单
- 跨所对冲
- 替代现有关键位/策略/期权页(可共存,但同标的限制见 §9)

---

## 2. 计仓模式门禁

沿用 `[docs/position-sizing-mode.md](./position-sizing-mode.md)`:

| `POSITION_SIZING_MODE` | 永期对冲 | 期期对冲 |
|------------------------|----------|----------|
| `risk`(以损定仓 / **非全仓**) | **仅测算**(左右行情 + 情景表);**禁止开仓/启动计划** | **允许开仓**(测算 + 启动计划) |
| `full_margin`(全仓杠杆) | **允许开仓** | **允许开仓** |

说明:

- **永期**依赖永续全仓名义与保证金节奏,故开仓仅限全仓.
- **期期**不占永续保证金,非全仓也允许开期权腿;非全仓下 UI 隐藏/禁用「启动永期」,仍可做永期**只读测算**.
- 切模式后若存在 `active` 永期计划,禁止切到 `risk`,或强制要求先结束计划(实现时二选一并写死校验).

额外硬门:

- 须 `OKX_OPTIONS_ENABLED=true` 且期权 API 可用.
- 实际开仓须实例允许实盘(`LIVE_ORDER` 等与永续/期权现有开关一致),并对冲计划自有开关见 §10.

---

## 3. 永期对冲 — 仓位与选期权

### 3.1 永续开仓量(全仓)

与现网全仓逻辑一致,对冲计划固定用于 **BTC / ETH**:

```
可用保证金 = 合约账户可用 USDT
占用保证金 = 可用 × FULL_MARGIN_BUFFER_RATIO(默认 0.98)
杠杆 = BTC_LEVERAGE / ETH 对应杠杆(默认 10x)
名义 ≈ 占用保证金 × 杠杆
张数 = amount_to_precision(名义 / 价格 / 合约面值)
```

页面左侧展示:**建议张数、名义、止损亏损额、止盈盈利额**(用户填止盈价/止损价后按该仓位即时算).

用户流程:

1. 选标的 ETH/BTC、方向(多/空).
2. 系统按全仓 ×0.98×10x 算出永续张数与到止盈/止损的 U 盈亏.
3. **再据此挑选右侧期权**(保费、张数、行权价),使「止损时保险腿」与「止盈保费损耗」可接受.
4. 通过情景表确认后启动计划.

### 3.2 期权腿选取

- 行情自动拉 OKX 期权链(复用 `build_option_chain`).
- **报价形态:列表式**;多仓默认筛 **Put**,空仓默认筛 **Call**.
- 权利金默认按 **卖一 ask** 估算;开仓限价买入.

### 3.3 左右布局

```
左:永续列表行情(标记/买卖一) + 方向/建议张数/开仓价/止盈/止损
右:期权列表(可「选用」一条腿)
下:情景测算 → [保存草稿] [启动计划]
```

---

## 4. 期期对冲 — 仓位与选腿

### 4.1 报价与选腿

- **T 型报价链**(复用期权页 T 型样式/数据结构).
- 用户选 **腿 A + 腿 B**(通常 Call + Put,或主方向 + 尾部).
- 预算:`B = min(交易户 USDC × OKX_OPTIONS_BUDGET_BUFFER, OKX_OPTIONS_TRADE_BUDGET_USDC)`(默认 buffer=0.95).
- 自动张数(选齐两腿后写入,可手改):
  - **同张数**(默认):最大 `n` 使 `n×(cost_A+cost_B) ≤ B`,两腿均填 `n`
  - **做多 / 做空**:须一 Call 一 Put;主:次默认 **7:3**(`HEDGE_PLAN_OO_BIAS_RATIO`,可改)
    - 做多:主腿=Call;做空:主腿=Put
    - 拆分口径 `HEDGE_PLAN_OO_BIAS_SPLIT_BY`:`budget`(默认,按权利金预算拆) / `sheets`(先按同张数得每腿 `n`,总张数 `2n` 再按比例拆到 Call/Put)
  - 另受各自卖一深度上限约束
  - 已移除页面「均分」;后端仍兼容旧 `split_budget` 入参(预算对半)

### 4.2 目标价

用户填 **预判价格 S\*** (「价格能到的位置」):

- 系统标明在 S\* 时哪条腿为 **盈利方**、哪条为 **亏损方**.
- 到达规则见 §5.2.

### 4.3 左右布局

```
左:指数价 + 到期日 + 预算 + 目标价 S*
右:T 型链,依次选用两腿
下:情景测算 → [保存草稿] [启动计划]
```

非全仓模式下期期布局同上(无永续区).

---

## 5. 退出规则(冻结)

### 5.1 永期对冲

| 事件 | 永续 | 期权 | 计划是否结束 | 设计意图 |
|------|------|------|--------------|----------|
| **永续止盈触发** | 交易所 TP 平仓 | **不强制平**(保险腿可自生自灭/人工) | **算结束** | 对冲计划以永续兑现目标收口 |
| **永续止损触发** | 交易所 SL 平仓 | **必须强制平仓** | **算结束** | 保护机制 |
| 期权单独到期 | — | 结算 | 若计划已因止盈结束则只更新腿快照,不再改计划合计 | |
| 人工结束计划 | 可选平永续 | 按选项 | **算结束** | |

**计划结束时盈亏口径(写入 `realized_pnl_*`,推送与统计共用):**

| 结束原因 | 公式(≈U,1:1) | 字段落库 |
|----------|--------------|----------|
| **止盈** `perp_tp` | **永续止盈已实现盈利 − 期权已付权利金** | `realized_pnl_perp` = 止盈盈利;`realized_pnl_options` = **−premium_total**(按权利金全额计成本,不论期权是否仍持仓);`realized_pnl_total` = 上两式之和 |
| **止损** `perp_sl` | **期权平仓盈利 − 永续止损亏损额** | `realized_pnl_options` = 期权强制平后已实现;`realized_pnl_perp` = 永续止损已实现(为负或记亏损额);`realized_pnl_total` = 期权盈利 − \|永续亏损\|(即有符号相加) |

说明:

- 止盈时期权**物理上可不平**,但 **计划账** 已按「保费打掉」收口,后续期权 thrift/到期盈亏 **不再回写计划合计**(可在腿上另记备注/浮盈,不进 `realized_pnl_total`).
- 止损时期权必须先强平再结账,用真实平仓盈亏,不是只扣权利金.

永续侧 TP/SL:沿用实例 **交易所条件单**,监控识别成交后触发计划结束逻辑 + 微信推送.

### 5.2 期期对冲

| 事件 | 盈利方 | 另一腿(残腿) | 计划是否结束 |
|------|--------|--------------|--------------|
| **标的价到达目标 + 平仓模式=到期平** | **自动平仓** | **不平**,持有至到期(`hold_expiry`) | 平盈利腿后仍 `active`;残腿到期后结账 |
| **标的价到达目标 + 平仓模式=全平**(默认) | **自动平仓** | **随即买一清残腿**(无 2×门控,失败则每轮重试) | 两腿都平完后 `closed` |
| **到期且整体无盈利** | — | 到期结算 | **算结束**;合计记 **总亏损** |
| **到期时组合合计仍盈利** | — | 到期结算 | **算结束**;按实际结算盈亏入账 |

- 界面「平仓模式」仅控制**盈利腿已平之后**另一腿的处理;须 `HEDGE_PLAN_OO_CLOSE_MODE_ENABLED=true`(默认开)才显示,页面默认选 **全平**.
- 关闭方案C开关时行为固定为 **到期平**.
- 判定「整体无盈利」:到期(或计划收口)时 `realized_pnl_total ≤ 0`(含双腿权利金全损).
- 盈利方判定:触达上破/下破时按浮盈较大一侧平仓;皆亏则等到期.

### 5.2.1 期权腿实盘平仓执行(与期权页共用)

对冲计划凡**必须物理平掉期权腿**时(如永期止损联动、期期平盈利腿),执行口径与独立期权模块一致:

| 规则 | 说明 |
|------|------|
| 禁市价 | 代码硬关闭,无市价兜底 |
| 只锁买一 | 本轮 `min(仓位, 买一深度)` × 买一限价;`reduceOnly` |
| 分批 | 买一不够则剩余下一轮再平再锁新买一 |
| 有效流动性 | 残档买一禁止按买盘平 |
| 2× 门控 | 目标位/自动类路径首次需可回收≥2×权利金并持续 hold;手动买一平只验流动性 |
| 平仓挂单 TTL | 卖出限价超 `OKX_OPTIONS_PENDING_TTL_SECONDS`(默认 10 分钟)自动撤;UI「委托」可见 |

完整说明(可单独打开):**[期权开平仓与监控说明.md](./期权开平仓与监控说明.md)** · 线上 `/options/guide`.

---

### 5.3 企业微信推送(起止必发)

| 时机 | 是否必发 | 内容要点 |
|------|----------|----------|
| **计划开始**(开仓成功 → `active`) | **必发** | 类型(永期/期期)、标的方向、关键价位、张数/保费、计划 id |
| **计划结束** | **必发** | 结束原因、`realized_pnl_total`、分项(永续/期权)、是否止盈/止损/到期亏损 |
| 半腿失败 / 强平失败 | 必发告警 | 便于人工介入 |
| 目标价平掉盈利腿(期期中间态) | 建议发 | 注明亏损腿仍持有 |

结束推送触发点与「算结束」一致:永期止盈、永期止损、期期到期收口(含无盈利总亏)、人工结束等.

---

## 6. 情景测算(开仓前必显)

### 6.1 永期

| 情景 | 含义 |
|------|------|
| 止盈 | 永续到 TP 的盈利 − 期权保费(期权按不强制平时的损耗估算) |
| 宽止损 | 永续到 SL 的亏损 + 期权平仓估值(强制平,用 mark/买一估算) |
| 到期横盘 | 永续≈0 + 期权权利金全损 |
| 价格扫描 | index ± 若干档合计 |

核心输出:**宽止损合计亏损**(人工评估是否开仓).

### 6.2 期期

| 情景 | 含义 |
|------|------|
| 到达 S\* | 盈利腿兑现估值 − 已付总保费中亏损腿残留 |
| 到期横盘 | 双腿权利金近似全损 |
| 到期大涨/大跌 | 结算内在价值 |

---

## 7. 数据来源(行情自动)

| 侧 | 来源 |
|----|------|
| 永续行情/规格 | OKX 账户 ccxt:ticker + 现有 `/api/hub/market` 规格逻辑 |
| 期权链 | `build_option_chain` / `/api/options/chain`(本实例直连,无需中控代理) |
| 指数价 | 期权 `index_px`,左右对齐 |

报价刷新:页面手动刷新 + 计划编辑态可选 10～30s 自动刷新.

---

## 8. 自动开仓编排

### 8.1 永期(仅全仓)

建议默认顺序:**先期权、后永续**(期权失败成本低;永续失败则提示处理刚开的期权).

```
校验 full_margin + LIVE + 无冲突计划
→ 期权限价买入(卖一)
→ 永续全仓张数市价开仓 + 挂交易所 TP/SL
→ 写 hedge_plans / legs,状态 active
```

部分失败补偿(最小集):

| 情况 | 动作 |
|------|------|
| 期权成、永续败 | 告警;建议自动平期权(可配置)或转人工 |
| 永续成、期权败 | 告警;可选撤永续或重试期权;计划标 `partial` |

### 8.2 期期(全仓与非全仓均可开)

```
校验 LIVE + 期权资金
→ 腿1 限价买
→ 腿2 限价买
→ active;记录 target_price S*
```

两腿间勿留长时间单腿敞口;第二腿失败则标 `partial` 并告警.

---

## 9. 状态机与冲突

```
draft → opening → active → closing → closed
                 ↘ partial / failed
draft → cancelled
```

冲突规则:

- **同标的同时至多 1 条 active 永期计划**(全局可 `MAX_ACTIVE_HEDGE_PLANS`).
- 永期 active 时与全仓「单仓」一致:**不与额外永续仓并存**(启动前校验无其它持仓,或本计划即为该仓).
- 期权页对手动平「计划绑定 inst」应提示归属对冲计划.

---

## 10. 历史记录、统计与复盘(独立)

**入口:** OKX 顶栏 **「对冲计划」** 页内三个 Tab(不单开顶栏项):

| Tab | 路由建议 | 内容 |
|-----|----------|------|
| **计划** | `/hedge-plan` | 新建 / 草稿 / 进行中 |
| **历史** | `/hedge-plan?tab=history` | 已结束与取消的计划列表 + 详情复盘 |
| **统计** | `/hedge-plan?tab=stats` | 独立统计看板 |

**不得**并入普通「交易记录与复盘」`/records`、全站「统计分析」`/stats`、策略交易记录.  
腿可可选关联 `options_trades` / 监控 id,但 **计划合计盈亏与胜率只读本模块表**.

币种展示约定:永续腿 USDT、期权腿 USDC;合计列标注 **「≈U(1:1)」**,不做实时汇率换算.

---

### 10.1 数据落库

库文件:OKX 实例 `crypto.db`(与其它表同库).

#### `hedge_plans`(一条计划)

| 字段 | 类型建议 | 说明 |
|------|----------|------|
| `id` | INTEGER PK | |
| `plan_type` | TEXT | `perp_options` 永期 / `options_options` 期期 |
| `status` | TEXT | draft / opening / active / closing / closed / partial / failed / cancelled |
| `underlying` | TEXT | BTC / ETH |
| `direction` | TEXT | 永期:long/short;期期可空 |
| `entry_mark` | REAL | 开仓参考价(标记/指数快照) |
| `tp` | REAL | 永期止盈价;可空 |
| `sl` | REAL | 永期止损价;可空 |
| `target_price` | REAL | 期期目标价 S\*;可空 |
| `sizing_mode_at_open` | TEXT | 开仓时 `risk`/`full_margin` 快照 |
| `perp_size` | REAL | 永期张数/币量快照;期期空 |
| `margin` | REAL | 占用保证金快照 |
| `leverage` | REAL | 杠杆快照 |
| `premium_total` | REAL | 期权已付权利金合计(USDC) |
| `realized_pnl_perp` | REAL | 永续已实现(USDT);止盈为正,止损为负 |
| `realized_pnl_options` | REAL | 期权账:止盈场景记 **−权利金**;止损场景记 **强平真实盈亏** |
| `realized_pnl_total` | REAL | 见 §5.1 / §5.2 公式;统计与微信共用此值 |
| `stats_bucket` | TEXT | 可选冗余:`tp` / `sl` / `oo_expiry_loss` / `oo_target` / `other` 便于统计筛选 |
| `close_reason` | TEXT | 见下表枚举 |
| `wechat_start_sent` | INTEGER | 开仓推送是否已发 |
| `wechat_end_sent` | INTEGER | 结束推送是否已发 |
| `note` | TEXT | 人工复盘短评 |
| `created_at` | TEXT | |
| `opened_at` | TEXT | 首次腿成交时间 |
| `closed_at` | TEXT | **计划结束时间**(止盈/止损/到期收口等) |
| `preview_json` | TEXT | 开仓前情景测算快照(可选) |

**`close_reason` 枚举**

| 值 | 含义 | 是否算计划结束 | 合计口径 |
|----|------|----------------|----------|
| `perp_tp` | 永续止盈 | **是**(立刻 closed) | **止盈盈利 − 权利金** |
| `perp_sl` | 永续止损 + 期权强制平 | **是** | **期权盈利 − 永续亏损** |
| `target_win_leg` | 期期已平盈利腿(中间态可暂不 closed) | 腿未齐前可不结束 | 待亏损腿到期后定合计 |
| `oo_expiry_loss` | 期期到期且合计无盈利 | **是** | **总亏损**(settled ≤ 0,常 ≈ −保费) |
| `oo_expiry_win` | 期期到期合计仍盈利 | **是** | 实际到期合计 |
| `expiry` | 其它到期收口 | **是** | 实际结算 |
| `manual` | 人工结束 | **是** | 按当时已实现 |
| `partial_fail` | 半腿失败收尾 | **是** | 按补偿结果 |
| `cancelled` | 未真正开仓取消 | 是(无盈亏) | 0 |

说明:止盈结束时期权腿可标 `hold_to_expiry`/`orphaned_after_tp`,**计划已 closed**,后续期权盈亏不回写 `realized_pnl_total`.

#### `hedge_plan_legs`(一条腿)

| 字段 | 类型建议 | 说明 |
|------|----------|------|
| `id` | INTEGER PK | |
| `plan_id` | INTEGER FK | |
| `leg_role` | TEXT | `perp` / `option_hedge` / `option_a` / `option_b` |
| `symbol` 或 `inst_id` | TEXT | 永续符号或期权合约 id |
| `opt_type` | TEXT | C/P;永续空 |
| `strike` | REAL | 期权行权价 |
| `side` | TEXT | long/short 或 buy |
| `size` | REAL | 张数或币量 |
| `avg_open` | REAL | 开仓均价/权利金单价 |
| `premium` | REAL | 该腿已付权利金(期权) |
| `status` | TEXT | open / closed / hold_to_expiry |
| `linked_monitor_id` | INTEGER | 可选,永续监控 |
| `options_trade_id` | INTEGER | 可选,期权成交表 |
| `realized_pnl` | REAL | 该腿已实现 |
| `close_reason` | TEXT | 腿级原因 |
| `opened_at` / `closed_at` | TEXT | |

---

### 10.2 历史列表(列定义)

筛选:**类型**(全部/永期/期期)、**状态**、**标的**、**日期**(按 `opened_at` 或 `closed_at`).

| 列 | 来源 | 展示 |
|----|------|------|
| ID | id | `#12` |
| 类型 | plan_type | 永期对冲 / 期期对冲 |
| 标的 | underlying + direction | 如 `ETH 多` / `ETH 双买` |
| 状态 | status | 中文标签 |
| 开仓时间 | opened_at | |
| 结束时间 | closed_at | 进行中显示 — |
| 平仓原因 | close_reason | 中文(止盈离场/止损联动平/目标价平盈利腿/到期…) |
| 保费 | premium_total | `x.xx USDC` |
| 合计盈亏 | realized_pnl_total | 着色 +/- ,单位 ≈U |
| 腿摘要 | legs | 如 `永续✓ · Put持仓` / `Call已平 · Put到期` |
| 操作 | | 详情 |

行操作:**详情**(主)、可选「补写短评」.

---

### 10.3 计划详情 / 复盘页(字段)

从历史点进去的详情页 = **主复盘面**,分块如下.

#### A. 计划摘要

| 项 | 字段 |
|----|------|
| 类型 / 标的 / 方向 | plan_type, underlying, direction |
| 状态 / 平仓原因 | status, close_reason |
| 时间线 | created_at → opened_at → closed_at |
| 开仓时计仓 | sizing_mode_at_open, margin, leverage, perp_size |
| 关键价位 | entry_mark, tp, sl(永期), target_price(期期) |
| 盈亏 | realized_pnl_perp / realized_pnl_options / realized_pnl_total |
| 开仓情景快照 | preview_json 折叠展示(止盈合计/宽止损合计等) |

#### B. 腿明细表

| 列 | 说明 |
|----|------|
| 角色 | 永续 / 保险期权 / 期期腿A/B |
| 合约 | symbol / inst_id |
| 数量 | size |
| 开仓价/保费 | avg_open, premium |
| 状态 | open / closed / 持有至到期 |
| 盈亏 | realized_pnl |
| 平仓原因 | close_reason |
| 关联 | 链到期权成交或监控(有则显示) |

#### C. 复盘短评(必做入口)

| 项 | 说明 |
|----|------|
| `note` | 多行文本,可空;保存 `PATCH /api/hedge-plan/<id>/note` |
| 提示文案 | 建议写:开仓理由、结果是否符合情景测算、下次调整 |

**不做(本期):** 复盘截图上传、填入「交易记录与复盘」表单、纳入 AI 日/周复盘.  
**可后置:** 以计划摘要生成 AI 点评(独立按钮,不写进 trade_records).

#### D. 终态示例文案(便于复盘理解)

| 场景 | 详情页状态说明 | 合计 |
|------|----------------|------|
| 永期止盈 | 「计划已结束(止盈);期权腿可不强平,账上已扣全部权利金」 | 止盈盈利 − 权利金 |
| 永期止损 + 期权已强平 | 「计划已结束(止损保护:期权已联动平仓)」 | 期权盈利 − 永续亏损 |
| 期期到期无盈利 | 「计划已结束(到期无盈利)」 | 总亏损(计入统计) |
| 期期达 S\* 后亏损腿仍持有 | 「盈利腿已平;待亏损腿到期后结账」 | 暂不入 closed 统计,或单独「收尾中」 |

---

### 10.4 统计页(独立看板)

**筛选:** 日期区间、类型(全部/永期/期期)、标的、结束桶(`tp`/`sl`/`oo_expiry_loss`/…).

**聚合规则:** 仅 `status=closed`;胜场 = `realized_pnl_total > 0`.

#### 永期口径(冻结)

| 统计桶 | `close_reason` | 单笔盈亏公式 | 汇总 |
|--------|----------------|--------------|------|
| **止盈统计** | `perp_tp` | **止盈盈利 − 期权权利金** | sum / 笔数 / 胜率 |
| **止损统计** | `perp_sl` | **期权盈利 − 永续亏损** | sum / 笔数 /「保护后净亏」均值 |

实现校验示例:

```
# 止盈
realized_pnl_total = pnl_perp_tp - premium_total

# 止损(亏损额取绝对值)
realized_pnl_total = pnl_option_close - abs(pnl_perp_sl)
# 等价有符号: pnl_option_close + pnl_perp_sl(后者为负)
```

#### 期期口径(冻结)

| 统计桶 | 条件 | 单笔盈亏 |
|--------|------|----------|
| **到期无盈利** | 到期收口且合计 ≤ 0 | **总亏损**写入 `realized_pnl_total`(负值),计入区间净亏与「到期亏损」汇总 |
| 目标价路径 | 盈利腿已平 + 亏损腿到期后 | 两腿 realized 之和 |
| 到期仍盈利 | 合计 &gt; 0 | 实际结算合计 |

#### 总览卡片

| 指标 | 计算 |
|------|------|
| 计划笔数 | count(closed) |
| 胜率 | 胜场 / 笔数 |
| 区间净盈亏 | sum(realized_pnl_total) |
| 止盈桶净盈亏 | sum where stats_bucket=tp |
| 止损桶净盈亏 | sum where stats_bucket=sl |
| 期期到期亏损合计 | sum where oo_expiry_loss(绝对值或带符号合计) |
| 总保费支出 | sum(premium_total) |
| 平均持仓时长 | avg(closed_at − opened_at) |

#### 分类型卡片

永期、期期各一套:笔数、胜率、净盈亏、平均保费;永期再拆 **止盈桶 / 止损桶**.

#### 退出结构

| 指标 | 过滤 |
|------|------|
| 止盈结束笔数 | `perp_tp` |
| 止损结束笔数 | `perp_sl` |
| 期期到期无盈利笔数 | `oo_expiry_loss` |
| 目标价路径完结 | 含 `target_win_leg` 后收尾 |
| 半腿/失败 | `partial_fail` / failed |

#### 简易表(可选)

最近 N 条已结束计划迷你列表,点击跳详情.

**导出(P5 可选):** CSV.

---

### 10.5 与现有页面关系

| 现有页 | 关系 |
|--------|------|
| 交易记录与复盘 | **不写入**;永续腿若系统仍落 `trade_records`,可标记来源「对冲计划#id」,但人工复盘以对冲详情为准 |
| 统计分析 | **不合并**对冲净盈亏到全站数字(避免重复或口径混乱) |
| 期权页成交/持仓 | 腿 `options_trade_id` 可跳转对照;期权页仍可看单腿 |
| 中控 | V1 不聚合;V2 可选只读摘要 |

---

### 10.6 API(历史 / 统计 / 复盘)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/hedge-plan/list` | 进行中+草稿;`status` 过滤 |
| GET | `/api/hedge-plan/history` | 已结束列表;类型/日期/标的 |
| GET | `/api/hedge-plan/<id>` | 详情 = 计划 + legs + note + preview |
| PATCH | `/api/hedge-plan/<id>/note` | 保存复盘短评 |
| GET | `/api/hedge-plan/stats` | query:`from`,`to`,`plan_type`,`underlying` → 总览+分类型+退出结构 |

---

## 11. 监控线程

在 `crypto_okx` 同进程内新增 **`hedge_plan_monitor_loop`**(可与 `options_monitor_loop` 并列):

| 职责 | |
|------|--|
| 永期 | 侦测永续 TP/SL → 按 §5.1 结束计划并结账;SL 时强制平期权 |
| 期期 | 侦测价触 S\* → 平盈利腿;到期无盈利 → 结束并记总亏损 |
| 微信 | **开始必推、结束必推**(§5.3);半腿/强平失败告警 |
| 幂等 | `wechat_start_sent` / `wechat_end_sent` 防重复推送 |

---

## 12. 配置项与前端 env 页

对冲相关开关 **一律在 OKX 实例「env 配置」页维护**,不要求 SSH 改 `.env`.  
实现对齐现有白名单模式(`lib/env/env_ui_manifest.py` 的「期权账户」分组).

### 12.1 前端分组

在 env 配置页新增独立卡片,标题 **「对冲计划」**:

- **仅 OKX** 展示(Binance/Gate 不出现)
- 放在 **「期权账户」下方**(依赖期权模块)
- 卡片说明文案建议:
  - 永期开仓还要求「交易执行」里计仓模式为 **全仓**(`POSITION_SIZING_MODE=full_margin`)
  - 真实下单还与「交易所与实盘」→ `LIVE_TRADING_ENABLED`、本卡片 `HEDGE_PLAN_LIVE_ORDER` 同时开启
  - `HEDGE_PLAN_ENABLED` 关闭时隐藏顶栏「对冲计划」并拒绝启动计划

### 12.2 本分组字段(前端可配)

| 变量 | 前端标签 | 默认 | 控件 | 热更新 | 说明 |
|------|----------|------|------|--------|------|
| `HEDGE_PLAN_ENABLED` | 启用对冲计划 | false | bool | 热更优先 | 总开关:导航 + API |
| `HEDGE_PLAN_SHOW_PERP_OPTIONS` | 显示永期对冲 | true | bool | 热更 | 关则隐藏永期 Tab,不可测算/开仓 |
| `HEDGE_PLAN_SHOW_OPTIONS_OPTIONS` | 显示期期对冲 | true | bool | 热更 | 关则隐藏期期 Tab,不可测算/开仓 |
| `HEDGE_PLAN_LIVE_ORDER` | 允许对冲真实下单 | false | bool | 热更 | 关则只测算/草稿 |
| `HEDGE_PLAN_OPEN_ORDER` | 永期开仓顺序 | options_first | select:`options_first`/`perp_first` | 热更 | 默认先期权后永续 |
| `HEDGE_PLAN_ON_PERP_SL_CLOSE_OPTIONS` | 永期止损后强制平期权 | true | bool | 热更 | **保护机制,默认 true** |
| `HEDGE_PLAN_ON_PERP_TP_CLOSE_OPTIONS` | 永期止盈后强制平期权 | false | bool | 热更 | **默认 false,保险腿不平** |
| `HEDGE_PLAN_OO_CLOSE_WINNER_ONLY` | 期期只平盈利腿 | true | bool | 热更 | 达目标价只平盈利方 |
| `HEDGE_PLAN_OO_CLOSE_MODE_ENABLED` | 期期平仓模式(方案C) | true | bool | 热更 | 开:页面可选到期平/全平;关:固定到期平 |
| `MAX_ACTIVE_HEDGE_PLANS` | 最大同时活跃计划数 | 1 | number | 热更 | 建议保持 1 |
| `HEDGE_PLAN_MONITOR_POLL_SECONDS` | 对冲监控轮询(秒) | 15 | number | 热更 | 侦测 TP/SL/目标价 |
| `HEDGE_PLAN_PARTIAL_AUTO_CLOSE_OPTION` | 半腿失败时自动平期权 | true | bool | 热更 | 期权成、永续败时的补偿 |

**不放入本分组、沿用已有卡片:**

| 已有位置 | 键 | 对冲用途 |
|----------|-----|----------|
| 交易执行 | `POSITION_SIZING_MODE` | 全仓才允许永期开仓 |
| 交易执行 | `FULL_MARGIN_BUFFER_RATIO` | 默认 0.98 |
| 交易执行 | `BTC_LEVERAGE` | BTC/ETH 档(默认 10) |
| 交易所与实盘 | `LIVE_TRADING_ENABLED` | 总实盘门 |
| 期权账户 | `OKX_OPTIONS_*` | 期权 API、预算、标的 |

### 12.3 `.env.example` 片段(实现时写入 OKX)

```env
# --- 对冲计划(仅 OKX;前端 env「对冲计划」) ---
HEDGE_PLAN_ENABLED=false
HEDGE_PLAN_SHOW_PERP_OPTIONS=true
HEDGE_PLAN_SHOW_OPTIONS_OPTIONS=true
HEDGE_PLAN_LIVE_ORDER=false
HEDGE_PLAN_OPEN_ORDER=options_first
HEDGE_PLAN_ON_PERP_SL_CLOSE_OPTIONS=true
HEDGE_PLAN_ON_PERP_TP_CLOSE_OPTIONS=false
HEDGE_PLAN_OO_CLOSE_WINNER_ONLY=true
HEDGE_PLAN_OO_CLOSE_MODE_ENABLED=true
MAX_ACTIVE_HEDGE_PLANS=1
HEDGE_PLAN_MONITOR_POLL_SECONDS=15
HEDGE_PLAN_PARTIAL_AUTO_CLOSE_OPTION=true
```

### 12.4 编码触点

| 文件 | 改动 |
|------|------|
| `lib/env/env_ui_manifest.py` | `_HEDGE_PLAN_SECTION`,`exchanges={"okx"}`,接入 `ui_sections_for_exchange` |
| `crypto_monitor_okx/.env.example` | 增加上表键与分组注释 |
| `lib/env/env_schema.py` | 纳入 `HOT_RELOAD_EXACT`(及必要时重启列表) |
| `docs/env配置说明.md` | 上线时补「对冲计划」小节 |

推荐分期:**P0 先做 env 白名单 + 开关可读**,页面按 `HEDGE_PLAN_ENABLED` 显隐导航.

---

## 13. 前端与路由(实现要点)

- 导航:OKX 实例顶栏 **「对冲计划」**(display prefs 可加 `show_nav_hedge_plan`).
- 路由建议:`/hedge-plan`(主)、`/hedge-plan/history`、`/hedge-plan/stats`(或单页 Tab).
- 模板/静态:`lib/options` 旁新增 `lib/hedge_plan/`(或 `lib/hedge/`),复用:
  - 期权链 CSS/T 型渲染思路(`options_panel.js` / `options-strike-table--t`)
  - `compute_full_margin_sizing` / `position_sizing_lib`
  - 永续下单 + TPSL、期权限价开平 API

API 草图:

- `GET /api/hedge-plan/market` — 永续行情 + 全仓试算
- `GET /api/hedge-plan/options-chain` — 期权链
- `POST /api/hedge-plan/preview` — 情景测算
- `GET /api/hedge-plan/list` / `history` / `<id>` / `stats`
- `PATCH /api/hedge-plan/<id>/note` — 复盘短评
- `POST /api/hedge-plan` — 保存草稿/启动
- `POST /api/hedge-plan/<id>/cancel|close`

非全仓请求启动永期 → `400` 明确:「永期对冲开仓仅全仓模式可用」.

---

## 14. 分期实施

| 阶段 | 交付 | 验收 |
|------|------|------|
| **P0** | env「对冲计划」分组 + 页框 + 行情 + 永期列表/期期 T + 情景测算 + 门禁 | env 可改开关;非全仓无法启动永期;全仓可看建议张数 |
| **P1** | 表结构 + 草稿/列表 | DB 可查 |
| **P2** | 永期自动开仓(全仓) | 双腿成交入计划 |
| **P3** | 监控:止损强制平期权;止盈不平期权 | 用例测 TP/SL 分支 |
| **P4** | 期期开仓 + 目标价只平盈利腿 | 达价仅平一侧 |
| **P5** | 历史列表列 + 详情复盘(note) + 统计看板 + 微信 | 与 /records /stats 隔离;止损/止盈文案可区分 |

建议顺序严格;P3 规则错误会误平保险腿,上线前用 dry-run / paper flags.

---

## 15. 与现有文档关系

| 文档 | 关系 |
|------|------|
| [期权对冲方案分析.md](./期权对冲方案分析.md) | 策略观念;本模块是其「计划化 + 自动执行」实现 |
| [对冲计划策略与P0校验.md](./对冲计划策略与P0校验.md) | P0 交付与口径校验 |
| [期权方案.md](./期权方案.md) / [期权用法.md](./期权用法.md) | 期权 API、仅买方、限价规则必须遵守 |
| [期权开平仓与监控说明.md](./期权开平仓与监控说明.md) | 买一平仓、门控、监控与风险;线上 `/options/guide` |
| [position-sizing-mode.md](./position-sizing-mode.md) | 全仓公式与缓冲 0.98 |

本模块上线后,可在《期权对冲方案分析》末尾增加「系统对冲计划」链接指向本文.

---

## 16. 已拍板规则摘要(校验清单)

- [x] 放在 **OKX 实例**,名 **永期对冲 / 期期对冲**
- [x] 永期止盈 → **期权不强制平**,但 **计划算结束**;统计 = **止盈盈利 − 权利金**
- [x] 永期止损 → **期权必须强制平**,计划结束;统计 = **期权盈利 − 永续亏损**
- [x] 期期按目标价 → **只平盈利方**;到期无盈利 → **算结束并统计总亏损**
- [x] 对冲计划 **开始与结束均企业微信推送**
- [x] **独立历史 + 独立统计 + 计划详情复盘**(短评 note;不进普通交易复盘)
- [x] 永期开仓 **仅全仓**;非全仓永期只算账
- [x] 非全仓允许 **期期**开仓;全仓永期+期期均可
- [x] 永期张数:**ETH/BTC 10x 全仓 × 0.98**,先算盈亏再选期权
- [x] 行情自动;永期期权 **列表式**;期期 **T 型**
- [x] 对冲开关在前端 **env 配置 →「对冲计划」** 维护(仅 OKX);计仓/杠杆/期权 API 复用已有分组
- [x] 期权腿实盘平仓:**禁市价、只锁买一、分批;流动性/2×门控见开平仓说明**

---

## 17. 免责与边界

- 双账户非原子成交,存在半腿风险.
- 止盈结束账上按权利金全额计成本;期权若仍持仓,后续行情 **不再改计划合计**,属设计意图.
- 止盈后期权可能继续损耗直至到期,与「计划已结束」并存.
- 买方权利金可能全部损失;期期到期无盈利记总亏损,属设计意图.
- 本文不构成投资建议.