完善虎牙外部单展示、状态恢复与礼包配置

docs/设计-虎牙外部CK协作台账.md

@@ -249,7 +249,9 @@ incomplete ─资料齐全且 CK 有效─▶ to_recharge ─充值核账─▶
 6. **回退必须显式声明**：目标阶段序号 < 当前时必须 `rollback=true`（界面勾「回退」），
    会清掉后面阶段的时间戳，审计里 `rollback=true` 留痕。
 7. **`failed` / `void` 是旁路**：流程内任意状态都能进（不用勾回退）；从这两态回到流程内
-   **必须** `rollback=true`。`void` 不可逆（只能编辑或新建），`failed` 可回流程内重试。
+   **必须** `rollback=true`。`void` 默认不可逆；确认属于误作废时，**超级管理员**可传
+   `force=true` + 必填原因强制恢复，审计记录操作人、原因和原 `void_reason`。
+   强制恢复只跳过“作废不可逆”限制，不绕过资料完整性与核账校验；`failed` 可回流程内重试。
 8. **`recharged` / `points_error` 不能人工直写**：`set_status()` 只有核账流程传
    `allow_recharge=True` 才接受这两个目标；普通状态接口和批量改状态都会返回
    `recharge_check_required`。`points_error` 补足/调整积分后重新核账即可回到 `recharged`
@@ -341,7 +343,8 @@ unverified ──探针成功──▶ valid ──探针失败──▶ invalid
 
 - 单条新增：表单里贴 CK（支持 `纯CK`、`账号----密码----CK` 两种形态，
   复用 `huya_service.parse_huya_cookie_line`，它是纯函数、不依赖账号表）
-  → 解析出 `uid/yyuid/hy_username` → 落表，`ck_status=unverified`。
+  → 解析出 `uid/yyuid/hy_username` → 只要带了 CK 就自动跑一次只读探针：
+  成功写绑定快照与虎牙昵称，失败如实写 `invalid` 和原因，但草稿单仍允许创建。
 - 批量导入：Excel/文本粘贴，见 §9.3。逐行解析，**部分失败不整体失败**，
   返回 `{created, updated, skipped, errors[]}`（每条错误的行号 + 原因）。
 - 重复 uid：如果 uid 已在本表 → 视为"换 CK"（更新 cookie 并记审计），
@@ -355,7 +358,7 @@ unverified ──探针成功──▶ valid ──探针失败──▶ invalid
 | 候选接口 | 有效 CK | 篡改/失效 | 能否当探针 |
 | --- | --- | --- | --- |
 | `get_redeem_need_goods`（积分中心） | 200 | 单改 `udb_cred`、甚至删光 `udb_` 字段仍 200 | ❌ 不校验凭据（tag7 是公共数据） |
-| `get_grow_level_user_info`（能拿虎牙昵称） | 成功 | 单改 `udb_cred` 仍成功 | ❌ 不看凭据 |
+| `get_grow_level_user_info` / `get_user_profile_batch`（能拿虎牙昵称） | 成功 | 单改 `udb_cred` 仍可能成功 | ❌ 不能单独判有效；只在绑定探针通过后做展示补全 |
 | `query_user_score` / `get_act_user_task_detail` / `get_user_prize_records` | — | — | ❌ 接口已下线（603「活动已结束」/ 601「活动已下线」） |
 | **`check_user_bind_game_account`** | `status=200` + 真实绑定数据 | **裸 cookie（无凭据）+ 真 uid → `None`；真 CK + 别人 uid → `None`** | ✅ **用它** |
 
@@ -370,8 +373,10 @@ unverified ──探针成功──▶ valid ──探针失败──▶ invalid
 - 成功时**覆盖写入绑定快照**：`bind_game_account` / `bind_game_role` / `bind_game_channel`
   + `bind_snapshot_at`（这几列探针独占，就是"现在到底绑了哪个号、哪个角色"）。
   覆盖前把旧值记进 `huya:collab:probe_snapshot` 审计；人工填的列（含 `bind_douyu_account`）**一律不碰**。
-- **不写 `nickname`**：按 §3.1 那是"虎牙号昵称"，这个探针给不出（能给出昵称的接口都不认凭据）
-  ——硬写就是假数据。
+- **`nickname` 单独补读**：绑定探针 `status=200` 后，再调 `huyauserui.getUserProfileBatch`
+  取该 uid 的 `nick`。这是展示辅助，不参与有效/失效判定；昵称接口失败时 CK 仍保持有效，
+  失败原因写进 `ck_check_message`。绝不能拿 `gameAccount.nick` 冒充，两者分别是
+  “绑定游戏账号昵称”和“虎牙平台账号昵称”。
 - 一次批量里单条失败不影响其他条（AGENTS §2：单项失败不要整体失败，但要如实暴露）。
   没有 CK 的行**保持 `unverified`**，不谎报成 `invalid`。
 
@@ -411,9 +416,14 @@ unverified ──探针成功──▶ valid ──探针失败──▶ invalid
   `gifts_message`，不影响 CK 的有效性结论）。商品积分取 `tag75.tag0.tag2`，与积分中心
   页面显示一致；不再依赖活动 SID。旧 `webActUI.getActPrizeList` 保留给精英宝典工作台的
   兑换链路，本模块不再调用；
+- **全部页签自动合并**（2026-11-11 HAR）：基础请求只返回第一个页签，页签定义在
+  `tag2[].tag5` 解出的分类列表里；后端自动用 `pageId + waterfallTabId` 补拉其余页签。
+  当前最新场次实测为「精英专享 18 + 限量返场 21 = 39」。活动参数可在「虎牙配置」里改
+  `points_page_code / points_source_id / points_scene`，自动发现失败时还可手工覆盖
+  `points_page_id / points_tab_ids`；
 - **礼包名默认空白**（2026-10-18 用户要求）：不再自动带上次选的礼包，避免没注意时建错单；
   想少点两下用「常用礼包」快捷按钮；
-- **礼包列表缓存**：前端 localStorage（`huya.collab.gifts.v2`，存 `{at, gifts}`）—— 一个活动期间礼包清单基本不变，
+- **礼包列表缓存**：前端 localStorage（`huya.collab.gifts.v3`，存 `{at, gifts}`）—— 一个活动期间礼包清单基本不变，
   贴 CK 时**不再每次都去虎牙拉**（`with_gifts=false`），要用最新库存点「强制刷新礼包」；
   缓存时间摆在礼包名下方，商品清单变了就点一次强制刷新；
 - **探针缓存**：同一份 CK 在 `PROBE_CACHE_TTL_SECONDS`（90 秒）内复用结论 ——
@@ -757,10 +767,10 @@ unverified ──探针成功──▶ valid ──探针失败──▶ invalid
 1. **探针判据必须是「非 None 且 `status == 200`」**：真机上「裸 cookie + 真 uid」与
    「真 CK + 别人 uid」都返回 `None`，只有两者都对才拿到 200——这是唯一能区分有效/失效的
    信号组合。反向验证（把判据改成「有数据就算成功」）会让 3 个用例变红。
-2. **探针能补的字段只有 `bind_douyu_account` / `bind_douyu_uid`**：返回的是**绑定在该虎牙号
-   上的游戏账号**（账号昵称 / 角色名 / 角色 id）。`nickname` 按 §3.1 是"虎牙号昵称"，
-   本探针给不出（能给出昵称的 `get_grow_level_user_info` 不校验凭据，当不了探针），
-   **不能拿游戏账号昵称冒充**。原稿 §5.2 写的"顺带补 nickname"据此修正。
+2. **游戏账号与虎牙昵称是两套字段**：绑定探针返回的是**绑定在该虎牙号上的游戏账号**
+   （`gameAccount.nick` / 角色名 / 角色 id）；`nickname` 按 §3.1 是"虎牙平台账号昵称"。
+   现在的做法是绑定探针确认 CK 有效后，再用 `get_user_profile_batch` 单独补 `nickname`；
+   昵称失败不影响 CK 结论，且**不能拿游戏账号昵称冒充**。
 3. **绑定快照由探针独占（2026-10-16 当天修订）**：最早实现是"只补空值写
    `bind_douyu_account`"，用户明确要求"展示绑定在该虎牙号上的游戏账号、**绑定角色重要**、
    之前那套不要了"之后，改成探针**覆盖写入** `bind_game_account`/`bind_game_role`/
@@ -829,6 +839,17 @@ unverified ──探针成功──▶ valid ──探针失败──▶ invalid
 6. **记忆里的礼包不在本次列表里**：清空并提示「上次选的「xx」不在这次拉到的礼包列表里，
    请重新点选」（拉取失败时**不**清，避免把人卡死）。
 
+### 11.4.1 2026-11-11 礼包页签自动发现
+
+1. `queryAllocation` 基础响应里的 `tag5` 同时包含当前页签商品和其他页签元数据
+   （`tag0=tabId`、`tag1=名称`、`tag7=商品数`）。后端据此自动补拉，`433` 这类 ID
+   随活动变化时不需要改代码。
+2. 新增 `huya_config.points_page_code / points_source_id / points_scene /
+   points_page_id / points_tab_ids`：前三个控制请求入口；后两个留空时自动发现，
+   填了才覆盖，接口小改版可直接在页面配置，不必重新发版。
+3. 缓存键升级为 v3。v2 缓存只有「精英专享」18 个商品，不换键会让部署后的页面继续
+   使用旧列表。
+
 ### 11.5 2026-10-16 第二轮页面复核（用户点着看又提的）
 
 1. **弹窗放大了**：新建协作单 `width` 520→**920**、表单 `size` 回到 `middle`、CK 输入框 3→5 行、