# 虎牙浏览器兑换（本机浏览器）

人工兑换在操作者自己的 Chrome/Edge 中完成：后端下发目标页地址和登录材料，登录态自动（扩展）或手动（控制台脚本）写入本机浏览器，兑换本身始终由人工点击，服务端不托管任何浏览器会话。

## 入口与账号范围

独立页面：虎牙 → 浏览器兑换。导航按角色区分：客服只看到浏览器兑换一个入口；管理员/运营仍显示完整的虎牙菜单（账号管理、精英宝典等）。

- 页面维护一份「兑换账号列表」，通过「导入账号」从自己可见的账号池勾选加入；客服只能看到分配给自己的账号。
- 列表按用户隔离保存（工作台 scope `browser_exchange`），与精英宝典的账号集合互不影响。
- 账号需已有 Cookie 才能执行兑换；账号的 App 协议登录由管理员在账号管理页（直链 `/huya/accounts`）完成，客服遇到无 Cookie 账号时联系管理员处理。

## 一键自动注入（推荐）：安装内置扩展

项目自带 Chrome/Edge 扩展 `web/extension/huya-exchange-helper/`，安装一次后即可自动注入：

1. 打开扩展管理页：Chrome 为 `chrome://extensions`，Edge 为 `edge://extensions`。
2. 开启「开发者模式」，点击「加载已解压的扩展程序」，选择仓库目录 `web/extension/huya-exchange-helper`。
3. 刷新后台页面（扩展的内容脚本需要对当前页生效）。

之后的流程：

1. 在兑换列表点击账号的「浏览器兑换」→ 后端返回兑换材料 → 扩展自动把该账号 Cookie 写入 `.huya.com` 域并在新标签页打开已登录的兑换页。
2. 确认页面右上角账号无误后，手动完成兑换。
3. 回到后台点击「完成」。

扩展只在注入时覆盖与登录态同名的旧 Cookie，其余虎牙 Cookie 不动；扩展图标点击可作为兜底（读取当前后台页签留存的材料）；未检测到材料时图标会显示「无任务」角标。

## 查询兑换记录

兑换列表每行的「兑换记录」按钮会为该账号创建 `query_exchange_records` 精英宝典任务（活动 SID 取精英宝典配置），前端轮询任务完成后：

- 表格新增的「兑换记录」列直接展示奖品名（多条时显示"xxx 等 N 条"，悬停可看全部名称），未查询显示"未查询"，查询中显示加载图标，失败显示"查询失败"及原因。
- 点击单元格中的奖品名可打开详情弹窗，查看每条记录的奖品、消耗积分、发放状态、兑换时间与订单号。

任务失败（如 SID 未配置、Cookie 失效）时弹窗内直接显示原因，可点击「重新查询」。

## 手动方式（未装扩展时的兜底）

1. 在兑换列表点击「浏览器兑换」，弹出「浏览器兑换」窗口。
2. 点击「打开兑换页面」在新标签页打开兑换活动页（地址来自配置的 `room_pid`，未配置时回落到活动页 `https://zt.huya.com/b02faae1/pc/index.html`）。
3. 点击「复制登录脚本」，在兑换页面按 `F12` 打开控制台，粘贴脚本并回车执行。Chrome/Edge 首次粘贴需先手动输入 `allow pasting` 再回车。脚本把该账号 Cookie 写入 `.huya.com` 域并自动跳转。
4. 确认登录态正确后完成兑换，回到系统点击「完成」。

没有控制台操作习惯时，可安装 Cookie-editor 类扩展，使用「复制 Cookie 字符串」在 `.huya.com` 域下导入。

## 接口

`POST /api/huya/accounts/{account_id}/browser-exchange`（权限 `huya:task`）返回：

```json
{
  "account_id": 1,
  "username": "xxx",
  "target_url": "https://...",
  "cookie_string": "yyuid=...; ...",
  "cookie_script": "(function(){...})();"
}
```

- 脚本由 `core.huya.cookie_utils.browser_login_script` 生成：Cookie 以 JSON 数组内联（自动转义），逐条 `document.cookie` 写入 `domain=.huya.com; path=/`，有效期 180 天，最后跳转目标页。
- 扩展注入走同一条接口：前端解析 `cookie_string` 后通过 DOM 事件交给扩展，由 `chrome.cookies` API 写入。
- 兑换账号列表复用 `/api/huya/workbench-accounts`（`handbook_scope=browser_exchange`）。
- 服务端不保存任何会话状态。

## 安全说明

- 接口受 `huya:task` 权限与账号可见范围约束；脚本、Cookie 字符串与扩展注入等同账号凭证，仅在授权用户点击时下发。
- 登录态只写入操作者自己的浏览器，不会在服务器留存浏览器进程或 Profile。
- 扩展为内部工具，通过开发者模式加载；其内容脚本在所有页面注入通信桥（manifest `<all_urls>`），但只响应本后台页面派发的固定事件，且只写 `huya.com` 域的 Cookie。
- 请勿把脚本、Cookie 或扩展转给无关人员；如需共享操作，建议使用系统的账号授权机制而非转发凭证。