# sanguo QMT bridge (D-1 MVP)

Windows 端 FastAPI 服务，封装 xtquant，供 sanguo(NAS) 跨网调 miniQMT 下单/查询。

## 前提

1. **miniQMT 客户端已登录并保持运行**（极简模式即可）
2. **xtquant 可 import**（miniQMT 安装目录自带，或 `pip install xtquant`）
3. Python 3.10+

## 安装

```powershell
cd C:\sanguo_qmt_bridge   # bridge 代码所在目录
pip install -r requirements.txt
```

> xtquant 来自 miniQMT 安装目录（`bin.x64\Lib\site-packages`），无需 pip install。
> 若 import 失败，确认 miniQMT 的 site-packages 在 PYTHONPATH，或 `pip install xtquant`。

## 配置（环境变量）

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `BRIDGE_TOKEN` | **必填**。共享密钥，sanguo 端同值。不设则受保护接口返回 503 | — |
| `MINIQMT_USERDATA` | miniQMT userdata_mini 路径 | `D:\国金QMT交易端模拟\userdata_mini` |
| `ACCOUNT_ID` | miniQMT 账户 ID | `66639661` |
| `BRIDGE_SESSION_ID` | xtquant session ID（int） | `20260710` |

**设置 BRIDGE_TOKEN**（PowerShell）：

```powershell
# 临时（当前终端）
$env:BRIDGE_TOKEN = "你的随机密钥"

# 永久（系统环境变量）
[Environment]::SetEnvironmentVariable("BRIDGE_TOKEN", "你的随机密钥", "User")
```

> 生成密钥：`python -c "import secrets; print(secrets.token_urlsafe(32))"`

## 启动

```powershell
cd C:\sanguo_qmt_bridge
uvicorn bridge:app --host 127.0.0.1 --port 8765
```

启动日志看到 `xtquant 连接成功` 即就绪。若 miniQMT 未连上，服务仍运行（`/health` 报 `disconnected`）。

## 接口

所有受保护接口需 header `X-Bridge-Token: <BRIDGE_TOKEN>`，`/health` 豁免。

### GET /health（无需鉴权）

```json
{"status": "ok", "miniqmt_connected": true}
```

### POST /order

请求：
```json
{
  "code": "sh600000",
  "action": "buy",
  "price": 10.50,
  "volume": 100,
  "price_type": "limit",
  "reason": "策略信号"
}
```

成功：
```json
{"ok": true, "order_id": 12345}
```

失败：
```json
{"ok": false, "error": "报单失败 order_id=-1"}
```

### GET /account

```json
{"ok": true, "cash": 100000.0, "frozen": 0.0, "market_value": 50000.0, "total": 150000.0}
```

### GET /positions

```json
{
  "ok": true,
  "positions": [
    {"code": "sh600000", "volume": 200, "can_use": 200, "avg_price": 10.30}
  ]
}
```

## 代码格式

- 入参（/order）：sanguo 格式 `sh600000` / `sz000001`
- 返回（/positions）：sanguo 格式 `sh600000` / `sz000001`
- bridge 内部自动转 xtquant 格式 `600000.SH` / `000001.SZ`

## 验证

跑过 `check_xtquant.py` 确认 xtquant 可用后，启动 bridge 再验证：

```powershell
# 健康检查（无需 token）
curl http://127.0.0.1:8765/health

# 查资金（需 token）
curl -H "X-Bridge-Token: 你的密钥" http://127.0.0.1:8765/account
```

## 自启（可选，D-2）

任务计划程序创建 `sanguo-bridge`，onstart，命令：
```
uvicorn bridge:app --host 127.0.0.1 --port 8765
```
工作目录设为 bridge 代码目录。依赖 miniQMT 客户端已先启动。