feat(hub): add symbol archive with permanent 5m klines

Add /archive page, hub_symbol_archive.db, trade overlay, 4h background sync, and instance /api/hub/trades/archive. Document in hub-symbol-archive-kline.md with cross-links.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/hub-symbol-archive-kline.md

@@ -0,0 +1,82 @@
+# 中控币种档案与永久 K 线
+
+## 概述
+
+「币种档案」页（`/archive`）按 **交易所 + 币种** 一行汇总历史已平仓记录，支持筛选、交易时间线、备注/犯病情绪标签，以及基于 **永久 5m 真源** 的 K 线大图（15m/1h/4h 由 5m 聚合）。
+
+与行情区 `hub_kline.db`（15 天滚动缓存）**完全独立**：档案库只增不删，从建档起永久保留。
+
+## 数据约定
+
+| 项 | 约定 |
+|----|------|
+| 列表粒度 | 一所一币一行 |
+| 交易来源 | 四所 `trade_records`，经 `/api/hub/trades/archive` 拉取 |
+| 筛选 | 交易所、有盈利单、有亏损单、犯病、情绪（中控 overlay） |
+| K 线真源 | 仅 **5m** 写入 `hub_symbol_archive.db` |
+| 建档种子 | 该币 **最早开仓** 向前 **30 天** 5m |
+| 增量同步 | 默认每 **4 小时** 补新 5m 至当前 |
+| 展示周期 | Tab：**5m / 15m / 1h / 4h**，默认 **15m** |
+| 视窗模式 | **持仓过程**（锚平仓，默认）/ **进场决策**（锚开仓） |
+| 时间跳转 | 上方输入 `YYYY-MM-DD HH:MM` 后点「跳转」 |
+| 图片 | **不上传** |
+
+## 存储
+
+- 默认路径：`manual_trading_hub/data/hub_symbol_archive.db`
+- 环境变量：`HUB_ARCHIVE_DB_PATH`
+- 表：
+  - `archive_meta` — 建档元数据
+  - `archive_bars_5m` — 永久 5m K 线
+  - `archive_trade_cache` — 从实例同步的交易快照
+  - `trade_overlay` — 犯病/情绪标签与备注（仅中控）
+
+## API（中控 FastAPI）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/archive/meta` | 周期、交易所、同步间隔等 |
+| GET | `/api/archive/list` | 币种列表（筛选 query） |
+| GET | `/api/archive/detail` | 单币种交易时间线 |
+| GET | `/api/archive/ohlcv` | K 线视窗（`timeframe` / `mode` / `anchor_ms` / `at`） |
+| PATCH | `/api/archive/trade/{exchange_key}/{trade_id}` | 更新标签/备注 |
+| POST | `/api/archive/sync` | 立即同步四所交易 + K 线 |
+
+实例侧新增：
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/hub/trades/archive` | 近 N 天已平仓（`days` / `limit`） |
+
+## 后台任务
+
+Hub 启动后在 lifespan 中运行 `hub-archive-sync`：
+
+1. 对各启用交易所调用 `/api/hub/trades/archive`
+2. 写入 `archive_trade_cache`
+3. 未建档币种：拉 30 天 5m 种子
+4. 已建档币种：增量补 5m
+
+间隔：`HUB_ARCHIVE_SYNC_INTERVAL_SEC`（默认 14400）。
+
+## 代码位置
+
+- `hub_symbol_archive_lib.py` — 库表、种子、增量、聚合、列表
+- `hub_trades_lib.py` — `fetch_trades_for_archive`
+- `hub_bridge.py` — 实例 `/api/hub/trades/archive`
+- `manual_trading_hub/hub.py` — 路由与后台同步
+- `manual_trading_hub/static/archive.js` — 前端页
+
+## 与行情区的区别
+
+| | 行情区 | 币种档案 |
+|--|--------|----------|
+| DB | `hub_kline.db` | `hub_symbol_archive.db` |
+| 保留 | 15 天滚动删除 | 建档起永久 |
+| 周期 | 多周期直存/拉取 | 仅存 5m，高周期聚合 |
+| 用途 | 实时看盘 | 复盘与档案 |
+
+## 相关文档
+
+- [中控平仓与交易记录](trend-hub-close-and-trade-records.md)
+- [中控使用说明](../manual_trading_hub/使用说明.md)

docs/trend-hub-close-and-trade-records.md

@@ -177,6 +177,7 @@ pm2 save
 | [策略交易说明.md](../策略交易说明.md) | 策略总览、策略交易记录页 |
 | [crypto_monitor_gate_bot/趋势回调策略说明.md](../crypto_monitor_gate_bot/趋势回调策略说明.md) | 趋势回调业务细则 |
 | [manual_trading_hub/使用说明.md](../manual_trading_hub/使用说明.md) | 中控监控与趋势卡布局 |
+| [hub-symbol-archive-kline.md](./hub-symbol-archive-kline.md) | 币种档案、永久 5m K 线、交易 overlay |
 
 ---