# 虎牙精英宝典联调指南

更新时间：2026-09-01

## 本次联调结论

当前联调阶段只验收 App 登录后的网页 Cookie 完整性，精英宝典任务统一使用 WSS：

| 阶段 | 结果 | 证据 |
| --- | --- | --- |
| WUP 登录 | 通过 | `cred=114B`，返回真实 UID |
| hydevice 指纹 | 通过 | 返回 `sdid`、`hdid` |
| QR 绑定 | 通过 | `getQrId`、`bindQrLoginUser`、`tryQrLogin(stage=2)` |
| 网页 Cookie | 待重新登录验证 | 必须包含 9.1 网页设备态字段 |
| 精英宝典任务 | 待验证 | 仅允许 WSS，会话失败即任务失败 |

旧登录结果中的 Cookie 缺少网页设备态，已不再作为成功登录或任务链路使用。

纯 App/HTTP 登录不会由 `web/cookie/verify` 下发网页设备 Cookie。浏览器只用于
人工调试和抓取来源，未集成到脚本；登录链已接入匿名设备态协议
（`core/huya/anon_device.py`）补 `udb_deviceid`/`udb_guiddata`/`udb_anobiztoken`/
`udb_anouid`，剩余脚本字段（`guid`/`game_did`/`_qimei_uuid42`/`__yamid_new`）
缺失时警告并保存，不伪造、不启动浏览器。

## 推荐联调顺序

1. 在 `http://localhost:5174/` 登录一个测试账号，确认日志出现 `App协议登录成功`。
2. 配置精英宝典 `SID`。9.1 抓包对应活动 SID 为 `2203`；以页面“精英宝典设置”中的当前值为准。
3. 按下面顺序在精英宝典工作台执行任务：
   - `query_game_name`：验证角色绑定状态。
   - `query_points`：验证积分响应和数据库写回。
   - `query_exchange_records`：验证记录解码和页面展示。
   - `refresh_goods`：拉取商品快照。
   - 选一个明确可兑换、价格低于余额的商品，再执行 `exchange_goods`。
4. 兑换成功后再次执行 `query_points` 和 `query_exchange_records`，核对余额扣减与新增记录。
5. 充值/开通链路单独联调：先 `refresh_recharge_goods`，再只生成支付码 `create_recharge_order`。支付确认不要和查询任务混在同一批次。

## 如何判定传输通道

执行器只检查字段是否存在，不记录字段值：

```text
必要字段：udb_cred、udb_biztoken、udb_uid、yyuid、sdid、udb_deviceid、udb_guiddata、udb_anobiztoken
```

- 字段齐全：尝试活动或商城 WSS。
- 缺少字段：任务日志列出缺失字段并停止，不创建 HTTP 客户端，例如：

```text
Cookie 缺少网页设备态(udb_deviceid, udb_guiddata, udb_anobiztoken)，已停止活动 HTTP 回退
```

`guid`/`game_did`/`_qimei_uuid42`/`__yamid_new` 四个脚本字段无服务端签发接口，
登录时缺失只警告不阻断保存，WSS 判定也不再要求（风控风险自担）。

- WSS 握手、`wsLaunch`、`getConfig` 或业务 RPC 任一步失败：任务直接失败并记录具体阶段，便于修复 Cookie 或协议参数。

## WSS 专项验收

只有从同一网页会话取得真实 `guid` 后，才做 WSS 专项联调。验收顺序为：

1. 活动 WSS 初始化：`wsLaunch -> AUTH -> mobileui.getConfig -> CONFIRM`。
2. 活动 RPC：`checkUserBindGameAccount -> getUserScore -> getUserPrizeRecords`。
3. 商城 WSS 初始化：`wsLaunch -> getConfig -> register -> CONFIRM`。
4. 商城只读 RPC：`getGoodsInfoV5 -> listPayChannelV5 -> checkHyProtocolV5`。
5. 最后才验证 `createOrder -> payOrderSubmit -> orderDetail`。

网页设备字段必须来自同一网页/设备会话；`_merge_web_cookie` 不会根据长度、正则或 UID 生成 `guid`、QIMEI、`udb_anobiztoken` 等字段。

## 本次测试命令

```bash
.venv/bin/python -m pytest -q tests/test_huya_app_login.py tests/test_huya_runner_transport.py
.venv/bin/python -m ruff check core/huya web/backend/services/huya_runner_core.py tests/test_huya_runner_transport.py
git diff --check
```

预期：测试通过、Ruff 无错误、差异检查无输出。真实联调以 `logs/app-YYYY-MM-DD.log` 中每个 RPC 的状态码和任务最终状态为准。