dekun/crypto_monitor
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2f7e6355a1b389ec2a8bd1c9fbfe186515be795c
crypto_monitor/docs/更新文档.md
T
dekun 041692a763 Retry pip installs during deploy to tolerate flaky mirrors. 
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-17 16:02:51 +08:00

465 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 更新文档（仓库级）
自 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=` 缓存等，见会话审计清单，不在本条范围。
Reference in New Issue View Git Blame Copy Permalink