修复(半自动履约): 拆分虎牙账号与角色身份并恢复CK注入
This commit is contained in:
+41
-21
@@ -3,16 +3,16 @@ type: 权威架构与实施计划
|
||||
description: 订单、内部 SKU、履约路由、履约执行、商品、成本与财务的唯一权威口径及重构计划。
|
||||
tags: [订单, 内部SKU, 履约, 商品, 成本, 财务, 迁移]
|
||||
status: authoritative
|
||||
version: 2.29
|
||||
updated_at: 2026-11-18
|
||||
version: 2.30
|
||||
updated_at: 2026-11-19
|
||||
---
|
||||
|
||||
# 统一订单、履约与财务模型
|
||||
|
||||
> 状态:**唯一权威文档**。
|
||||
> 最后校准:2026-11-18。
|
||||
> 生产基线:迁移 `166`。
|
||||
> 开发基线:迁移 `172`(仅本地,尚未部署生产)。
|
||||
> 生产基线:迁移 `175`(2026-11-19 核对)。
|
||||
> 开发基线:迁移 `176`(仅本地,尚未部署生产)。
|
||||
>
|
||||
> 从本文件生效起,订单、内部 SKU、履约渠道、履约载体、标准商品、成本和财务相关实现,
|
||||
> 只能以本文件为业务口径。其他旧分析只作为历史资料,不再具备设计或验收效力。
|
||||
@@ -318,23 +318,31 @@ manual fulfillment
|
||||
- 半自动任务必须在 manual 渠道判定、人工配置保存/重匹配或 Carrier 补配成功后按订单项主动物化,
|
||||
不能依赖客户先打开 `/c/<订单号>` 或客服先打开半自动任务列表。后台和客户页的幂等回填仅作为兜底。
|
||||
- 虎牙客户页流程固定为「登录 → 填写资料 → 绑定角色 → 客服处理」:
|
||||
① 资料三项(区服、游戏编号、角色名)只能在登录成功后保存,未填全时不得生成绑定二维码,
|
||||
① 资料三项(区服、游戏角色 UID、角色名)只能在登录成功后保存,未填全时不得生成绑定二维码,
|
||||
页面状态显示「待客户填写资料」;
|
||||
② 游戏编号应填写虎牙账号 UID;平台返回数值角色 ID 时以该 ID 核对,仅返回加密角色 ID 时
|
||||
回退登录账号 UID,两者都拿不到判 `unknown`;
|
||||
③ 区服、角色名、角色 ID 三项必须全部存在且一致,`compareBindingRole` 返回 `match` 后才允许
|
||||
「提交平台绑定」;任一项缺失判 `unknown` 转客服核实,任一项不等判 `mismatch` 禁止提交。
|
||||
② 虎牙账号 UID(`huya_uid`)只用于 WUP/RPC 请求身份,与客户填写的游戏角色 UID 没有任何对应关系,
|
||||
禁止互相回退或比较;
|
||||
③ 虎牙 `gameRole.roleId` 是 40 位加密 opaque token,只保存为平台角色标识,用于判断虎牙前后两次
|
||||
查询是否仍是同一角色,不得展示成游戏角色 UID,也不得与账号 UID 或客户游戏角色 UID 比较;
|
||||
④ 当前虎牙接口未稳定返回独立数值游戏角色 UID。自动放行依据固定为角色名与区服:
|
||||
`compareBindingRole` 仅在 `roleName + serverZone` 一致时返回 `match`;客户游戏角色 UID 只留档,
|
||||
除非平台未来明确返回独立数值角色 UID,否则不参与自动比对;
|
||||
⑤ 客户确认前必须通过 outer/inner 双路查询得到本次 pending 角色;确认绑定必须先呈现 pending 角色,
|
||||
客户明确提交后才调用 `confirmBindActAccount`,写后回查 current 角色与 pending 一致才能进入
|
||||
`binding_status = confirmed`。确认请求必须携带页面已核对的角色名、role token 与渠道快照,
|
||||
Connector 发现 pending 已变化时拒绝写入;轮询和二维码刷新不得自动提交平台写操作。
|
||||
- 角色不一致时客户页固定提供两个动作:「重新扫码换绑」和「上一步修改资料」。
|
||||
平台已有旧角色导致首次不一致、扫码绑定后不一致、换绑被虎牙拒绝或未生效时,以重新扫码换绑为主;
|
||||
换绑后仍不一致时以「上一步修改资料」为主。取消「直接使用原角色」的快捷确认:
|
||||
客户若想使用平台现有角色,必须返回上一步让资料与平台角色一致后再提交。
|
||||
平台未返回可核对角色 ID 或比对缺项时,只提供「复制订单号联系客服」和「刷新状态」。
|
||||
平台未返回角色名或比对缺项时,只提供「复制订单号联系客服」和「刷新状态」。
|
||||
- 客户点「上一步修改资料」时清空当前绑定与换绑失败状态:`binding_status` 回到 `not_started`,
|
||||
清空 `bind_game_*`、`bound_at`、`last_error` 与换绑失败痕迹(`rebindUnchanged`/`rebindConfirmState` 等),
|
||||
但保留登录状态、`credential_id`、`connector_session_id` 和客户已填资料三项。页面回到第二步并保留资料可编辑,
|
||||
客户重新「提交资料」后重新识别平台角色、重新生成绑定二维码,不能复用旧的换绑失败状态。
|
||||
- 登录状态和执行状态保存于 `semi_auto_tasks`,不得写入 `material_json` 作为正式状态。
|
||||
`binding_status`、`bind_game_*`、`bind_game_role_id`、`bound_at` 和客户资料三项属于正式绑定流程,
|
||||
`binding_status`、`bind_game_*`、`bind_game_role_token`、pending 角色、`bound_at` 和客户资料三项
|
||||
属于正式绑定流程,
|
||||
迁移 `168`、`169` 已落库;绑定确认后执行状态才进入 `waiting_operator`。
|
||||
- 平台 CK 是账号级凭证,唯一持久化真源为 `semi_auto_credentials`。Cookie 集合按平台 UID 唯一保存,
|
||||
以未加密 Cookie JSON 写入 `credential_payload_json`,并记录来源、更新时间、健康状态和最近检查错误。
|
||||
@@ -342,6 +350,9 @@ manual fulfillment
|
||||
- Connector 会话仍是进程内短期缓存,但不再是唯一真源。进程重启、会话过期或实例切换后,
|
||||
支持恢复的执行器必须从账号级 Cookie JSON 恢复会话;恢复前校验平台 UID,
|
||||
恢复失败时更新凭证健康状态并要求重新登录。
|
||||
- 后台“注入浏览器”必须先生成或恢复当前任务的 Connector 会话,再创建一次性注入票据;
|
||||
不得只读取数据库 `credential_status = valid` 就直接要求内存会话存在。虎牙内置 Connector
|
||||
必须从账号级 CK 恢复账号 UID、登录 Cookie 和设备身份后继续生成票据。
|
||||
- 平台明确返回 CK 失效或账号不一致时,当前任务必须退出“已授权”状态,清空当前 Connector 会话并回到
|
||||
`waiting_customer / waiting_login / not_started`;账号级凭证和历史事件保留用于审计。客服可对该任务
|
||||
执行“重新发送授权”,重置当前任务并复制客户 `/c/<平台订单号>` 链接,客户重新登录后更新 CK。
|
||||
@@ -380,8 +391,9 @@ manual fulfillment
|
||||
不绕过平台风控。发码与挑战原始响应必须记录到集成日志,但日志系统必须继续屏蔽 Cookie、令牌、
|
||||
验证码等敏感字段。`qr_auth` 和二次短信验证必须明确提示,不得伪装成可完成的图形验证。
|
||||
- 虎牙客户登录成功后立即保存 CK,但流程继续进入「填写资料 → 绑定角色」,不直接进入等待客服。
|
||||
提交资料后平台账号没有角色时展示绑定二维码;已有角色时与资料比对,三项完全一致才允许提交平台绑定;
|
||||
不一致时只能重新扫码换绑或返回上一步修改资料,不能绕过确认门禁直接完成履约。
|
||||
提交资料后平台账号没有角色时展示绑定二维码;扫码后先用双路查询识别 pending 角色,
|
||||
角色名与区服一致且客户明确确认后才允许提交平台绑定;不一致时只能重新扫码换绑或返回上一步修改资料,
|
||||
不能绕过确认门禁直接完成履约。
|
||||
- 浏览器扩展复用 live-hub-py 的 `web/extension/huya-exchange-helper`,不新增第二个扩展;
|
||||
扩展只允许消费一次性注入票据,页面不得直接读取 CK。
|
||||
- 客服完成半自动任务必须与 `confirmManualFulfillment` 在同一数据库事务中提交:
|
||||
@@ -390,7 +402,8 @@ manual fulfillment
|
||||
- 半自动履约状态采用与斗鱼领取一致的同步原则:客户操作、Connector 回调和后台操作都是状态快照输入,
|
||||
统一由一个状态收敛服务在任务行锁内写入正式字段并追加事件;多个入口不得各自拼接或覆盖状态。
|
||||
- 账号绑定能力由平台声明,不由页面或业务服务按平台散落判断。虎牙、斗鱼、微博均为 `game_role`:
|
||||
虎牙必需字段 `roleName / roleId / serverZone`,由 order_site 查询、客户比对确认和提交换绑;
|
||||
虎牙必需字段为 `roleName / serverZone`;平台若未来明确返回独立数值游戏角色 UID,才额外启用
|
||||
`roleId` 核验,`gameRole.roleId` 加密 token 本身不参与客户资料比对;
|
||||
斗鱼必需字段 `roleName / serverZone`,由 live-hub 查询和提交换绑;
|
||||
微博必需字段 `roleName`,由 order_site 查询,微信/QQ 扫码完成绑定或换绑,不要求客户重复填写角色资料。
|
||||
公共策略还必须声明 `confirmationMode` 与 `rebindMode`:虎牙、斗鱼为客户资料比对确认,
|
||||
@@ -720,8 +733,9 @@ has_active_cost
|
||||
```
|
||||
|
||||
- 虎牙三步进度固定为「登录虎牙账号 → 填写游戏资料 → 绑定游戏角色」,当前步骤高亮,已完成为勾选。
|
||||
- 登录成功后才展示资料表单;资料三项(区服 / 游戏编号 / 角色名)未填全时不展示绑定二维码。
|
||||
- 绑定角色页展示平台角色与客户资料的逐项对照:三项完全一致才出现「提交平台绑定」;
|
||||
- 登录成功后才展示资料表单;资料三项(区服 / 游戏角色 UID / 角色名)未填全时不展示绑定二维码。
|
||||
- 绑定角色页分别展示虎牙账号 UID、当前平台角色、本次待确认角色与客户资料;角色名和区服一致才允许确认绑定,
|
||||
客户游戏角色 UID 不与虎牙账号 UID 或平台加密 role token 比对;
|
||||
不一致时固定显示「重新扫码换绑」「上一步修改资料」,换绑后仍不一致时以修改资料为主。
|
||||
- 微博登录成功后直接展示微信/QQ 绑定入口;平台返回已绑定角色时直接进入等待客服,
|
||||
未绑定时展示扫码二维码,扫码后重新读取平台角色,角色名发生变化才视为换绑成功。
|
||||
@@ -1147,7 +1161,7 @@ docs/archive/
|
||||
|
||||
## 十三、当前下一步
|
||||
|
||||
截至 2026-11-18,生产基线为 `166`,集成分支开发基线为 `172`。迁移 `152` 保护订单来源快照,
|
||||
截至 2026-11-19,生产基线为 `175`,当前开发基线为 `176`。迁移 `152` 保护订单来源快照,
|
||||
迁移 `158–160` 收口寄卖登记人同步、寄卖平台与自动匹配设置;
|
||||
迁移 `161` 一次建立人工渠道半自动任务、内置 Connector 默认值、账号级 Cookie JSON 凭证、
|
||||
任务凭证引用和最终约束;迁移 `162` 建立履约待办四桶只读投影、补载体专用索引和新单优先扫描口径。
|
||||
@@ -1161,12 +1175,17 @@ docs/archive/
|
||||
迁移 `166` 让接单平台路由支持动态模板匹配,清理历史伪造 key 和草稿商品,并拒绝对不存在模板
|
||||
的非空 `workRuleKey` 写入。
|
||||
迁移 `167` 清理待判定履约记录对历史假草稿商品的残留引用,并增加履约商品关联闸门。
|
||||
迁移 `168` 为半自动任务增加可核对的绑定角色 ID(`bind_game_role_id`)。
|
||||
迁移 `168` 曾新增 `bind_game_role_id`,后续生产事实证实现行虎牙返回的是加密 role token;
|
||||
迁移 `176` 将其语义拆分并冻结旧字段,新增 `bind_game_role_token`、`platform_game_role_uid`、
|
||||
pending 角色快照、`role_identity_source` 与 `verification_basis`。
|
||||
迁移 `169` 增加客户游戏角色资料三项(`customer_game_role_name` / `customer_game_role_id` /
|
||||
`customer_game_server_zone`),并允许从工单素材回退合并;客户页流程收敛为
|
||||
「登录 → 填写资料 → 绑定角色」,资料未填全不得生成绑定二维码。
|
||||
迁移 `170` 增加半自动全链路报文日志,客户页、管理端和外部 Connector 共用同一追踪口径;
|
||||
角色比对仍以区服、角色名、角色 ID 三项完全一致作为「提交平台绑定」的唯一放行条件。
|
||||
虎牙角色自动比对改为角色名与区服;账号 UID、加密 role token、客户游戏角色 UID 三类身份禁止混用。
|
||||
只读审计命令为 `npm run audit:huya-binding-identity -- --strict`。历史 `legacy_*` 留档只用于追溯,
|
||||
当前字段出现账号 UID 复用、非法 role token、非法平台角色 UID,或平台角色 UID 由账号 UID
|
||||
回填时,严格审计必须失败。
|
||||
迁移 `171` 建立斗鱼客户领取、live-hub 事务 Outbox/Inbox 和绑定状态安全投影。
|
||||
迁移 `172` 将 order_site → live-hub 订单事件升级为订单项快照契约,增加配置停用/订单关闭收敛、
|
||||
稳定去重指纹和 `live_state_version`;live-hub 同步增加 `next_allocate_at`、即时选号唤醒与
|
||||
@@ -1184,6 +1203,7 @@ docs/archive/
|
||||
6. 半自动平台负责客户登录、账号 CK 获取和游戏角色绑定;微博支持手机号登录、易盾二次验证、
|
||||
完整域名 Cookie 保存、会话恢复、游戏角色查询和微信/QQ 扫码绑定;虎牙支持客户手动触发的
|
||||
短信验证码登录和扫码登录。
|
||||
虎牙客户登录后必须先填写区服 / 游戏编号 / 角色名,再进入绑定;三项与平台角色完全一致
|
||||
才能提交平台绑定,不一致时只能重新扫码换绑或返回上一步修改资料,不提供直接使用原角色的快捷确认。
|
||||
虎牙客户登录后必须先填写区服 / 游戏角色 UID / 角色名,再进入绑定;虎牙账号 UID 只用于登录请求,
|
||||
游戏角色 UID 只作为客户资料留档。角色名与区服一致后,客户确认本次 pending 角色才可提交平台绑定;
|
||||
不一致时只能重新扫码换绑或返回上一步修改资料,不提供直接使用原角色的快捷确认。
|
||||
7. 观察期结束后,再单独发布兼容表、旧脚本别名和 `legacy_*` 字段的删除迁移。
|
||||
|
||||
Reference in New Issue
Block a user