修复(半自动履约): 稳定任务排序并拆分虎牙角色UID

This commit is contained in:
yml
2026-11-20 15:44:59 +08:00
parent 3b7d133dc9
commit e17d1ac8ab
23 changed files with 643 additions and 239 deletions
@@ -12,7 +12,7 @@ updated_at: 2026-11-20
> 状态:**唯一权威文档**。
> 最后校准:2026-11-20。
> 生产基线:迁移 `175`(2026-11-19 核对)。
> 开发基线:迁移 `178`(仅本地,尚未部署生产)。
> 开发基线:迁移 `179`(仅本地,尚未部署生产)。
>
> 从本文件生效起,订单、内部 SKU、履约渠道、履约载体、标准商品、成本和财务相关实现,
> 只能以本文件为业务口径。其他旧分析只作为历史资料,不再具备设计或验收效力。
@@ -317,16 +317,17 @@ manual fulfillment
- 半自动任务必须绑定 `order_item_id`、`fulfillments.id` 和人工履约配置,不得伪造接单平台工单。
- 半自动任务必须在 manual 渠道判定、人工配置保存/重匹配或 Carrier 补配成功后按订单项主动物化,
不能依赖客户先打开 `/c/<订单号>` 或客服先打开半自动任务列表。后台和客户页的幂等回填仅作为兜底。
- 虎牙客户页流程固定为「登录 → 填写资料 → 绑定角色 → 客服处理」:
① 资料三项(区服、游戏角色 UID、角色名)只能在登录成功后保存,未填全时不得生成绑定二维码,
- 虎牙客户页流程固定为「填写资料 → 登录虎牙账号 → 绑定角色 → 客服处理」:
① 资料三项(区服、游戏角色 UID、角色名)必须先保存,未填全时不得展示虎牙登录或生成绑定二维码,
页面状态显示「待客户填写资料」;
② 虎牙账号 UID(`huya_uid`)只用于 WUP/RPC 请求身份,与客户填写的游戏角色 UID 没有任何对应关系,
禁止互相回退或比较;
③ 虎牙 `gameRole.roleId` 是 40 位加密 opaque token,只保存为平台角色标识,用于判断虎牙前后两次
查询是否仍是同一角色,不得展示成游戏角色 UID,也不得与账号 UID 或客户游戏角色 UID 比较;
④ 当前虎牙接口未稳定返回独立数值游戏角色 UID。自动放行依据固定为角色名与区服:
`compareBindingRole` 仅在 `roleName + serverZone` 一致时返回 `match`;客户游戏角色 UID 只留档,
除非平台未来明确返回独立数值角色 UID,否则不参与自动比对;
③ 虎牙 `gameRole.roleId` 是 40 位加密 opaque token,只可在 Connector 内部用于判断前后两次查询
是否仍是同一角色;客户页、管理端和历史摘要不得展示该标识,也不得把它当角色 UID;
④ 平台返回 `gameSerial` 或 `gameRole.extendInfo` 中明确的数值角色 UID 时,必须分别保存到
`platform_game_role_uid` / `pending_platform_game_role_uid` 并纳入角色比对;当前实际响应可能
不返回独立数值 UID,此时页面只能展示客户填写的目标角色 UID,并明确平台未提供绑定角色 UID,
不得由加密 token、账号 UID 或客户 UID 互相回填;
⑤ 客户确认前必须通过 outer/inner 双路查询得到本次 pending 角色;确认绑定必须先呈现 pending 角色,
客户明确提交后才调用 `confirmBindActAccount`,写后回查 current 角色与 pending 一致才能进入
`binding_status = confirmed`。确认请求必须携带页面已核对的角色名、role token 与渠道快照,
@@ -338,7 +339,7 @@ manual fulfillment
平台未返回角色名或比对缺项时,只提供「复制订单号联系客服」和「刷新状态」。
- 客户点「上一步修改资料」时清空当前绑定与换绑失败状态:`binding_status` 回到 `not_started`,
清空 `bind_game_*`、`bound_at`、`last_error` 与换绑失败痕迹(`rebindUnchanged`/`rebindConfirmState` 等),
但保留登录状态、`credential_id`、`connector_session_id` 和客户已填资料三项。页面回到第二步并保留资料可编辑,
但保留登录状态、`credential_id`、`connector_session_id` 和客户已填资料三项。页面回到第一步并保留资料可编辑,
客户重新「提交资料」后重新识别平台角色、重新生成绑定二维码,不能复用旧的换绑失败状态。
- 登录状态和执行状态保存于 `semi_auto_tasks`,不得写入 `material_json` 作为正式状态。
`binding_status`、`bind_game_*`、`bind_game_role_token`、pending 角色、`bound_at` 和客户资料三项
@@ -744,13 +745,14 @@ has_active_cost
客户页 `/c/<平台订单号>` 统一展示:
```text
登录 → 查询或填写角色资料 → 绑定角色 → 客服处理 → 完成
填写或确认订单角色资料 → 登录平台账号 → 绑定角色 → 客服处理 → 完成
```
- 虎牙三步进度固定为「登录虎牙账号 → 填写游戏资料 → 绑定游戏角色」,当前步骤高亮,已完成为勾选。
- 登录成功后才展示资料表单;资料三项(区服 / 游戏角色 UID / 角色名)未填全时不展示绑定二维码。
- 虎牙三步进度固定为「填写游戏资料 → 登录虎牙账号 → 绑定游戏角色」,当前步骤高亮,已完成为勾选。
- 资料三项(区服 / 游戏角色 UID / 角色名)未填全时不展示虎牙登录和绑定二维码;资料保存后才引导登录。
- 绑定角色页分别展示虎牙账号 UID、当前平台角色、本次待确认角色与客户资料;角色名和区服一致才允许确认绑定,
客户游戏角色 UID 不与虎牙账号 UID 或平台加密 role token 比对;
客户游戏角色 UID 不与虎牙账号 UID 或平台加密 role token 比对;平台返回独立数值角色 UID 时同时展示
当前角色与待确认角色 UID,未返回时只能展示客户填写的目标角色 UID,不得把加密 role token 显示成 UID;
不一致时固定显示「重新扫码换绑」「上一步修改资料」,换绑后仍不一致时以修改资料为主。
- 微博登录成功后直接展示微信/QQ 绑定入口;平台返回已绑定角色时直接进入等待客服,
未绑定时展示扫码二维码,扫码后重新读取平台角色,角色名发生变化才视为换绑成功。
@@ -1176,7 +1178,7 @@ docs/archive/
## 十三、当前下一步
截至 2026-11-20,生产基线为 `175`,当前开发基线为 `178`。迁移 `152` 保护订单来源快照,
截至 2026-11-20,生产基线为 `175`,当前开发基线为 `179`。迁移 `152` 保护订单来源快照,
迁移 `158–160` 收口寄卖登记人同步、寄卖平台与自动匹配设置;
迁移 `161` 一次建立人工渠道半自动任务、内置 Connector 默认值、账号级 Cookie JSON 凭证、
任务凭证引用和最终约束;迁移 `162` 建立履约待办四桶只读投影、补载体专用索引和新单优先扫描口径。
@@ -1203,9 +1205,11 @@ pending 角色快照、`role_identity_source` 与 `verification_basis`。
区服无法解析或角色名/区服不一致时退出客服待办,进入客户补资料或换绑流程;无取消任务的唯一索引
允许旧任务保留审计、新配置创建新的活动任务。确认绑定写平台前先持久化 `submitting`,重启或超时后
只按数据库 pending 与平台 current 回查收敛,不得重复提交平台写操作。
迁移 `179` 将当前角色与待确认角色的平台数值 UID 分开持久化,禁止把待确认角色 UID 写入当前角色字段;
加密 role token 与数值角色 UID 是两个独立字段,任何情况下都不得互相回填。
迁移 `169` 增加客户游戏角色资料三项(`customer_game_role_name` / `customer_game_role_id` /
`customer_game_server_zone`),并允许从工单素材回退合并;客户页流程收敛为
「登录 → 填写资料 → 绑定角色」,资料未填全不得生成绑定二维码。
「填写资料 → 登录 → 绑定角色」,资料未填全不得展示登录或绑定二维码。
迁移 `170` 增加半自动全链路报文日志,客户页、管理端和外部 Connector 共用同一追踪口径;
虎牙角色自动比对改为角色名与区服;账号 UID、加密 role token、客户游戏角色 UID 三类身份禁止混用。
只读审计命令为 `npm run audit:huya-binding-identity -- --strict`。历史 `legacy_*` 留档只用于追溯,
@@ -1228,7 +1232,8 @@ pending 角色快照、`role_identity_source` 与 `verification_basis`。
6. 半自动平台负责客户登录、账号 CK 获取和游戏角色绑定;微博支持手机号登录、易盾二次验证、
完整域名 Cookie 保存、会话恢复、游戏角色查询和微信/QQ 扫码绑定;虎牙支持客户手动触发的
短信验证码登录和扫码登录。
虎牙客户登录后必须先填写区服 / 游戏角色 UID / 角色名,再进入绑定;虎牙账号 UID 只用于登录请求,
游戏角色 UID 只作为客户资料留档。角色名与区服一致后,客户确认本次 pending 角色才可提交平台绑定;
不一致时只能重新扫码换绑或返回上一步修改资料,不提供直接使用原角色的快捷确认。
虎牙客户必须先填写区服 / 游戏角色 UID / 角色名,再登录账号并进入绑定;虎牙账号 UID 只用于登录请求,
客户游戏角色 UID 作为订单目标资料,平台明确返回独立数值角色 UID 时必须另行保存并参与比对。
角色名与区服一致后,客户确认本次 pending 角色才可提交平台绑定;不一致时只能重新扫码换绑或返回
上一步修改资料,不提供直接使用原角色的快捷确认。
7. 观察期结束后,再单独发布兼容表、旧脚本别名和 `legacy_*` 字段的删除迁移。