# 行情区（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. 数据拉取与本地库

| 项 | 说明 |
|------|------|
| **策略** | 先读本地库，不足或过期则向对应实例拉取并写入库；无后台定时全量同步 |
| **库文件** | 默认 `manual_trading_hub/data/hub_kline.db`（不纳入 Git） |
| **保留** | 默认 **15 天**（`HUB_KLINE_RETENTION_DAYS`），每次请求顺带清理更早数据 |
| **根数** | 日内周期约 **1000** 根；`1d` / `1w` 约 **500** 根 |
| **刷新** | 约 **5 秒** 自动刷新最新一根；**加载** 用缓存；**强制刷新** 忽略缓存重拉 |
| **分页** | 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
```

---

## 4. 图表功能

- **主图**：K 线 + 成交量（Lightweight Charts）。
- **价格轴**：「自动」切换是否跟随最新价缩放。
- **技术指标**（可选勾选）：EMA 21/55、MACD、RSI（含 30/70 参考线）；副图自上而下为 MACD、RSI。
- **持仓标记**（从监控跳转时）：展示入场、止损、止盈、委托摘要；K 线上绘制对应价格线。趋势回调若止盈为程序监控，止盈栏显示「程序监控」且不与止损同价误显。
- **背离**：MACD/RSI 与价格简易背离标注（箭头 + 图例说明）。

---

## 5. HTTP API（中控）

须登录（与监控区相同，`/api/ping` 等白名单除外）。

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/chart/meta` | 已启用交易所列表、周期列表、各周期 limit、保留天数 |
| GET | `/api/chart/ohlcv` | 查询参数：`exchange_key`、`symbol`、`timeframe`、可选 `refresh=1` 强制刷新 |

实例侧（中控转发）：

| 路径 | 说明 |
|------|------|
| 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`、`crypto_gate_bot`（名称以你环境为准）。
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_*` 等变量 |