crypto_monitor/docs/更新文档.md

更新文档（仓库级）

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

---

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= 缓存等，见会话审计清单，不在本条范围。