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

系统分析：期权主链条

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

---

0. 总览

0.1 三条控制面

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

0.2 资金主链（商业真源）

USDT(交易户)
  │ 开仓前快照 trading_usdt_before
  ▼
买 ETH/BTC（现货桥）
  ▼
买期权（IOC @ 卖一）
  ▼
持仓中（禁划转；浮盈跟盘）
  ▼
卖期权（买一 / 深度）
  ▼
卖回残留币 → 快照 trading_usdt_after
  ▼
realized_pnl_usdt = after − before，pnl_settled=1（冻结，永不改）
  ▼
复盘 / 统计只读冻结值

0.3 启动装配

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 流程

请求 {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 流程

卖期权（买一或深度，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 数据流

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 思路）：

Σ 冻结已实现 + 当前浮盈  ≈  面板合计盈亏
Σ 冻结已实现 + 区间净划转  ≈  钱包 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 生命周期

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. 对账前提：一次一仓 + 持仓禁划转 + 卖回后冻结；破坏任一前提，钱包差分将无法与单笔盈亏对齐。