docs补齐期权主链条系统分析，并重写详细使用说明。

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

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

@@ -0,0 +1,401 @@
+# 系统分析：期权主链条
+
+> 范围：币本位期权（`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
+  ▼
+买 ETH/BTC（现货桥）
+  ▼
+买期权（IOC @ 卖一）
+  ▼
+持仓中（禁划转；浮盈跟盘）
+  ▼
+卖期权（买一 / 深度）
+  ▼
+卖回残留币 → 快照 trading_usdt_after
+  ▼
+realized_pnl_usdt = after − before，pnl_settled=1（冻结，永不改）
+  ▼
+复盘 / 统计只读冻结值
+```
+
+### 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. **对账前提**：一次一仓 + 持仓禁划转 + 卖回后冻结；破坏任一前提，钱包差分将无法与单笔盈亏对齐。

使用说明.md

@@ -1,187 +1,590 @@
-# 使用说明
+# 使用说明（详细版）
 
 **仓库:** [https://git.bz121.com/dekun/crypto_okx.git](https://git.bz121.com/dekun/crypto_okx.git)
 
-基于 Flask 的 **OKX 期权 / 对冲** Web 控制台.与中控、其它交易所实例无关.
+本实例是基于 Flask 的 **OKX 币本位期权** Web 控制台，可独立使用，也可挂到中控（`crypto_okx_hub`）做远程盯盘、条件单与远程平仓。
 
-**部署 / PM2 / SOCKS** 见 **[部署文档.md](./部署文档.md)**；**新机纯实盘**见 **[新机纯实盘部署.md](./新机纯实盘部署.md)**:
+| 文档 | 用途 |
+|------|------|
+| 本文 | 操作员完整用法：交易所前置 → env → 系统设置 → 开平仓 → 复盘/统计 → 中控 |
+| [部署文档.md](./部署文档.md) | 部署 / PM2 / SOCKS |
+| [docs/实盘说明.md](./docs/实盘说明.md) | 实盘 API、账户模式（站内「实盘说明」同源） |
+| [docs/规格-期权交易账户盈亏结算.md](./docs/规格-期权交易账户盈亏结算.md) | 盈亏真源与冻结规则 |
+| [docs/系统分析-期权主链条.md](./docs/系统分析-期权主链条.md) | 代码主链与模块对照 |
+
+一键部署（详见部署文档）：
 
 ```bash
 curl -fsSL https://git.bz121.com/dekun/crypto_okx/raw/branch/main/deploy/manage.sh | bash
 ```
 
-默认访问: `http://<服务器IP>:5004` → 首页跳转 **期权** `/options`.
+默认访问：`http://<服务器IP>:5004` → 首页进入 **期权** `/options`。
 
 ---
 
-## 1. 能做什么
+## 目录
 
-| 模块 | 路由 | 说明 |
-|------|------|------|
-| **期权** | `/options` | 看期权链、开平仓、持仓监控(翻倍出场等) |
-| **期权复盘** | `/options/review` | 期权成交记录 → 复盘表单 → 复盘列表与统计 |
-| **对冲计划** | `/hedge-plan` | 永期对冲或期期对冲:测算、启动、进行中/历史/统计 |
-| **模拟资金** | 系统设置 → 模拟资金 | 本地钱包撮合,吃公开买卖一,**不下真实交易所单** |
-| **env 配置** | `/env_config` | 浏览器改 `.env`(API、交易模式、预算等) |
-| **系统设置** | `/settings` | 导航显示、模拟/实盘、密码、划转、导出等 |
-
-顶栏还可按需显示:关键位监控(提醒)、数据看板、账户流水、风控说明等(在 **系统设置 → 导航显示** 开关).
-
-**已移除:** 策略交易、关键位自动下单、永续实盘下单页、永续交易记录/复盘、AI 复盘、中控对接.
+1. [系统能做什么](#1-系统能做什么)
+2. [系统前：交易所准备](#2-系统前交易所准备)
+3. [登录与顶栏读数](#3-登录与顶栏读数)
+4. [模拟资金 vs 实盘](#4-模拟资金-vs-实盘)
+5. [env 配置（详细）](#5-env-配置详细)
+6. [系统设置（详细）](#6-系统设置详细)
+7. [期权页：开仓 / 平仓 / 持仓](#7-期权页开仓--平仓--持仓)
+8. [盈亏、对账与划转规则](#8-盈亏对账与划转规则)
+9. [期权复盘与数据统计](#9-期权复盘与数据统计)
+10. [中控使用（详细）](#10-中控使用详细)
+11. [推荐上手路径](#11-推荐上手路径)
+12. [常见问题与报错](#12-常见问题与报错)
+13. [风险说明](#13-风险说明)
 
 ---
 
-## 2. 登录与顶栏
+## 1. 系统能做什么
 
-1. 打开站点 → 登录(`APP_USERNAME` / `APP_PASSWORD`,见 `.env`).
-2. 顶栏标题区显示交易所名;若为模拟模式会标 **模拟**.
-3. 资金条含:总资金、资金/交易账户(USDT)、期权资金/交易账户(USDC)、实时盈亏等(模拟/实盘数据源不同).
+### 1.1 功能一览
+
+| 模块 | 路由 / 入口 | 说明 |
+|------|-------------|------|
+| **期权** | `/options` | 期权链、买币并开仓、持仓、目标位、翻倍出场、买一平仓、卖回、面板统计 |
+| **期权复盘** | `/options/review` | 本地成交同步 → 复盘笔记/配图 → 复盘统计 |
+| **env 配置** | `/env_config` | 浏览器改 `.env`（API、预算、门控、中控 Token 等） |
+| **系统设置** | `/settings` | 导航显示、模拟/实盘、密码、期权划转、导出、备份 |
+| **实盘说明** | 顶栏「实盘说明」 | 渲染 `docs/实盘说明.md` |
+| **中控 Bridge** | `/api/hub/*` | 供中控拉快照/统计、远程全平、条件单、远程更新 |
+| **关键位监控等** | 顶栏可开关 | 提醒类；在系统设置 → 导航显示中开关 |
+
+当前主路径为 **币本位期权**（USDT 买 ETH/BTC → 用币付权利金开期权）。USDC 期权开仓路径已下线。交易模式固定为 **单独期权**（`OKX_TRADE_MODE=options`）。
+
+### 1.2 三条控制面（心里要有数）
+
+| 控制面 | 谁在用 | 做什么 |
+|--------|--------|--------|
+| 本机面板 | 你在浏览器里点 | 开平仓、划转、看链、复盘 |
+| 后台监控线程 | 实例进程常驻 | 目标位平仓、翻倍出场、条件单触发、持仓同步、卖回扫尾 |
+| 中控 Hub | 中控站 | 多实例盯盘、下条件单、远程全平、远程更新 |
+
+**进程必须在跑**，目标位 / 翻倍 / 条件单才会自动执行。
 
 ---
 
-## 3. 交易模式(必读)
+## 2. 系统前：交易所准备
 
-在 **env 配置** 或 `.env` 中设置 **`OKX_TRADE_MODE`**(多数可热更,启用类开关改后建议重启):
+在填本系统任何密钥之前，先在 OKX 把账户与 API 准备好。币本位开仓会 **先现货买币，再开期权**，缺一不可。
 
-| 值 | 含义 |
+### 2.1 账户模式（必须）
+
+OKX App / 网页 → **交易** → **账户模式**（首次切换需在官方界面手动确认）：
+
+| 账户模式 | 是否可用 | 说明 |
+|----------|----------|------|
+| 仅现货 / 简单模式 | 否 | 无法正常开期权 |
+| **合约模式（现货和合约）** | **推荐** | 现货 `cash`，与程序一致 |
+| 跨币种保证金 | 不推荐 | 现货常需 `cross`，程序按 `cash` 下单会报 `tdMode` |
+| 组合保证金 | 不推荐 | 同上 |
+
+**推荐固定：合约模式 → 再在本系统点「买币并开仓」。**
+
+### 2.2 创建 API Key
+
+1. OKX → **个人中心 → API** → 创建 API Key。  
+2. 权限勾选 **交易（Trade）**。  
+3. 若有细分，务必打开 **现货（Spot）**（买 ETH/BTC 用）。  
+4. 建议开 **IP 白名单** = 本实例服务器出口 IP。  
+5. 保存得到：`API Key` / `Secret Key` / `Passphrase`。  
+
+本系统 **永续与期权共用同一套** `OKX_API_*`，不必再单独配期权 Key。
+
+### 2.3 资金准备
+
+| 账户 | 用途 |
+|------|------|
+| **交易账户 USDT** | 开仓时买 ETH/BTC；盈亏结算看交易户 USDT 差分 |
+| **资金账户** | 充值/提现中转；用「期权划转」拨到交易户 |
+| 标的币 ETH/BTC | 开仓前若交易户里还有**可卖**标的币，系统会拒开（须先卖回），避免污染单笔对账 |
+
+实盘建议：平时把要用的 USDT 留在交易户；持仓期间不要划转（系统也会禁止）。
+
+### 2.4 交易所侧自检清单
+
+- [ ] 账户模式 = **合约模式**  
+- [ ] API 有 **交易 + 现货**，IP 白名单正确  
+- [ ] 交易账户有足够 **USDT**  
+- [ ] 清楚：开仓 = 买币 + 买期权；平仓 = 卖期权 + 卖回币  
+
+---
+
+## 3. 登录与顶栏读数
+
+1. 打开站点 → 登录（`APP_USERNAME` / `APP_PASSWORD`，在 `.env` 或首次部署配置）。  
+2. 顶栏账户标签示例：`okx_sim`（模拟）/ `okx_live`（实盘）。  
+3. 资金条主要看：  
+   - **总资金 / 资金账户 / 交易账户（USDT）**：钱包余额（交易所或模拟钱包）  
+   - **合计盈亏 / 窗口统计**：盈亏账本（已冻结历史 + 持仓浮盈），**不是**钱包余额本身  
+
+双账不要混：
+
+| 看见什么 | 含义 |
+|----------|------|
+| 顶栏钱包余额 | 账户里有多少 USDT，会随划转变 |
+| 合计 / 复盘 / 统计盈亏 | 单笔冻结盈亏之和（+ 浮盈）；已冻结单不因划转改写 |
+
+---
+
+## 4. 模拟资金 vs 实盘
+
+### 4.1 在哪里切换
+
+**系统设置 → 模拟资金**：
+
+| 操作 | 效果 |
+|------|------|
+| 切换到模拟资金 | 本地 SQLite 钱包；吃 OKX **公开买卖一**撮合，**不向交易所发真实单** |
+| 切换到实盘 | 走真实 API（须密钥正确且 `LIVE_TRADING_ENABLED=true`） |
+| 重置权益 | 无仓时可重置；强制重置会清仓 |
+| 模拟划转 | 只动模拟钱包 |
+
+启动默认：`SIM_DEFAULT_MODE=sim` 或 `live`（env）。运行中也可在系统设置切换。
+
+### 4.2 实盘还要开的开关
+
+| 项 | 说明 |
 |----|------|
-| `options` | **单独期权**:可单独开期权;隐藏对冲导航 |
-| `perp_options` | **永期对冲**:不可单独开期权;对冲页显示「永期对冲」 |
-| `options_options` | **期期对冲**:不可单独开期权;对冲页显示「期期对冲」 |
+| `LIVE_TRADING_ENABLED=true` | 允许向交易所发单；关则多走本地/拒真下单 |
+| 系统设置切到实盘 / `SIM_DEFAULT_MODE=live` | 顶栏变为 `okx_live`，余额读交易所 |
+| API 三项已填 | Key / Secret / Passphrase |
 
-对冲模式下期权页仍可查看/平仓已有仓,但不能单独新开期权.
-
-对冲与单独期权默认可互斥(`HEDGE_PLAN_OPTIONS_MUTUAL_EXCLUSIVE=true`):有对冲计划时不可单独开期权,有单独期权时不可启动对冲.
+实盘后：顶栏只显示交易所真实余额；模拟钱包数字不会带过去。
 
 ---
 
-## 4. 期权页(`/options`)
+## 5. env 配置（详细）
 
-### 4.1 前置
+入口：**顶栏 → env 配置**（`/env_config`），或直接改服务器 `.env` 后按提示重启。  
+页面按分组展示中文标签；**未写入 `.env` 的项以页面「生效默认」为准**（可能与旧版 `.env.example` 不一致，以页面为准）。
 
-- `OKX_OPTIONS_ENABLED=true`(默认 true)
-- 已配置 `OKX_API_KEY` / `OKX_API_SECRET` / `OKX_API_PASSPHRASE`(永续与期权共用)
-- 实盘真下单需 `LIVE_TRADING_ENABLED=true`;否则多为本地流程/模拟(见第 7 节)
-- 期权账户为 **USDC**;永续腿为 **USDT**,资金不互通
+敏感项保存后勿提交 Git；`git pull` 不会覆盖本地 `.env`。
 
-### 4.2 开仓流程
+### 5.1 交易所与实盘
 
-1. 选标的 **ETH / BTC**、到期日.
-2. **列表** 或 **T 型** 看链;可筛看涨/看跌、实值/虚值;勾选「展开全部」看全部行权价.
-3. 环境「链上仅显示有卖一」开启时,无真实卖一或深度不足 1 张的合约会隐藏.
-4. 点某行 **买入** → 下单面板确认张数、权利金、到期平衡等.
-5. 张数:「按可用余额打满」受单笔预算 `OKX_OPTIONS_TRADE_BUDGET_USDC` × 缓冲 `OKX_OPTIONS_BUDGET_BUFFER` 限制;「全仓复利」用交易户全部可用(可设全仓上限),且通常仅允许同时 1 笔持仓.
-6. 可勾选 **翻倍出场**(盈利达权利金倍数后限价平).
+| 变量 | 中文 | 说明 | 建议 |
+|------|------|------|------|
+| `LIVE_TRADING_ENABLED` | 开启实盘下单 | 关闭时不向交易所发真实单 | 模拟熟悉后再开 |
+| `OKX_API_KEY` | API Key | 账户 API（期权共用） | 必填（拉链/实盘） |
+| `OKX_API_SECRET` | API Secret | 同上 | 必填 |
+| `OKX_API_PASSPHRASE` | API Passphrase | OKX 必填 | 必填 |
+| `OKX_ACCOUNT_LABEL` | 账户备注 | 企业微信推送里显示 | 如 `主账户` |
+| `OKX_SHOW_PERP_FUNDS` | 显示 USDT 资金/交易账户 | 默认关；币本位开仓仍会用到交易户可用额展示 | 一般保持默认 |
 
-### 4.3 持仓与平仓
+代理（若服务器访问 OKX 受限，写在 `.env`，不一定都在 UI 白名单里）：
 
-- 右侧/下方持仓卡可改翻倍倍数或关闭、执行平仓.
-- 平仓默认买一限价;是否允许市价平见 `OKX_OPTIONS_ALLOW_MARKET_CLOSE`.
-- 页面内「开仓规则说明」与 `/options/guide` 有更细规则.
+```env
+OKX_SOCKS_PROXY=socks5h://127.0.0.1:1080
+```
+
+### 5.2 企业微信（可选）
+
+| 变量 | 中文 | 说明 |
+|------|------|------|
+| `WECHAT_WEBHOOK` | 机器人 Webhook | 开平仓/风控等推送 |
+| `WECHAT_TIMEOUT_SECONDS` | 推送超时(秒) | 默认 10 |
+
+### 5.3 中控对接
+
+| 变量 | 中文 | 说明 |
+|------|------|------|
+| `HUB_BRIDGE_TOKEN` | 中控 Bridge Token | **首次打开 env 页会自动生成**；复制到中控「添加实例」 |
+| `HUB_EMBED_FRAME_ANCESTORS` | 允许嵌入的中控 Origin | 一般留空；中控 iframe 打不开时再填中控地址（空格分隔），调试可用 `*` |
+
+详见 [第 10 章](#10-中控使用详细)。
+
+### 5.4 期权账户（币本位核心）
+
+保证金模式固定为 **币本位（coin）**，无需再配 USDC 期权预算。
+
+| 变量 | 中文 | 默认（生效） | 说明 |
+|------|------|--------------|------|
+| `OKX_OPTIONS_ENABLED` | 启用期权模块 | true | 与上方 API 同源 |
+| `OKX_OPTIONS_ACCOUNT_LABEL` | 期权账户备注 | — | 推送区分 |
+| `OKX_OPTIONS_BUDGET_BUFFER` | 预算缓冲比例 | **1** | 复利/固定预算共用；预算×缓冲后再估张数 |
+| `OKX_OPTIONS_COIN_COMPOUND` | 按交易户 USDT 复利 | **true** | true：预算≈交易户 USDT×缓冲；false：用固定预算 |
+| `OKX_OPTIONS_COIN_BUDGET_USDT` | 固定预算(USDT) | 如 10 | **仅复利关闭时生效** |
+| `OKX_OPTIONS_COIN_MAX_USDT_ENABLED` | 单笔上限开关 | false | false=靠人工划走控规模 |
+| `OKX_OPTIONS_COIN_MAX_USDT` | 单笔上限(USDT) | 如 50 | 仅上限开关开启时生效 |
+| `OKX_OPTIONS_COIN_SPOT_BUY_BUFFER` | 现货买入缓冲 | **1.05** | 按最大可开张数×卖一权利金×缓冲买币，不全额兑完 |
+| `OKX_OPTIONS_MAX_ACTIVE_POSITIONS` | 期权持仓上限(笔) | **1** | **1=一次一仓**（对账规格前提）；0=不限制 |
+| `OKX_OPTIONS_DEFAULT_UNDERLY` | 默认标的 | ETH | ETH / BTC |
+| `OKX_OPTIONS_CHAIN_MAX_DTE_DAYS` | 期权链展示天数 | 14 | 到期日下拉范围 |
+| `OKX_OPTIONS_MAX_DTE_DAYS` | 开仓最大剩余天数 | 2 | 开仓拒绝更远到期（与链展示独立） |
+| `OKX_OPTIONS_CHAIN_ASK_LIQ_FILTER_ENABLED` | 链上仅显示有卖一 | true | 隐藏无卖一或深度不足 1 张的行 |
+
+#### 目标平仓门控（自动目标位平仓用；手动平仓不强制）
+
+| 变量 | 中文 | 默认 | 说明 |
+|------|------|------|------|
+| `OKX_OPTIONS_CLOSE_GATE_MODE` | 门控模式 | premium | `premium`=可回收≥权利金×倍数；`net_pnl`=净盈亏折 U≥阈值 |
+| `OKX_OPTIONS_CLOSE_RECYCLE_MULT_COIN` | 门控权利金倍数 | 1.05 | 仅 premium |
+| `OKX_OPTIONS_CLOSE_NET_PNL_MIN_USDT` | 门控净盈亏下限(U) | 0 | 仅 net_pnl |
+| `OKX_OPTIONS_CLOSE_HOLD_SECONDS` | 门控持续秒数 | **20** | 条件达标后需持续满足的秒数 |
+
+### 5.5 登录与其它（常在 `.env`）
+
+| 变量 | 说明 |
+|------|------|
+| `APP_USERNAME` / `APP_PASSWORD` | 站点登录 |
+| `FLASK_SECRET_KEY` | Session 密钥，务必改掉默认值 |
+| `SIM_DEFAULT_MODE` | `sim` / `live` 启动默认 |
+| `OKX_TRADE_MODE` | 当前为 `options`（单独期权） |
+
+保存后：按页面提示 **保存并重启**（或 PM2 重启），再硬刷新浏览器。
+
+### 5.6 预算怎么理解（举例）
+
+假设交易户 **100 USDT**，复利开、缓冲 1、现货缓冲 1.05、默认「按可用余额打满」：
+
+1. 可用预算 ≈ 100 × 1 = 100 USDT（若开了单笔上限则再封顶）。  
+2. 按卖一权利金估算最多可开张数。  
+3. 买币金额 ≈ 张数对应权利金 × **1.05**（多买一点防滑点，不是把 100U 全换成币）。  
+4. 用买到的币支付权利金开期权；多余币开仓后可能卖回一部分。
+
+复利关闭时：把 `OKX_OPTIONS_COIN_BUDGET_USDT` 设成你想每笔用的固定 USDT。
 
 ---
 
-## 5. 期权复盘(`/options/review`)
+## 6. 系统设置（详细）
 
-1. **交易记录**:筛选期权成交/平仓记录.
-2. **复盘表单**:选中一笔填写复盘内容并保存.
-3. **复盘记录 / 统计**:查看已复盘条目与汇总.
+入口：`/settings`。各页签如下。
 
-该页只覆盖期权侧,不含已移除的永续交易日记账.
+### 6.1 导航显示
+
+控制顶栏入口与设置内子块是否显示（存在本机偏好，即时生效）。常见项：
+
+- 期权、期权复盘、数据统计、风控说明、实盘说明、env 配置  
+- 关键位监控、看板、流水等（按需开）  
+
+### 6.2 模拟资金
+
+见 [第 4 章](#4-模拟资金-vs-实盘)。实盘前请先在此确认当前是模拟还是实盘。
+
+### 6.3 账户密码
+
+修改登录密码（若导航里打开了该页签）。
+
+### 6.4 数据导出
+
+导出关键位当前/历史等 CSV（与期权成交主账无关时也可作备份辅助）。
+
+### 6.5 备份恢复
+
+本机备份/恢复实例数据。中控也可拉备份列表与下载（含 `.env`，注意保密）。
+
+### 6.6 期权划转
+
+币本位下在 **资金账户 ↔ 交易账户** 之间划转：
+
+| 币种 | 常见用途 |
+|------|----------|
+| USDT | 给交易户加开仓子弹 / 把利润转回资金户 |
+| ETH / BTC | 异常残留时人工处理（正常应走自动卖回） |
+
+规则：
+
+- **有期权持仓，或平仓后待卖回** → 划转按钮灰色，API 也会拒绝。  
+- 无持仓、无待卖回 → 可划转；划转后顶栏余额刷新。  
+- 划转只影响**下一笔**开仓前的 `trading_usdt_before`，**不会改写**已冻结历史盈亏。
+
+USDC 兑换类入口已下线。
 
 ---
 
-## 6. 对冲计划(`/hedge-plan`)
+## 7. 期权页：开仓 / 平仓 / 持仓
 
-需将 `OKX_TRADE_MODE` 设为 `perp_options` 或 `options_options`.
+路由：`/options`。
 
-### 6.1 页签
+### 7.1 界面结构
 
-| Tab | 说明 |
-|-----|------|
-| 永期对冲 | 期权腿 + 永续腿(仅 `perp_options`) |
-| 期期对冲 | 双期权腿(仅 `options_options`) |
-| 进行中的计划 | 盯盘 / 开仓中 / 半腿 / 持仓中 |
-| 历史记录 | 已结束计划 |
-| 统计分析 | 对冲结果汇总 |
+- **左侧**：标的、到期、列表/T 型链、买入弹窗。  
+- **右侧持仓区页签**：当前持仓 | 当前委托 | 数据统计 | 期权历史。  
+- 若中控有活跃条件单：顶部会出现占用提示，**禁止手动开仓**。  
+- 交易户有可卖残留币时：出现 **重试卖回**。
 
-### 6.2 永期对冲要点
+### 7.2 开仓步骤
 
-- **账户**:永续 → 合约账户(USDT);期权 → 期权账户(USDC).
-- **以期权为主**(`HEDGE_PLAN_OPTION_PRIMARY=true`):填参后「策略启动」进入盯盘,条件达标后自动先开期权再市价永续.
-- **保险模式**(`HEDGE_PLAN_OPTION_PRIMARY=false`):做多配 Put、做空配 Call;现场按开仓价与止盈止损执行,交易所 TP/SL 出场.
-- 组数上限:`MAX_ACTIVE_HEDGE_PLANS`(默认 1).
+1. 选标的 **ETH / BTC**、到期日（受「链展示天数」「开仓最大剩余天数」约束）。  
+2. 列表或 T 型查看；可筛看涨/看跌、实值/虚值；「链上仅显示有卖一」开启时无深度行会隐藏。  
+3. 点某行 **买入** → 下单弹窗：  
+   - 卖一/买一、估张数、估权利金、盈亏平衡等  
+   - **尺寸模式**（默认 **按可用余额打满**）  
+   - 可选：**目标位（指数）**、**翻倍出场**（倍数，默认 1）  
+   - 备注  
+4. 确认 **买币并开仓** → 系统：快照交易户 USDT → 现货买币 → IOC 限价买期权 @ 卖一。  
+5. 成功后可到「当前委托 / 当前持仓」查看；失败买币会尝试回滚。
 
-### 6.3 期期对冲要点
+#### 尺寸模式
 
-- 按预算或张数拆分主/次腿(见 `HEDGE_PLAN_OO_BIAS_*`).
-- 平仓模式(到期平 / 全平等)受 `HEDGE_PLAN_OO_CLOSE_MODE_ENABLED` 控制.
+| 模式 | 含义 | 建议 |
+|------|------|------|
+| **按可用余额打满** | 按预算（复利或固定）×缓冲算张数 | **默认，日常用这个** |
+| 指定张数 | 手动填张数 | 试单、精确张数时用 |
+| 指定币数量 | 按币量反推张数 | 进阶；优先熟悉打满/张数即可 |
+| 全仓复利（UI） | 与「按交易户复利」env 相关的展示分支 | 以 env `OKX_OPTIONS_COIN_COMPOUND` 为准 |
 
-### 6.4 半腿
+### 7.3 开仓会被拒绝的常见原因
 
-一侧成交、另一侧失败时,默认可挂 `partial` 在页面 **手动补开**(`HEDGE_PLAN_MANUAL_COMPLETE_ON_PARTIAL=true`),避免误自动平掉已成腿.
+- 交易户仍有**可卖** ETH/BTC（先点重试卖回或扫尾）  
+- 已有持仓且持仓上限=1  
+- 中控条件单占用中  
+- 无卖一深度 / 深度不足  
+- 到期超过 `OKX_OPTIONS_MAX_DTE_DAYS`  
+- 实盘未开 `LIVE_TRADING_ENABLED` 或 API/账户模式不对  
+- 交易户 USDT 不足买币  
 
-真下单还需 `HEDGE_PLAN_LIVE_ORDER=true` 与 `LIVE_TRADING_ENABLED=true`(以 env 为准).
-
----
-
-## 7. 模拟资金 vs 实盘
-
-**系统设置 → 模拟资金**:
+### 7.4 持仓上可做的事
 
 | 操作 | 说明 |
 |------|------|
-| 切换到模拟资金 | 本地 SQLite 钱包;用 OKX **公开行情** 吃买卖一结算,**不向交易所下真实单** |
-| 切换到实盘 | 走真实 API(须密钥正确且允许实盘) |
-| 重置权益 | 无仓时可重置;强制重置会清仓 |
-| 划转 / USDT↔USDC | 仅作用于模拟钱包 |
+| **买一平仓** | 手动限价全平/按深度可平部分；**不强制**走目标门控 |
+| **目标位** | 设定/取消指数目标；触达后须过门控（倍数+持续秒数）才自动平 |
+| **翻倍出场** | 买一可回收 ≥ 开仓权利金 × (1+倍数) 时自动买一平；可与目标位并行 |
+| **重试卖回** | 期权已平但币没卖完时，把残留 ETH/BTC 卖回 USDT，才能冻结本单盈亏 |
 
-启动默认模式:`SIM_DEFAULT_MODE=sim` 或 `live`.顶栏出现 **模拟** 徽章即表示当前为模拟.
+说明：
+
+- 无单独「止损价」；不设出场则可能拿到期。  
+- 门控本身不会在未设目标时平仓；它是**目标位自动平**的附加条件。  
+- 手动平仓可在流动性允许时直接平。
+
+### 7.5 平仓后发生什么
+
+```text
+卖出期权（买一限价）
+  → 触发卖回残留标的币
+  → 卖回成功：拍交易户 USDT after
+  → 本单已实现 U = after − before，冻结
+  → 复盘/统计读冻结值
+```
+
+卖回失败时本单处于 **待结算**：已实现不进统计；请用 **重试卖回**，或等监控扫尾。
 
 ---
 
-## 8. 系统设置与 env
+## 8. 盈亏、对账与划转规则
 
-### 系统设置(`/settings`)
+完整规格见 [docs/规格-期权交易账户盈亏结算.md](./docs/规格-期权交易账户盈亏结算.md)。操作员只需记住：
 
-- **导航显示**:开关顶栏各入口
-- **模拟资金**:见上节
-- **账户密码**:改登录口令
-- **永续划转 / 期权划转 / 币种兑换**:实盘账户内资金操作(模拟模式有对应模拟划转)
-- **数据导出**:导出相关 CSV
+### 8.1 一句话
 
-### env 配置(`/env_config`)
+**一笔单的已实现盈亏 = 卖回完成后的交易户 USDT − 开仓前（买币前）的交易户 USDT。冻结后永不改。**
 
-常用项:
+### 8.2 生命周期
 
-| 类别 | 变量示例 |
-|------|----------|
-| 登录 | `APP_PASSWORD`,`FLASK_SECRET_KEY` |
-| API | `OKX_API_*`,`OKX_TD_MODE`,`OKX_POS_MODE` |
-| 代理 | `OKX_SOCKS_PROXY=socks5h://127.0.0.1:1080` |
-| 实盘开关 | `LIVE_TRADING_ENABLED` |
-| 模式 | `OKX_TRADE_MODE` |
-| 期权预算 | `OKX_OPTIONS_TRADE_BUDGET_USDC`,`OKX_OPTIONS_COMPOUND_FULL_*` |
-| 对冲 | `HEDGE_PLAN_*`,`MAX_ACTIVE_HEDGE_PLANS` |
-| 企业微信 | `WECHAT_WEBHOOK` |
+```text
+空仓且无残留币
+  → 开仓前拒「有可卖币」；快照 before
+  → 买币 → 开期权（持仓中禁划转）
+  → 平期权 → 卖回币
+  → 快照 after，冻结盈亏
+  → 允许划转；准备下一笔
+```
 
-完整注释见根目录 **`.env.example`**.`.env` 勿提交 Git;`git pull` 不会覆盖本地 `.env`.
+### 8.3 面板数字怎么读
+
+| 数字 | 跟不跟盘 | 说明 |
+|------|----------|------|
+| 持仓浮盈 | 跟盘 | 按买一回收估算 |
+| 合计盈亏 | 部分跟盘 | Σ已冻结 + 当前浮盈 |
+| 复盘/统计已实现 | 冻结后固定 | 只认 settled |
+| 顶栏钱包 | 跟划转 | 与单笔盈亏账分离 |
+
+**一次一仓**（持仓上限默认 1）是钱包差分能和单笔盈亏对齐的前提。不要在持仓中从外部乱划资金。
 
 ---
 
-## 9. 首次上手建议
+## 9. 期权复盘与数据统计
 
-1. 部署并打开站点,登录后到 **系统设置 → 模拟资金**,确认处于 **模拟**.
-2. **env 配置** 填 API(模拟下单可不真下交易所,但拉链/行情通常仍需可达 OKX;本机受限时配 SOCKS).
-3. 设 `OKX_TRADE_MODE=options`,在 **期权** 页熟悉开平仓与持仓卡.
-4. 需要复盘时用 **期权复盘**.
-5. 再按需改成永期/期期对冲,先模拟跑通再切实盘.
-6. 实盘前再开 `LIVE_TRADING_ENABLED` / `HEDGE_PLAN_LIVE_ORDER`,并确认 OKX 权限、持仓模式、IP 白名单.
+### 9.1 复盘 `/options/review`
+
+1. **同步**：把本地已平 `options_trades` 同步进复盘表。  
+2. **交易记录**：筛选、点开一笔。  
+3. **复盘表单**：写笔记、上传多周期图等并保存。  
+4. **复盘记录 / 统计**：看已复盘条目与汇总。  
+
+盈亏列：
+
+- 已冻结 → 显示冻结 USDT；  
+- 有 before 但未卖回结算 → 显示待结算，不会用假数字充数；  
+- 很老的无快照历史单 → 遗留口径，不强制改写。
+
+### 9.2 面板「数据统计」与顶栏窗口
+
+- 窗口常见：今日 / 7 日 / 30 日 / 全部。  
+- **已实现**只统计已冻结单；待卖回不进已实现。  
+- **合计**通常 = 净已实现 + 持仓浮盈。  
+
+中控统计窗口参数与此同源（见下章）。
 
 ---
 
-## 10. 风险与合规
+## 10. 中控使用（详细）
 
-- 期权与永续杠杆风险高,实盘盈亏自负.
-- 勿把 `.env`、API 密钥提交到仓库或发到公网.
-- 请遵守当地法规与 OKX 用户协议;本说明仅描述产品用法,不构成投资建议.
+中控仓库一般为独立项目 **`crypto_okx_hub`**。本实例扮演 **客户端（Bridge）**。
+
+### 10.1 接入步骤
+
+1. 部署并启动本实例，浏览器登录。  
+2. 打开 **env 配置 → 中控对接**。  
+3. 若 `HUB_BRIDGE_TOKEN` 为空，首次打开会 **自动生成** 并写入 `.env`。  
+4. 点复制，到中控 **添加实例**：填写  
+   - 实例访问地址（如 `http://IP:5004`）  
+   - Bridge Token（与上面一致）  
+5. 中控探测 `GET /api/hub/version`：应显示在线与版本。  
+6. 若中控用 iframe 嵌入本机页面打不开：再填 `HUB_EMBED_FRAME_ANCESTORS` 为中控 Origin。  
+7. 嵌入登录走 `/hub_sso`（中控签发短时 token）。  
+
+Token 校验：请求头 `X-Hub-Token` 或 `Authorization: Bearer <token>` 必须与实例一致；否则一律「未授权」。
+
+### 10.2 中控上能做什么
+
+| 能力 | 说明 |
+|------|------|
+| **快照** | 资金、权利金占用、持仓摘要、流动性/残档、条件单占用、行情 |
+| **统计** | 窗口已实现 + 浮盈等 KPI（`today` / `7d` / `30d` / `all`） |
+| **远程全平** | 指定 `inst_id`，**仅买一限价全平**（不支持市价、不支持指定张数） |
+| **条件单** | 创建 / 列表 / 取消（未开仓前）/ 开仓后改出场 |
+| **远程更新** | `git pull` + 进程重启（依赖 `/api/hub/update`） |
+| **备份下载** | 列表与下载（含敏感 `.env`，权限要收紧） |
+
+### 10.3 条件单（中控主打自动化）
+
+#### 创建时常见字段
+
+| 字段 | 含义 | 规则 |
+|------|------|------|
+| `hub_order_id` | 中控侧唯一 ID | 必填；重复提交会去重成功 |
+| `underlying` | 标的 | 如 ETH |
+| `opt_type` | `P` / `C` | 必填 |
+| `trigger_px` | 触发指数价 | > 0 |
+| `deviation_pct` | 触发带百分比 | 带 = 触发价 × (1±pct/100) |
+| `min_expiry_hours` | 选合约最短剩余小时 | > 0 |
+| `target_index` 和/或 翻倍出场 | 出场 | **至少配置一种** |
+| `profit_exit_mult` | 翻倍倍数 | 默认 1.0 |
+
+方向约定（中控传入的 trigger_side 会被忽略）：**Put 看上穿、Call 看下穿**。
+
+#### 创建前守卫
+
+- 本机已有期权持仓 → 拒  
+- 触及持仓笔数上限 → 拒  
+- 已有活跃条件单 → 拒  
+
+#### 生命周期（操作员可见）
+
+```text
+armed（待命）
+  → triggering（触发开仓中）
+  → open（已持仓，监控出场）
+  → leave_up / leave_down / cancel / timeout / closed 等结束态
+```
+
+- 未触发的 armed 单会在策略时间点（如 **周四 23:00**，按应用时区）自动过期取消。  
+- 活跃期间：本机期权页显示 **中控条件单占用**，**禁止手动开仓**。  
+- 已 `open` 不能「取消单」了事：应改出场或远程/本地平仓。  
+- 开仓成功后走与手动相同的买币开仓链路，盈亏同样卖回后冻结。
+
+#### 触发后选约
+
+在触发带内选取满足最短到期时间的合适实值合约，再执行币本位开仓；随后挂目标位和/或翻倍出场，由监控线程盯盘。
+
+### 10.4 中控远程平仓注意
+
+- 只接受全平；不要指望中控传张数或市价。  
+- 买一无效或严重残档会被拒绝（与本机一致）。  
+- 平完后仍可能要在本机看是否出现 **重试卖回**（卖回失败时）。
+
+### 10.5 中控远程更新
+
+中控「客户端远程更新」依赖：
+
+- `GET /api/hub/version`  
+- `POST /api/hub/update`  
+
+若版本列显示非 JSON / 404：先在该实例服务器手动 `git pull` 并重启一次，再在中控刷新。
+
+### 10.6 中控日常操作建议
+
+1. 本机 env 配好 Token、API、预算、持仓上限=1、门控。  
+2. 中控确认实例在线、快照资金与持仓正常。  
+3. 需要自动化时用条件单；需要手工精细选约时用本机面板（确认无条件单占用）。  
+4. 远程平仓后核对：持仓是否清空、卖回是否完成、统计是否出现冻结盈亏。  
+5. 多实例时每个实例 Token 独立，勿共用。
+
+---
+
+## 11. 推荐上手路径
+
+### A. 全新实例（先模拟）
+
+1. 按 [部署文档.md](./部署文档.md) 部署，打开站点并登录。  
+2. **系统设置 → 模拟资金**：确认 **模拟**。  
+3. **env 配置**：填 API（模拟不下真单，但拉链/行情通常仍要能访问 OKX；必要时配 SOCKS）。  
+4. 期权账户：复利、缓冲 1、现货缓冲 1.05、持仓上限 1、门控秒数 20 —— 与默认对齐即可。  
+5. 在 **期权** 页用「打满」或「1 张」走通：开仓 → 看持仓浮盈 → 手动买一平 → 确认卖回 → 看统计/复盘数字。  
+6. 需要中控时：复制 Bridge Token → 中控添加实例 → 试快照与条件单（仍建议先模拟）。  
+
+### B. 切实盘
+
+1. 完成 [第 2 章](#2-系统前交易所准备) 交易所清单。  
+2. env：`LIVE_TRADING_ENABLED=true`，密钥正确；系统设置切 **实盘**。  
+3. 交易户转入计划使用的 USDT。  
+4. 小预算试一笔完整闭环（含卖回与复盘）。  
+5. 再按需放大固定预算或开启复利；保持一次一仓直到你清楚对账含义。  
+
+### C. 日常交易习惯
+
+1. 开仓前看：无残留币、无条件单锁、交易户 USDT 够。  
+2. 默认打满；设好目标位和/或翻倍。  
+3. 平仓后确认卖回完成再划转资金。  
+4. 当日结束看面板统计 + 复盘是否与交易户变动大致可对上。  
+
+---
+
+## 12. 常见问题与报错
+
+| 现象 | 常见原因 | 处理 |
+|------|----------|------|
+| `50123` 无 Crypto 交易权限 | API 无现货/交易权限 | 编辑 Key，勾选交易+现货 |
+| `51010` 当前账户模式不能完成请求 | 非合约模式等 | 改为 **合约模式** |
+| Parameter tdMode error | 跨币种/组合下仍用 cash | 改回合约模式 |
+| 开仓提示先卖回 / 有币拒开 | 交易户有可卖 ETH/BTC | 点 **重试卖回** |
+| 划转按钮灰色 | 持仓中或待卖回 | 先平仓并卖回完成 |
+| 下单弹窗总是「指定张数」 | 旧前端缓存或模式被归一错 | 硬刷新；拉新版本（默认应为打满） |
+| 统计有单但已实现为 0/空 | 未卖回、未冻结 | 重试卖回，等 settled |
+| 中控未授权 | Token 不一致或未配置 | 核对 `HUB_BRIDGE_TOKEN` |
+| 中控版本非 JSON/404 | 旧代码无 hub 接口 | 本机 `git pull` 重启后再探测 |
+| 条件单占用无法手动开 | 设计如此 | 取消未触发单，或等持仓结束 |
+| 目标位到了却不平 | 未过门控持续秒数/倍数 | 看门控 env；或手动买一平 |
+
+---
+
+## 13. 风险说明
+
+- 期权杠杆高，实盘盈亏自负。  
+- 勿把 `.env`、API 密钥、中控 Token、备份包发到公网或提交 Git。  
+- 中控备份下载可能含密钥，中控侧权限与传输需同等重视。  
+- 请遵守当地法规与 OKX 用户协议；本说明只描述产品用法，不构成投资建议。  
+
+---
+
+## 附录：相关文档与默认速查
+
+| 项 | 当前常用默认 |
+|----|----------------|
+| 持仓上限 | 1（一次一仓） |
+| 预算缓冲 | 1 |
+| 现货买入缓冲 | 1.05 |
+| 门控持续秒数 | 20 |
+| 门控模式 | premium × 1.05 |
+| 下单尺寸默认 | 按可用余额打满 |
+| 保证金 | 币本位 coin（固定） |
+
+更深的模块与数据流：[docs/系统分析-期权主链条.md](./docs/系统分析-期权主链条.md)。