# DB 与币安订单对账说明

## 一、查询系统今日落入 DB 的单子

### 1. 命令行脚本（推荐）

```bash
# 今日、默认账号、按创建时间（落库时间）
python scripts/query_trades_today.py

# 指定账号
python scripts/query_trades_today.py --account 2

# 指定日期
python scripts/query_trades_today.py --date 2026-02-21

# 按入场时间筛选
python scripts/query_trades_today.py --time-filter entry

# 仅可对账记录（有开仓/平仓订单号）
python scripts/query_trades_today.py --reconciled-only

# 导出到 JSON 文件
python scripts/query_trades_today.py -o today_trades.json
```

### 2. API 接口

```
GET /api/trades?period=today&time_filter=created&reconciled_only=false
```

- `period=today`：今天
- `time_filter=created`：按创建时间（落库时间），便于对照「何时写入 DB」
- `time_filter=entry`：按入场时间
- `time_filter=exit`：按平仓时间
- `reconciled_only=false`：包含所有记录（含取消、无订单号）

### 3. 前端导出

交易记录页面 → 选择「今天」→ 导出 JSON / Excel。

---

## 二、币安订单推送日志

系统会将收到的 **ORDER_TRADE_UPDATE**、**ALGO_UPDATE** 写入日志，便于与 DB 对照。

### 日志路径

```
{项目根}/logs/binance_order_events.log
```

### 格式

每行一条 JSON，例如：

```json
{"ts":1737500000000,"event_type":"ORDER_TRADE_UPDATE","account_id":1,"E":1737500000123,"symbol":"BTCUSDT","orderId":123456,"clientOrderId":"SYS_1737500000_abcd","event":"TRADE","status":"FILLED","reduceOnly":false,"avgPrice":"95000","executedQty":"0.01","realizedPnl":"0"}
```

### 字段说明

| 字段 | 说明 |
|------|------|
| ts | 本机接收时间戳 |
| event_type | ORDER_TRADE_UPDATE / ALGO_UPDATE |
| account_id | 账号 ID |
| E | 币安事件时间（毫秒） |
| symbol | 交易对 |
| orderId | 币安订单号 |
| clientOrderId | 自定义订单号（系统前缀） |
| event | NEW/TRADE/CANCELED |
| status | NEW/FILLED/CANCELED 等 |
| reduceOnly | 是否只减仓（平仓单） |
| avgPrice/executedQty | 成交价/成交量（FILLED 时） |
| realizedPnl | 实现盈亏（平仓时） |
| algoId/triggeredOrderId | ALGO_UPDATE 专用 |

### 对账用法

```bash
# 查看今天收到的所有订单推送
grep "ORDER_TRADE_UPDATE" logs/binance_order_events.log

# 查看 FILLED 成交
grep '"status":"FILLED"' logs/binance_order_events.log

# 按 clientOrderId 对照
grep "SYS_1737500000_abcd" logs/binance_order_events.log
```

---

## 三、从币安拉取订单/成交（DB 缺失时）

当 DB 记录查不到或需直接从币安做策略分析时，可用脚本拉取：

```bash
# 拉取最近 7 天成交记录（默认，适合策略分析）
python scripts/fetch_binance_orders.py --account 2 --symbol BTCUSDT

# 多个交易对
python scripts/fetch_binance_orders.py --account 2 --symbols ASTERUSDT,FILUSDT,PENGUUSDT

# 拉取订单列表
python scripts/fetch_binance_orders.py --account 2 --symbol BTCUSDT --type orders

# 指定天数、导出
python scripts/fetch_binance_orders.py --account 2 --symbol BTCUSDT --days 7 -o binance_trades.json
```

- `--type trades`：成交记录（含价格、数量、盈亏，策略分析推荐）
- `--type orders`：订单列表（含 FILLED/CANCELED）
- 币安单次时间范围最多 7 天

---

## 四、对账流程建议

1. **查 DB 今日记录**：`python scripts/query_trades_today.py -o db_today.json`
2. **查币安推送日志**：`tail -f logs/binance_order_events.log` 或 `grep "ORDER_TRADE_UPDATE" logs/binance_order_events.log`
3. **对照**：用 `clientOrderId` 或 `orderId` 关联 DB 记录与推送日志，确认：
   - DB 有 pending 且收到 FILLED 推送 → 应更新为 open
   - DB 有 open 且收到 reduceOnly FILLED → 应更新 exit_order_id
   - 收到推送但 DB 无对应记录 → 可能漏建或为手动单