crypto_monitor/docs/更新文档.md

更新文档（仓库级）

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

---

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