From 845884fc6781716f6349a6d6def4ff49b554c77b Mon Sep 17 00:00:00 2001
From: dekun <dekun@local>
Date: Tue, 28 Jul 2026 13:08:25 +0800
Subject: [PATCH] Document perpetual-options hedge calculator and
 snapshot/20260728.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/快照备份.md       |   7 +-
 docs/永期对冲计算器.md | 167 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 171 insertions(+), 3 deletions(-)
 create mode 100644 docs/永期对冲计算器.md

diff --git a/docs/快照备份.md b/docs/快照备份.md
index ed55bf1..083c736 100644
--- a/docs/快照备份.md
+++ b/docs/快照备份.md
@@ -6,10 +6,11 @@
 
 | 标签 | 指向提交 | 说明 |
 |------|----------|------|
-| `snapshot/20260727` | `f53f281` | 2026-07-27：实例手机壳(下单/关键位/期权)、著作权声明、托管合同(一用户一机)、服务说明与报价说明 |
+| `snapshot/20260728` | `c73e363` | 2026-07-28：中控永期对冲计算器（由波动推仓位 / 由比例推点数）、说明文档 |
+| `snapshot/20260727` | `f53f281` | 2026-07-27：实例手机壳(下单/持仓/期权)、著作权声明、托管合同(一用户一机)、服务说明与报价说明 |
 | `snapshot/20260726-2` | `4a79e01` | 2026-07-26 午：执行手册脑图（业务主题）、`.xmind` 按二进制入库、去掉缩略图避免 Gitea raw 换行损坏 |
 | `snapshot/20260726` | `a2075ba` | 2026-07-26：Gate划转币种大写修复、系统设置划转页签停留、自动划转账户/币种下拉默认、期权「按可用余额打满」=min(余额,单笔预算)及说明 |
-| `snapshot/20260724` | `890659f` | 2026-07-24：执行手册v2(无对冲)、监控/策略页签显隐、内照明心期权档案同步、期权开平仓微信必发、实例导航显隐关键位/实盘下单等 |
+| `snapshot/20260724` | `890659f` | 2026-07-24：执行手册v2(无对冲)、监控/策略页签显隐、内照明心期权档案同步、期权开平仓微信必发、实例导航显隐持仓/实盘下单等 |
 | `snapshot/20260723-2` | `9e0591c` | 2026-07-23：策略对比页（合约/单期权/期期7:3）、监控与看板隐藏浮盈偏好、对比页卡片内边距等 |
 | `snapshot/20260723-pre-amp-stats` | `40be3a5` | 2026-07-23：振幅统计开发前；含执行手册进教练、日亏损冻结、手机监控 UI、振幅统计开发方案等 |
 | `snapshot/20260721-2` | `a721642` | 2026-07-21 晚：日亏损次数冻结、交易执行手册入中控策略说明、期权/Gate 执行手册文档等 |
@@ -32,7 +33,7 @@
 git tag -l 'snapshot/*'
 
 # 检出快照（只读查看，勿在此分支直接开发）
-git checkout snapshot/20260727
+git checkout snapshot/20260728
 
 # 回到主线
 git checkout main
diff --git a/docs/永期对冲计算器.md b/docs/永期对冲计算器.md
new file mode 100644
index 0000000..2e0b393
--- /dev/null
+++ b/docs/永期对冲计算器.md
@@ -0,0 +1,167 @@
+# 永期对冲计算器
+
+中控 **策略计算器** 第 3 个 tab：永期对冲。用于离线测算「永续 1 币 + 买方期权」在目标盈利口径下的期权仓位，或按永续:期权比例反推达目标所需波动点数。
+
+入口：中控 → 策略计算器 → **永期对冲**。  
+API：`POST /api/calculator/perp-options`  
+逻辑库：`lib/hub/hub_perp_options_calc_lib.py`  
+单测：`tests/test_hub_perp_options_calc_lib.py`
+
+与实例页「对冲计划」不同：本页**不实盘下单、不拉期权链**，价格与杠杆均为手填。
+
+---
+
+## 共同假设
+
+| 项 | 口径 |
+|----|------|
+| 品种 | BTC / ETH |
+| 永续仓位 | 固定 **1 币** |
+| 单币权利金 | `现价 / 期权杠杆`（例：1800÷100=18U） |
+| 权利金 | **按全亏**计入；忽略时间价值 / Theta |
+| 永续手续费 | 开+平各 `0.05%`（`PERP_TAKER_FEE_RATE`，默认 0.0005） |
+| 期权手续费 | **不算** |
+| 交易资金 | 仅参考：与 `现价/永续杠杆` 比保证金是否够开 |
+| `ct_mult` | 默认 0.01；张数 = 期权币数 / ct_mult |
+| 展示 | 金额与点数统一 **小数点后两位** |
+
+---
+
+## 模式一：由波动推期权仓位（`calc_mode=size`）
+
+已知波动（点数或波动率%）、目标盈利、期权杠杆 → 反推期权开多少币/张。
+
+### 公式
+
+```text
+单币权利金 = 现价 / 期权杠杆
+永续毛收益 = 波动点数 × 1
+           （波动率模式：现价 × 波动率% × 1）
+平仓价     ≈ 现价 + 波动点数（永续方向对按上涨测算）
+永续手续费 = (开仓名义 + 平仓名义) × 0.05%
+
+权利金预算 = 永续毛收益 − 目标盈利 − 永续手续费
+期权币数   = 权利金预算 / 单币权利金
+期权张数   = 期权币数 / ct_mult
+```
+
+若权利金预算 ≤ 0：提示「波动收益不足以覆盖目标盈利+手续费，无法开期权」。
+
+### 情景
+
+**A · 永续方向对（期权全亏）**
+
+```text
+净利 = 永续毛收益 − 权利金总额 − 永续手续费
+     （设计上 ≈ 目标盈利）
+```
+
+**B · 期权方向对（永续 1 币反向亏同等波动）**
+
+```text
+期权内在 = 期权币数 × 波动点数
+期权净利 = 期权内在 − 权利金总额
+永续亏损 = −永续毛收益
+组合净利 = 期权净利 + 永续亏损
+```
+
+### 手测示例
+
+现价 1800、波动 50 点、目标盈利 15、期权杠杆 100、永续杠杆 10：
+
+| 量 | 约值 |
+|----|------|
+| 单币权利金 | 18U |
+| 永续手续费 | 1.83U |
+| 权利金预算 | 33.18U |
+| 期权币数 / 张数 | ≈1.84 币 / ≈184 张 |
+| A 净利 | ≈15U |
+| B 期权净利 / 组合 | ≈59U / ≈9U |
+
+---
+
+## 模式二：由比例推波动点数（`calc_mode=points`）
+
+已知永续:期权比例（如 **1:2**）、目标盈利、期权杠杆 → 反推两套情景要涨/跌多少点才能达到目标。
+
+### 仓位
+
+```text
+永续币数 = 1
+期权币数 = 1 × (期权比例 / 永续比例)   # 1:2 → 2 币
+权利金总额 = 期权币数 × (现价 / 期权杠杆)
+```
+
+### 情景 A · 永续方向对
+
+净利 = 目标盈利：
+
+```text
+move − 权利金 − fee(move) = 目标
+fee(move) = (2×现价 + move) × 0.05%
+
+move = (目标 + 权利金 + 2×现价×0.05%) / (1 − 0.05%)
+```
+
+### 情景 B · 期权方向对（以组合净利为准）
+
+组合净利 = 目标盈利：
+
+```text
+组合 = 期权币数×move − 权利金 − 1×move
+     = move×(期权币数 − 1) − 权利金
+
+move = (目标 + 权利金) / (期权币数 − 1)
+```
+
+要求期权币数 > 永续币数（比例须使期权侧更重，如 1:2）；若为 1:1，组合恒为 −权利金，无法解出正目标。
+
+结果区展示：所需波动点数（及折合%）、组合净利、其中期权净利、其中永续盈亏。
+
+### 手测示例
+
+现价 1800、目标 15、期权杠杆 100、比例 1:2 → 权利金总额 36U：
+
+| 情景 | 所需点数（约） |
+|------|----------------|
+| A 永续方向对（净利=15） | ≈52.83 |
+| B 组合净利=15 | 51.00 |
+
+---
+
+## API 请求体（摘要）
+
+```json
+{
+  "calc_mode": "size | points",
+  "base": "ETH",
+  "spot": 1800,
+  "capital_usdt": 3000,
+  "target_profit_u": 15,
+  "move_mode": "points",
+  "move_value": 50,
+  "perp_leverage": 10,
+  "option_leverage": 100,
+  "ct_mult": 0.01,
+  "ratio_perp": 1,
+  "ratio_opt": 2
+}
+```
+
+- `size` 模式必填 `move_value`；`points` 模式用 `ratio_perp` / `ratio_opt`，可不填波动。
+
+---
+
+## 相关文件
+
+| 路径 | 作用 |
+|------|------|
+| `lib/hub/hub_perp_options_calc_lib.py` | 纯函数测算 |
+| `manual_trading_hub/hub.py` | `POST /api/calculator/perp-options` |
+| `manual_trading_hub/static/index.html` | 计算器 tab UI |
+| `manual_trading_hub/static/calculator.js` | 提交与结果渲染 |
+| `lib/trade/trade_fee_lib.py` | 永续双边手续费 |
+
+## 不做
+
+实盘开平仓、拉 OKX 期权链卖一、把本页结果自动写入对冲计划。