Add HEDGE_PO_MODE instance modes with shared sim/live path.

Lock one mode per instance/subaccount, cross-asset BTC option/ETH perp sizing, combo-U exit, and ship docs/tests/audit.

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

docs/永期对冲三模式.md

@@ -0,0 +1,137 @@
+# 永期对冲三模式（一实例 · 一模式 · 一子账户）
+
+> 模拟盘与实盘 **同一执行路径**；差别仅在 API Key / `LIVE_TRADING_ENABLED` / 模拟开关。  
+> 实现入口：`lib/hedge_plan/hedge_po_mode_lib.py`。
+
+---
+
+## 1. 定稿口径
+
+| 模式 `HEDGE_PO_MODE` | 期权标的 | 永续标的 | 名义关系 |
+|----------------------|----------|----------|----------|
+| `eth` | ETH | ETH | 永续名义 = 期权名义 ÷ 比例（默认比例 2 → 一半） |
+| `btc` | BTC | BTC | 同上 |
+| `btc_eth` | BTC | ETH | 永续名义(U) = 期权名义(U) × `HEDGE_CROSS_NOTIONAL_K`（默认 **0.5**） |
+
+### 方向（以期权为主，强制）
+
+- 买 **Call** → 永续 **空**
+- 买 **Put** → 永续 **多**
+
+### 出场（强制）
+
+- 仅 **组合盈利金额(U)**  
+- 口径：`期权净利(币) × 期权指数 + 永续净利(U)`（扣开平双边手续费）  
+- 与持仓卡 `combo.net_usdt`、监控出场门控一致；**禁止**币与 U 直接相加
+
+### 部署约束
+
+- **一个实例一种模式对应一个子账户**；账户之间互不干涉  
+- **禁止**同一子账户挂两个实例  
+- **禁止**运行中热切 `HEDGE_PO_MODE`（须换实例 / 换子账户 / 重启）  
+- 模拟 → 实盘：同模式、同定仓/出场逻辑，只换密钥与 live/sim 开关
+
+---
+
+## 2. 环境变量
+
+```env
+# 必配(建议显式写出);非法值启动时钳制并打日志
+HEDGE_PO_MODE=eth          # eth | btc | btc_eth
+HEDGE_CROSS_NOTIONAL_K=0.5 # 仅 btc_eth;永续名义/期权名义
+
+# 会与模式同步:期权链默认标的 = 模式的期权腿
+OKX_OPTIONS_DEFAULT_UNDERLY=ETH
+
+# 以期权为主(实例模式会强制 true)
+HEDGE_PLAN_OPTION_PRIMARY=true
+
+# 真下单:模拟可开;实盘须再开 LIVE_TRADING_ENABLED
+HEDGE_PLAN_LIVE_ORDER=true
+LIVE_TRADING_ENABLED=false
+```
+
+改 `HEDGE_PO_MODE` / `HEDGE_CROSS_NOTIONAL_K` 后须 **重启 PM2**（启动时 `clamp_hedge_po_mode_on_startup`）。
+
+---
+
+## 3. 多实例部署示例
+
+| 进程 / 域名 | `.env` | 子账户 |
+|-------------|--------|--------|
+| 实例 A | `HEDGE_PO_MODE=eth` | OKX 子账户「ETH对冲」 |
+| 实例 B | `HEDGE_PO_MODE=btc` | OKX 子账户「BTC对冲」 |
+| 实例 C | `HEDGE_PO_MODE=btc_eth` | OKX 子账户「跨币」 |
+
+模拟盘同样拆三套（或三库），**不要**一个模拟进程里切三种模式共一把钥匙。
+
+---
+
+## 4. 代码落点
+
+| 模块 | 作用 |
+|------|------|
+| `hedge_po_mode_lib.py` | 模式规范化、启动钳制、跨币名义、组合 U、body 钳制 |
+| `hedge_plan_option_primary_lib.py` | `size_from_premium` / `contracts_from_option_sheets` 支持双指数 |
+| `hedge_plan_orders_lib.py` | 启动前定仓刷新、校验按模式钳制 |
+| `hedge_plan_monitor_lib.py` | 出场门控用组合 U；跨币指数分腿 |
+| `hedge_plan_register.py` | 安装时钳制；行情/期权链锁定标的；落库 `po_mode`/`perp_underlying` |
+| `hedge_plan.js` + panel | 页内锁定标的；展示模式徽标；强制盈利金额出场 |
+| env schema / UI manifest | `HEDGE_PO_MODE`、`HEDGE_CROSS_NOTIONAL_K` |
+
+---
+
+## 5. 测试
+
+```bash
+python -m unittest tests.test_hedge_po_mode tests.test_hedge_plan_option_primary -v
+```
+
+覆盖：模式规范化、启动钳制、跨币名义半仓、组合 U 口径、body 校验。
+
+---
+
+## 6. 审计清单（模拟 / 实盘通用）
+
+启动后日志应出现：
+
+```text
+[HEDGE_PO_MODE] mode=... option=... perp=... k=... (一实例一模式一子账户)
+```
+
+| # | 检查项 | 期望 |
+|---|--------|------|
+| 1 | `/api/hedge-plan/po-mode` | `po_mode` / `option_underlying` / `perp_underlying` / `exit_mode=profit` |
+| 2 | 对冲页顶栏徽标 | 显示模式名；跨币显示「期权BTC/永续ETH」 |
+| 3 | ETH/BTC 切换钮 | 永期页禁用，与模式期权标的一致 |
+| 4 | 期权链 | 仅模式期权标的；拉错标的 API 400 |
+| 5 | 永续行情 `exchange_symbol` | 前缀=模式永续标的 |
+| 6 | 手动开仓 body | 服务端重写 `underlying`/`exit_mode`/`option_perp_ratio`(跨币) |
+| 7 | 定仓（跨币） | 期权名义U × K ≈ 永续名义U |
+| 8 | 持仓卡 `combo.net_usdt` | 期权币×期权指数 + 永续U |
+| 9 | 监控出场 | 达 `profit_target_usdt` 才平；比较的是组合 U |
+| 10 | 卖回币 | 卖 **期权标的**币（跨币卖 BTC） |
+| 11 | 模拟 vs 实盘 | 同一套 orders/monitor；仅 Key 与 live 开关不同 |
+| 12 | 子账户 | 三模式三 Key；无交叉下单 |
+
+快速审计脚本：
+
+```bash
+python scripts/audit_hedge_po_mode.py
+```
+
+---
+
+## 7. 实盘上线顺序建议
+
+1. 模拟实例 `HEDGE_PO_MODE=eth` 走通开平与组合 U 出场  
+2. 同模式换实盘子账户 Key，`LIVE_TRADING_ENABLED=true` + `HEDGE_PLAN_LIVE_ORDER=true`  
+3. 再开 `btc` / `btc_eth` 独立实例灰度  
+
+---
+
+## 8. 相关文档
+
+- [对冲计划-以期权为主.md](./对冲计划-以期权为主.md)  
+- [对冲计划策略与P0校验.md](./对冲计划策略与P0校验.md)  
+- [对冲计划开发方案.md](./对冲计划开发方案.md)