# 持仓查询接口（GET /trade/positions 增强）

> 版本: 1.0 (2026-08-26)
> 状态: ✅ 已完成
> 关联: docs/设计/整体设计方案_v3.md 第四节(trade 命名空间)、docs/桥接口清单与sfgrid满足度对照.md
> 本次迭代: **持仓查询接口返回全部持仓信息（语义化字段 + 汇总），不做过滤筛选，不兼容旧调用模式**

## 一、已确认的设计决策

1. **接口**: `GET /trade/positions`（复用现有路由，不改 URI）
2. **返回全部持仓信息**: 每一行 = 语义化字段（xt 风格，供 sfgrid 等消费方直接使用）+ 完整原始 m_* 字段（透传，不丢弃）
3. **不做过滤筛选**: 不加 code/status 等过滤参数；客户端需要单票时自行从全量中取（sfgrid 的 getStockPosition 本就以全部持仓为缓存）
4. **不兼容旧调用模式**: 不再承诺只返回 m_* 原始字段；新返回为超集（m_* 仍在，新增语义字段），旧调用方读 m_* 不受影响，但返回结构/示例以本设计为准
5. **增加汇总 summary**: count（持仓只数）、total_market_value（总市值）、total_profit（总浮动盈亏）
6. **字段映射**（QMT POSITION 行 → 语义字段，字段缺失时安全降级）:

| 语义字段 | 来源(m_* 候选,按序探测) | 说明 |
|----------|------------------------|------|
| stock_code | m_strInstrumentID | 完整代码(带交易所后缀,如 600519.SH) |
| stock_name | m_strInstrumentName | 股票名称 |
| volume | m_nVolume | 总持仓量 |
| available | m_nCanUseVolume | 可用持仓量 |
| frozen_volume | m_nFrozenVolume | 冻结数量 |
| on_road_volume | m_nOnRoadVolume | 在途数量 |
| yesterday_volume | m_nYesterdayVolume | 昨仓数量 |
| avg_price | m_dOpenPrice / m_dCostPrice | 持仓成本价 |
| price | m_dLastPrice / m_dSettlementPrice / m_dOpenPrice | 最新价(缺失时兜底成本价) |
| market_value | m_dMarketValue / m_dInstrumentValue / volume*price 计算 | 持仓市值 |
| open_price | m_dOpenPrice | 开仓价(与 avg_price 同源) |
| profit | m_dFloatProfit / 计算 (price-avg_price)*volume | 浮动盈亏 |
| profit_pct | 计算 | 盈亏比例 % |
| direction | m_nDirection | 方向(默认 48=多) |

7. **JSON 安全**: 所有值经 `_json_safe` 处理（QMT 可能返回 numpy 类型）

## 二、实现记录（已完成）

- `src/bridge_data_adapter.py` 新增 `get_positions()`:
  - 从 `bridge_util.get_trade_cache("position")` 读缓存（策略线程 300ms 刷新，HTTP 线程只读）
  - 每行先 `_obj_to_dict` 得到 m_* 字段，再补充语义字段（含缺失字段探测与计算兜底）
  - 计算 summary: count / total_market_value / total_profit
  - 返回 `{"positions": [...], "summary": {...}}`
- `src/bridge_http_server.py` `_api_trade`: `dtype == "position"` 时调用新 `get_positions()`，返回 `{"ok":true,"data":{...}}`
- `tests/test_trade.py`: 更新持仓断言（语义字段 + summary）
- `docs/api_spec/openapi.yaml`: `/trade/positions` 响应示例更新为语义字段 + summary
- 重新生成 `docs/api_spec/openapi.json`

## 三、返回结构（示例）

```json
{
  "ok": true,
  "data": {
    "positions": [
      {
        "stock_code": "600519.SH",
        "stock_name": "贵州茅台",
        "volume": 100,
        "available": 100,
        "frozen_volume": 0,
        "on_road_volume": 0,
        "yesterday_volume": 0,
        "avg_price": 1500.0,
        "price": 1510.0,
        "market_value": 151000.0,
        "open_price": 1500.0,
        "profit": 1000.0,
        "profit_pct": 0.67,
        "direction": 48,
        "m_strInstrumentID": "600519.SH",
        "m_nVolume": 100,
        "m_nCanUseVolume": 100,
        "m_dOpenPrice": 1500.0,
        "m_dFloatProfit": 1000.0
      }
    ],
    "summary": {
      "count": 1,
      "total_market_value": 151000.0,
      "total_profit": 1000.0
    }
  }
}
```

> 说明: 语义字段名以 xtquant 风格为准（sfgrid `qmt_real.py`/`data_store.py` 消费的 `volume/avg_price/stock_code/instrument_name` 等）；原始 `m_*` 字段作为超集保留在同一行，避免旧调用方（如已部署脚本）因删字段而失效。