文档更新

This commit is contained in:
2026-11-17 20:41:19 +08:00
parent 23b8e4fdd3
commit 96b1690754
@@ -299,7 +299,9 @@ terminal 已退款、退款申请、平台取消或商业订单已关闭
```text
manual fulfillment
→ semi_auto_tasks
→ 平台登录 / 获取账号 CK
→ 客户登录平台并获取账号 CK
→ 客户填写游戏角色资料(区服 / 游戏编号 / 角色名)
→ 核对并绑定平台角色
→ 客服使用 CK 在平台侧手动处理
→ confirmManualFulfillment
```
@@ -311,11 +313,25 @@ manual fulfillment
- 半自动任务必须绑定 `order_item_id`、`fulfillments.id` 和人工履约配置,不得伪造接单平台工单。
- 半自动任务必须在 manual 渠道判定、人工配置保存/重匹配或 Carrier 补配成功后按订单项主动物化,
不能依赖客户先打开 `/c/<订单号>` 或客服先打开半自动任务列表。后台和客户页的幂等回填仅作为兜底。
- 当前阶段半自动平台接入的唯一职责是让客户完成平台登录并取得账号 CK。角色绑定、换绑、
角色校验和绑定失败处置属于后续业务流程,不进入当前客户页、主状态机或完成门禁。
- 虎牙客户页流程固定为「登录 → 填写资料 → 绑定角色 → 客服处理」:
① 资料三项(区服、游戏编号、角色名)只能在登录成功后保存,未填全时不得生成绑定二维码,
页面状态显示「待客户填写资料」;
② 游戏编号应填写虎牙账号 UID;平台返回数值角色 ID 时以该 ID 核对,仅返回加密角色 ID 时
回退登录账号 UID,两者都拿不到判 `unknown`;
③ 区服、角色名、角色 ID 三项必须全部存在且一致,`compareBindingRole` 返回 `match` 后才允许
「提交平台绑定」;任一项缺失判 `unknown` 转客服核实,任一项不等判 `mismatch` 禁止提交。
- 角色不一致时客户页固定提供两个动作:「重新扫码换绑」和「上一步修改资料」。
平台已有旧角色导致首次不一致、扫码绑定后不一致、换绑被虎牙拒绝或未生效时,以重新扫码换绑为主;
换绑后仍不一致时以「上一步修改资料」为主。取消「直接使用原角色」的快捷确认:
客户若想使用平台现有角色,必须返回上一步让资料与平台角色一致后再提交。
平台未返回可核对角色 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_*` 和 `bound_at` 仅作历史兼容字段保留,当前登录、客服处理和完成主流程
不读取、不写入、不作为任何门禁。
`binding_status`、`bind_game_*`、`bind_game_role_id`、`bound_at` 和客户资料三项属于正式绑定流程,
迁移 `168`、`169` 已落库;绑定确认后执行状态才进入 `waiting_operator`。
- 平台 CK 是账号级凭证,唯一持久化真源为 `semi_auto_credentials`。Cookie 集合按平台 UID 唯一保存,
以未加密 Cookie JSON 写入 `credential_payload_json`,并记录来源、更新时间、健康状态和最近检查错误。
`semi_auto_tasks.credential_id` 只引用账号凭证,任务表不保存 CK 明文。
@@ -347,8 +363,9 @@ manual fulfillment
页面完成,服务端接收客户最终角度或点击坐标后生成对应交互轨迹。所有自动化都只复现正常浏览器交互,
不绕过平台风控。发码与挑战原始响应必须记录到集成日志,但日志系统必须继续屏蔽 Cookie、令牌、
验证码等敏感字段。`qr_auth` 和二次短信验证必须明确提示,不得伪装成可完成的图形验证。
- 虎牙客户登录成功后,无论账号此前是否已有角色,都立即保存 CK 并进入等待客服处理。
角色绑定、换绑和角色状态查询在后续独立流程实现,不能阻塞当前 CK 获取。
- 虎牙客户登录成功后立即保存 CK,但流程继续进入「填写资料 → 绑定角色」,不直接进入等待客服。
提交资料后平台账号没有角色时展示绑定二维码;已有角色时与资料比对,三项完全一致才允许提交平台绑定;
不一致时只能重新扫码换绑或返回上一步修改资料,不能绕过确认门禁直接完成履约。
- 浏览器扩展复用 live-hub-py 的 `web/extension/huya-exchange-helper`,不新增第二个扩展;
扩展只允许消费一次性注入票据,页面不得直接读取 CK。
- 客服完成半自动任务必须与 `confirmManualFulfillment` 在同一数据库事务中提交:
@@ -639,12 +656,16 @@ has_active_cost
客户页 `/c/<平台订单号>` 统一展示:
```text
平台登录 → 获取 CK → 客服处理 → 完成
登录 → 填写资料 → 绑定角色 → 客服处理 → 完成
```
页面只能展示客户完成操作所需的最小信息,不得展示 CK、内部成本或其他订单。后台默认只展示平台 UID、
凭证来源、健康状态、更新时间、CK 导出和一次性注入入口。CK 导出不依赖角色绑定、任务领取人或
额外权限;导出动作必须留审计且不得复用普通详情接口。
- 三步进度固定为「登录虎牙账号 → 填写游戏资料 → 绑定游戏角色」,当前步骤高亮,已完成为勾选。
- 登录成功后才展示资料表单;资料三项(区服 / 游戏编号 / 角色名)未填全时不展示绑定二维码。
- 绑定角色页展示平台角色与客户资料的逐项对照:三项完全一致才出现「提交平台绑定」;
不一致时固定显示「重新扫码换绑」「上一步修改资料」,换绑后仍不一致时以修改资料为主。
- 页面只能展示客户完成操作所需的最小信息,不得展示 CK、内部成本或其他订单。后台默认只展示平台 UID、
凭证来源、健康状态、更新时间、CK 导出和一次性注入入口。CK 导出不依赖绑定状态、任务领取人或
额外权限;导出动作必须留审计且不得复用普通详情接口。
### 7.2 接单平台订单关闭
@@ -1064,7 +1085,7 @@ docs/archive/
## 十三、当前下一步
截至 2026-11-15,生产基线为 `166`,集成分支开发基线为 `167`。迁移 `152` 保护订单来源快照,
截至 2026-11-17,生产基线为 `166`,集成分支开发基线为 `170`。迁移 `152` 保护订单来源快照,
迁移 `158–160` 收口寄卖登记人同步、寄卖平台与自动匹配设置;
迁移 `161` 一次建立人工渠道半自动任务、内置 Connector 默认值、账号级 Cookie JSON 凭证、
任务凭证引用和最终约束;迁移 `162` 建立履约待办四桶只读投影、补载体专用索引和新单优先扫描口径。
@@ -1078,6 +1099,12 @@ docs/archive/
迁移 `166` 让接单平台路由支持动态模板匹配,清理历史伪造 key 和草稿商品,并拒绝对不存在模板
的非空 `workRuleKey` 写入。
迁移 `167` 清理待判定履约记录对历史假草稿商品的残留引用,并增加履约商品关联闸门。
迁移 `168` 为半自动任务增加可核对的绑定角色 ID(`bind_game_role_id`)。
迁移 `169` 增加客户游戏角色资料三项(`customer_game_role_name` / `customer_game_role_id` /
`customer_game_server_zone`),并允许从工单素材回退合并;客户页流程收敛为
「登录 → 填写资料 → 绑定角色」,资料未填全不得生成绑定二维码。
迁移 `170` 增加半自动全链路报文日志,客户页、管理端和外部 Connector 共用同一追踪口径;
角色比对仍以区服、角色名、角色 ID 三项完全一致作为「提交平台绑定」的唯一放行条件。
迁移中保留的 `semi_auto.credential.export` 权限仅作兼容记录,
不再作为 CK 导出门禁。
@@ -1088,7 +1115,8 @@ docs/archive/
4. 执行 `finance:rebuild-derived` 的 dry-run,核对 A 级数据守恒后,
再按窗口执行 `--execute --confirm=REBUILD_DERIVED`,并验证第二次重建幂等。
5. 观察一个完整财务期间,确认页面、履约、事实和总账持续对平。
6. 半自动平台当前只负责客户登录和账号 CK 获取;微博支持手机号登录、易盾二次验证、
6. 半自动平台负责客户登录、账号 CK 获取和游戏角色绑定;微博支持手机号登录、易盾二次验证、
完整域名 Cookie 保存和会话恢复;虎牙支持客户手动触发的短信验证码登录和扫码登录。
角色绑定与换绑后续独立设计,不阻塞 CK 获取和客服处理。
虎牙客户登录后必须先填写区服 / 游戏编号 / 角色名,再进入绑定;三项与平台角色完全一致
才能提交平台绑定,不一致时只能重新扫码换绑或返回上一步修改资料,不提供直接使用原角色的快捷确认。
7. 观察期结束后,再单独发布兼容表、旧脚本别名和 `legacy_*` 字段的删除迁移。