# 内照明心与永久 K 线

## 概述

「内照明心」页(`/archive`)用于 **复盘语录 + 交易记录回顾 + 按需 K 线**.左侧维护每日复盘语录(最多 100 条);右侧按日期区间列出开仓记录,展示区间统计,并可展开 K 线图表对照单笔交易.

与行情区 `hub_kline.db`(15 天滚动缓存)**完全独立**:档案库只增不删,从建档起永久保留.

## 页面布局

| 区域 | 说明 |
|------|------|
| **复盘语录** | 左栏;按日期添加/编辑/删除,一日一条 |
| **日期与筛选** | 顶栏:本日 / 本周 / 本月 / 自选区间;盈利单,亏损单,犯病,交易所,搜索 |
| **区间统计** | 统计栏随日期选择自动更新(见下) |
| **K 线图表** | 默认折叠;点「图表」或展开后按需加载 |
| **交易记录** | 默认展开;犯病行 **红色字体**(无红底);可编辑标签与备注 |

## 日期区间

交易日按北京时间 **8:00** 切日(`TRADING_DAY_RESET_HOUR`).

| 模式 | 范围 |
|------|------|
| **本日** | 可选单个交易日(默认当前交易日) |
| **本周** | 当周周一至当前交易日 |
| **本月** | 当月 1 日至当前交易日 |
| **区间** | 自选 `date_from`～`date_to`(含首尾交易日) |

## 区间统计(统计栏)

基于当前 **列表筛选结果**(含盈利/亏损/犯病勾选,合约搜索;交易所下拉仍限定数据源):

| 指标 | 说明 |
|------|------|
| 总开仓次数 | 区间内开仓笔数 |
| 盈利单 / 亏损单 | 盈亏 &gt; 0 / &lt; 0 的笔数(持平不计) |
| 平均盈利 / 平均亏损 | 盈利单,亏损单各自的均值(U) |
| 最大盈利 / 最大亏损 | 单笔最大盈利,最大亏损(U) |
| 犯病次数 / 占比 | `behavior_tag = sick` 的笔数及占开仓比例 |
| 盈亏 | 区间内全部已平仓盈亏合计 |
| 剔除犯病盈亏 | 排除犯病单后的盈亏合计 |
| 各交易所 | 每所同上分项 |

在搜索框输入币种(如 `BTC`)后,统计栏与下方列表同步按该条件收窄.

## 数据约定

| 项 | 约定 |
|----|------|
| 交易来源 | 三所 `trade_records` + 未落库的 `strategy_trade_snapshots`,经 `/api/hub/trades/archive` 拉取 |
| 犯病标签 | 中控 `trade_overlay.behavior_tag = sick` |
| 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` — 犯病标签与备注(仅中控)
  - `archive_review_quotes` — 复盘语录

## API(中控 FastAPI)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/archive/meta` | 周期,交易所,同步间隔等 |
| GET | `/api/archive/daily-trades` | 区间交易列表与统计(见 query) |
| GET | `/api/archive/quotes` | 复盘语录列表 |
| POST | `/api/archive/quotes` | 新增语录 |
| PATCH | `/api/archive/quotes/{id}` | 更新语录 |
| DELETE | `/api/archive/quotes/{id}` | 删除语录 |
| 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/archive/daily-trades` 主要 query:

| 参数 | 说明 |
|------|------|
| `period` | `today` / `week` / `month` / `range` |
| `trading_day` | 本日模式下的交易日 `YYYY-MM-DD` |
| `date_from` / `date_to` | 区间模式起止日 |
| `exchange_key` | 可选,按交易所筛选 |
| `filter_profit` / `filter_loss` / `filter_sick` | 过滤列表与统计 |
| `search` | 合约 / 交易所 / 备注搜索(同步过滤列表与统计) |

返回 `stats` 含 `open_count`,`win_count`,`loss_count`,`win_rate`,`avg_win`,`avg_loss`,`profit_loss_ratio`,`max_win`,`max_loss`,`sick_count`,`sick_pct`,`pnl_total`,`pnl_ex_sick`,`by_exchange`.

实例侧:

| 方法 | 路径 | 说明 |
|------|------|------|
| 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)
