crypto_monitor/docs/更新文档.md

更新文档（仓库级）

自 2026-07-16 起：凡修改或更新功能，必须在本文件追加一条记录，写明原因、改动位置、目标与交付验收。实例目录下旧版说明可保留，但共享逻辑（lib/）以本文为准。

---

2026-07-19 · 期权复盘详情改为对话框 + 截图显示修复

修改原因

复盘详情嵌在列表下方不便查看；截图缩略图易裁切/偶发加载失败。

修改的地方

文件	改动摘要
options_review_panel.html	详情改为居中对话框；2×2 截图网格
options_review.js	点复盘记录打开弹窗；截图 basename + onerror
options_review_register.py	截图静态路由不强制登录(防 iframe 401)

交付之后的验收

点「复盘记录」行弹出对话框；5m/15m/1h/4h 截图完整可见(缺失显示提示)；关闭/Esc/点遮罩可关。

---

2026-07-19 · 期期情景测算：盈亏配色 + 盈亏比(亏=全额保费)

修改原因

情景弹窗合计无红绿区分；需要一眼看盈亏，并按「最大亏损=权利金全亏」给出上破/下破盈亏比。

修改的地方

文件	改动摘要
hedge_plan.js	合计/腿盈亏用 hp-pnl-pos/neg；摘要显示盈亏比
hedge_plan_calc_lib.py	summary 增加 rr_at_up / rr_at_down / rr_risk_premium

交付之后的验收

正数为绿、负数为红；摘要可见「盈亏比 上破 x:1 / 下破 y:1（亏=全额保费）」。

---

2026-07-19 · 修复期期「按张数」拆分：用同张数总张数 2n

修改原因

sheets 口径误把同张数每腿 n 当总张数拆，规模偏小；应对齐「先算完同张数两侧合计总张数 2n，再按比例拆」。

修改的地方

文件	改动摘要
hedge_plan_calc_lib.py / hedge_plan.js	total = n_same * 2 再拆
相关 docs / env 文案	口径说明改为总张数 2n

交付之后的验收

同张数 n=5 时，sheets+做空(0.7) → Put 7 / Call 3（合计 10）。

---

2026-07-19 · 期期张数：做多/做空替代均分 + env 拆分口径

修改原因

期期「均分」与方向偏好无关；需要按 Call/Put 7:3（可配）做偏多/偏空自动张数，并可用 env 在「预算金额 / 张数」两种拆法间切换。

修改的地方

文件	改动摘要
lib/hedge_plan/hedge_plan_calc_lib.py	long_bias/short_bias；budget/sheets + bias_ratio
lib/hedge_plan/hedge_plan_register.py	gates 下发 oo_bias_split_by / oo_bias_ratio
lib/hedge_plan/templates/hedge_plan_panel.html	张数段：同张数 / 做多 / 做空
lib/common/static/hedge_plan.js	前端建议张数与 env 同步
crypto_monitor_okx/.env.example + env UI/schema	HEDGE_PLAN_OO_BIAS_SPLIT_BY、HEDGE_PLAN_OO_BIAS_RATIO
docs/系统说明.md 等	同步操作与配置说明

达成的目标

1. 默认仍为同张数。
2. 做多=Call 主占比、做空=Put 主占比；默认比例 0.7，口径默认预算金额。
3. sheets 口径：先算同张数每腿 n，总张数 2n 再拆（见上一条修正）。

交付之后的验收

1. 期期页可见「同张数 / 做多 / 做空」，无「均分」。
2. env 配置可改口径与比例；生产 OKX .env 已补齐键。
3. 选一 Call 一 Put 后自动张数符合比例；非 C+P 时提示。

---

2026-07-17 · 修复 pip>=26 部署依赖安装失败

修改原因

单所验证时 setup_env 升级到 pip 26 后,--progress-bar ascii 非法,依赖安装中断;腾讯源偶发空索引也会导致一次失败.

修改的地方

文件	改动摘要
deploy/lib/common.sh	pip_progress_bar_arg 改为 on(兼容 pip 26);pip install 加 --retries 5

达成的目标

非 TTY / SSH 下一键安装可顺利 pip install -r.

交付之后的验收

bash deploy/lib/install.sh --exchange okx 能过依赖安装并起 crypto_okx.

---

2026-07-17 · 一键部署支持单所仅实例(不含中控)

修改原因

新机或专用机只需跑某一所 Flask 时,全套 7 进程过重;希望菜单可直接选「仅 OKX / Binance / Gate」,不起中控与 agent.

修改的地方

文件	改动摘要
deploy/manage.sh	菜单增加 4/5/6 单所实例入口
deploy/lib/install.sh	--exchange okx|binance|gate 单所流水线
deploy/pm2_start_all.sh	--only 只启对应 ecosystem
deploy/lib/common.sh	单所验收 / 完成提示 / 辅助映射
deploy/README.md	菜单说明

达成的目标

1. 选 4/5/6: setup_env --only <所> + 仅启动该所 PM2,不含 hub/agent.
2. 选 1: 全套行为与改前一致.
3. 仍共用整仓 /opt/crypto_monitor,不拆仓库.

交付之后的验收

1. 菜单可见 4/5/6.
2. bash deploy/lib/install.sh --exchange okx 后仅 crypto_okx 起来,:5004 可访问.
3. 全套选项 1 仍可部署三所+中控.

---

2026-07-17 · 永续估算盈亏统一扣双边 taker 手续费

修改原因

中控/实例「盈利金额」、微信推送「本单盈亏」、交易记录 pnl_amount 使用价差毛利，未扣开平手续费，与交易所实际净盈亏及盈亏比体感偏差较大。

定稿口径

项	约定
浮盈亏	仍读交易所，不改
费率	taker 单边 0.05%（PERP_TAKER_FEE_RATE，默认 0.0005），开+平双边
净盈亏	毛利 − 开仓名义×费率 − 平仓名义×费率（不考虑滑点）
RR	净盈利 / 原风险（风险侧加费第二步再做）
历史记录	不回算

修改的地方

文件	改动摘要
lib/trade/trade_fee_lib.py	新增公共扣费 / 净盈亏
lib/strategy/strategy_roll_ui_lib.py	reward_at_tp_usdt → 净盈利
lib/strategy/strategy_roll_lib.py	同上
lib/strategy/strategy_trend_lib.py	calc_tp_profit_usdt → 净盈利
lib/hub/hub_calculator_lib.py	滚仓预览止盈盈利 / 首仓盈利扣费；RR 跟净盈利
crypto_monitor_okx/app.py	calc_pnl → 净盈亏（推送/记账）
crypto_monitor_gate/app.py	同上
crypto_monitor_binance/app.py	calc_pnl / 成交回退扣费；income 真费路径优先不改
tests/test_trade_fee_lib.py	新增
tests/test_strategy_roll_ui_lib.py	断言改净额
tests/test_order_monitor_display_lib.py	断言改净额

达成的目标

1. 中控持仓「盈利金额」、实例「盈利金额」、计算器止盈盈利、趋势/滚仓预览一致为净盈亏。
2. 微信推送与新建交易记录的 pnl_amount 与上述估算口径一致。
3. 币安若能拉到 income 净额（已含真实手续费）仍优先用交易所数。
4. 浮盈亏展示仍跟交易所。

交付之后的验收

1. 同一笔持仓：中控盈利金额 ≈ 实例盈利金额（均为扣费后）。
2. 平仓推送「本单盈亏」与新写入记录接近，不再明显大于交易所净利。
3. 浮盈亏与交易所 App 一致（本改不动）。
4. 单测：python -m unittest tests.test_trade_fee_lib tests.test_strategy_roll_ui_lib tests.test_order_monitor_display_lib tests.test_trend_preview_tp -v 通过。

---

2026-07-16 · 计算器左侧 Tab + 三行输入

修改原因

电脑端顶部横向 Tab 与纵向表单不协调，输入项行数偏多。

修改的地方

文件	改动摘要
manual_trading_hub/static/index.html	增加计算器工作区容器，更新 CSS 缓存
manual_trading_hub/static/app.css	电脑端 Tab 改为左侧竖排；≥1200px 基础输入改为五列、三行排列

达成的目标

电脑端左侧切换计算器，右侧集中填写；宽屏基础输入压缩为三行。

交付之后的验收

1. 电脑端两个计算器 Tab 位于左侧。
2. 1920px 宽屏基础输入区为三行。
3. Tab 切换和计算功能正常；手机端保持原布局。

---

2026-07-16 · 电脑端计算器改为 Tab 切换

修改原因

电脑端同时并排显示趋势回调与滚仓计算器，横向空间利用和操作聚焦不理想。

修改的地方

文件	改动摘要
manual_trading_hub/static/index.html	计算器 Tab 增加电脑端完整名称，更新 CSS 缓存
manual_trading_hub/static/app.css	电脑端显示 Tab、单列展示当前计算器；手机端沿用原紧凑 Tab

达成的目标

电脑端通过「趋势回调计算器 / 滚仓计算器」Tab 切换，一次只显示一个计算器。

交付之后的验收

1. 电脑端默认显示趋势回调计算器。
2. 点击滚仓计算器 Tab 后只显示滚仓计算器，切回正常。
3. 手机端原有计算器 Tab 样式和交互不变。

---

2026-07-16 · 资金概况移除累计盈亏长条

修改原因

「同步快照」后方的累计盈亏长条与下方汇总卡片重复，占用横向空间。

修改的地方

文件	改动摘要
manual_trading_hub/static/index.html	删除资金工具栏中的累计盈亏/较昨日长条

达成的目标

资金概况工具栏仅保留「同步快照」和状态信息，累计盈亏继续由下方汇总卡展示。

交付之后的验收

1. 「同步快照」按钮后不再显示累计盈亏长条。
2. 下方累计盈亏、较昨日汇总卡数据正常显示。

---

2026-07-16 · 今日统计默认折叠 + 交易所标题行下移

修改原因

今日统计常占一行挤空间;默认只需看总浮盈亏。交易所卡标题/打开实例贴顶过紧。

修改的地方

文件	改动摘要
manual_trading_hub/static/app.js	今日统计默认折叠只露总浮盈亏;展开显示明细;状态写入 localStorage
manual_trading_hub/static/app.css	折叠/展开样式;展开后明细字号加大;分栏卡 card-head 上内边距加大
manual_trading_hub/static/index.html	缓存 20260716-hub-stats-fold

达成的目标

监控区默认更省高;需要时一键展开更大明细;交易所标识行不再贴顶。

交付之后的验收

1. 默认只见「今日统计 + 总浮盈亏」与「展开明细」。
2. 点展开后六项明细可见且数字更大。
3. OKX/币安等卡标题与按钮相对顶边有更明显间距。

---

2026-07-16 · 监控芯片还原 + 底栏贴底 + 1080p 留白

修改原因

「监控位」本意是原先关键位/趋势回调/顺势加仓芯片,不是单独「无监控位」槽;全屏提示须贴卡片最底;1920×1080 两侧需留白,带鱼屏保持现宽。

修改的地方

文件	改动摘要
manual_trading_hub/static/app.js	去掉错误的监控位槽;恢复策略芯片(仍隐藏期权 N仓)
manual_trading_hub/static/app.css	分栏卡 card-expand-hint margin-top:auto 贴底;≤2000px 加大左右留白,>2000px 保持 1860 内容宽
manual_trading_hub/static/index.html	缓存 20260716-hub-chips-margin

达成的目标

有关键位/趋势/顺势时仍以芯片显示;提示条在卡底;1080p 两侧有留白,带鱼屏观感不变。

交付之后的验收

1. 无「监控位 · 0 / 无监控位」区块;有关键位等时出现原芯片样式。
2. 「点击标题栏进入全屏…」贴在各分栏卡最底部。
3. 1920×1080 内容两侧留白明显;带鱼屏内容宽度仍约 1860。

---

2026-07-16 · 监控区 2×2 细化(目标监控列/预留行/去平板专属)

修改原因

四卡对齐后需：左右等宽；期权表改目标监控列；去掉打开期权页与永续卡「期权 N仓」；合约卡预留仓位+监控位两行并统一全屏提示；多仓时同行左右一起长高；平板改用浏览器 80% 缩放，去掉 hub-tablet 专属样式（手机 UI 不动）。

修改的地方

文件	改动摘要
manual_trading_hub/static/app.js	平铺 monitor-split-2x2；期权表删指数/到期平衡/平掉回本，加目标监控列(有=绿/无=—)；去打开期权页；永续卡隐藏期权徽章；预留仓位/监控位槽；去掉 isTabletLayout
manual_trading_hub/static/app.css	左右 1:1；minmax(min-content,1fr) 同行同高可外扩；删除全部 hub-tablet 规则
manual_trading_hub/static/index.html	缓存 20260716-hub-2x2-slots

达成的目标

桌面监控区四卡等宽对齐；期权看目标监控列；永续卡结构为仓位行+监控位行+提示行；≥2 仓左右一起加高；平板不再走单独 CSS。

交付之后的验收

1. 左右列等宽；永续卡无「期权 1仓」、无「打开期权页」。
2. 期权表有「目标监控」列，有监控绿色、无则 —；无指数/到期平衡/平掉回本。
3. 永续/币安卡可见预留仓位行、监控位行与完整全屏提示文案。
4. 多开仓后该行变高且左右同高；body 无 hub-tablet；手机布局未改。

---

2026-07-16 · OKX 拆成永续/期权双卡(2×2 对齐)

修改原因

OKX 单卡内嵌永续+期权过高，右侧币安/Gate 两卡对不齐，1080p 观感不协调。按产品建议改为四卡对齐。

修改的地方

文件	改动摘要
manual_trading_hub/static/app.js	期权分栏时 OKX 渲染为「·永续」「·期权」两张独立卡；标题与操作按钮按卡片分流
manual_trading_hub/static/app.css	左右列均 1fr/1fr，四卡 2×2 等高对齐；卡体内滚
manual_trading_hub/static/index.html	静态资源缓存 20260716-hub-okx-2x2

达成的目标

监控区呈现：左上永续 / 左下期权 / 右上币安 / 右下 Gate，四卡对齐。

交付之后的验收

1. 桌面监控区可见 OKX_趋势 · 永续 与 OKX_趋势 · 期权 两张独立卡。
2. 四卡与右侧币安、Gate 同行等高，不再一大两小。
3. 点击任一张 OKX 卡标题仍可全屏；期权卡「全平」不重复出现。

---

2026-07-16 · 1080p 监控区无持仓空洞收紧

修改原因

1920×1080 上一屏适配用 1fr/1fr 把永续/分所空卡强行均分拉高，「无持仓」下方大片空洞；带鱼屏尚可，短屏观感差。

修改的地方

文件	改动摘要
manual_trading_hub/static/app.css	OKX 内卡改为 auto + 1fr（永续按内容、期权吃剩余）；右侧 Gate/币安改为 auto auto 按内容收紧；1080p 短屏左侧略加宽
manual_trading_hub/static/index.html	CSS 缓存 20260716-hub-1080-tight

达成的目标

无持仓区块不再被拉成半屏空黑；有期权/持仓的区域拿到更多可视高度。

交付之后的验收

1. 1920×1080 监控区：永续「无持仓」仅占内容高度，期权表区域明显变高。
2. 右侧币安/Gate 无仓时卡片贴内容，不再卡片内大片空洞。
3. 带鱼屏布局仍可用；持仓变多时右侧列可内滚。

---

2026-07-16 · 电脑端误判平板导致发糊

修改原因

isTabletLayout() 曾用「高度 ≤920 即平板」；1080p 电脑有任务栏/浏览器栏时 innerHeight 常落在此区间，桌面被套上平板压缩字号（约 10px），观感发糊发虚。

修改的地方

文件	改动摘要
manual_trading_hub/static/app.js	平板判定改为横屏 721–1366 × ≤900 / 竖屏 ≤920 × ≥900；去掉仅按高度命中
manual_trading_hub/static/index.html	JS 缓存 20260716-hub-desktop-clear

达成的目标

常规电脑端不再误加 hub-tablet，恢复桌面字号与清晰度；真平板视口仍走一屏密度样式。

交付之后的验收

1. 1080p/1440p 电脑打开中控，正文与表格清晰，非异常小字。
2. 浏览器开发者工具确认 body 无 hub-tablet（窄窗模拟平板除外）。
3. 平板横/竖仍为一屏密度布局。

---

2026-07-16 · 平板一屏密度适配(不裁切)

修改原因

平板字号偏大、留白空、卡片半截裁切或底部大片空黑，显得 low；需要「一屏看完」且正文不被拦腰裁掉。

修改的地方

文件	改动摘要
manual_trading_hub/static/app.css	hub-tablet：锁 100dvh；压缩字号/间距；监控区 flex 填满；竖屏 OKX 上 + Gate/币安并排；表体内滚兜底；资金页缩曲线、压汇总数字、分户卡完整可见
manual_trading_hub/static/index.html	CSS 缓存 20260716-hub-tablet-onescreen

达成的目标

平板监控区/资金概况一屏呈现、信息密度接近桌面；常规持仓与分户名称/余额不被裁半；持仓很多时仅表体内滚。

交付之后的验收

1. 平板强制刷新后，监控区三所卡片同屏，余额与持仓列完整可读。
2. 资金概况：四格汇总 + 曲线 + 分户卡同一屏，账户名不被切半。
3. 底部不再大片空黑；桌面大屏一屏规则不受影响。

---

2026-07-16 · 平板监控卡片内容裁切修复(已由一屏密度方案取代)

先前改为整页可滚以避免裁切；用户要求改为「一屏 + 不裁切 + 提密度」，由上一条覆盖。

---

2026-07-16 · 中控平板一屏适配(2560×1600)

修改原因

平板物理分辨率 2560×1600 在 2× 缩放下 CSS 视口约为 1280×800，进不了此前桌面规则 min-width:1600px，监控/行情/资金仍整页滚动。

修改的地方

文件	改动摘要
manual_trading_hub/static/app.js	新增 isTabletLayout()；hub-tablet body class
manual_trading_hub/static/app.css	一屏适配门槛降为 min-width:721px + min-height:650px；另增平板矮/窄视口加密度规则
manual_trading_hub/static/index.html	缓存版本 20260716-hub-fit-tablet

达成的目标

平板（含 2560×1600@2x）与桌面一样：监控区 / 行情区 / 资金概况尽量一屏、无整页下拉。

交付之后的验收

1. 平板横屏打开中控，强制刷新后 body 应有 hub-tablet（开发者工具）。
2. 监控区（OKX 一期权 ± 永续空/一仓，另两所各 ≤1 仓）：无整页纵向滚动。
3. 行情区、资金概况同屏无整页滚动。
4. 手机（≤720px）仍走 hub-phone，不受影响。

---

2026-07-16 · 中控三页 1920×1080 一屏显示

修改原因

监控区在 OKX「一永续 + 一期权」、另两所各一仓（或空仓）时，以及行情区、资金概况在 1920×1080 下出现整页纵向滚动，无法一屏看完。

修改的地方

文件	改动摘要
manual_trading_hub/static/app.js	setActiveNav 增加 hub-page-monitor / hub-page-market body class
manual_trading_hub/static/app.css	@media (min-width:1600px) and (min-height:900px) 一屏适配：壳层 100dvh 不滚动；三页 flex 填满；监控卡片/表格压缩；行情 K 线区 flex 吃剩余高度；资金曲线与分户区压缩
manual_trading_hub/static/index.html	app.css / app.js 缓存版本 20260716-hub-fit-1080

未改： 期权开平仓规则、实例交易页、手机端 hub-phone 布局。

达成的目标

1. 监控区：桌面大屏下整页无纵向滚动；OKX 左右分栏（永续+期权）与 Binance/Gate 同屏可见。仓位表过长时仅卡片内部滚动。
2. 行情区：工具条 + K 线同屏，图表占满剩余高度。
3. 资金概况：统计卡 + 曲线 + 三分户同屏。

交付之后的验收（1920×1080，浏览器缩放 100%）

1. 打开中控监控区：服务器状态与操作栏保持折叠时，页面无浏览器纵向滚动条；OKX 期权 1 仓 + 另两所空仓/各 1 仓均一屏可见。
2. 行情区：加载 BTC 日线后，OHLCV + 图在一屏内，无整页滚动。
3. 资金概况：曲线与三分户卡片同屏，无整页滚动。
4. 窄屏/手机（hub-phone）布局不受影响。
5. 展开「服务器状态」后若内容过高，允许监控网格内部滚动，仍尽量避免整页滚动。

---

2026-07-16 · 期权/对冲开仓仅认真实卖一深度

修改原因

此前报价在无盘口卖一时会用标记价顶进 ask，界面仍显示「限价买入 @ 卖一」，造成误以为在吃卖一；深度实值合约还容易「链上有 ~ 价、点选却失败或按估算价下单」。需要与产品规则对齐：开仓只吃真实卖一，且必须有卖一量。

修改的地方（明确清单）

文件	改动摘要
lib/exchange/okx_options_lib.py	新增 option_buy_liquidity_ok / cap_option_buy_sheets_to_ask_depth；quote_option_contract 不再用 mark 填充开仓 ask；返回 can_open / ref_ask / open_block_msg / ask_source
lib/options/options_register.py	/api/options/quote 开仓 sizing 仅在 can_open 时计算，张数 cap 到卖一深度；/api/options/open 服务端再验深度并 cap 张数
lib/common/static/options_panel.js	面板展示参考标记价；无深度禁用开仓按钮与说明文案；开仓前校验 can_open
lib/options/templates/options_panel.html	提示文案；增加「参考标记价」字段；脚本 ?v=37
lib/hedge_plan/hedge_plan_orders_lib.py	仅 _buy_option（买入开仓）同步深度门禁与张数 cap；未改 _sell_option 平仓
lib/hedge_plan/templates/hedge_plan_panel.html	单位说明补充开仓规则
tests/test_option_buy_liquidity.py	新增门禁/深度 cap 单测
tests/test_hedge_plan_orders.py	mock 补 ask_sz；无深度拒绝 / 深度 cap 用例

铁律：未改动任何平仓规则（期权买一平仓、_sell_option、close_preview / close 执行路径逻辑保持原样；报价里买一仍可用 mark 补展示，仅服务平仓读 bid）。

达成的目标

1. 开仓条件：askPx 有效 且 askSz > 0。
2. 无卖一/无深度：可展示参考标记价 ref_ask/mark，明确「不可用于开仓」，按钮禁用。
3. 有深度时：限价买 @ 真实卖一；张数不超过卖一深度（向下取整）。
4. 期权面板与对冲计划买入路径规则一致。

交付之后的验收

1. 有卖一深度：选合约 → 卖一显示 价/量 → 按钮「限价买入 @ 卖一」可点 → 下单张数 ≤ 卖一量。
2. 无卖一或深度为 0：卖一为 —；参考标记价显示 ~xx (不可开仓)；红色说明含「仅供参考,不可用于开仓」；按钮为「暂无卖一深度,无法开仓」且不可点；直接调 open API 应返回失败文案。
3. 链上 ~ 估算：仍可浏览；点选后若无真实深度，不得用估算价成交。
4. 平仓：持仓「买一平仓」行为与改前一致（抽测一条即可）。
5. 对冲计划：执行买入腿时无深度应失败并提示；有深度 dry_run/实盘张数不超过卖一量。
6. 单测：python -m pytest tests/test_option_buy_liquidity.py tests/test_hedge_plan_orders.py -q 通过。

未纳入本次（另单）

硬刷新链可能毁掉下单面板、限频 fallback tick、CSS ?v= 缓存等，见会话审计清单，不在本条范围。