# 账户流水（三所统一）

从**交易所 API**拉取资金账户与交易账户账单，在实例内展示。  
不使用程序本地 `transfer_logs` 作为主数据源。

## 能力概览

| 项 | 说明 |
|----|------|
| 导航 | 「账户流水」Tab；默认关闭，在 **系统设置 → 导航显示** 打开 |
| Tab | **资金账户** / **交易账户** |
| 分页 | 每页 10 条，时间倒序 |
| 时间窗 | 跟随顶栏 UTC **预设**（与列表 `list_window` 一致） |
| 同步 | 后台约 **120s** 拉一次交易所；完成后 **SSE** 推版本，前端自动刷新 |
| 币种 | USDT；OKX 另含 **USDC** |
| 三所 | Binance / OKX / Gate 同一套 UI 与路由 |

## 使用

1. 系统设置 → 导航显示 → 勾选「账户流水」→ 保存  
2. 顶栏选预设时间并点「应用」  
3. 打开「账户流水」，切换资金/交易 Tab；可点「立即同步」

## API

| 路由 | 说明 |
|------|------|
| `GET /api/account_ledger?account=funding\|trading&page=1` | 按当前 session 时间窗分页查询缓存 |
| `GET /api/account_ledger/stream` | SSE，`event: ledger`，载荷含 `ledger_version` |
| `POST /api/account_ledger/refresh` | 手动触发同步（有冷却，默认 30s） |

均需登录（与实例其他 API 相同）。

## 交易所数据源

| 所 | 资金账户 | 交易账户 |
|----|----------|----------|
| Gate | spot `account_book`（USDT） | USDT 永续 `account_book` |
| OKX | `asset/bills`（USDT+USDC） | `account/bills` + `bills-archive`（USDT+USDC） |
| Binance | 充提 + `fetch_transfers`（USDT） | U 本位 `fapi` income（USDT） |

后台默认回看 **90 天**（`ACCOUNT_LEDGER_LOOKBACK_DAYS`），写入本地 SQLite 缓存后再按顶栏时间窗过滤展示。  
「全部 / 近 6 月」等超出回看窗口的部分，仅能看到缓存内数据。

## 环境变量（可选）

| 变量 | 默认 | 说明 |
|------|------|------|
| `ACCOUNT_LEDGER_POLL_SEC` | `120` | 后台轮询秒数 |
| `ACCOUNT_LEDGER_LOOKBACK_DAYS` | `90` | 拉取与手动同步上限天数 |
| `ACCOUNT_LEDGER_MANUAL_COOLDOWN_SEC` | `30` | 手动同步冷却 |
| `ACCOUNT_LEDGER_SSE_HEARTBEAT_SEC` | `25` | SSE 心跳 |

## 代码位置

```
lib/account_ledger/           # DB / 同步 / SSE / 注册 / 面板
lib/exchange/*_ledger_lib.py  # 三所拉取适配
lib/common/static/account_ledger.js
```

三所 `app.py` 调用：`install_account_ledger(..., exchange_key=...)`。

## 审计摘要（2026-08-10）

- 路由均 `@login_required`；SSE 仅推版本号，不含账单正文  
- SQL 参数化；`account` 白名单；币种服务端固定  
- 前端表格字段 `escapeHtml`  
- **已修复**：手动同步强制套用 lookback 上限 + 冷却，避免滥用刷交易所 API  

详见同目录旁注或 PR 说明；安全复查子代理结论：修复后无未关闭的中高危项。