# 更新文档（仓库级）

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

---

## 2026-07-16 · 平板监控卡片内容裁切修复

### 修改原因

平板一屏适配用 `overflow:hidden` + 均分 `1fr/1fr` 行高，把永续/期权/分所卡片内容裁掉，表格与余额显示不全。

### 修改的地方

| 文件 | 改动摘要 |
|------|----------|
| `manual_trading_hub/static/app.css` | `hub-tablet` 下取消强裁切：卡片/内卡 `overflow:visible`，行高改 `auto`，允许整页滚动；恢复可读字号；去掉过度压缩的平板加密度块 |
| `manual_trading_hub/static/index.html` | CSS 缓存 `20260716-hub-tablet-noclip` |

### 达成的目标

平板上监控区/资金卡片内容完整可见；空间不够时整页可滚，不再把字和表格裁没。

### 交付之后的验收

1. 平板强制刷新后，OKX 永续+期权、Binance/Gate 卡片余额与持仓表完整可见。  
2. 期权表列（合约/张数/盈亏等）不被裁切。  
3. 桌面 1920×1080 一屏规则仍可用（无 `hub-tablet` 时）。

---

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