Add OKX hedge-plan P0: env group, preview page, and PnL scenario math.

Co-authored-by: Cursor <cursoragent@cursor.com>

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

@@ -0,0 +1,661 @@
+# 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,或主方向 + 尾部).
+- 预算受 `OKX_OPTIONS_TRADE_BUDGET_USDC` 等既有约束;可拆预算到两腿.
+
+### 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 期期对冲
+
+| 事件 | 盈利方 | 亏损方 | 计划是否结束 |
+|------|--------|--------|--------------|
+| **标的价到达用户目标价 S\*** | **自动平仓** | **不平**,持有至到期 | 平盈利腿后计划可标 `closing`;**全部腿终态后结束**(亏损腿到期后结账) |
+| **到期且整体无盈利** | — | 到期结算 | **算结束**;合计记 **总亏损**(通常 ≈ −全部权利金,或到期结算净值 < 0 的合计) |
+| 到期时组合合计仍盈利 | — | 到期结算 | **算结束**;按实际结算盈亏入账 |
+| 未达 S\* 至到期 | 两腿均到期 | | 同上,按结算合计结束 |
+
+判定「整体无盈利」:到期(或计划收口)时 `realized_pnl_total ≤ 0`(含双腿权利金全损).
+
+盈利方判定规则仍按前文(触达 S\* 时按浮盈较大一侧平仓;皆亏则等到期).
+
+---
+
+### 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_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 | 热更 | 达目标价只平盈利方 |
+| `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_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
+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、仅买方、限价规则必须遵守 |
+| [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 复用已有分组
+
+---
+
+## 17. 免责与边界
+
+- 双账户非原子成交,存在半腿风险.
+- 止盈结束账上按权利金全额计成本;期权若仍持仓,后续行情 **不再改计划合计**,属设计意图.
+- 止盈后期权可能继续损耗直至到期,与「计划已结束」并存.
+- 买方权利金可能全部损失;期期到期无盈利记总亏损,属设计意图.
+- 本文不构成投资建议.

docs/对冲计划策略与P0校验.md

@@ -0,0 +1,109 @@
+# 对冲计划策略说明与 P0 校验
+
+> 配套实现方案:[对冲计划开发方案.md](./对冲计划开发方案.md)  
+> 本文记录 **策略口径** 与 **P0 代码校验**,确认可继续 P1+.
+
+---
+
+## 1. 策略摘要
+
+| 类型 | 账户 | 作用 |
+|------|------|------|
+| **永期对冲** | 永续子账户 + 期权主账户买方 | 全仓做方向,期权买保险 |
+| **期期对冲** | 仅期权主账户双买方 | 目标价兑现盈利腿,亏损腿到期 |
+
+### 永期结束与统计
+
+| 事件 | 期权处理 | 计划 | 统计公式 |
+|------|----------|------|----------|
+| 止盈 | 不强平 | **结束** | **止盈盈利 − 权利金** |
+| 止损 | **强制平** | **结束** | **期权盈利 − 永续亏损**(有符号相加) |
+
+### 期期结束与统计
+
+| 事件 | 处理 | 统计 |
+|------|------|------|
+| 达目标价 | 只平盈利腿 | 待亏损腿到期后结账 |
+| 到期无盈利 | **结束** | **总亏损** |
+
+起止均企业微信推送(P2+ 监控落地后再接).
+
+### 门禁
+
+- 永期开仓:**仅** `POSITION_SIZING_MODE=full_margin`
+- 非全仓:永期可测算不可开;期期 P0 起可测算(开仓后续版本)
+- env:OKX「对冲计划」分组;须 `HEDGE_PLAN_ENABLED=true` 才显示导航
+
+---
+
+## 2. P0 已交付
+
+| 项 | 状态 |
+|----|------|
+| env 白名单「对冲计划」9 字段 | 有 |
+| OKX `.env.example` 字段 | 有 |
+| `/hedge-plan` 页(永期列表 / 期期 T) | 有 |
+| `/api/hedge-plan/market|options-chain|preview|gates` | 有 |
+| 全仓建议张数(可用×0.98×10x) | 有 |
+| 情景测算止盈/止损口径 | 有 |
+| 启动开仓 | **禁用**(明示 P0) |
+| 历史/统计/监控/微信 | **未做**(P1–P5) |
+
+关键文件:
+
+- `lib/hedge_plan/hedge_plan_calc_lib.py`
+- `lib/hedge_plan/hedge_plan_register.py`
+- `lib/hedge_plan/templates/hedge_plan_panel.html`
+- `lib/common/static/hedge_plan.js`
+- `tests/test_hedge_plan_calc.py`
+
+---
+
+## 3. 校验清单(可行性)
+
+### 计算口径
+
+```
+止盈: perp_pnl(tp) - premium
+止损: option_expiry_pnl(spot=sl) + perp_pnl(sl)
+期期到期无盈利: expiry_flat_total <= 0 → 记总亏损
+```
+
+单测覆盖:`tests/test_hedge_plan_calc.py`.
+
+### 门禁
+
+- `risk` + 永期 → `can_start=false`,文案含「全仓」
+- `HEDGE_PLAN_ENABLED=false` → 导航隐藏(服务端 template 读 env)
+
+### 行情
+
+- 永续:`exchange.fetch_ticker` + `get_available_trading_usdt` + `compute_full_margin_sizing`
+- 期权:`build_option_chain`(与期权页同源)
+
+### 已知边界(非 P0 bug)
+
+1. 建议张数未强制 `amount_to_precision`(开仓阶段再对齐交易所精度).
+2. 止盈账扣全额权利金,与期权是否仍持仓无关(策略如此).
+3. 热更新 `HEDGE_PLAN_ENABLED` 后需刷新页面才显隐导航.
+4. 嵌入壳 Tab 已注册 `hedge_plan`;中控能力勾选若需显式「对冲」可后续加.
+
+---
+
+## 4. 服务器启用步骤
+
+```bash
+# env 配置页 → 对冲计划 → HEDGE_PLAN_ENABLED=true → 保存
+# 或服务器:
+cd /opt/crypto_monitor/crypto_monitor_okx
+# 确保 .env 含 HEDGE_PLAN_* 字段后
+pm2 restart crypto_okx --update-env
+```
+
+验收:
+
+1. 顶栏出现「对冲计划」
+2. 永期可见建议张数(全仓时)
+3. 点「计算」得到止盈/止损合计
+4. 「启动计划」禁用
+5. env 页可见「对冲计划」分组