# 行情区(K 线)说明

中控 **行情区** `/market` 提供多交易所 K 线查看:按需拉取,本地 SQLite 缓存,可选技术指标与持仓价格线.数据经各实例 Flask 的 `/api/hub/ohlcv`(底层 `hub_ohlcv_lib` + ccxt)获取.

相关代码:`manual_trading_hub/static/chart.js`,`hub_kline_store.py`(仓库根目录),`hub.py` 的 `/api/chart/*`.

---

## 1. 入口与导航

| 方式 | 说明 |
|------|------|
| 顶栏 **行情区** | 打开 `/market` |
| 监控区持仓 | 点击合约名(**打开行情区**)→ 跳转 `/market?exchange_key=...&symbol=...`,并带入入场/止损/止盈等标记(`sessionStorage`) |
| 全屏工具条 | K 线全屏时可在顶部切换交易所,币种,周期并 **加载** |

---

## 2. 支持的周期

下拉框与后端 `CHART_TIMEFRAMES` 一致:

| 周期 | 数字快捷键(分钟) |
|------|-------------------|
| 1m | `1`(稍停或 Enter 确认;连按 `1`→`5` 为 15m) |
| 5m | `5` |
| 15m | `15` |
| 1h | `60` |
| 2h | `120` |
| 4h | `240` |
| 12h | `720` |
| 1d | `1440` |
| 1w | `10080` |

- 快捷键仅在行情页,且焦点不在输入框/下拉框时生效.
- **全屏**:按 **`F`** 切换;全屏时 **`Esc`** 退出.
- 无效或已移除的周期(如 URL 带 `6h`)会回退为默认 **5m**.

---

## 3. 数据拉取与本地库

| 项 | 说明 |
|------|------|
| **策略** | 先读本地库,不足或过期则向对应实例拉取并写入库;Hub **后台轮询** 增量更新尾部 K 线 |
| **库文件** | 默认 `manual_trading_hub/data/hub_kline.db`(不纳入 Git) |
| **保留** | 默认 **15 天**(`HUB_KLINE_RETENTION_DAYS`),每次请求顺带清理更早数据 |
| **根数** | 日内周期约 **1000** 根;`1d` / `1w` 约 **500** 根 |
| **刷新** | Hub 约 **5 秒** 轮询:① 监控区**有持仓**的合约(默认周期 `5m`)② 行情页 **watch** 的交易所+币种+周期(页面打开时每 25s 续期).浏览器经 **SSE** 收 `chart_version` 后拉 `/api/chart/ohlcv`.**加载** 读库;**强制刷新** 全量重拉 |
| **分页** | OKX/Gate 等单次常限 ~300 根,中控会自动分页补全 |
| **12h** | 若交易所无原生 12h 或 K 线间隔异常,会从 **1h** 聚合生成 |

环境变量(`manual_trading_hub/.env`):

```bash
# HUB_KLINE_RETENTION_DAYS=15
# HUB_KLINE_DB_PATH=/opt/crypto_monitor/manual_trading_hub/data/hub_kline.db
# HUB_CHART_POLL_INTERVAL=5
# HUB_CHART_POSITION_TIMEFRAME=5m
# HUB_CHART_WATCH_TTL_SEC=45
```

---

## 4. 图表功能

- **主图**:K 线 + 成交量(Lightweight Charts).
- **价格轴**:「自动」切换是否跟随最新价缩放.
- **技术指标**(可选勾选):EMA 21/55,MACD,RSI(含 30/70 参考线);副图自上而下为 MACD,RSI.
- **持仓标记**(从监控跳转时):展示入场,止损,止盈,张数,**浮盈亏**(约 5 秒随监控快照刷新),委托摘要;K 线上绘制对应价格线.趋势回调若止盈为程序监控,止盈栏显示「程序监控」且不与止损同价误显.
- **趋势保本移交**:移交到下单监控后,持仓卡止盈/止损与「交易所止盈止损」与实例 **下单监控** 计划价一致(不再清空为程序监控占位);交易所仅市价只减仓单时也会按价格推断展示.
- **拖动止损线**:鼠标靠近红色止损线(⟷)可上下拖动;松手确认后调用与监控区相同的 **挂止盈/止损** API(先撤全部条件单再挂新止损+止盈).须已有有效止盈价(交易所条件单或计划止盈);仅改止损,不改止盈时止盈价沿用当前上下文.
- **背离**:MACD/RSI 与价格简易背离标注(箭头 + 图例说明).

---

## 5. HTTP API(中控)

须登录(与监控区相同,`/api/ping` 等白名单除外).

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/chart/meta` | 已启用交易所列表,周期列表,各周期 limit,保留天数 |
| GET | `/api/chart/ohlcv` | 查询参数:`exchange_key`,`symbol`,`timeframe`,可选 `refresh=1` 强制刷新 |
| POST | `/api/chart/watch` | 行情页订阅(JSON:`exchange_key`,`symbol`,`timeframe`),45s 内需续期 |
| POST | `/api/chart/unwatch` | 离开行情页取消订阅 |
| GET | `/api/chart/stream` | SSE:`event: chart`,含 `chart_version` 与各 `series` 版本 |
| GET | `/api/chart/poll/meta` | 当前轮询状态与各 series 版本 |

实例侧(中控转发):

| 路径 | 说明 |
|------|------|
| GET | `/api/hub/ohlcv` | 各 `crypto_monitor_*` 经 `hub_bridge` 注册;参数 `symbol`,`timeframe`,`since_ms`,`limit` |

---

## 6. 部署与升级注意

1. **hub** 与 **三实例 Flask** 均需 `git pull` 到含 `hub_ohlcv_lib.py`,`hub_kline_store.py` 的版本.
2. 重启:`pm2 restart manual-trading-hub` 及 `crypto_binance`,`crypto_okx`,`crypto_gate`,``(名称以你环境为准).
3. 浏览器 **强刷**(`chart.js` 带版本 query,避免旧前端缓存).
4. 周期或拉取逻辑升级后,对异常图表点一次 **强制刷新**,必要时可删 `data/hub_kline.db` 后重拉(会丢失本地缓存,不影响策略库).

回滚标签说明见 [SNAPSHOT_ROLLBACK.md](./SNAPSHOT_ROLLBACK.md).

---

## 7. 常见问题

| 现象 | 处理 |
|------|------|
| 只显示约 300 根 | `git pull` 实例与 hub,强制刷新;确认 `hub_ohlcv_lib` 已含分页逻辑 |
| 12h 错乱或过少 | 强制刷新;Gate 等无原生 12h 时依赖 1h 聚合,需实例 OHLCV 正常 |
| 周期下拉无某项 | 以当前 `CHART_TIMEFRAMES` 为准;已移除 3m/10m/20m/30m/6h/8h 等 |
| 快捷键无效 | 确认在行情页;全屏用 **F**;数字键勿在币种输入框内按 |
| 持仓线不显示 | 须从监控区点击合约进入;或清除标记后重新跳转 |

更多中控共性问题见 [常见问题.md](./常见问题.md).

---

## 8. 文档索引

| 文档 | 内容 |
|------|------|
| [使用说明.md](./使用说明.md) | 中控总览(含行情区摘要) |
| [行情区说明.md](./行情区说明.md) | 本文 |
| [部署文档.md](./部署文档.md) | PM2 / 反代 / 验收 |
| [.env.example](./.env.example) | `HUB_KLINE_*` 等变量 |
