Initial CoinOX instance: coin-margined options + USDT hedge.

Forked from crypto_monitor OKX instance (copy-only). Keeps standalone options, perp-options and options-options hedge; drops standalone perp entrypoints; forces coin margin; adds sim wallets; default port 5010.

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

docs/OKX单笔期权-币本位与USDT桥-开发方案.md

@@ -0,0 +1,279 @@
+# OKX 单笔期权 · 币本位模式（USDT 桥 + 复利）— 开发方案
+
+> 状态:**已实现首版**(按本文落地;改需求先改本文).  
+> 范围:**`crypto_monitor_okx` 单笔期权开平** + **中控对 OKX 期权只读字段**(能识别币本位);对冲计划(永期/期期)**不接币本位**.  
+> **硬约束:本次不改 Gate**(不改 `crypto_monitor_gate/`、不改 Gate 专用模板/静态/测试;共享 `lib` 若动刀不得改变 Gate 启动与交易行为).  
+> 相关:[期权方案.md](./期权方案.md) · [期权用法.md](./期权用法.md) · [期权开平仓与监控说明.md](./期权开平仓与监控说明.md) · [position-sizing-mode.md](./position-sizing-mode.md) · [更新文档.md](./更新文档.md)
+
+---
+
+## 1. 背景与动机
+
+当前单笔期权仅支持 **USDⓈ 本位**(权利金 **USDC**):人工 USDT→USDC 兑换/划转后,按 `OKX_OPTIONS_TRADE_BUDGET_USDC` 卖一开 / 买一平.
+
+实盘观察:**部分到期与行权附近,币本位期权流动性往往好于 USDC 期权**,更利于「只锁卖一 / 买一」的成交质量.
+
+币本位权利金用 **ETH/BTC** 支付,操作者仍习惯用 **USDT** 思考本金与复利.因此需要一条自动资金桥,并支持交易账户 USDT 滚仓放大.
+
+---
+
+## 2. 目标(首版)
+
+1. **env 切换**单笔期权模式:`usdc`(现状) ↔ `coin`(币本位 + USDT↔ETH/BTC 桥).  
+2. **币本位开仓**:按交易账户 USDT 预算 **先买满现货** → 再用币 **尽量开满** 期权(不按权利金精算买币数量).  
+3. **币本位平仓**:期权卖出成功后,**自动现货市价**把剩余标的币卖回 USDT.  
+4. **USDT 全仓复利**:每轮预算默认 = 交易账户 USDT × 缓冲(0.95);赚留在交易户则下一轮自动变大;减规模靠 **人工转走**.  
+5. **可选单笔上限**:开关默认 **关闭**;开启后 `min(账户×0.95, N U)`.  
+6. **有未平单笔期权或桥流程半成品时,拒绝切换模式**.  
+7. **对冲计划**继续只走 USDC 路径;币本位模式下对冲开仓保持不可用或明确提示未支持.  
+8. **中控不代下期权单**,但监控/快照/持仓卡片等 **只读字段须能识别币本位**(见 §7.5).  
+9. **不涉及 Gate** 任何业务改动.
+
+---
+
+## 3. 不做(首版外)
+
+- 对冲计划(永期/期期)币本位腿或双模式混开  
+- 盘中按单笔切换本位(必须 env + 重启/无仓校验)  
+- 按权利金精确计算后再买现货(明确不做;见 §5)  
+- 自动把资金账户 USDT 划入交易账户(首版只读 **交易账户** 可用 USDT;不足则提示人工划转)  
+- 市价平期权(继续沿用现有「买一限价、禁市价平」纪律,除非另改总则)  
+- 多笔并行单笔期权仓(维持「一次一仓」)  
+- **中控代下 / 中控内嵌开平仓按钮**触发币本位或 USDC 期权下单(开平仍只在 OKX 实例页)  
+- **任何 Gate 相关改动**(含为「顺便统一」去动 Gate 模板或共享路径上的 Gate 分支)
+
+---
+
+## 4. 模式开关与互斥
+
+### 4.1 env(草案)
+
+| 变量 | 含义 | 默认 |
+|------|------|------|
+| `OKX_OPTIONS_MARGIN_MODE` | `usdc` \| `coin` | `coin` |
+| `OKX_OPTIONS_TRADE_BUDGET_USDC` | USDC 模式单笔权利金预算上限(现有) | `10` |
+| `OKX_OPTIONS_BUDGET_BUFFER` | 预算缓冲(现有,币本位复利亦用) | `0.95` |
+| `OKX_OPTIONS_COIN_COMPOUND` | 币本位是否按交易户 USDT 复利 | `true`(建议默认开) |
+| `OKX_OPTIONS_COIN_BUDGET_USDT` | 复利关闭时的固定 USDT 预算;或作展示参考 | `10` |
+| `OKX_OPTIONS_COIN_MAX_USDT_ENABLED` | 单笔不超过 N U 开关 | `false`(**默认关**) |
+| `OKX_OPTIONS_COIN_MAX_USDT` | 上限 N(仅开关开启时生效) | 如 `50`(可改) |
+| `OKX_OPTIONS_COIN_SPOT_BUY_BUFFER` | 现货买入相对权利金倍数(也可写 `0.10`=+10%) | `1.10` |
+
+开仓买币:**先按预算估最大可开张数 → 买币 USDT ≈ 张数×卖一权利金×现货缓冲**,不全额把预算换成币。
+
+说明:
+
+- **主路径(复利开 + 上限关)**:`budget_usdt = trading_usdt_available × OKX_OPTIONS_BUDGET_BUFFER`.  
+- **上限开**:`budget_usdt = min(上式, OKX_OPTIONS_COIN_MAX_USDT)`.  
+- **复利关**:`budget_usdt = OKX_OPTIONS_COIN_BUDGET_USDT × buffer`(或直接固定值,实现时二选一写死一种,避免歧义;推荐 `固定值 × buffer` 与现 USDC 习惯一致).
+
+### 4.2 切换门禁
+
+| 条件 | 行为 |
+|------|------|
+| 本地/交易所存在未平 **单笔期权** 持仓 | **拒绝**切换 `usdc`↔`coin` |
+| 存在未完成桥状态(已买币未开期权、已平期权未卖回 USDT 等) | **拒绝**切换 |
+| 对冲计划运行中 | **不阻断**单笔模式切换,但币本位下对冲仍不可开新币本位腿;UI 标明对冲仅 USDC |
+| 无仓且无半成品 | 允许改 env 并重启后生效 |
+
+启动或保存配置时若检测到「模式与当前持仓族不一致」,应拒绝进入交易或强制只读提示,避免按错误货币计价.
+
+---
+
+## 5. 币本位资金桥与开平流水
+
+### 5.1 开仓(先买满,再开满)
+
+```
+1. 读取交易账户 USDT 可用
+2. 计算 budget_usdt(§4.1)
+3. 现货市价:用约 budget_usdt 买入标的币(ETH 或 BTC,与所选期权一致)
+4. 用账户中可用于权利金的标的币,按卖一限价尽量开满币本位期权
+   - 受:最小张数、卖一深度、单笔一仓规则约束
+   - 不要求「币数量精确等于权利金」;允许开满后仍残留部分币
+5. 本地记录本轮:模式=coin、budget_usdt、买入币数量/成本、期权成交、桥状态=holding
+```
+
+### 5.2 平仓(先平期权,再卖回 USDT)
+
+```
+1. 按现有纪律买一限价卖出期权(可分批深度)
+2. 期权仓清零(或本轮目标完成)后:
+   现货市价卖出账户内「本桥残留 + 平仓回收」相关标的币 → USDT
+3. 桥状态=closed;交易账户 USDT 更新 → 下一轮自动按新余额复利
+```
+
+### 5.3 失败回滚(必须)
+
+| 失败点 | 处理 |
+|--------|------|
+| 现货买入失败 | 不开期权;报错 |
+| 现货买入成功、期权开仓失败/无卖一 | **自动市价卖回 USDT**;桥状态回滚;告警 |
+| 期权平仓成功、现货卖回失败 | 持仓显示/告警 **「待卖回 USDT」**;提供仅重试卖币接口;拒绝新开仓直至清理 |
+| 半成品状态下进程重启 | 启动扫描未完成桥,提示或自动尝试卖回 |
+
+---
+
+## 6. 复利与「人工转走」
+
+### 6.1 口径
+
+- **加仓/放大**:利润留在 **交易账户 USDT**,下一轮 `×0.95` 自动变大(例:10U 一轮后约 20U → 下一轮约 19U 预算).  
+- **缩小**:运营者 **人工** 将 USDT 转出交易账户(划转到资金账户/提现/他用);系统不自动「复位到 10U」.  
+- **单笔上限开关**(`OKX_OPTIONS_COIN_MAX_USDT_ENABLED`):  
+  - **默认关闭** → 纯靠人工转走控规模.  
+  - **开启** → `min(账户×0.95, N)`，防止单笔过大.
+
+### 6.2 与永续「全仓」的关系
+
+思想同类(吃可用 × 缓冲),但资产不同:
+
+- 永续全仓:USDT 保证金 × 杠杆 → 合约名义  
+- 币本位单笔:USDT × 缓冲 → 现货币 → 期权权利金  
+
+**不要**复用 `POSITION_SIZING_MODE=full_margin` 直接驱动期权;用 §4.1 独立开关,避免永续模式与期权桥耦合.
+
+### 6.3 一次一仓
+
+复利放大后必须坚持:**同时仅一个单笔期权仓**.新开前检查无持仓、无「待卖回」半成品.
+
+---
+
+## 7. 产品与 UI
+
+### 7.1 模式可见性
+
+- 顶栏或期权设置页展示当前:`单笔期权模式: USDC / 币本位`.  
+- 币本位时展示:交易户 USDT、本轮预估预算(`×0.95` 与是否触达 N 上限)、桥状态.  
+- USDC 模式保持现有 USDC 余额与预算展示.
+
+### 7.2 开仓按钮文案(示例)
+
+- 币本位:`买币并开仓(预算 ≈ xx USDT)`  
+- 确认框写明:将市价买 ETH/BTC → 限价买期权;失败会尝试卖回 USDT.
+
+### 7.3 对冲
+
+- 币本位模式下:对冲计划入口保持「仅 USDC / 未支持币本位」禁用或只读测算.  
+- 不在此模式自动把对冲预算改成 USDT 桥.
+
+### 7.4 复盘字段(建议)
+
+单笔 round-trip 尽量可拆:
+
+- 期权腿盈亏(币或折合 USDT)  
+- 桥兑换盈亏(买币成本 vs 卖币回收)  
+- 合计 USDT 变化(对复利最有意义)
+
+首版若难拆细,至少记录:**开仓前 USDT、平仓卖币后 USDT、差值**.
+
+### 7.5 中控只读(要做)与不下单(不做)
+
+中控保持现有分工:**监控只读 + 点「期权」进 OKX 实例操作**;本方案**不**在中控增加开平仓/买币桥按钮.
+
+只读侧须能区分并展示币本位,避免仍按「一律 USDC 权利金」误读.实例上报快照/期权字段建议至少包含:
+
+| 字段(名可调) | 含义 |
+|--------------|------|
+| `options_margin_mode` | `usdc` \| `coin` |
+| 持仓行可辨本位 | 合约族/结算币/标签,卡片上能看出「币本位」或「USDC」 |
+| 币本位时预算口径 | 可选:交易户 USDT、本轮 `×0.95` 预估预算、是否触达 N 上限 |
+| 桥状态(若有半成品) | 如 `holding` / `pending_sell_spot`(待卖回 USDT),中控只展示与告警,不代执行 |
+
+展示落点(与现网对齐即可,不新开中控交易页):
+
+- OKX 账户监控里的期权区块 / 期权持仓卡片  
+- 推给教练等用的监控快照文案(若已注入期权行,须带本位标记,避免 AI/人工当成 USDC)
+
+**不做:**中控代下单、中控触发买 ETH/卖 ETH、中控改 env 切模式.
+
+---
+
+## 8. 技术要点
+
+### 8.1 合约与报价
+
+- USDC 模式:继续 `ETH-USD_UM` / `BTC-USD_UM` 等现有路径.  
+- 币本位模式:走 OKX **币本位期权**合约族(实现时以 OKX/ccxt 实际 `instId`/settle 为准,写入适配层,勿与 UM 混用同一计价假设).  
+- 权利金与张数换算按币本位规则单独实现;复用「卖一开、买一平、深度校验」状态机,不复用 USDC 金额公式硬套.
+
+### 8.2 模块建议
+
+| 块 | 职责 |
+|----|------|
+| 模式读取 + 门禁 | env、有仓拒切、启动一致性 |
+| `options_spot_bridge_lib`(名可调) | USDT↔币 市价买卖、回滚、待卖回重试 |
+| 开平编排 | 买满 → 开满 → 平 → 卖回 状态机 |
+| 定价/张数 | 币本位分支 |
+| UI/API | 预算预览、确认、半成品提示 |
+| 中控只读 | 消费实例快照中的 `options_margin_mode` 等字段;卡片/文案可识别币本位;**无下单 API** |
+| Gate | **不纳入**;禁止为本次需求修改 Gate 树 |
+
+现货下单可与现有账户兑换/划转能力并列,但 **桥必须可自动、可回滚**,与「人工 USDT→USDC」不同.
+
+共享 `lib/options*` / 快照序列化若调整:仅扩展 OKX 期权载荷;Binance/Gate 账户快照路径保持原样.
+
+### 8.3 权限与账户
+
+- API 需具备:交易账户现货市价、期权开平.  
+- 预算只认 **交易账户 USDT**;资金账户有钱但交易户不足 → 明确提示先划转(首版不自动划).
+
+### 8.4 测试
+
+- 预算计算:复利开/关、上限开/关、余额边界.  
+- 状态机:开仓失败回滚卖币;平仓后卖币失败 → 待卖回 → 重试成功.  
+- 门禁:有仓切换拒绝;一次一仓.  
+- 回归: `margin_mode=usdc` 时行为与现网一致;对冲仍仅 USDC.  
+- 中控只读:快照含本位字段时卡片/文案可区分 `usdc`/`coin`.  
+- Gate:本次 diff **不应出现** `crypto_monitor_gate/` 业务文件变更.
+
+---
+
+## 9. 验收标准
+
+1. `usdc` 模式:单笔期权行为与现网一致.  
+2. `coin` 模式:一轮开平后交易户 USDT 变化符合「买币→期权→卖币」;无异常残留币(或残留时必有待卖回告警).  
+3. 复利:人为把交易户从约 10U 做到约 20U 后,下一轮预览预算约为 `20×0.95`(上限关闭时).  
+4. 上限开关默认关;开启后预算不超过 N.  
+5. 有持仓或半成品时切换模式被拒绝.  
+6. 币本位下对冲不能误开币本位腿.  
+7. 开仓失败自动卖回 USDT,不留下无主现货.  
+8. 中控:**无**期权下单入口新增;监控/快照/持仓只读能看出当前为币本位或 USDC.  
+9. Gate:无相关代码改动;Gate 实例行为与改前一致.
+
+---
+
+## 10. 实现顺序建议
+
+1. 模式 env + 有仓/半成品门禁 + OKX 实例 UI 展示当前模式  
+2. 现货桥(买/卖/回滚/待卖回) + 单测  
+3. 币本位合约适配 + 卖一开/买一平接入编排  
+4. 复利预算预览与开仓确认  
+5. 上限开关  
+6. 快照字段上报 + **中控只读识别币本位**(卡片/文案;不下单)  
+7. 文档:`期权用法.md` 增补币本位章节;`更新文档.md` 记一笔  
+
+---
+
+## 11. 决策摘要(已拍板)
+
+| 决策 | 结论 |
+|------|------|
+| 对冲 | 暂不接币本位 |
+| 单笔模式 | env:`usdc` ↔ `coin` |
+| 有持仓切换 | **拒绝** |
+| 买币方式 | **先买满预算 USDT 对应的币,再开满期权**(不按权利金精算) |
+| 复利 | 交易账户 USDT × 0.95;人工转走控规模 |
+| 单笔不超过 N U | **独立开关,默认关闭** |
+| 中控 | **不下单**;只读字段/快照**能识别币本位** |
+| Gate | **本次不改** |
+| 动机 | 币本位流动性往往优于 USDC,利于成交 |
+
+---
+
+## 12. 风险与说明
+
+- 现货双边手续费与滑点会吃掉部分「名义预算」;小资金下占比更明显.  
+- 持仓期间若账户内残留标的币,平仓卖回时含现货汇率盈亏,需与期权腿区分看待.  
+- 流动性优势随到期、行权、标的变化,不保证每一张合约都厚于 USDC;开仓仍以当场卖一深度为准.  
+- 本方案不改变「符合机会才做、不符合就等」的交易纪律;仅改单笔期权的资金路径与合约族.

docs/env配置说明.md

@@ -0,0 +1,231 @@
+# env 配置页说明
+
+本文档描述各交易实例 Web 端 **「env 配置」** 页展示项,含义,生效方式,以及与系统设置,中控密钥的分工.
+
+> **不在本页展示的配置**(服务端口,数据库路径,关键位门控,轮询间隔等)仍保存在实例目录 `.env` 中,需 SSH 编辑或部署脚本维护,见文末「隐藏项」.
+
+---
+
+## 1. 设计原则
+
+| 原则 | 说明 |
+|------|------|
+| **只展示运营相关项** | 不暴露全量 `.env`,避免误改基础设施 |
+| **前端仅中文** | 页面只显示中文标签与说明,不显示 `APP_XXX` 等变量名 |
+| **账户密码不进本页** | 登录用户名/密码在 **系统设置 → 账户密码修改** 中维护 |
+| **密钥自动托管** | 中控通信密钥,登录会话密钥由 **首次部署脚本自动生成并写入**(一次生成,不轮换),本页不提供编辑 |
+| **交易所 API 不进本页** | `OKX/BINANCE/GATE_API_*` 仅在服务器实例目录 `.env` 配置;新机默认为空,填真钥后 `pm2 restart --update-env` |
+| **AI 仅中控配置** | OpenAI / Ollama 等 AI 项已从中控 **系统设置 → AI 配置** 统一维护并同步三所,本页不再展示 |
+| **保存标注** | 每项标注「保存即生效」或「需重启」;含需重启项时可用「保存并重启」 |
+
+---
+
+## 2. 密钥分工(自动生成,本页不可见)
+
+部署时由脚本统一生成并写入对应 `.env`(已有值则跳过,避免覆盖生产环境).
+
+| 类型 | 环境变量 | 写入位置 | 用途 |
+|------|----------|----------|------|
+| **中控通信密钥** | `HUB_BRIDGE_TOKEN` | 中控 `manual_trading_hub/.env` + 三实例 `.env`(**相同值**) | 中控调用实例 API(`X-Hub-Token`),iframe SSO 签发与校验 |
+| **登录会话密钥** | `FLASK_SECRET_KEY` | 三实例 `.env`(**三所相同**) | Flask Session 签名;与网页登录态相关,与中控密钥 **分离** |
+| **中控会话密钥** | `HUB_SESSION_SECRET` | 中控 `.env` | 中控登录 Cookie 签名 |
+| **登录账号** | `APP_USERNAME` / `APP_PASSWORD` | 三实例 `.env`(建议三所统一) | 直链实例 `/login` 使用;**仅在系统设置中修改** |
+| **中控登录** | `HUB_USERNAME` / `HUB_PASSWORD` | 中控 `.env` | 中控网页登录;**仅在中控系统设置改密** |
+
+说明:
+
+- **长期密钥一次生成,不轮换**:`setup_env.sh` 末尾调用 `scripts/bootstrap_deploy_secrets.py`;已有非占位值不会被覆盖.
+- **SSO 链接不变**:仍为中控每次签发,默认 2 小时有效,单次使用(`HUB_SSO_TTL_SEC`),与长期 `HUB_BRIDGE_TOKEN` 分离.
+- 经中控 iframe / SSO 打开实例时,可免输实例密码;直链 IP/域名仍走 `/login`.
+- 首次部署可生成随机强密码;用户日后在 **系统设置** 改密,不经过本页.
+
+---
+
+## 3. 页面布局(三列卡片)
+
+| 列 1 | 列 2 | 列 3 |
+|------|------|------|
+| 交易所与实盘 | 企业微信 | 交易执行 |
+| 交易风控 | 账户冷静期 | 自动划转 |
+| 当日资金 | 期权账户(仅 OKX) | |
+
+> **AI 复盘**(OpenAI / Ollama)已移至中控 **系统设置 → AI 配置**,保存后强制同步三所 `.env`.详见 [中控AI与密钥配置.md](./中控AI与密钥配置.md).
+
+Binance / Gate 无期权模块时,第三列最后一格不显示或显示「本所无期权」.
+
+---
+
+## 4. 各卡片字段(中文展示名)
+
+### 4.1 交易所与实盘
+
+| 中文名 | 说明 | 重启 |
+|--------|------|------|
+| 开启实盘下单 | 关闭时仅走本地流程,不向交易所发单 | 需重启 |
+| 保证金模式 | 全仓 / 逐仓 | 需重启 |
+| 持仓模式 | 双向 / 单向净持仓等(按所) | 需重启 |
+| 仓位查询类型 | 仅 OKX:如 SWAP | 需重启 |
+| 账户备注 | 企业微信推送中显示的交易所备注 | 保存即生效 |
+| 显示永续资金 | 仅 OKX:关闭后顶栏隐藏 USDT 资金/交易账户,总资金仅计期权 USDC 侧 | 保存即生效 |
+
+**交易所 API Key / Secret / Passphrase 不在本页**:请 SSH 编辑各所 `crypto_monitor_*/.env`,新机部署后应为空;配好真钥后重启对应 Flask 与子代理(`pm2 restart … --update-env`).占位符或错误密钥会导致鉴权失败,Gate 上反复请求还可能封 IP.
+
+**本卡片不包含**:网页登录账号密码,是否关闭登录校验,中控通信密钥.
+
+---
+
+### 4.2 企业微信
+
+| 中文名 | 说明 |
+|--------|------|
+| 机器人 Webhook | 行情,风控,提醒推送地址 |
+| 推送超时(秒) | 可选,默认 10 |
+
+---
+
+### 4.3 AI 复盘(已移至中控)
+
+AI 相关环境变量(`AI_PROVIDER`,`OPENAI_*`,`OLLAMA_*`,`AI_MODEL`,`AI_TIMEOUT_SECONDS`)**不再在本页展示**.
+
+请在中控 **系统设置 → AI 配置** 修改;保存后写入中控 `.env` 并 **强制同步** 至 OKX / Binance / Gate 三实例.详见 [中控AI与密钥配置.md](./中控AI与密钥配置.md).
+
+---
+
+### 4.4 交易执行
+
+| 中文名 | 说明 |
+|--------|------|
+| 计仓模式 | 以损定仓 / 全仓杠杆 |
+| 以损定仓风险% | 单笔风险占资金比例 |
+| 全仓资金缓冲比例 | 全仓模式下可用资金折扣 |
+| BTC 默认杠杆 | |
+| 山寨默认杠杆 | |
+| 方向限制开关 | |
+| 允许方向 | 多 / 空 / 双向 |
+| 币种白名单开关 | |
+| 白名单币种 | 逗号分隔 |
+| 交易日切点(北京时间) | 默认 8 点 |
+| 切点前禁止新开仓 | |
+| 最大同时持仓 | |
+| 人工最低盈亏比 | |
+| 强制清仓开关 | `FORCE_CLOSE_ENABLED`;开启后在指定北京整点小时内,市价平掉本地 active 监控仓 |
+| 强制清仓整点(北京) | `FORCE_CLOSE_BJ_HOUR`(0–23);例 `8` 表示 08:00～08:59;仅扫监控仓,不含交易所裸仓 |
+
+---
+
+### 4.5 交易风控(日内开仓)
+
+| 中文名 | 说明 |
+|--------|------|
+| 单日开仓提醒阈值 | 达到次数后 AI 克制提醒(不拦单) |
+| 单日开仓硬上限 | 0 表示不启用;达到后禁止新开仓 |
+
+详见 [daily-open-limit.md](./daily-open-limit.md).
+
+---
+
+### 4.6 账户冷静期
+
+| 中文名 | 说明 |
+|--------|------|
+| 冷静期总开关 | |
+| 手动平仓冷静(小时) | |
+| 复盘情绪冷静(小时) | |
+| 日手动平仓次数上限 | |
+| 日亏损次数上限 | 默认2;达限当日冻结开仓;0=不启用 |
+| 情绪标签日冻结 | |
+
+详见 [account-risk-cooldown.md](./account-risk-cooldown.md).
+
+---
+
+### 4.7 自动划转
+
+| 中文名 | 说明 |
+|--------|------|
+| 启用自动划转 | |
+| 目标余额(U) | 交易账户目标 USDT |
+| 划出账户 | funding / swap |
+| 划入账户 | swap / funding |
+| 执行整点(北京时间) | |
+| 划转币种 | 默认 USDT |
+
+详见 [auto-transfer-daily.md](./auto-transfer-daily.md).
+
+---
+
+### 4.8 当日资金
+
+| 中文名 | 说明 |
+|--------|------|
+| 日起始基数(U) | |
+| 回撤后基数(U) | |
+| 盈利后基数(U) | |
+
+与自动划转目标余额相互独立;若需一致请手动对齐.
+
+---
+
+### 4.9 期权账户(仅 OKX)
+
+| 中文名 | 说明 |
+|--------|------|
+| 启用期权模块 | 与永续共用 `OKX_API_*`;不再单独配置期权密钥 |
+| 期权账户备注 | |
+| 单笔预算(USDC) | |
+| 预算缓冲比例 | |
+| 默认标的 | 如 ETH |
+| 最大到期天数 | 等常用策略参数 |
+
+高级参数与完整说明见 [期权方案.md](./期权方案.md),[期权用法.md](./期权用法.md),[期权开平仓与监控说明.md](./期权开平仓与监控说明.md)(线上 `/options/guide`).
+
+---
+
+## 5. 操作说明
+
+1. 修改后点 **保存**:即时生效项立即应用;需重启项写入 `.env` 但未重启进程.
+2. 含需重启项时点 **保存并重启**:写 `.env` 后 PM2 重启当前实例.
+3. **重新加载**:从磁盘重新读取 `.env` 刷新表单(放弃未保存修改).
+4. 敏感项(API,密钥)显示为掩码;**留空提交表示不修改原值**.
+
+---
+
+## 6. 隐藏项(本页不展示)
+
+以下仍存在于 `.env`,仅供运维或 SSH 修改:
+
+- 服务:`APP_HOST`,`APP_PORT`,`APP_DEBUG`
+- 数据:`DB_PATH`,`UPLOAD_DIR`
+- **交易所 API**:`OKX_API_*`,`BINANCE_API_*`,`GATE_API_*`(仅 SSH;新机应为空)
+- 关键位门控:全部 `KEY_*`,`KLINE_*`
+- 轮询与同步:`BALANCE_REFRESH_SECONDS`,`PRICE_REFRESH_SECONDS`,`MONITOR_POLL_SECONDS`,`BREAKEVEN_*`,`RECONCILE_*`
+- 代理:`OKX_SOCKS_PROXY`,`BINANCE_HTTP_PROXY` 等
+- 备份:`BACKUP_*`
+- 中控嵌入细节:`APP_ALLOW_HUB_EMBED`,`HUB_EMBED_*`,`APP_COOKIE_SECURE`
+- 登录相关:`APP_AUTH_DISABLED`,`APP_USERNAME`,`APP_PASSWORD`,`FLASK_SECRET_KEY`,`HUB_BRIDGE_TOKEN`
+
+后续若需要可增加「高级模式」折叠区,默认关闭.
+
+---
+
+## 7. 与系统设置的关系
+
+| 能力 | env 配置 | 系统设置 | 中控系统设置 |
+|------|----------|----------|--------------|
+| 登录用户名/密码 | ❌ | ✅ 账户密码修改 | ✅ 中控账户密码 |
+| 交易所 API | ❌(仅服务器 `.env`) | ❌ | ❌ |
+| AI / OpenAI | ❌ | ❌ | ✅ AI 配置(同步三所) |
+| 导航/区块显示 | ❌ | ✅ 导航显示 | ✅ 显示与导航 |
+| 手动资金划转 | ❌ | ✅ 永续资金划转 | ❌ |
+| 数据导出 | ❌ | ✅ 数据导出 | ❌ |
+| 期权兑换/划转 UI | ❌ | ✅(OKX,可开关) | ❌ |
+
+系统设置说明见 [系统设置说明.md](./系统设置说明.md);中控 AI 与部署密钥见 [中控AI与密钥配置.md](./中控AI与密钥配置.md).
+
+---
+
+## 8. 实现备注(开发用)
+
+- 白名单分组:`lib/env/env_ui_manifest.py`(按 `exchange_key` 过滤)
+- 中文标签:`ENV_UI_LABELS` 映射,模板只渲染 `label` / `note`
+- 全量校验仍基于 `.env.example`;POST 仅接受 manifest 内 key

docs/lib-structure.md

@@ -0,0 +1,147 @@
+# lib/ 共用模块结构
+
+三所实例与中控共用的 Python 库,模板与静态资源统一放在仓库根目录的 **`lib/`** 下.部署单元(`crypto_monitor_*`,`manual_trading_hub`)仍保持独立目录与 PM2 配置不变.
+
+**重构前快照 Git 标签**:`pre-lib-modularization`(可用 `git checkout pre-lib-modularization` 查看旧布局).  
+**移除 gate_bot 前快照 Git 标签**:`pre-remove-gate-bot`.
+
+---
+
+## 顶层目录
+
+```
+crypto_monitor/
+├── crypto_monitor_binance/      # 三所:各自 app + .env + PM2
+├── crypto_monitor_gate/
+├── crypto_monitor_okx/
+├── manual_trading_hub/          # 中控 + 子代理 agent
+│
+├── lib/                         # 共用模块(本说明)
+│   ├── strategy/
+│   ├── key_monitor/
+│   ├── trade/
+│   ├── hub/
+│   ├── ai/
+│   ├── instance/
+│   ├── exchange/
+│   ├── common/
+│   └── paths.py
+│
+├── brand/                       # 各所共用图标
+├── docs/
+├── deploy/
+├── scripts/
+├── tests/
+├── requirements.txt
+└── README.md
+```
+
+---
+
+## lib/ 子包说明
+
+| 子包 | 职责 | 主要模块 |
+|------|------|----------|
+| **`lib/strategy/`** | 策略交易(顺势加仓,趋势回调,快照与记录) | `strategy_register.py`,`strategy_trend_register.py`,`strategy_db.py`,`strategy_roll_*`,`strategy_trend_*` |
+| **`lib/strategy/templates/`** | 策略页 Jinja 模板(原 `strategy_templates/`) | `strategy_trading_page.html`,`strategy_roll_panel.html` 等 |
+| **`lib/key_monitor/`** | 关键位监控,斐波,假突破,止盈止损方案 | `key_monitor_lib.py`,`fib_key_monitor_lib.py`,`key_sl_tp_lib.py` 等 |
+| **`lib/trade/`** | 下单监控展示,计仓,账户风控,手动 SL/TP | `order_monitor_display_lib.py`,`position_sizing_lib.py`,`account_risk_lib.py` 等 |
+| **`lib/hub/`** | 中控 API,K 线,归档,计仓器,SSO/Bridge | `hub_bridge.py`,`hub_kline_store.py`,`hub_trades_lib.py` 等 |
+| **`lib/ai/`** | AI 复盘与文本生成 | `ai_client.py`,`ai_review_lib.py` |
+| **`lib/instance/`** | 中控 iframe 嵌入,导航,复盘图表 | `instance_embed_lib.py`,`focus_chart_lib.py`,`journal_chart_lib.py` |
+| **`lib/instance/templates/`** | 嵌入页片段(原 `embed_templates/`) | `embed_page_fragment.html` |
+| **`lib/exchange/`** | 特定交易所工具 | `gate_transfer_lib.py`,`okx_orders_lib.py` 等 |
+| **`lib/common/`** | 跨功能小工具 | `form_submit_lib.py`,`wechat_notify_lib.py` 等 |
+| **`lib/common/static/`** | 三所与中控共用的 JS/CSS(原根目录 `static/`) | `instance_theme.js`,`strategy_roll.js` 等 |
+
+> **说明**:`hub_*` 命名表示「中控侧能力或行情聚合」,但部分模块(如 `hub_volume_rank_lib`,`hub_market_info_lib`)三所 `app.py` 也会调用,并非中控独占.
+
+---
+
+## 路径辅助函数
+
+`lib/paths.py` 集中维护资源目录,避免硬编码:
+
+```python
+from lib.paths import strategy_templates_dir, embed_templates_dir, common_static_dir
+
+strategy_templates_dir()   # .../lib/strategy/templates
+embed_templates_dir()      # .../lib/instance/templates
+common_static_dir()        # .../lib/common/static
+```
+
+可选传入 `repo_root`(字符串或 `Path`),默认使用 `lib/` 的上级目录即仓库根.
+
+---
+
+## Python 导入约定
+
+各部署目录在启动时将 **仓库根** 加入 `sys.path`(与重构前相同):
+
+```python
+_REPO_ROOT = os.path.dirname(BASE_DIR)  # 或 Path(__file__).resolve().parent.parent
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+```
+
+之后使用 **`lib.<子包>.<模块>`** 形式导入,例如:
+
+```python
+from lib.strategy.strategy_db import init_strategy_tables
+from lib.key_monitor.key_monitor_lib import check_key_monitors
+from lib.hub.hub_bridge import install_on_app
+from lib.ai.ai_client import ai_review
+```
+
+策略注册仍在各所 `app.py` 末尾:
+
+```python
+from lib.strategy.strategy_register import install_strategy_trading
+from lib.strategy.strategy_trend_register import install_strategy_trend
+
+install_strategy_trading(app, _REPO_ROOT, app_module=sys.modules[__name__])
+install_strategy_trend(app, _REPO_ROOT, app_module=sys.modules[__name__])
+```
+
+---
+
+## 静态资源与 URL
+
+- 三所页面仍通过 **`/static/...`** 访问共用脚本;`hub_bridge.install_instance_theme_static` 从 `lib/common/static/` 提供部分根级静态路由.
+- 各所目录下 **`static/`**(图标,上传图片等)仍为实例私有,未迁入 `lib/`.
+- 中控 `manual_trading_hub/hub.py` 通过 `_REPO_ROOT / "lib" / "common" / "static"` 挂载与三所共用的 badge,复盘 JS 等.
+
+---
+
+## 测试
+
+在仓库根执行(需将根目录置于 Python 路径,或从根目录运行):
+
+```bash
+cd /opt/crypto_monitor
+python -m unittest discover -s tests -p "test_*.py"
+```
+
+测试文件内统一 `from lib.<子包>.<模块> import ...`.使用 `@patch` 时目标写完整模块路径,例如 `lib.hub.hub_calculator_lib._resolve_market`.
+
+---
+
+## 迁移脚本
+
+一次性迁移由 `scripts/migrate_to_lib.py` 完成(移动文件 + 批量改写 import).**不要在已迁移后的仓库上重复执行**.
+
+---
+
+## 后续可选整理
+
+- 三所 `app.py` 体量接近,可逐步抽取公共 `exchange_app` 基座(改动面大,单独规划).
+- `manual_trading_hub/okx_orders_lib.py` 为 agent 本地副本,可与 `lib/exchange/okx_orders_lib.py` 合并去重.
+- 可引入 `pyproject.toml` + `pip install -e .`,替代 `sys.path.insert`(长期维护更规范).
+
+---
+
+## 相关文档
+
+- [README.md](../README.md) — 总览与部署
+- [策略交易说明.md](../策略交易说明.md)
+- [manual_trading_hub/使用说明.md](../manual_trading_hub/使用说明.md)

docs/position-sizing-mode.md

@@ -0,0 +1,73 @@
+# 计仓模式(三所统一)
+
+## 配置
+
+在各实例 `.env` 中设置(**仅能通过 env 切换,修改后须重启进程**):
+
+```env
+# risk(默认)= 以损定仓
+# full_margin = 全仓杠杆(合约可用保证金 × 比例)
+POSITION_SIZING_MODE=risk
+FULL_MARGIN_BUFFER_RATIO=0.98
+
+# 关键位程序自动单(默认 false,详见各所 关键位自动下单说明.md)
+KEY_AUTO_ORDER_ENABLED=false
+```
+
+切换为全仓杠杆前:**交易所须无持仓**(`MAX_ACTIVE_POSITIONS` 默认 1,全仓模式会强制单仓).
+
+## 模式说明
+
+| 模式 | 保证金计算 | 杠杆 | 允许入口 |
+|------|------------|------|----------|
+| `risk` | `RISK_PERCENT` × 交易资金,按止损距离反推 | 表单可选 / 同步交易所 | 实盘人工,关键位自动(须 `KEY_AUTO_ORDER_ENABLED=true`),趋势回调,顺势加仓 |
+| `full_margin` | **合约账户可用 USDT × `FULL_MARGIN_BUFFER_RATIO`**(保留 2 位小数) | BTC/ETH **10x**,其它 **5x**(与 `BTC_LEVERAGE`/`ALT_LEVERAGE` 一致) | **实盘人工下单**,**关键位触价**(须 `KEY_AUTO_ORDER_ENABLED=true`);阻力/支撑仅提醒 |
+
+全仓模式下:
+
+- **`KEY_AUTO_ORDER_ENABLED=false`(默认)** 时,触价程序自动单也不执行.
+- **`KEY_AUTO_ORDER_ENABLED=true`** 时,仅触价可程序自动开仓;箱体/斐波等仍禁止.
+- 仍校验 **计划盈亏比**(实盘用 `MANUAL_MIN_PLANNED_RR`;触价开仓用 `KEY_AUTO_MIN_PLANNED_RR`).
+- 下单张数由 `prepare_order_amount` + 交易所 `amount_to_precision` 决定.
+- `order_monitors.initial_stop_loss` 仍记录**开仓时**止损快照;交易记录复盘以该快照为准.
+- 已存在的 **箱体突破 / 收敛突破 / 斐波 / 假突破** 监控:进程启动时**自动撤销**并企业微信通知.
+
+## 不允许(全仓模式)
+
+- 关键位:箱体突破,收敛突破,斐波,假突破(添加时拒绝;已存在则启动时撤销).
+- 趋势回调,顺势加仓(策略入口返回明确错误).
+
+**允许(须 `KEY_AUTO_ORDER_ENABLED=true`):** 关键位 **回调触价开仓** / **突破触价开仓**(程序盯价,触达/穿越计划入场后市价成交,无交易所挂单;全仓下仅允许一条待触发).
+
+## `KEY_AUTO_ORDER_ENABLED`(三所统一,默认 `false`)
+
+| 计仓 | 开关 | 效果 |
+|------|------|------|
+| `risk` | `false` | 关闭全部关键位程序自动单(含触价);顺势加仓不受影响 |
+| `risk` | `true` | 关键位全套自动(旧行为) |
+| `full_margin` | `false` | 关闭触价自动 |
+| `full_margin` | `true` | 仅触价自动 |
+
+详见各实例目录 `关键位自动下单说明.md`.
+
+## 用脚本更新三所 `.env`
+
+详见 **[env-sync-scripts.md](./env-sync-scripts.md)**.常用命令:
+
+```bash
+git pull
+
+# 仅补全计仓相关项(缺省 risk,缓冲 0.98)
+python scripts/sync_four_exchange_position_sizing_env.py
+
+# 无仓后切换全仓
+python scripts/sync_four_exchange_position_sizing_env.py --set-mode full_margin
+
+# 无仓后切回以损定仓
+python scripts/sync_four_exchange_position_sizing_env.py --set-mode risk
+
+# 计仓 + 划转一并补全
+python scripts/sync_four_exchange_env.py
+
+pm2 restart crypto-monitor-binance crypto-monitor-okx crypto-monitor-gate
+```

docs/对冲计划-以期权为主.md

@@ -0,0 +1,71 @@
+# 对冲计划 · 永期「以期权为主」
+
+> 实现日:2026-08-09 · 在现有永期**保险模式**上增加子模式,不新增 `OKX_TRADE_MODE`。  
+> 模式由 env `HEDGE_PLAN_OPTION_PRIMARY` 切换(默认 `true`),页面标题前显示标识,不可在页内切换。
+
+## 1. 模式对照
+
+| | 保险模式(`OPTION_PRIMARY=false`) | 以期权为主(`true`) |
+|--|------------------|-------------------|
+| UI 做多 | 永续多 + 买 Put | 买 Call + 永续空 |
+| UI 做空 | 永续空 + 买 Call | 买 Put + 永续多 |
+| 左卡 | 开仓价 / 张数 / TP / SL | 资金与杠杆 / 选约条件 / 出场条件 三组 |
+| 右卡 | 上永续行情 · 下期权链 | 同上;仅展示间隔+类型+杠杆达标候选 |
+| 选约 | 仅实值/平值 | 类型下拉(默认虚值)+间隔+杠杆门槛 |
+| 开仓 | 受 `HEDGE_PLAN_OPEN_ORDER` | **策略启动=盯盘**(status=`watching`),达标后才先期权后市价永续(**不挂**交易所 TP/SL) |
+| 出场 | 交易所 TP/SL | 相对 K 的点数目标分叉 |
+
+## 2. 左卡默认
+
+| 字段 | 默认 |
+|------|------|
+| 权利金 | 用户填(USDC 预算) |
+| 永续杠杆 | 100 |
+| 期权杠杆 | 实/平 100;虚 200 |
+| 期权:永续比例 | 实/平 2;虚 4 |
+| 到期时间(最短 h) | 36 |
+| 期权间隔(点) | 15 |
+| 期权/永续目标位 | 相对 K 点数,须 **>0** |
+
+## 3. 定仓
+
+```
+usable = 权利金 × 0.95
+eth_qty = floor2(usable / ask)          # ETH 名义,两位小数
+sheets  = floor(eth_qty / ct_mult)      # 整张
+perp_eth = eth_qty / 比例
+contracts = perp_eth / contract_size
+```
+
+启动前再拉卖一重算;卖一深度不足则缩量。
+
+## 4. 出场
+
+触达任一目标位(做多 `index ≥ K+N`,做空 `index ≤ K−N`)后立即执行:
+
+| 触达 | 规则 |
+|------|------|
+| **期权目标** | 验买一流动性 + **扣费净利 > 0** → 先平期权再平永续 |
+| **永续目标** | 市价平永续;期权 `hold_to_expiry` 至到期结算 |
+
+净利:平仓/卖出手续费**按买入费率**估算(`HEDGE_PLAN_FEE_RATE` / `OKX_TAKER_FEE`,默认 0.0005)。
+
+若期权目标因买一/净利未过、但永续目标已触达 → 改走永续目标。  
+期权已平永续失败 → `opt_target_perp_pending` 下轮只补平永续。  
+两腿仍开但期权到期 → 结算期权并平永续,避免裸奔。
+
+## 5. 代码落点
+
+| 文件 | 作用 |
+|------|------|
+| `lib/hedge_plan/hedge_plan_option_primary_lib.py` | 定仓/方向/目标/净利/校验 |
+| `hedge_plan_orders_lib.py` | 路径、开平永续、启动前定仓刷新 |
+| `hedge_plan_monitor_lib.py` | `_tick_po_option_primary*` |
+| `hedge_plan_register.py` / `hedge_plan_db.py` | preview/start/persist；`options-chain?option_primary&min_hours&strike_interval` |
+| `hedge_plan.js` + `hedge_plan_panel.html` | env 模式标识、左三组参数、右上永续/右下期权 |
+
+## 6. 测试
+
+```bash
+python -m unittest tests.test_hedge_plan_option_primary -v
+```

docs/对冲计划-选约与虚实值.md

@@ -0,0 +1,76 @@
+# 对冲计划 · 选约与虚实值
+
+> 实现日:2026-08-05 · 吸收 `eth_hedge_sim`(比特骆驼)选约几何;退出仍用本仓 TP/SL/S*,**不**移植仿真「净盈亏 15U 离场」。
+
+## 1. 冻结规则
+
+| 计划类型 | 允许虚实值 | 禁止 | 推荐模板 |
+|----------|------------|------|----------|
+| **永期保险** `perp_options`(开关关) | 实值、平值 | **虚值** | 距指数最近的实值/平值(做多 Put / 做空 Call) |
+| **永期以期权为主** `option_primary=1` | 实值、平值、**虚值** | —(间隔+杠杆门) | 做多 Call+永续空 / 做空 Put+永续多;详见 `docs/对冲计划-以期权为主.md` |
+| **期期** `options_options` | 平值、虚值 | **实值** | 平值跨式(ATM C+P);双虚值(OTM C+P) |
+
+口径与 `lib/options/options_pricing_lib.option_moneyness` 一致:ATM 带 = `max(指数×0.2%, 2U)`。
+
+永期几何兜底(与仿真一致):
+
+- Call 实值/平值:`K ≤ S`
+- Put 实值/平值:`K ≥ S`
+
+## 2. 代码落点
+
+| 层 | 文件 | 作用 |
+|----|------|------|
+| 选约/校验库 | `lib/hedge_plan/hedge_plan_moneyness_lib.py` | `is_itm_or_atm` / `is_atm_or_otm` / `pick_*` / `recommend_oo_legs` / `validate_*` |
+| 启动门禁 | `hedge_plan_orders_lib.validate_start_body` | 测算外再拦一遍;防绕过 UI 直 POST |
+| 测算 | `hedge_plan_register._preview_po/_preview_oo` | 预览同样拒绝违规腿 |
+| UI | `hedge_plan.js` + `hedge_plan_panel.html` | 筛选锁定、推荐按钮、选用前校验 |
+| Env | `env_ui_manifest` 永期分组 | `HEDGE_PLAN_ITM_MAX_DIST_USD` / `MIN_OPTION_HOURS` / `MIN_OPTION_LEVERAGE` |
+
+## 3. Env
+
+| 键 | 默认 | 说明 |
+|----|------|------|
+| `HEDGE_PLAN_ITM_MAX_DIST_USD` | 空→沿用 `OKX_OPTIONS_ITM_MAX_DIST_USD`(常 30) | 永期过深实值上限;0=不限 |
+| `HEDGE_PLAN_MIN_OPTION_HOURS` | 8 | 仅当请求带 `hours_to_expiry` 时生效 |
+| `HEDGE_PLAN_MIN_OPTION_LEVERAGE` | 0 | `指数/卖一`;0=关闭 |
+
+## 4. 可用性审计
+
+| 项 | 结论 |
+|----|------|
+| 默认筛选 | 永期默认「实值/平值」;期期默认「平/虚」—减少误选 |
+| 推荐一键 | 永期「推荐」;期期「推荐跨式 / 推荐双虚」—降低手选成本 |
+| 文案 | 规则说明与 alert 明确禁虚(永期)/禁实(期期) |
+| 服务端一致 | UI 过滤可绕过时,preview/start 仍会 400 |
+| 兼容旧 API | 未传 `strike` 时从 `inst_id` 解析;未传 `index_px` 时永期用 `entry`、期期用上下破中点 |
+| 以期权为主 | 见 `docs/对冲计划-以期权为主.md`:点数目标+扣费净利出场(非仿真 15U 固定);保险模式仍不接仿真净盈亏离场 |
+
+**已知局限:**
+
+- 链上 `moneyness` 依赖刷新时指数;剧烈跳动后需「刷新链」再选。
+- `MIN_OPTION_HOURS` 需前端/调用方传入 `hours_to_expiry` 才校验(当前链行未必带该字段)。
+- 期期「推荐跨式」优先 ATM,若无 ATM 会回退到最近允许档(含 OTM)。
+
+## 5. 安全性审计
+
+| 风险 | 控制 |
+|------|------|
+| 客户端改包选虚值永期保险 | `validate_start_body` + preview 服务端拒绝 |
+| 客户端选实值期期腿 | 同上 |
+| 过深实值权利金过贵 / 杠杆过低 | `ITM_MAX_DIST` + 可选 `MIN_OPTION_LEVERAGE` |
+| 误开实盘 | 既有 `HEDGE_PLAN_LIVE_ORDER` ∩ `LIVE_TRADING_ENABLED` ∩ 全仓(永期)门禁不变 |
+| 保险模式平仓 | 不变:交易所 TP/SL |
+| 以期权为主平仓 | 独立监控分支;不改保险模式路径 |
+
+## 6. 测试
+
+```bash
+python -m unittest tests.test_hedge_plan_moneyness tests.test_hedge_plan_orders -v
+```
+
+覆盖:虚实值几何、永期拒 OTM、期期拒 ITM、`validate_start_body` 集成。
+
+## 7. 与开发方案对齐
+
+更新 `docs/对冲计划开发方案.md` §3.2 / §4.1 选约约束,与本文件一致。

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

@@ -0,0 +1,695 @@
+# 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**.
+- **虚实值(冻结):**仅允许 **实值或平值**,**禁止虚值**(保险腿须有内在价值或贴近平值).详见 [对冲计划-选约与虚实值.md](./对冲计划-选约与虚实值.md).
+- 页面默认筛「实值/平值」,提供「推荐」取距指数最近档;服务端 `validate_start_body` / preview 二次校验.
+- 权利金默认按 **卖一 ask** 估算;开仓限价买入.
+
+### 3.3 左右布局
+
+```
+左:永续列表行情(标记/买卖一) + 方向/建议张数/开仓价/止盈/止损
+右:期权列表(可「选用」一条腿)
+下:情景测算 → [保存草稿] [启动计划]
+```
+
+---
+
+## 4. 期期对冲 — 仓位与选腿
+
+### 4.1 报价与选腿
+
+- **T 型报价链**(复用期权页 T 型样式/数据结构).
+- 用户选 **腿 A + 腿 B**(通常 Call + Put,或主方向 + 尾部).
+- **虚实值(冻结):**两腿仅允许 **平值或虚值**,**禁止实值**;推荐模板:平值跨式 / 双虚值.详见 [对冲计划-选约与虚实值.md](./对冲计划-选约与虚实值.md).
+- 预算:`B = min(交易户 USDC × 对冲缓冲 HEDGE_PLAN_BUDGET_BUFFER, 单笔预算)`(默认 buffer=0.95;与期权页 buffer 独立).
+- 自动张数(选齐两腿后写入,可手改):
+  - **同张数**(默认):最大 `n` 使 `n×(cost_A+cost_B) ≤ B`,两腿均填 `n`
+  - **做多 / 做空**:须一 Call 一 Put;主:次默认 **7:3**(`HEDGE_PLAN_OO_BIAS_RATIO`,可改)
+    - 做多:主腿=Call;做空:主腿=Put
+    - 拆分口径 `HEDGE_PLAN_OO_BIAS_SPLIT_BY`:`budget`(默认,按权利金预算拆) / `sheets`(先按同张数得每腿 `n`,总张数 `2n` 再按比例拆到 Call/Put)
+  - 另受各自卖一深度上限约束
+  - 已移除页面「均分」;后端仍兼容旧 `split_budget` 入参(预算对半)
+
+### 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 期期对冲
+
+| 事件 | 盈利方 | 另一腿(残腿) | 计划是否结束 |
+|------|--------|--------------|--------------|
+| **标的价到达目标 + 平仓模式=到期平** | **自动平仓** | **不平**,持有至到期(`hold_expiry`) | 平盈利腿后仍 `active`;残腿到期后结账 |
+| **标的价到达目标 + 平仓模式=全平**(默认) | **自动平仓** | **随即买一清残腿**(无 2×门控,失败则每轮重试) | 两腿都平完后 `closed` |
+| **到期且整体无盈利** | — | 到期结算 | **算结束**;合计记 **总亏损** |
+| **到期时组合合计仍盈利** | — | 到期结算 | **算结束**;按实际结算盈亏入账 |
+
+- 界面「平仓模式」仅控制**盈利腿已平之后**另一腿的处理;须 `HEDGE_PLAN_OO_CLOSE_MODE_ENABLED=true`(默认开)才显示,页面默认选 **全平**.
+- 关闭方案C开关时行为固定为 **到期平**.
+- 判定「整体无盈利」:到期(或计划收口)时 `realized_pnl_total ≤ 0`(含双腿权利金全损).
+- 盈利方判定:触达上破/下破时按浮盈较大一侧平仓;皆亏则等到期.
+
+### 5.2.1 期权腿实盘平仓执行(与期权页共用)
+
+对冲计划凡**必须物理平掉期权腿**时(如永期止损联动、期期平盈利腿),执行口径与独立期权模块一致:
+
+| 规则 | 说明 |
+|------|------|
+| 禁市价 | 代码硬关闭,无市价兜底 |
+| 只锁买一 | 本轮 `min(仓位, 买一深度)` × 买一限价;`reduceOnly` |
+| 分批 | 买一不够则剩余下一轮再平再锁新买一 |
+| 有效流动性 | 残档买一禁止按买盘平 |
+| 2× 门控 | 目标位/自动类路径首次需可回收≥2×权利金并持续 hold;手动买一平只验流动性 |
+| 平仓挂单 TTL | 卖出限价超 `OKX_OPTIONS_PENDING_TTL_SECONDS`(默认 10 分钟)自动撤;UI「委托」可见 |
+
+完整说明(可单独打开):**[期权开平仓与监控说明.md](./期权开平仓与监控说明.md)** · 线上 `/options/guide`.
+
+---
+
+### 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_SHOW_PERP_OPTIONS` | 显示永期对冲 | true | bool | 热更 | 关则隐藏永期 Tab,不可测算/开仓 |
+| `HEDGE_PLAN_SHOW_OPTIONS_OPTIONS` | 显示期期对冲 | true | bool | 热更 | 关则隐藏期期 Tab,不可测算/开仓 |
+| `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 | 热更 | 达目标价只平盈利方 |
+| `HEDGE_PLAN_OO_CLOSE_MODE_ENABLED` | 期期平仓模式(方案C) | 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_SHOW_PERP_OPTIONS=true
+HEDGE_PLAN_SHOW_OPTIONS_OPTIONS=true
+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
+HEDGE_PLAN_OO_CLOSE_MODE_ENABLED=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、仅买方、限价规则必须遵守 |
+| [期权开平仓与监控说明.md](./期权开平仓与监控说明.md) | 买一平仓、门控、监控与风险;线上 `/options/guide` |
+| [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 复用已有分组
+- [x] 期权腿实盘平仓:**禁市价、只锁买一、分批;流动性/2×门控见开平仓说明**
+
+---
+
+## 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 页可见「对冲计划」分组

docs/期权开平仓与监控说明.md

@@ -0,0 +1,104 @@
+# OKX 期权 — 开平仓与监控说明
+
+> 独立页查看(登录后):`/options/guide`  
+> 对冲计划侧同步见 [对冲计划开发方案.md](./对冲计划开发方案.md) §期权腿开平仓.
+
+---
+
+## 1. 开仓方式
+
+| 项 | 规则 |
+|----|------|
+| 方向 | **仅买方**(Call / Put 限价买入) |
+| 价格 | **卖一 ask** 限价;无卖一时可用标记估算展示,实下单仍以可挂限价为准 |
+| 张数 | 1 张 = 0.01 ETH/BTC;可按预算打满或指定数量 |
+| 资金 | 交易账户 **USDC**(或 USDG);不自动兑划 |
+| 入口 | OKX 实例 **期权** 页列表 / T 型;对冲计划可带期权腿开仓 |
+
+开仓后写入 `options_trades`(open),并在持仓卡展示权利金、买盘深度、按买一可回收等.
+
+**同合约加仓**:每次买入再插一条 open 记录;展示权利金 / 平仓门控 / 翻倍提醒按同合约 **SUM(premium_paid)** 汇总,不再只取最新一笔.
+
+---
+
+## 2. 平仓方式
+
+### 2.1 统一规则(手动 / 目标自动共用执行核)
+
+1. **禁止市价平仓**(代码硬关闭,忽略 `OKX_OPTIONS_ALLOW_MARKET_CLOSE`).
+2. **只锁买一**:本轮张数 = `min(持仓, 买一深度)`,限价 = 校验通过当刻的买一价.
+3. **不吃买二及以下**;买一不够则只平本轮能吃掉的部分,**剩余仓位保留**,下次再平再锁新的买一.
+4. 全程 `reduceOnly` 限价卖.
+5. **平仓限价挂单超时自动撤**:卖出/平仓委托未成交超过默认 **10 分钟**(`OKX_OPTIONS_PENDING_TTL_SECONDS`,默认 600)由监控自动撤销,并可微信通知;UI「委托」面板实时展示挂单与剩余自动撤倒计时.
+
+示例:持仓 300、买一深度 200 → 本轮只平 200;剩 100 等下次「买一平仓」或目标位再次触发.
+
+### 2.2 手动「买一平仓」
+
+- 入口:持仓卡按钮.
+- **只校验有效流动性**(买一非残档、有深度).
+- **不卡**「回收 ≥ 2×权利金」门控(用户主动平仓).
+
+### 2.3 目标位自动平仓
+
+- 设置目标指数后由监控轮询;Call 指数 ≥ 目标 / Put 指数 ≤ 目标触发.
+- 触发后走同一买一执行核.
+- **额外门控**(不是独立自动平):仅当目标已触达时才检查;买一可回收 ≥ **权利金 × 2**,且连续约 **120 秒**(env:`OKX_OPTIONS_CLOSE_RECYCLE_MULT` / `OKX_OPTIONS_CLOSE_HOLD_SECONDS`).**到 2× 本身不会自动平仓**.
+- 首次通过后,同仓**续批**只再验流动性,不再重跑 2 分钟计时.
+- 无有效买一或门控未就绪 → 本轮不挂单,等下一轮;已有未成交卖平单则等成交,不撤了重挂.
+
+### 2.4 翻倍出场(可选)
+
+- 开仓勾选或持仓卡开启;倍数默认 **1**(盈利金额 = 初始权利金).
+- 触发条件:买一可回收 ≥ 权利金 × (1 + 倍数);达标后走买一限价平,**不再**额外卡「回收≥2×」门控(倍数本身已是出场条件).
+- 可随时关闭;与目标位监控并行,谁先达标谁平.
+- 与「翻倍提醒」独立:提醒只推微信,翻倍出场会真正挂平仓单.
+
+---
+
+## 3. 监控逻辑
+
+| 监控 | 行为 |
+|------|------|
+| 持仓 / 买盘预览 | 轮询刷新;净盈亏按**本轮买一可回收 − 权利金** |
+| 残档买一 | 买一 ≪ 标记/内在价值(默认 < 30%) → 禁止按买盘平,UI 显示无效 |
+| 未成交委托 | 期权下单区右侧「委托」列表展示开/平仓限价单,可手动撤销;页面轮询刷新 |
+| 平仓挂单超时 | 卖出平仓限价超 TTL 未成交 → 自动撤单(默认 10 分钟) |
+| 目标位 | 独立监控表;触发后买一平;推送企业微信(防重复) |
+| 翻倍出场 | 开仓/持仓可开关;自选倍数(默认1);1倍=盈利等于权利金(可回收≥2×权利金)达标后买一限价平;可随时关闭;与目标位并行 |
+| 翻倍提醒 | 未实现口径达权利金 × `OKX_OPTIONS_PROFIT_ALERT_RATIO` 时推送一次(仅提醒,不平仓) |
+| 到期 | 无系统止损;到期交割/保险腿自灭(对冲计划另有退出规则) |
+
+---
+
+## 4. 平仓校验(门控)
+
+| 门控 | 手动买一平 | 目标自动平 | 翻倍出场 | 说明 |
+|------|------------|------------|----------|------|
+| 有效流动性 | ✅ 必验 | ✅ 必验 | ✅ 必验 | 残档买一 / 无买一 → 拒平 |
+| 回收 ≥ 2× 权利金 + 持续 hold | ❌ | ✅ 首次 | ❌(倍数即条件) | 目标平仓专用门控 |
+| 回收 ≥ 权利金×(1+倍数) | ❌ | ❌ | ✅ 触发条件 | 1倍 ⇒ 回收≥2×权利金 |
+| 锁定买一价 | ✅ | ✅ | ✅ | 下单价 = 通过校验时的买一 |
+| 市价兜底 | ❌ | ❌ | ❌ | 永不市价 |
+
+---
+
+## 5. 风险点
+
+1. **流动性不足**:只平买一深度,大仓位可能多次才能平完;若买一突然撤档,限价可能挂着 — 超 TTL 会自动撤,之后需再次点平或等目标触发.
+2. **开仓挂单**:买入委托不在超时自动撤范围(仅平仓卖单);可在「委托」面板手动撤销.
+3. **残档假买一**:若未拦住残档会严重贱卖 — 系统用标记/内在价值比例拦截,但不等于保证最优成交价.
+4. **权利金沉没**:手动可在未达 2× 时平仓,可能主动止损或提前锁利不及预期.
+5. **无市价强平**:盘口真空时系统**不会**市价砸盘,仓位可能留到到期.
+6. **目标位只看指数**:触达后仍受买一/2×门控约束,可能「到价却平不掉」.
+7. **对冲计划腿**:期权腿退出规则见对冲方案;独立期权页平仓勿与计划状态脱节.
+8. **期期自动张数**:对冲计划页为「同张数 / 做多 / 做空」(已无均分);做多/做空按 Call·Put 比例拆,口径与比例见 env `HEDGE_PLAN_OO_BIAS_SPLIT_BY`、`HEDGE_PLAN_OO_BIAS_RATIO`.
+
+---
+
+## 6. 相关文档
+
+- [期权用法.md](./期权用法.md) — 资金兑划与页面操作
+- [期权方案.md](./期权方案.md) — env 与架构
+- [对冲计划开发方案.md](./对冲计划开发方案.md) — 永期/期期与期权腿
+- [系统说明.md](./系统说明.md) — 实例操作与门禁总手册

docs/期权方案.md

@@ -0,0 +1,78 @@
+# OKX 期权模块 — 技术方案
+
+> 适用范围:`crypto_monitor_okx` 实例;永续与期权共用同一套 `OKX_API_*`,不新增 PM2 进程.
+
+## 1. 目标
+
+在现有 OKX 监控实例中增加 **USDⓈ 本位期权(买方)** 能力:
+
+- 永续/关键位与期权:**同一账户 API**(`OKX_API_*`)
+- 两个 ccxt 客户端:`exchange`(defaultType=swap)与 `exchange_options`(defaultType=option),身份相同
+- 顶栏资金:**资金账户/交易账户=USDT**;**期权资金/期权交易=USDC**
+- 支持 **手动 USDT→USDC 兑换** 与 **账户内划转**(无主↔子划转)
+- **无总资金池上限**;单笔权利金上限可配置(默认 10 USDC)
+
+## 2. 交易规则(硬约束)
+
+| 规则 | 说明 |
+|------|------|
+| 仅买方 | 开仓 `buy`,平仓 `sell`;禁止卖方开仓 |
+| 产品 | `BTC-USD_UM` / `ETH-USD_UM`(线性,USDC/USDG 结算) |
+| 到期 | 仅展示 ≤2 日到期合约(可配置 `OKX_OPTIONS_MAX_DTE_DAYS`) |
+| 虚实 | 仅 **轻度实值**(`OKX_OPTIONS_ITM_ONLY`) |
+| 合约规格 | **1 张 = 0.01 ETH/BTC**(`ctMult=0.01`,以接口为准) |
+| 报价单位 | 盘口 ask/bid = **每 1 ETH/BTC** 的 USD 价 |
+| 权利金 | `总权利金 = 报价 × ETH数量`;`张数 = ETH数量 / 0.01` |
+| 单笔预算 | `≤ OKX_OPTIONS_TRADE_BUDGET_USDC`(默认 10),算张数 × `OKX_OPTIONS_BUDGET_BUFFER`(默认 0.95) |
+| 开仓 | 限价买单,价格 = 卖一 |
+| 平仓 | 限价卖单,价格 = 买一(市价需显式开启且二次确认) |
+| 监控 | 浮盈 / 已付权利金 ≥ 100% → 企业微信推送一次 |
+
+## 3. 架构
+
+```
+crypto_okx(单 PM2)
+├── exchange (swap)          ← OKX_API_*
+└── exchange_options (option)← 同一套 OKX_API_*
+
+lib/options/
+├── okx_options_lib.py      # 封装于 lib/exchange/
+├── options_pricing_lib.py
+├── options_db.py
+├── options_monitor_lib.py
+└── options_register.py     # 路由 + 监控线程
+```
+
+**说明:** `defaultType` 分离避免错路由;密钥身份唯一.旧 `OKX_OPTIONS_API_*` 已废弃.
+
+## 4. 资金与兑换
+
+### 4.1 展示(实例顶栏)
+
+- **资金账户 / 交易账户**:USDT(永续侧)
+- **期权资金账户 / 期权交易账户**:USDC
+- 总资金:USDT + USDC(1:1),同账户 USDT 不重复累加期权侧 USDT
+
+### 4.2 兑换与划转
+
+- 系统设置「币种兑换」:资金账户内 USDT ↔ USDC
+- 「期权划转」:同账户 funding ↔ trading(USDC/USDT)
+- **已移除**主↔子账户划转
+
+## 5. 环境变量(要点)
+
+```bash
+OKX_API_KEY=
+OKX_API_SECRET=
+OKX_API_PASSPHRASE=
+OKX_OPTIONS_ENABLED=true
+OKX_OPTIONS_TRADE_BUDGET_USDC=10
+OKX_OPTIONS_ACCOUNT_LABEL=账户·期权
+```
+
+详见 [env配置说明.md](./env配置说明.md) 与 `.env.example`.
+
+## 6. 相关文档
+
+- [期权用法.md](./期权用法.md)
+- [对冲计划开发方案.md](./对冲计划开发方案.md)

docs/期权用法.md

@@ -0,0 +1,107 @@
+# OKX 期权 — 使用说明
+
+## 1. 前置条件
+
+1. OKX 账户已开通期权(USDⓈ 本位),且 App 中可见 `ETHUSD UM` / `BTCUSD UM`.
+2. 在 `crypto_monitor_okx/.env` 配置 **唯一账户 API**(永续与期权共用):
+
+```bash
+OKX_API_KEY=你的账户Key
+OKX_API_SECRET=...
+OKX_API_PASSPHRASE=...
+OKX_OPTIONS_ENABLED=true
+```
+
+3. 重启实例:`pm2 restart crypto_okx --update-env`
+
+> 旧 `OKX_OPTIONS_API_*` 已废弃.若仅残留 OPTIONS 键而 `OKX_API_*` 为空,启动会自动回填.
+
+## 2. 资金准备
+
+期权权利金使用 **USDC**,不能直接用 USDT 买入.
+
+### 推荐步骤
+
+1. 查看顶栏:
+   - **资金账户 / 交易账户**:USDT
+   - **期权资金账户 / 期权交易账户**:USDC
+2. **币种兑换**(资金账户内)  
+   - 从 USDT 兑换为 USDC  
+   - 先点 **询价**,确认预估获得量后点 **确认兑换**
+3. **账户内划转**  
+   - 从:资金账户 → 到:交易账户  
+   - 币种:USDC  
+   - 将兑换得到的 USDC 划到交易账户
+4. 确认 **期权交易账户 USDC** 足够支付本笔权利金
+
+系统 **不会** 自动兑换或划转,避免误动资金.
+
+## 3. 下单流程
+
+1. 顶栏进入 **期权**
+2. 选择 **ETH** 或 **BTC**
+3. 选择 **到期日**(默认仅 1～2 日)
+4. 选择 **看涨 Call** 或 **看跌 Put**
+5. 在行权价列表中选 **轻度实值** 合约
+6. 查看:
+   - **卖一价**(每 1 ETH/BTC 的报价)
+   - **张数 / ETH 数量**
+   - **预估权利金**(USDC)
+7. 选择 **按预算打满**(默认 10U×0.95)或 **指定 ETH 数量**
+8. 点击 **限价买入**(价格 = 卖一)
+
+### 张数说明
+
+- **1 张 = 0.01 ETH**(或 0.01 BTC)— 与 OKX App「合约价值」一致
+- 盘口报价是 **每 1 ETH** 的价格  
+  例:报价 15.6,买 0.5 ETH(50 张)→ 权利金 ≈ 15.6 × 0.5 = **7.8 USDC**
+
+## 4. 持仓与平仓
+
+持仓表字段对齐 OKX:合约,张数,开仓均价,标记价,净盈亏,收益率,到期等.
+
+**买一平仓:**
+
+1. 在持仓卡点击 **买一平仓**
+2. 系统重读盘口并校验有效买一(非残档)
+3. 本轮只按买一深度限价卖出;买一不够则剩余下次再平
+4. **市价平仓已禁用**(代码硬关闭)
+
+目标位自动平另需「可回收 ≥ 2×权利金并持续约 2 分钟」;细则见独立说明:
+
+- 仓库文档:[期权开平仓与监控说明.md](./期权开平仓与监控说明.md)
+- 线上(登录后):`/options/guide`
+
+## 5. 微信提醒
+
+需已配置 `WECHAT_WEBHOOK`.
+
+| 场景 | 标题 | 说明 |
+|------|------|------|
+| **开仓** | 【OKX期权·开仓】 | 下单成功并写入本地后必发(幂等) |
+| **平仓** | 【OKX期权·平仓】 | 手动全平 / 目标位全平 / 到期或交易所平仓同步后必发(幂等) |
+| 浮盈翻倍 | 【OKX期权·翻倍提醒】 | 未实现盈亏 ≥ 已付权利金约 100%,同一笔只提醒一次 |
+| 挂单超时撤销 | 【OKX期权·挂单超时撤销】 | 平仓挂单超时被系统撤销 |
+
+## 6. 与永续 / 对冲计划的关系
+
+| | 永续 | 期权 |
+|--|------|------|
+| API | `OKX_API_*`(同一套) | `OKX_API_*`(同一套) |
+| 页面 | 实盘下单 / 关键位 | 期权 · 对冲计划 |
+| 顶栏 | USDT 资金户+交易户 | USDC 期权资金+期权交易 |
+
+**期期对冲张数**(对冲计划页,与单独开期权共用预算算法):
+
+| 模式 | 说明 |
+|------|------|
+| 同张数(默认) | 两腿同 `n`,总权利金 ≤ 预算 |
+| 按比例 | 主腿/次腿按 `HEDGE_PLAN_OO_BIAS_*` |
+
+## 7. 常见问题
+
+**Q:以前的期权专用密钥还要配吗?**  
+- 不需要.统一写到 `OKX_API_*`.
+
+**Q:还能主↔子划转吗?**  
+- 已移除.只保留同账户内划转与币种兑换.