# Phase 3D Windows 端部署 + 联调清单

> D 期实盘集成：Windows miniQMT bridge 部署 + sanguo 联调一站式清单。
> 前序：D-1 bridge MVP（commit `eff9ed2`）+ D-3 sanguo 影子下单（commit `ff84b3d`）代码已完成。
> 本清单是 Windows 端实操（D-1 实测 / D-2 自启 / D-4a 联调）——这些步骤 miniQMT 只在 Windows，必须人工执行。

## 架构回顾

```
sanguo(NAS) ──HTTPS──► Caddy(VPS:443 bridge.mysanguo.top)
                             ↓ 反代
                         frps(18765) ◄─frp隧道─ Windows frpc
                                                         ↓
                                           bridge(:8765) → xtquant → miniQMT
```

## 0. 前提确认

- [ ] miniQMT 客户端已登录常驻（极简模式 / 独立交易）
- [ ] `check_xtquant.py` 跑通（import + connect + query 三步 ✅，账户 66639661）
- [ ] frpc 已配 + 连上 VPS（`curl https://bridge.mysanguo.top/health` 返回 502 = 隧道通，bridge 未启）

## 1. 获取 bridge 代码

从 gitea 拉 `sanguo_qmt_bridge/` 目录（bridge.py / xt_gateway.py / auth.py / requirements.txt / README.md）：

```
http://git.mysanguo.top/sanguo/sanguo_vnpy_v2/src/branch/master/sanguo_qmt_bridge
```

下到 Windows，例如 `C:\sanguo_qmt_bridge\`

## 2. 安装 + 配置

```powershell
cd C:\sanguo_qmt_bridge
pip install -r requirements.txt   # fastapi + uvicorn

# 生成 BRIDGE_TOKEN（随机密钥，记下来！sanguo 端要同值）
python -c "import secrets; print(secrets.token_urlsafe(32))"

# 设为系统环境变量（永久）
[Environment]::SetEnvironmentVariable("BRIDGE_TOKEN", "上面生成的密钥", "User")
```

重开终端使 `BRIDGE_TOKEN` 生效。userdata / account 默认值已对（`D:\国金QMT交易端模拟\userdata_mini` / `66639661`），如不同设 `MINIQMT_USERDATA` / `ACCOUNT_ID` 环境变量。

## 3. 启动 + 实测（D-1 验证）

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

启动日志看到「xtquant 连接成功」。另开终端测：

```powershell
curl http://127.0.0.1:8765/health
# {"status":"ok","miniqmt_connected":true}

curl -H "X-Bridge-Token: 你的密钥" http://127.0.0.1:8765/account
# {"ok":true,"cash":10000000.0,"frozen":0.0,"market_value":0.0,"total":10000000.0}

curl -H "X-Bridge-Token: 你的密钥" http://127.0.0.1:8765/positions
# {"ok":true,"positions":[]}
```

✅ 三接口通 = **D-1 完成**。

## 4. 公网联调（sanguo → bridge）

NAS sanguo 容器经 `bridge.mysanguo.top` 访问。在 NAS 测全链路：

```bash
ssh sanguo-nas
/var/packages/Docker/target/usr/bin/docker exec sanguo_vnpy_v2 \
  curl -H "X-Bridge-Token: 你的密钥" https://bridge.mysanguo.top/health
# {"status":"ok","miniqmt_connected":true}  → 公网 6 跳全通
```

## 5. sanguo 端开影子下单（D-3 启用）

NAS `config/data_platform.yaml`：

```yaml
live:
  enabled: true              # D-4a 联调开（默认 false）
  bridge_url: https://bridge.mysanguo.top
  shadow: true
```

设 sanguo 容器 `BRIDGE_TOKEN` 环境变量（**= Windows 同值**），重启容器生效：

```bash
docker restart sanguo_vnpy_v2
```

## 6. D-4a 端到端联调

触发一次 live_step（有当日成交时会影子下单到 bridge）：

```bash
docker exec sanguo_vnpy_v2 python -c \
  "from sanguo_trader.live_orchestrator import run_live_step; \
   run_live_step('/volume1/stock/sanguo_vnpy/data/quant_trading.db')"
```

观察：
- **Windows bridge 日志**：应有 `POST /order`（影子下单）+ miniQMT 客户端出现委托记录
- **NAS**：`paper_shadow_orders` 表有记录（幂等去重）

## 7. 开机自启（D-2）

bridge + frpc 都要开机自启（任务计划程序 `schtasks`，Windows 自带，不用 nssm）：

```powershell
# sanguo-bridge（onstart，依赖 miniQMT 已先启动登录）
schtasks /create /tn "sanguo-bridge" /tr "cmd /c cd /d C:\sanguo_qmt_bridge && uvicorn bridge:app --host 127.0.0.1 --port 8765" /sc onstart /ru SYSTEM /f

# sanguo-frpc（配置见 NAS /volume1/stock/frp_windows/，同样 schtasks onstart 或启动文件夹）
```

> miniQMT 客户端本身也要开机自启登录（其自身设置或启动文件夹 `shell:startup`）。

## 故障排查

| 现象 | 排查 |
|------|------|
| `/health` miniqmt_connected:false | miniQMT 未登录 / userdata 路径错 / 账户 ID 错 |
| 401 token 无效 | sanguo 与 Windows 的 `BRIDGE_TOKEN` 不一致 |
| 公网 502 | frpc 断 / bridge 没启；先 `curl 127.0.0.1:8765/health` 验本地 |
| 影子下单未触发 | `live.enabled` 是否 true / 当日是否有成交 / `BRIDGE_TOKEN` 是否设 / bridge_url 是否对 |
| 重复下单 | 不会 —— `paper_shadow_orders` 表 `UNIQUE(account_id, trade_id)` 幂等去重 |