crypto_okx/docs/系统分析-期权主链条.md

# 系统分析：期权主链条

> 范围：币本位期权（`OKX_OPTIONS_MARGIN_MODE=coin`）  
> 配套规格：[规格-期权交易账户盈亏结算.md](./规格-期权交易账户盈亏结算.md)、[实盘说明.md](./实盘说明.md)  
> 目的：从架构到开仓 / 平仓 / 展示 / 复盘 / 统计 / 对账 / 条件单，说明数据流、关键模块与边界

---

## 0. 总览

### 0.1 三条控制面

| 控制面 | 入口 | 职责 |
|--------|------|------|
| 面板 API | `/options` → `/api/options/*` | 人工开平仓、链/报价、持仓、划转、统计 |
| 监控线程 | `options_monitor_lib`（安装时拉起） | 目标位平仓、止盈平仓、条件单、持仓同步、卖回扫尾 |
| 中控 Hub | `/api/hub/options/*` | 快照、统计、远程平仓、条件单 CRUD |

### 0.2 资金主链（双口径）

```text
USDT(交易户)
  │ 开仓前快照 trading_usdt_before；initial_premium = 开仓指数×权利金币量
  ▼
买 ETH/BTC（现货桥）
  ▼
买期权（IOC @ 卖一）
  ▼
持仓中（禁划转；浮盈跟盘）
  ▼
卖期权（可多次部分平；以全部平完为准）
  ▼
卖光可卖标的币（禁止按开仓权利金封顶）→ 快照 trading_usdt_after
  ▼
口径 A（复盘真盈亏）: 币盈亏×卖回VWAP − 权利金×(买VWAP−卖回VWAP)；卖完再结算
口径 B（期权历史/数据统计）: 仅期权腿币盈亏（×卖回价折 U）；不含现货/权利金U波动修正
```

### 0.3 启动装配

```text
app.py
  → install_options_trading        # options_register
  → install_options_review         # options_review_register
  → register_hub_bridge_routes     # hub_bridge_register
  → 监控守护线程                   # options_monitor_lib
```

核心配置包：`_build_cfg`（交易所、DB、预算、报价/下单回调）。  
UI：`lib/options/templates/options_panel.html` + `lib/common/static/options_panel.js`。

### 0.4 关键表（SQLite）

| 表 | 用途 |
|----|------|
| `options_trades` | 本地开平流水；含 `trading_usdt_before/after`、`realized_pnl_usdt`、`pnl_settled` |
| `options_spot_bridge` | 买币/卖回桥状态 |
| `options_target_monitors` | 目标位监控 |
| `options_cond_orders` | 条件单 |
| `options_exchange_pnl_freeze` | 实盘历史盈亏冻结辅助 |
| `options_review_*` | 复盘成交 / 笔记 / 隐藏 / 图 |
| `options_transfer_log` 等 | 划转等资金侧日志 |

---

## 1. 主链条（架构）

### 1.1 模块分层

| 层 | 代表文件 | 说明 |
|----|----------|------|
| 路由装配 | `lib/options/options_register.py` | HTTP、尺寸归一、同步持仓 |
| 开仓编排 | `options_coin_open_lib.py` | 预算→买币→开期权→写库 |
| 平仓执行 | `options_close_exec_lib.py` | 买一/深度卖出 |
| 账户结算 | `options_account_pnl_lib.py` | USDT 快照、卖回后冻结 |
| 公式结算 | `options_pnl_settle_lib.py` | 权利金侧辅助结算（有账户快照时 U 以账户为准） |
| 交易所 | `lib/exchange/okx_options_lib.py` | 链、报价、下单、持仓 |
| 模式/预算 | `options_margin_mode_lib.py` | 币本位、预算、张数规划 |
| 展示 enrichment | `options_positions_lib.py` / `options_history_lib.py` | 浮盈、平仓预览 |
| Env UI | `lib/env/env_ui_manifest.py` | 期权相关默认与文案 |

### 1.2 运行模式

- `OKX_TRADE_MODE=options`：主站偏期权。
- `OKX_OPTIONS_ENABLED`：模块开关。
- 模拟 / 实盘由顶栏 `trading.mode` + `LIVE_TRADING_ENABLED` 等控制；实盘要求现货+期权权限（见实盘说明）。

### 1.3 与盈亏规格的关系

规格文档定义**产品规则**；本分析描述**代码落点**。  
凡「已实现盈亏」对外展示（复盘 / 统计 / 顶栏已实现），在新规则下均以 `pnl_settled=1` 的账户差分为准；旧单无快照字段时走遗留口径，互不回写。

---

## 2. 开仓

### 2.1 入口

| 来源 | 路径 / 调用 |
|------|-------------|
| 面板 | `POST /api/options/open` |
| 条件单触发 | `options_cond_order_lib` → 同一套 `open_coin_option_buy_full` |

前端默认尺寸模式：**按可用余额打满**（`budget_full`）；复利开时 UI 切 `compound_full`。  
后端 `_normalize_size_mode`：币本位保留 `budget_full` / `compound_full`；USDC 遗留路径才落到 `sheets`。

### 2.2 尺寸模式

| mode | 含义 |
|------|------|
| `budget_full` | min(可用 USDT, 单笔预算) × 预算缓冲 → 张数（默认） |
| `compound_full` | 交易户可用 × 缓冲（受全仓上限 env 约束） |
| `sheets` | 指定张数 |
| `eth` / `eth_amount` | 指定币数量反推张数 |

预算计算：`compute_coin_budget_usdt` / `plan_coin_open_by_budget`（`options_margin_mode_lib.py`）。

### 2.3 流程

```text
请求 {inst_id, mode, sheets?, eth?, target_index?, profit_exit_*}
  → 交易模式门禁 / 条件单占用锁 / 持仓笔数上限
  → 有可卖标的币 → 拒开（须先卖回）
  → coin_budget_preview → 规划张数与买币量
  → fetch_trading_usdt → 写入 trading_usdt_before
  → 现货市价买币（× SPOT_BUY_BUFFER）→ options_spot_bridge=bought
  → 期权限价 IOC @ 卖一 → 等待成交
       失败 → 回滚卖币
       成功 → bridge=holding，_insert_coin_trade(open, pnl_settled=0)
  → 可选：目标位 / 止盈倍数 / 微信通知
```

### 2.4 关键 env

| 变量 | 默认（代码/清单） | 作用 |
|------|-------------------|------|
| `OKX_OPTIONS_COIN_COMPOUND` | true | 是否按交易户复利 |
| `OKX_OPTIONS_COIN_BUDGET_USDT` | （单笔预算） | 打满时的封顶 |
| `OKX_OPTIONS_BUDGET_BUFFER` | 1 | 预算缓冲 |
| `OKX_OPTIONS_COIN_SPOT_BUY_BUFFER` | 1.05 | 现货多买缓冲 |
| `OKX_OPTIONS_MAX_ACTIVE_POSITIONS` | 1 | 同时持仓笔数；0=不限 |
| `OKX_OPTIONS_OPEN_FILL_TIMEOUT_SEC` | — | 开仓等待成交超时 |

### 2.5 边界

- 开仓**只快照 before**，不结算盈亏。
- 持仓或桥未完成期间：`transfer_blocked_by_position_msg` 禁止划转。
- 一次一仓是对账规格前提；上限默认 1。

---

## 3. 平仓

### 3.1 三条平仓通道

| 通道 | 触发 | 门控 | 执行 |
|------|------|------|------|
| 手动 / Hub | 用户或中控 | 一般只校验流动性 | `close_option_by_bid1(require_recycle_gate=False)` |
| 目标位 | 指数触达目标 | 回收门控（权利金倍数 / 净盈亏 + 持续秒数） | `close_option_by_bid_depth` |
| 止盈倍数 | 买一回收 ≥ 权利金×(1+mult) | 自有回收条件，不走 close_gate | `close_option_by_bid_profit_exit` |

监控循环：`run_options_target_closes` / `run_options_profit_exits`。

### 3.2 流程

```text
卖期权（买一或深度，reduce-only）
  → 部分成交：累计平仓张数
  → 全平：
       settle_closed_pnl（币侧/费用；有账户快照时 U 不以公式定稿）
       → maybe_sell_spot_after_close / sell_residual
       → try_settle_after_sellback
            after − before → realized_pnl_usdt，pnl_settled=1
```

卖回失败：本单「待结算」，已实现不进统计；可 `POST /api/options/spot-bridge/retry-sell` 或监控扫尾。

### 3.3 回收门控 env

| 变量 | 默认 | 作用 |
|------|------|------|
| `OKX_OPTIONS_CLOSE_GATE_MODE` | premium | `premium` / `net_pnl` |
| `OKX_OPTIONS_CLOSE_RECYCLE_MULT_COIN` | 1.05 | 币本位回收倍数 |
| `OKX_OPTIONS_CLOSE_HOLD_SECONDS` | 20 | 条件持续秒数 |
| `OKX_OPTIONS_CLOSE_NET_PNL_MIN_USDT` | 0 | net_pnl 模式下限 |

### 3.4 边界

- 手动平仓可绕过回收门控；自动目标位不可。
- 冻结后任何划转、指数、复盘同步**不得改写** `realized_pnl_usdt`。

---

## 4. 期权显示

### 4.1 页面与 API

| UI | API | 数据源 |
|----|-----|--------|
| 期权链 / 到期 / 虚实度过滤 | `GET /api/options/chain` | `build_option_chain` |
| 下单弹窗报价与估张 | `GET /api/options/quote` | `quote_option_contract` + 币本位规划 |
| 持仓卡片 | `GET /api/options/positions` | 交易所持仓 + 本地 trade enrichment |
| 余额 / 顶栏 | `GET /api/options/balances` + header pack | 交易户 / 资金户 |
| 挂单 / 目标位 | `.../orders/pending`、`.../targets` | 本地 + 交易所 |
| 中控快照 | `GET /api/hub/options/snapshot` | `build_options_hub_snapshot` |

前端主文件：`options_panel.js`、`options_position_cards.js`、`options_expiry_countdown.js`。

### 4.2 展示口径（勿与冻结混淆）

| 指标 | 口径 |
|------|------|
| 持仓浮盈 | 买一回收估算（`display_pnl_*`），跟盘变 |
| 合计盈亏 | Σ已冻结 + 当前浮盈 |
| 顶栏钱包 | 交易所余额，不是盈亏账本 |
| 下单估权利金 / 杠杆 / 打满提示 | 报价瞬间估算，非成交结果 |

### 4.3 链过滤 env

`OKX_OPTIONS_CHAIN_MAX_DTE_DAYS`、`OKX_OPTIONS_CHAIN_ASK_LIQ_FILTER_ENABLED`、`OKX_OPTIONS_ITM_MAX_DIST_USD`、`OKX_OPTIONS_DEFAULT_UNDERLY`。

---

## 5. 复盘

### 5.1 入口

- 页：`/options/review`
- 注册：`options_review_register.py`
- 逻辑：`options_review_lib.py` + `options_review_db.py`
- 前端：`options_review_panel.html`、`options_review.js`

### 5.2 数据流

```text
options_trades（已平）
  → sync_options_from_local_trades / ensure_local_review_synced
  → options_review_trades（history_key ≈ local_opt:{id}）
  → 笔记 options_review_entries + 上传图 / 异步图表
  → 隐藏 options_review_hidden
```

主要 API：`POST /api/options/review/sync`，`GET/DELETE .../trades`，`POST .../entry`，`POST .../upload_slot`，`GET .../stats`。

### 5.3 盈亏读取规则

| 本地单状态 | 复盘展示 |
|------------|----------|
| 有 `trading_usdt_before` 且未 `pnl_settled` | 已实现 U 待结算（不展示假冻结） |
| `pnl_settled=1` | 只读冻结 `realized_pnl_usdt` |
| 无账户快照的历史单 | 遗留口径，不强制改写成账户差分 |

复盘是**消费者**，不负责改写结算真源。

---

## 6. 统计

### 6.1 入口

| 场景 | API / 函数 |
|------|------------|
| 期权面板 KPI | `GET /api/options/stats` → `compute_options_stats_auto` |
| 复盘页统计 | `GET /api/options/review/stats` |
| 顶栏窗口统计 | `header_options_stats_for_window` |
| 中控 | `GET /api/hub/options/stats` |

核心库：`options_stats_lib.py`。

### 6.2 窗口与构成

- 窗口：`today` / `7d` / `30d` / `all`（`normalize_stats_window`）。
- 模拟：本地已平且已结算样本。
- 实盘：交易所历史 + `options_exchange_pnl_freeze` 对齐后同一套 KPI。
- 面板合计：`净已实现（仅 settled） + 持仓浮盈`。

### 6.3 边界

- 待卖回、未冻结单**不计入**已实现。
- 统计不重新推导账户差分；最多做冻结补齐 / 修复类运维函数（如 `freeze_missing_realized_pnl_usdt`），与规格「冻结后不改」一致的运维路径需谨慎使用。

---

## 7. 对账

此处「对账」= **交易账户快照结算 + 本地/交易所持仓对齐**，不是已删除的永续 `reconcile_flat`。

### 7.1 结算真源（账户账）

| 步骤 | 函数 | 结果 |
|------|------|------|
| 开仓前 | `fetch_trading_usdt` | `trading_usdt_before` |
| 卖回后 | `try_settle_after_sellback` / `settle_closed_trades_from_trading_account` | `after`、`realized_pnl_usdt`、`pnl_settled=1` |
| 持仓禁划转 | `transfer_blocked_by_position_msg` | 前端灰 + API 拒 |

公式身份（规格 §6 思路）：

```text
Σ 冻结已实现 + 当前浮盈  ≈  面板合计盈亏
Σ 冻结已实现 + 区间净划转  ≈  钱包 USDT 变动（在一次一仓、无并行污染前提下）
```

### 7.2 持仓对齐（仓位账）

监控 / `_sync_options_trades`：

| 动作 | 含义 |
|------|------|
| `reconcile_live_open_trades` / `sync_open_options_trades` | 交易所仍有仓而本地已关 → 纠偏重开等 |
| `backfill_closed_options_realized_pnl_from_history` | 历史回填；**跳过已冻结 U** |
| `sell_spot_after_options_sync` / `sweep_spot_after_options_flat` | 平仓后残留币扫尾，推动账户结算 |

### 7.3 双账清晰

| 账本 | 看见什么 |
|------|----------|
| 钱包（顶栏） | 交易所余额，随划转变 |
| 盈亏账 | 冻结历史 + 浮盈；划转不改已冻结单 |

---

## 8. 条件单

### 8.1 定位

中控下发「价格带触发 → 自动开仓 → 挂目标/止盈 → 等平仓结束」的自动化；与面板互斥：有活跃条件单时**锁定手动开仓**（`cond_order_blocks_manual_open_msg`）。

### 8.2 入口

| API | 作用 |
|-----|------|
| `GET/POST /api/hub/options/cond_orders` | 列表 / 创建 |
| `POST .../<hub_order_id>/cancel` | 取消 |
| `POST .../exit` | 更新出场参数 |

库：`options_cond_order_lib.py`。  
Tick：监控循环 `run_cond_orders_tick` → `_tick_one`。

### 8.3 生命周期

```text
Hub 创建（trigger_px, deviation_pct, 认购/认沽, 出场）
  → options_cond_orders = armed
  → 指数落入 band_bounds
  → pick_nearest_itm_contract
  → 走 open_coin_option_buy_full（同人工开仓：before 快照、买币、IOC）
  → 挂目标位 / 止盈
  → 等待仓位平坦 → _end_order
  → 周四 23:00 等策略可 expire 未触发单
```

### 8.4 与主链关系

- **不另建盈亏账本**；触发开仓后的卖回冻结与人工单相同。
- 占用期间面板开仓按钮应不可用，避免双开破坏「一次一仓」。

---

## 9. 端到端对照表

| 阶段 | 写库 / 状态 | 用户可见 | 消费方 |
|------|-------------|----------|--------|
| 开仓成功 | trade open + before + bridge holding | 持仓卡、浮盈 | 监控、禁划转 |
| 期权已平、币未卖回 | 待结算 | 提示待卖回 | 统计不含已实现 |
| 卖回成功 | after、realized、settled=1 | 复盘/统计定格 | 对账完成 |
| 条件单 armed | cond_orders | 横幅锁定手动开仓 | 监控 tick |
| 目标位/止盈触发 | 平仓执行 | 持仓消失→卖回→冻结 | 同平仓链 |

---

## 10. 关键文件索引

| 主题 | 路径 |
|------|------|
| 路由 / 开平仓 API | `lib/options/options_register.py` |
| 币本位开仓 | `lib/options/options_coin_open_lib.py` |
| 现货桥 | `lib/options/options_spot_bridge_lib.py` |
| 平仓执行 | `lib/options/options_close_exec_lib.py` |
| 回收门控 | `lib/options/options_close_gate_lib.py` |
| 目标位 | `lib/options/options_target_lib.py` |
| 止盈 | `lib/options/options_profit_exit_lib.py` |
| 账户盈亏 | `lib/options/options_account_pnl_lib.py` |
| 统计 | `lib/options/options_stats_lib.py` |
| 复盘 | `lib/options/options_review_*.py` |
| 条件单 | `lib/options/options_cond_order_lib.py` |
| 监控 | `lib/options/options_monitor_lib.py` |
| Hub 快照 | `lib/options/options_hub_lib.py` |
| Hub 路由 | `lib/hub/hub_bridge_register.py` |
| Schema | `lib/options/options_db.py` |
| 面板 | `lib/options/templates/options_panel.html`、`lib/common/static/options_panel.js` |

---

## 11. 维护时注意

1. **改盈亏口径**：先改规格文档，再改 `options_account_pnl_lib` 与复盘/统计读取，避免三处漂移。  
2. **改开仓默认尺寸**：同时看前端 `currentSizeMode`、HTML `checked`、后端 `_normalize_size_mode`（币本位勿再压成 `sheets`）。  
3. **改门控秒数/缓冲**：代码默认、`env_ui_manifest` 文案与 `_RUNTIME_ENV_DEFAULTS` 一并对齐；已有 `.env` 旧值不会自动覆盖。  
4. **条件单与手动开仓**：任何新开仓入口都要接 `cond_order_blocks_manual_open_msg`（或等价锁）。  
5. **对账前提**：一次一仓 + 持仓禁划转 + 卖回后冻结；破坏任一前提，钱包差分将无法与单笔盈亏对齐。