dekun
6a56928d59
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>
3.1 KiB
3.1 KiB
中控币种档案与永久 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：
- 对各启用交易所调用
/api/hub/trades/archive - 写入
archive_trade_cache - 未建档币种：拉 30 天 5m 种子
- 已建档币种：增量补 5m
间隔：HUB_ARCHIVE_SYNC_INTERVAL_SEC（默认 14400）。
代码位置
hub_symbol_archive_lib.py— 库表、种子、增量、聚合、列表hub_trades_lib.py—fetch_trades_for_archivehub_bridge.py— 实例/api/hub/trades/archivemanual_trading_hub/hub.py— 路由与后台同步manual_trading_hub/static/archive.js— 前端页
与行情区的区别
| 行情区 | 币种档案 | |
|---|---|---|
| DB | hub_kline.db |
hub_symbol_archive.db |
| 保留 | 15 天滚动删除 | 建档起永久 |
| 周期 | 多周期直存/拉取 | 仅存 5m，高周期聚合 |
| 用途 | 实时看盘 | 复盘与档案 |