crypto_monitor/crypto_monitor_okx/更新文档.md

# 界面与风控更新说明（OKX 实例）

与 Gate / Binance 主站对齐的列表窗、统计分品类、交易记录展示、复盘与移动保本交易所同步；OKX 仍为 **三页导航**（交易执行 / 记录复盘 / 统计），关键位监控合并在 **交易执行** 页，**无** Gate 独立「关键位监控」页与斐波限价监控。

## 顶栏导航（3 项）

| 顺序 | 名称 | 路由 | 说明 |
|------|------|------|------|
| 1 | 交易执行 | `/trade` | 关键位监控 + 实盘下单（**默认首页** `/` → `/trade`） |
| 2 | 交易记录与复盘 | `/records` | 交易记录、复盘表单、AI 历史（受顶栏 UTC 时间窗筛选） |
| 3 | 统计分析 | `/stats` | 按北京时间交易日切日 + 分品类统计块 |

## 列表时间窗（UTC，全站顶栏）

共用模块：仓库根目录 `history_window_lib.py`（与 Gate / Binance 一致）。

| 项 | 说明 |
|----|------|
| 默认 | **UTC 当日**（`win_preset=utc_today`） |
| 可选 | 近 24 小时、近 7 天、自定义起止（UTC） |
| 作用范围 | 关键位历史、交易记录列表、复盘 API、AI 历史 API、导出「交易记录」「关键位历史」 |
| 与统计 | **仅影响列表/导出**；统计页仍按北京时间 `TRADING_DAY_RESET_HOUR`（默认 8:00）切日 |
| 切换 | 顶栏「列表筛选（UTC）」→ 应用（保留当前路由 query） |

## 交易记录与复盘

- 列表 **止损(开仓)**：展示 `initial_stop_loss` 快照（`display_open_stop_loss`）。
- 类型列显示 `monitor_type` 与 `key_signal_type`（若有）。
- 平仓入库：`stop_loss` / `initial_stop_loss` 为开仓止损快照；机器单 `entry_reason` 可按 `key_signal_type` 自动映射（箱体突破 / 收敛突破 → 四条固定关键位开仓类型文案）。
- 复盘：开仓类型下拉含四条关键位固定文案 +「其他」；离场触发含 **「止盈」**；从交易记录填入时按结果与信号预填。
- 复盘 K 线图：以 **平仓时间** 为锚点向前约 `ORDER_CHART_LIMIT`（默认 100）根（`_fetch_ohlcv_ending_at`）。
- `/api/journals`、`/api/reviews` 与顶栏 UTC 窗一致。

### 导出（交易记录 v3）

- 文件名：`trade_records_v3_YYYYMMDD.csv`
- 含 `key_signal_type`、`initial_stop_loss`、计划/实际 RR、`risk_amount` 等；末列「开仓类型」为有效展示文案。
- 受 UTC 列表窗限制；关键位历史导出同理。

## 实盘下单（交易执行页）

- **移动保本**：表单可勾选「启用移动保本」；触发阶梯上移后 **先撤后挂** 交易所 TP/SL（`replace_active_monitor_tpsl_on_exchange`），仅成功后才写库；企业微信提示含「交易所：已先撤后挂止盈止损」。未配置实盘 API 时仅更新本地止损。
- 开仓 TP/SL 仍通过 OKX `attachAlgoOrds`（与原有逻辑一致）；重挂使用 ccxt `stopLoss` / `takeProfit` 参数，触发价经 `_okx_algo_trigger_price_str` 格式化。

## 统计分析页（`/stats`）

| 项 | 说明 |
|----|------|
| 切日 | 北京时间；边界 = `TRADING_DAY_RESET_HOUR:00`（默认 8） |
| 品类下拉 | 全部交易、下单监控、关键位箱体突破、关键位收敛结构、关键位斐波0.618、关键位斐波0.786 |
| URL | `stats_segment=`（`all` / `manual` / `key_box` / `key_conv` / `key_fib618` / `key_fib786`） |
| 与 UTC 窗 | 统计 **不** 随顶栏列表窗变化 |

## 斐波关键位监控（与 Gate / Binance 对齐）

| 项 | 说明 |
|----|------|
| 类型 | **斐波回调0.618**、**斐波回调0.786**（交易执行页关键位表单） |
| 同币互斥 | 每币仅一条斐波监控 |
| 挂单价 E | 做多 `E = H − ratio×(H−L)`；做空 `E = L + ratio×(H−L)`；SL/TP 为 L/H |
| 添加后 | 立即在 OKX 挂限价单；卡片显示 **挂E**、限价单 ID |
| 失效 | 标记价触达止盈侧且限价未成交 → 仅撤本条限价单（`cancel_fib_limit_order`） |
| 成交后 | 挂交易所 TP/SL → 写入 `order_monitors`（`monitor_type=关键位监控`，`key_signal_type=斐波回调…`）→ 从关键位表移除 |
| 轮询 | `check_fib_key_monitors()`（与箱体/收敛 `check_key_monitors()` 分离） |
| 盈亏比 | 计划 RR 须 > `KEY_AUTO_MIN_PLANNED_RR`（默认 1.5） |
| 日成交量 | 排名前 `KEY_DAILY_VOLUME_RANK_MAX`（默认 30） |

计算逻辑见仓库根目录 `fib_key_monitor_lib.py`。

## 与 Gate 的差异（其余）

- 无独立「关键位监控」导航页（斐波在 **交易执行** 页添加）。
- 箱体/收敛与 Gate/Binance 相同：**门控 + RR 达标后自动市价开仓**（须 `LIVE_TRADING_ENABLED=true`）。

## 交易所已实现盈亏（与 Gate 一致）

- 打开 **交易执行 / 交易记录** 等主页面时，若已配置 `OKX_API_KEY` / `OKX_API_SECRET` / `OKX_API_PASSPHRASE`（只读即可），同进程约 **25 秒**内最多调用一次 OKX **历史仓位**（`fetch_positions_history`），为未写入 `exchange_sync_key` 的记录匹配并回填 `exchange_realized_pnl`。
- 复盘列表盈亏优先展示交易所 U（旁标 **所**）；本地公式估算标 **估**；人工复核优先。
- 手动强制同步：`GET /api/sync_exchange_pnl`（需登录）。
- 可选 `.env`：`EXCHANGE_POSITION_SYNC_FROM_BJ`（北京时间起点）、`EXCHANGE_POSITION_HISTORY_LIMIT`（默认 200）。

## 企业微信推送（与 Gate 对齐）

- 平仓：`📉 … 平仓完成` 模板（盈亏 ±X.XX U、价位两位/按币价精度、账户资金 2 位小数）。
- 开仓成功：与 Gate 相同的 emoji 分段（条件委托状态文案、RR/张数/名义 2 位小数）。
- 移动保本：仅首次触发推送；交易所同步失败同一监控单只告警一次。
- 斐波/关键位/划转等推送数值格式与 Gate 一致（`format_wechat_scalar_2dp`）。

## 配置与部署

- 详见 `.env.example` 中 OKX（`OKX_*`）与通用风控项。
- 代码更新后请 **重启 OKX 监控进程**；旧库行不做批量回填，展示字段有则用之、无则回退。