# 雪球 Cookie 配置说明

## 问题背景

本项目的 ETF 历史 K 线与实时行情数据来自雪球（xueqiu）接口。雪球 API 需要在请求头中携带 Cookie（尤其是 `xq_a_token`）。程序默认通过**无头浏览器（Playwright）访问雪球网一次**自动获取并缓存 cookie，供后续 K 线与实时接口使用。

## 解决方案

### 方案 1: 无头浏览器自动获取（默认）

程序会使用 Playwright 无头模式打开 `https://xueqiu.com/`，等待页面加载后提取 cookie 并缓存（约 30 分钟有效）。无需手动操作。

**依赖**：需已安装 Playwright 与 Chromium：

```bash
pip install playwright
playwright install chromium
```

若自动获取失败（如网络或反爬限制），可尝试方案 2。

### 方案 2: 有头浏览器手动验证

在无头获取失败或需登录时，程序在**交互式终端**下可调起有头浏览器，由用户手动完成雪球页面的验证或登录，完成后在终端按回车，程序会读取当前 cookie 并缓存。

**注意**：非交互式环境（如后台 cron）下不会弹窗，只会使用无头获取或已有缓存。

### 请求报错时的日志

雪球 K 线或实时接口请求失败时，程序会将**本次请求的报文详情**写入日志（Cookie 已脱敏），便于排查：

- 请求方法、完整 URL
- 请求头（Cookie 显示为 `***`）
- 错误信息、HTTP 状态码、响应体片段

使用项目日志工具或 `_debug_log` 输出；同时会向 stderr 打印简要错误信息。

## 故障排除

1. **无 cookie 或 401**：先运行一次无头获取；若失败，在支持 stdin 的终端下运行以触发有头验证。
2. **Playwright 未安装**：执行 `pip install playwright && playwright install chromium`。
3. **网络/代理**：雪球请求在代码中会临时禁用代理（`_disable_proxy`）；若环境必须走代理，可联系维护者调整。

详细 Playwright 安装与无头/有头说明见 [INSTALL_PLAYWRIGHT.md](./INSTALL_PLAYWRIGHT.md)。