# 更新文档（仓库级）

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

---

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