fix(douyu): 修复多 alias 待确认绑定并补充协议文档
This commit is contained in:
+2
-1
@@ -1,6 +1,6 @@
|
||||
# 项目文档索引
|
||||
|
||||
更新时间:2026-11-08
|
||||
更新时间:2026-11-21
|
||||
|
||||
本文只列当前仍有维护价值、能直接用于开发或排查的文档。已被代码实现取代的
|
||||
一次性计划、事故经过和中间抓包记录已删除;需要追查历史时使用 Git 历史。
|
||||
@@ -18,6 +18,7 @@
|
||||
- [精英宝典 HAR 提取](虎牙/HAR提取CK与积分中心.md):HAR 中的完整 CK、积分中心和商品结构。
|
||||
- [皮肤准入映射分析](皮肤准入映射分析.md):快手皮肤订单到斗鱼商品的覆盖与映射边界。
|
||||
- [直播账号履约工作台](直播账号履约工作台.md):order_site 人工订单、斗鱼账号租约、客户扫码绑定和人工兑换。
|
||||
- [斗鱼协议总览](斗鱼/DOUYU_PROTOCOL_OVERVIEW.md):斗鱼绑定、精英宝典、兑换、支付、多 alias 判定和排障日志的统一入口。
|
||||
|
||||
## 协议与逆向证据
|
||||
|
||||
|
||||
@@ -0,0 +1,239 @@
|
||||
# 斗鱼协议总览
|
||||
|
||||
更新时间:2026-11-21
|
||||
|
||||
本文是斗鱼协议、状态判定和线上排障的统一入口。代码是最终依据;本文记录代码
|
||||
难以直接表达的协议语义、字段优先级、已验证边界和历史踩坑,避免重复分析。
|
||||
|
||||
## 维护规则
|
||||
|
||||
每次修改斗鱼协议相关代码时,同一个提交必须同步更新本文:
|
||||
|
||||
1. 新增或修改字段时,补字段真值表和影响范围;
|
||||
2. 新增 `actAlias`、接口或任务类型时,说明它在多渠道判定中的职责;
|
||||
3. 修复线上问题时,在“踩坑记录”追加日期、现象、根因、判定变化和回归用例;
|
||||
4. 抓包只能证明当时行为,不能直接覆盖已由代码和线上回归验证的结论;
|
||||
5. CK、Cookie、手机号、订单号和完整设备标识不得写入本文。
|
||||
|
||||
## 权威代码入口
|
||||
|
||||
| 范围 | 唯一权威入口 |
|
||||
| --- | --- |
|
||||
| 斗鱼 HTTP 协议与原始字段解析 | `core/douyu/activity_client.py` |
|
||||
| 绑定业务状态和 pending 判定 | `web/backend/services/account_binding.py` |
|
||||
| 二维码、轮询、确认绑定状态机 | `web/backend/services/douyu_runner_bind.py` |
|
||||
| 账号探针和多 alias 角色汇总 | `web/backend/services/douyu_account_probe.py` |
|
||||
| 只读查询统一入口 | `web/backend/services/douyu_activity_query.py` |
|
||||
| 任务类型和入口校验 | `web/backend/services/douyu_service.py` |
|
||||
| 任务并发与任务槽 | `web/backend/services/task_runtime.py` |
|
||||
| 履约投影和客户侧会话 | `web/backend/services/platform_fulfillment/` |
|
||||
|
||||
页面、履约、外部单协作和自动化不得自行解释 `bindAct` / `needBindAct`,只能消费
|
||||
`binding_snapshot()`、`binding_pending_decision()` 及其派生结果。
|
||||
|
||||
## 凭证与请求约束
|
||||
|
||||
- 业务请求依赖斗鱼登录 Cookie;写请求还可能需要 `cvl_csrf_token` / `acf_ccn`。
|
||||
- 查询和绑定扫码任务直连,不走代理;兑换、支付、充值、开通和送礼等写操作按任务
|
||||
从代理配置取代理。
|
||||
- `Origin`、`Referer` 必须与当前浏览器流程一致,不能只复制 URL。
|
||||
- 日志只记录脱敏状态,不记录 Cookie、CSRF、完整二维码签名或账号密码。
|
||||
|
||||
## 腾讯游戏角色绑定
|
||||
|
||||
### 接口
|
||||
|
||||
| 动作 | 方法 | 地址/常量 | 关键参数 |
|
||||
| --- | --- | --- | --- |
|
||||
| 查询绑定信息 | GET | `/wgapi/ordnc/live/memberthird/tencent/bindInfo` | `actAlias` |
|
||||
| 生成角色二维码 | GET | `/wgapi/ordnc/live/memberthird/tencent/bindRoleParam` | `actAlias` |
|
||||
| 确认绑定 | POST multipart | `/wgapi/ordnc/live/memberthird/tencent/actBind` | `actAlias`、`acf_ccn` |
|
||||
|
||||
### alias 职责
|
||||
|
||||
站内绑定信息不是单一数据源,`actAlias` 必须按职责区分:
|
||||
|
||||
| 来源 | 典型值 | 职责 | 不能做什么 |
|
||||
| --- | --- | --- | --- |
|
||||
| 活动动作 alias | `20260120QYOOB` | 当前精英宝典二维码、待确认和最终确认的权威动作通道 | 不能被 legacy 的旧角色覆盖 |
|
||||
| legacy 最新态 | `cjm` | 补充最新换绑/扫码角色,常更早暴露新角色 | 不能单独代表当前活动已确认;不能压掉活动 alias pending |
|
||||
| 历史查询 alias | `20250213NQCYX` 等配置值 | 兼容旧活动查询 | 不作为当前动作主通道 |
|
||||
|
||||
`query_act_aliases` 是“要查哪些来源”的集合;`action_act_aliases` 是“哪些来源可以
|
||||
执行确认”的集合。两者不能混用。查询顺序不是业务优先级;最终角色由 pending 判定
|
||||
和动作 alias 规则选出。
|
||||
|
||||
### 字段真值表
|
||||
|
||||
| 字段 | 语义 |
|
||||
| --- | --- |
|
||||
| `bindAccount=1` | 已绑定腾讯账号 |
|
||||
| `bindRole=1` | 已选中游戏角色 |
|
||||
| `bindAct=1` | 最终活动绑定已生效,这是唯一 `bound` 信号 |
|
||||
| `bindAct=0 + bindRole=1` | 角色已选中但未确认,是 `pending` |
|
||||
| `needBindAct=1` | 当前活动要求继续执行确认 |
|
||||
| `needBindRole=1` | 当前流程仍需要角色选择/角色信息 |
|
||||
| `changeRoleWaitTime` | 换绑倒计时;只有 `bindAct=1` 时才可能是真实冷却 |
|
||||
| `canChangeTime` | 可换绑绝对时间;未确认绑定不能据此拦截 |
|
||||
| `canChangeRole` | 页面/接口的换绑可用提示,必须结合 `bindAct` 解释 |
|
||||
|
||||
绑定响应没有游戏 UID、角色 ID、OpenID。不要尝试从角色名推导稳定角色身份。
|
||||
|
||||
### pending 判定顺序
|
||||
|
||||
单个候选按以下顺序解释,详细结果由 `binding_pending_decision()` 返回:
|
||||
|
||||
1. 没有角色名:不可确认;
|
||||
2. 动作 alias 上 `bindAct=0 + needBindAct=1 + roleName`:可确认,原因
|
||||
`existing_actionable_pending`;
|
||||
3. 没有扫码前 baseline:可确认,原因 `first_role_without_baseline`;
|
||||
4. 角色名与 baseline 不同:可确认,原因 `role_changed`;
|
||||
5. 角色名相同且 `bindAct=1`:已经绑定,不可重复确认;
|
||||
6. 同 alias 从 `bindAct=1` 转为 `bindAct=0 + needBindAct=1`:可确认,原因
|
||||
`same_alias_after_bound_transition`;
|
||||
7. 其他同名角色:视为旧残留,原因 `same_role_stale`。
|
||||
|
||||
规则 2 是 2026-11-21 线上修复:动作 alias 已经存在同名 pending 时,它仍是可执行
|
||||
确认的 pending,不应因为“角色名没变化”一直灰掉确认按钮。
|
||||
|
||||
### 完整流程
|
||||
|
||||
```text
|
||||
查询所有 query_act_aliases
|
||||
-> 找当前 bindAct=1(bound)
|
||||
-> 找动作 alias 上的可确认 pending
|
||||
-> 生成二维码
|
||||
-> 持久化 baseline、候选来源、判定原因
|
||||
-> binding_poll 每次只查一次角色
|
||||
-> 找到确认条件:任务 success + bind_ready_for_confirm=true
|
||||
-> actBind
|
||||
-> 回查 bindAct=1
|
||||
-> 写 accounts 当前角色和 role_bind_status=bound
|
||||
```
|
||||
|
||||
二维码任务不能在 worker 内长时间阻塞;出码后写 `binding_poll`、`next_run_at` 和
|
||||
`run_deadline_at`,由数据库调度器继续轮询。
|
||||
|
||||
### 确认前保护
|
||||
|
||||
- 传 `expected_role_name` 时,回查角色变化必须失败,不能确认另一个角色。
|
||||
- 确认失败时保留 `before_bound` 的已生效角色,不能把待确认角色写入账号。
|
||||
- `bindAct=0` 时 `changeRoleWaitTime` 再大也不是真实换绑冷却。
|
||||
- 只有确认后的 `bindAct=1` 才允许写 `bound` 和 `role_change_available_at`。
|
||||
|
||||
## 诊断日志
|
||||
|
||||
### 多渠道判定
|
||||
|
||||
日志关键字:`绑定多渠道判定 |`
|
||||
|
||||
每次输出一条 JSON,包含:
|
||||
|
||||
- `task_id`、`stage`:任务和阶段,如 `qr_preflight`、`poll:N`、
|
||||
`query_game_name`、`confirm_precheck`;
|
||||
- `action_aliases`:允许确认的活动来源;
|
||||
- `baseline_alias`、`baseline_role`、`baseline_bind_act`;
|
||||
- `selected_alias`;
|
||||
- `candidates[]`:每个 alias 的角色、`bindAct`、`bindRole`、`needBindAct`、
|
||||
`needBindRole`、是否动作 alias、是否可确认以及原因。
|
||||
|
||||
### 其他绑定日志
|
||||
|
||||
- `绑定前状态`:二维码生成前所有 alias、baseline、cooldown 和 pending 命中情况;
|
||||
- `轮询绑定#N`:每轮选中候选和摘要;
|
||||
- `确认前状态`:确认目标、expected role 和候选摘要;
|
||||
- `绑定判定`:确认/失败后的最终收敛。
|
||||
|
||||
任务结果持久化字段:
|
||||
|
||||
- `action_act_aliases`
|
||||
- `bind_decision`
|
||||
- `bind_candidate_decisions`
|
||||
- `pending_role_name`
|
||||
- `bind_summary`
|
||||
|
||||
建议的生产只读查询:
|
||||
|
||||
```sql
|
||||
SELECT id, task_type, status, message, created_at, finished_at,
|
||||
JSON_EXTRACT(result, '$.bind_decision') AS decision,
|
||||
JSON_EXTRACT(result, '$.bind_candidate_decisions') AS candidates,
|
||||
JSON_EXTRACT(result, '$.bind_summary') AS summary
|
||||
FROM douyu_tasks
|
||||
WHERE account_id = ?
|
||||
ORDER BY id DESC
|
||||
LIMIT 20;
|
||||
```
|
||||
|
||||
日志检索:
|
||||
|
||||
```bash
|
||||
docker compose logs douyu-login | grep '绑定多渠道判定'
|
||||
docker compose logs douyu-login | grep '确认前状态'
|
||||
```
|
||||
|
||||
## 精英宝典与兑换
|
||||
|
||||
当前精英宝典活动由 `manual_id`、`rid` 和配置中的活动 alias 共同确定。商品、积分、
|
||||
限兑、兑换记录和锁单查询统一走 `douyu_activity_query.py`。
|
||||
|
||||
| 范围 | 关键接口 |
|
||||
| --- | --- |
|
||||
| 手册用户信息 | `/wgapi/ordnc/activity/peace/getUserInfo` |
|
||||
| 商品列表 | `/wgapi/ordnc/activity/peace/storehome` |
|
||||
| 商品详情 | `/wgapi/ordnc/activity/peace/storedetail` |
|
||||
| 锁单 | `/wgapi/ordnc/activity/peace/createExchangeOrder` |
|
||||
| 支付锁单 | `/wgapi/ordnc/activity/peace/payExchangeOrder` |
|
||||
| 锁单列表 | `/wgapi/ordnc/activity/peace/getExchangeOrderList` |
|
||||
| 兑换记录 | `/wgapi/ordnc/activity/peace/exchangeList` |
|
||||
|
||||
兑换成功的唯一业务收口必须是 `payExchangeOrder` 成功后写入兑换事件;预约到货、
|
||||
预兑和等待开放即使返回 `success`,也不能当成真实兑换。
|
||||
|
||||
## 鱼翅、积分与支付
|
||||
|
||||
- 鱼翅余额:`https://cz.douyu.com/item/gold/account`
|
||||
- 钱包兑换余额:`https://www.douyu.com/wjapi/nc/exchange/fim`
|
||||
- 支付码:`/japi/oms/web/pay/getQrCode`
|
||||
- 供应商鱼翅直充按供应商协议执行;到账必须核对斗鱼余额相对下单前基线增加,
|
||||
供应商长期“待处理”不能覆盖实际到账事实。
|
||||
- 支付任务只负责出码和记录基线,到账轮询进入 `payment_poll` 独立任务槽。
|
||||
|
||||
## 电竞手册、和平小店与送礼
|
||||
|
||||
- 电竞手册绑定复用腾讯 `bindInfo` / `bindRoleParam` / `actBind`,但活动页、
|
||||
`manual_id`、`actAlias` 和账号字段必须独立,不能写成精英宝典数据。
|
||||
- 和平小店绑定和下单来自道聚城接口,确认逻辑仍遵守
|
||||
`bindAct=0` 为 pending、`bindAct=1` 为 bound。
|
||||
- 送礼是写操作,必须走写任务槽和代理;查询余额/积分不能替代送礼结果回查。
|
||||
|
||||
## 已知踩坑
|
||||
|
||||
### 2026-11-21:同名 pending 导致确认按钮一直灰
|
||||
|
||||
现象:二维码已出,界面显示“当前绑定”和角色,但 `pending=0`,确认按钮禁用。
|
||||
|
||||
生产证据:账号 `23385` 的二维码任务轮询 106 次后 `role_timeout`;`cjm` 与
|
||||
`20260120QYOOB` 返回同名角色,`cjm.needBindAct=0`,
|
||||
`QYOOB.bindAct=0 + needBindAct=1`。旧逻辑只接受“角色名变化”或“同 alias 从
|
||||
`bindAct=1` 转为 pending”,把已经存在的活动 pending 误判成旧残留。
|
||||
|
||||
修复:动作 alias 已存在同名 pending 时直接视为可确认,原因
|
||||
`existing_actionable_pending`;二维码预检也会立即收敛为 `role_ready`。
|
||||
|
||||
回归:`tests/test_douyu_binding_state.py`、`tests/test_douyu_account_probe.py`、
|
||||
`tests/test_douyu_task_concurrency.py`。
|
||||
|
||||
### 历史固定规则
|
||||
|
||||
- 不要把 `bindRole=1` 当成已绑定;
|
||||
- 不要把未确认时的换绑倒计时当成冷却;
|
||||
- 不要用 `cjm` 的旧角色覆盖活动 alias pending;
|
||||
- 不要在页面层重新实现 `bindAct/needBindAct` 判断;
|
||||
- 不要把原始 `bind_summary` 当业务文案,它只用于排障。
|
||||
|
||||
## 变更记录
|
||||
|
||||
| 日期 | 变更 |
|
||||
| --- | --- |
|
||||
| 2026-11-21 | 建立斗鱼协议总览;补充多 alias 职责、pending 真值表、结构化判定日志和同名 pending 修复记录 |
|
||||
@@ -49,6 +49,9 @@
|
||||
- 绑定响应只有角色名、区服、平台、昵称和头像,没有游戏 UID / 角色 ID;
|
||||
- 未最终绑定时即使接口返回换绑倒计时,也不能当成真实冷却。
|
||||
|
||||
完整的斗鱼绑定字段、`actAlias` 多来源规则、pending 判定原因和日志检索方式见
|
||||
[斗鱼协议总览](斗鱼/DOUYU_PROTOCOL_OVERVIEW.md)。
|
||||
|
||||
选号前会调用 `web/backend/services/douyu_account_state.py` 实时刷新账号:
|
||||
|
||||
- 不依赖 `status`、`ck_check_status`、`elite_opened`、`points` 等缓存结论;
|
||||
|
||||
Reference in New Issue
Block a user