# 技术实现方案：05-交易记录接入（订单与成交 + 日期导航）

> 依据：PLAN-006 ｜ 需求：R-007 ｜ 设计约束：技术约束-001/003/004/010、产品约束-007 方向语义

## 技术选型

- **数据源**：复用 QmtBridgeRestDataSource（REST 直连，技术约束-003），新增 3 方法；
- **服务端 API**：webServer 自开路由（技术约束-004），新增 api/trades.js 领域；
- **前端数据流**：服务端中转 + 前端轮询（技术约束-010 思路，复用 market-snapshot 模式）；
- **UI**：React 组件 + 现有表格风格（LoadState 三态 / 内联样式 / Toast）；
- **时间段查询**（v3，2026-09-01）：RangeSelector 组件（今日/本周/上周快捷 + 手动起止日期），替代单日导航。

## 架构设计

### 服务端

```
QmtBridgeRestDataSource.getOrders({code,status})  → GET /trade/orders    → 语义化映射 order 列表
QmtBridgeRestDataSource.getTrades()              → GET /trade/trades    → 语义化映射 trade 列表
QmtBridgeRestDataSource.getTradingDates({s,e})   → GET /data/calendar/trading_dates → dates[]

api/trades.js（新增领域）:
  orders          → dataSource.getOrders(args)
  trades          → dataSource.getTrades()
  trading-dates   → dataSource.getTradingDates(args)
  （registerApi 合并 TRADE_METHODS + HANDLERS）
```

**语义化映射（核心）**：

```
order:  { orderId, code, name, exchange, direction(48买/49卖), status, orderVolume,
         tradedVolume, totalVolume, limitPrice, tradedPrice, amount, insertTime }
trade:  { tradeId, orderId, code, name, exchange, direction, price, volume, amount,
         commission, tradeTime }
```

**方向判定**：m_nOffsetFlag（48=买入/49=卖出）为主 + m_strOptName 交叉验证（R-007 Q3 闭环）。

### 客户端（单表合并）

```
TradeRecordsTab（标题 + 时间段同一行 + 单表）
  ├─ RangeSelector：trading-dates → 快捷范围（今日/本周/上周）+ 手动起止日期
  │   今日=最近交易日单日（完整互斥时间段）；本周=所在自然周周一~周五（不考虑周六日）；本月=所在自然月1号~月末
  ├─ 合并逻辑：fetch orders+trades（带 start/end）→ 按 orderId 分组 → 聚合
  │   聚合：成交量=Σ、成交均价=加权、成交额=Σ、手续费=Σ
  ├─ OrderRow：委托主行（聚合成交），点击展开/折叠
  └─ TradeDetailRows：展开的每笔成交明细
```

**合并规则**：
- 主行 = 一笔委托（orderId 唯一）；
- 成交聚合：m_strOrderSysID 匹配的 trades 聚合进主行（加权均价 + 求和）；
- 无成交（待报/已撤/废单）：成交量/均价/金额/手续费显示 —；
- 展开：逐笔渲染成交（时间/价/量/额/手续费/成交号）。

**排序**：委托主行默认按时间降序（最新在前）；表头点击排序（时间/代码/方向/状态/委托量/成交量/金额），再次点击切换升/降序。

**轮询**：仅「今日」范围（最近交易日单日）3-5s 轮询；切换时间段取消轮询、按 range 一次性查询（历史接口就绪后接入 start/end 实际过滤）。

**时间段查询（v3 定稿）**：
- 服务端 orders/trades 端点接收 start/end（透传，QMT Bridge 历史接口就绪后生效）；
- 前端 RangeSelector：三个快捷按钮 + 两个 date input；
- 历史范围（非今日）本期占位「历史数据接口开发中」。

## 涉及设计约束

| 约束 | 内容 |
|---|---|
| 技术约束-001 | 统一数据源抽象：交易数据走 QmtBridgeRestDataSource 适配器 |
| 技术约束-003 | 直连 QMT Bridge REST（不经过 MCP） |
| 技术约束-004 | webServer 自开路由 /odl/api/*（不占 /api interceptor） |
| 技术约束-010 | 服务端中转 + 前端轮询（复用市场模式） |
| 产品约束-007 | 方向着色沿用红/绿习惯语义（交易：红买绿卖） |

## 实现步骤

1. 文档骨架：PLAN-006 + 迭代 05（本步）；
2. 数据源：getOrders/getTrades/getTradingDates + 语义化映射；
3. 服务端 API：api/trades.js 三端点 + 领域分发；
4. 客户端合并逻辑：fetch 两接口 → 分组 → 聚合；
5. UI：DateNav + OrderRow + TradeDetailRows + TradeRecordsTab + 排序；
6. 构建安装：pnpm run build + 刷新/重启；
7. 验收 + 复盘。