refactor(huya): 协作台账 failed 状态展示名「兑换失败」→「抢购失败」（枚举值不变）

2026-10-16 22:09:21 +08:00
parent fdc57752dc
commit 6ef74c8e45
5 changed files with 29 additions and 28 deletions
@@ -202,7 +202,7 @@ CK 自带完整生命周期（导入 → 验证 → 使用/失效 → 重贴/重
 ```
 pending ─人工确认─▶ bound ─充值─▶ recharged ─上脚本─▶ scripted ─抢购成功─▶ done
   │                 │              │                 │                  │
-   └─────────────────┴──────────────┴─────────────────┴──────────────────┴──▶ failed（兑换失败）
+   └─────────────────┴──────────────┴─────────────────┴──────────────────┴──▶ failed（抢购失败）
   │                 │              │                 │                  │
   └─────────────────┴──────────────┴─────────────────┴──────────────────┴──▶ void（作废）
 ```
@@ -214,7 +214,7 @@ pending ─人工确认─▶ bound ─充值─▶ recharged ─上脚本─▶
 | `recharged` | 已充值 | 充值完成后手动切（可跳步）；写 `recharged_at` | 人工 |
 | `scripted` | 已上脚本 | 脚本上完后手动切（可跳步）；写 `scripted_at` | 人工 |
 | `done` | **抢购成功** | 人工切；**或**「已上脚本」的单查积分/兑换记录命中礼包后自动切（§5.7） | 人工 / 系统判定 |
-| `failed` | **兑换失败** | 人工切；**或**「已上脚本」的单查兑换记录**没有**这个礼包后自动切（§5.7） | 人工 / 系统判定 |
+| `failed` | **抢购失败** | 人工切；**或**「已上脚本」的单查兑换记录**没有**这个礼包后自动切（§5.7） | 人工 / 系统判定 |
 | `void` | 已作废 | 任意流程内状态可进；`void_reason` 必填 | 人工 |

 **规则**（2026-10-16 用户拍板的口径，旧版"只能一步一步往前"作废）：
@@ -391,7 +391,7 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**（红
 | 情况 | verdict | 业务状态 |
 | --- | --- | --- |
 | 兑换记录里有这一单的礼包（名字互相包含即算命中，`gift_matches_records()`） | `success` | 「已上脚本」→ 自动「抢购成功」`done` |
-| 接口通了，但记录里没有这个礼包 | `failed` | 「已上脚本」→ 自动「兑换失败」`failed` |
+| 接口通了，但记录里没有这个礼包 | `failed` | 「已上脚本」→ 自动「抢购失败」`failed` |
 | 接口没通 / 这单没填礼包名 | `unknown` | **不动**（数据不够，不许瞎判） |

 **四条边界**：
@@ -543,7 +543,7 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**（红
 - **状态**：Tag 展示，行内"下一步"按钮推进（带二次确认）；
 - **CK 状态**：Tag + 一键"验证"；
 - 筛选：店铺 / 负责人 / 业务状态 / CK 状态 / 关键词（订单号、绑定账号、角色、uid）；
- 页头统计条：`待处理 N / 已确认绑定 N / 已充值·已上脚本 N / 抢购成功 N / 兑换失败 N / 已作废 N`（`done` 的展示名 2026-10-16 由「已完成」改为「抢购成功」，枚举值与库里数据不变）。
+- 页头统计条：`待处理 N / 已确认绑定 N / 已充值·已上脚本 N / 抢购成功 N / 抢购失败 N / 已作废 N`（`done` / `failed` 的展示名 2026-10-16 由「已完成」/「兑换失败」改成「抢购成功」/「抢购失败」，枚举值与库里数据不变）。

 > 交互细节（2026-10-16 用户拍板）：**店铺是点选按钮组**（列表里点单元格弹出同一组按钮，
 > 筛选条里也是），不是下拉；**新建时不用选负责人**——默认就是当前登录账号
@@ -802,12 +802,12 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**（红

 | 面 | 落地 |
 | --- | --- |
-| 状态机（服务层） | 新增终态 `failed`（兑换失败）；`bound` 标签改「已确认绑定」；`is_forward_status()` 允许往前跳步；`_assert_can_enter_bound()` 改成 CK + 绑定角色 + 主页截图；`void`/`failed` 不动时间戳 |
+| 状态机（服务层） | 新增终态 `failed`（抢购失败）；`bound` 标签改「已确认绑定」；`is_forward_status()` 允许往前跳步；`_assert_can_enter_bound()` 改成 CK + 绑定角色 + 主页截图；`void`/`failed` 不动时间戳 |
 | 批量改状态 | `set_status_batch()` + `POST /external-orders/status/batch`（逐行 SAVEPOINT 隔离，上限 50） |
 | 全生命周期 | 新表 `huya_external_order_metrics` + 迁移 `20261016_0059`；`query_order_activity()` / `query_activity_batch()`；`POST /{id}/activity/query`、`POST /activity/query`、`GET /{id}/metrics`；列表回填 `last_score/last_metric_at/last_verdict/last_metric_message` |
-| 前端 | 状态筛选与汇总卡片加「兑换失败」；工具栏「批量改状态（下拉选目标）」+「批量查积分/兑换」；行操作加「查积分 / 兑换记录」「改状态…」；列表加「积分」列（积分 + 判定徽标 + 时间，全文进 Tooltip）；详情抽屉加「账号全生命周期」时间线 + 逐条命中的兑换记录 |
+| 前端 | 状态筛选与汇总卡片加「抢购失败」；工具栏「批量改状态（下拉选目标）」+「批量查积分/兑换」；行操作加「查积分 / 兑换记录」「改状态…」；列表加「积分」列（积分 + 判定徽标 + 时间，全文进 Tooltip）；详情抽屉加「账号全生命周期」时间线 + 逐条命中的兑换记录 |
 | 测试 | 新增 `TestCollabStatusBatch`（4 例）、`TestCollabActivityLifecycle`（9 例）；`tests/test_migrations.py` 的 `HEAD_REVISION` → `20261016_0059`；全量 `pytest` 944 passed / 6 skipped |
-| 接口冒烟 | `/tmp/smoke_collab_api.py` 补到 **67 项全绿**：批量跳步 + 时间戳补齐、单行查询命中→自动「抢购成功」、非 `scripted` 只记快照、时间线倒序、列表回填、批量查询判定→自动「兑换失败」、`failed` 状态筛选、批量逐行隔离、回退仍要 `rollback`、删单级联删快照 |
+| 接口冒烟 | `/tmp/smoke_collab_api.py` 补到 **67 项全绿**：批量跳步 + 时间戳补齐、单行查询命中→自动「抢购成功」、非 `scripted` 只记快照、时间线倒序、列表回填、批量查询判定→自动「抢购失败」、`failed` 状态筛选、批量逐行隔离、回退仍要 `rollback`、删单级联删快照 |

 **这一轮踩到/定下的点**：

@@ -817,17 +817,18 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**（红
   反过来，回退必须清掉后面阶段的时间戳（`_sync_stage_timestamps()` 两个方向都管）。
 3. **自动改状态只在 `scripted` 生效**，其它状态只写快照 + 在结论里说清原因 ——
   自动改状态是最容易"越权"的地方，口径必须窄。
-4. **`unknown`（判不了）不写状态**：接口抖一下就把单子判成"兑换失败"，比不判更糟。
+4. **`unknown`（判不了）不写状态**：接口抖一下就把单子判成"抢购失败"，比不判更糟。
 5. **`statusAction` 弹窗合一**：单行的「改状态 / 回退 / 作废」共用一个 Modal，
   靠 `mode: 'set' | 'rollback' | 'void'` 分支（`set` 允许选全部状态含 `failed`/`void`，
   `rollback` 只在流程链里选），避免三个弹窗三套校验。
 6. **尚未真机验证**：`getUserScore` / `getUserPrizeRecords` 两个接口只做了假客户端单测，
   真机字段名（`available_score` / `records[].prize_name`）还没拿真 CK 跑过一次；
-   真机跑通前不要把"兑换失败"当成定论（先用单行查询看一眼 `raw`）。
-7. **展示名调整（同日第二刀）**：`done` 的展示名由「已完成」改成**「抢购成功」**
-   —— 只改 `ORDER_STATUS_LABELS` / `STATUS_META` / 下拉与卡片文案，
-   **枚举值仍是 `done`**（库里数据、接口参数、审计 detail 全不变，无需迁移）。
-   「判定结论」里的 `success` 仍叫「兑换成功」（那是"查到兑换记录"的结论，与状态名分开）。
+   真机跑通前不要把"抢购失败"当成定论（先用单行查询看一眼 `raw`）。
+7. **展示名调整（同日第二刀）**：`done` 的展示名由「已完成」改成**「抢购成功」**、
+   `failed` 由「兑换失败」改成**「抢购失败」** —— 只改 `ORDER_STATUS_LABELS` / `STATUS_META` /
+   下拉与卡片文案，**枚举值仍是 `done` / `failed`**（库里数据、接口参数、审计 detail 全不变，无需迁移）。
+   注意「判定结论」（verdict）那三个标签仍是「兑换成功 / 兑换失败 / 无法判定」：
+   它说的是"兑换记录里查到没有"，与业务状态名是两个概念，徽标放在列表「积分」列与生命周期时间线上。

 ---

@@ -838,7 +839,7 @@ CK 失效了业务上可能仍然有效。列表上只做**显式提示**（红
 | 与 `huya_accounts` 出现"两份 CK 谁是准的" | §2.3 已写死：本表 CK 只在协作语境有效，不自动同步；需要跑任务时人工导入 |
 | 探针接口被风控 | 只做人工触发、串行、带间隔；不做定时轮询 |
 | 积分 / 兑换记录查询被风控 | 同上：只手动触发（单行 + 勾选批量，串行带间隔），不做定时轮询（§5.7） |
-| 自动改状态误判（接口抖动 → 判成"兑换失败"） | 三态判定：取不到数据一律 `unknown` 且不动状态；只有 `scripted` 的单才自动改；每次查询留快照，人工可回退（`rollback`） |
+| 自动改状态误判（接口抖动 → 判成"抢购失败"） | 三态判定：取不到数据一律 `unknown` 且不动状态；只有 `scripted` 的单才自动改；每次查询留快照，人工可回退（`rollback`） |
 | 活动换 ID（SID 过期）→ 礼包列表空白 | 礼包 SID 一律读 `huya_config.sid`（工作台「虎牙配置」可改，见 §11.4）；空列表时结论直接提示去改 SID |
 | 自由文本的"绑定斗鱼号"没法校验 | 先按文本存（Excel 里就是文本）；能拿到结构化 uid 时补 `bind_douyu_uid` |
 | 图片越攒越多 | §6.4 孤儿清理脚本 + `file_assets` 台账已有 `size_bytes` 可统计 |
@@ -1734,7 +1734,7 @@ class TestCollabActivityLifecycle(TestCollabBase):
        assert order.scripted_at is not None
        assert order.done_at is None

-        # 从「兑换失败」回流程内要显式回退
+        # 从「抢购失败」回流程内要显式回退
        with pytest.raises(collab.CollabError) as excinfo:
            collab.set_status(self.db, self.user, order, "scripted")
        assert excinfo.value.code == "status_not_forward"
@@ -341,7 +341,7 @@ def batch_query_external_order_activity(
    """勾选多行查询积分 + 兑换记录（**串行带间隔**，防风控）。

    每行都会落一条生命周期快照；「已上脚本」的单按查询结果自动改状态
-    （查到礼包 → 抢购成功；没查到 → 兑换失败），其它状态只记录不动状态。
+    （查到礼包 → 抢购成功；没查到 → 抢购失败），其它状态只记录不动状态。
    """
    try:
        orders = collab.list_orders_by_ids(db, req.ids)
@@ -479,7 +479,7 @@ def query_external_order_activity(
    """查这一单的积分 + 兑换记录（单行「查询」按钮）：写一条生命周期快照。

    「已上脚本」的单按查询结果自动改状态：查到这一单的礼包 → 抢购成功；
-    接口通了但没查到 → 兑换失败；接口没通 → 不动（数据不够不许瞎判）。
+    接口通了但没查到 → 抢购失败；接口没通 → 不动（数据不够不许瞎判）。
    """
    try:
        order = collab.get_order(db, order_id)
@@ -78,7 +78,7 @@ ORDER_STATUS_LABELS = {
    # 抢购跑到结果：查兑换记录能确认（自动改）也可以人工切（2026-10-16 用户把「已完成」改叫这个）
    STATUS_DONE: "抢购成功",
    # 旁路终态：抢购后查兑换记录，没查到这一单的礼包 → 判失败（人工确认后可作废或回退重试）
-    STATUS_FAILED: "兑换失败",
+    STATUS_FAILED: "抢购失败",
    STATUS_VOID: "已作废",
 }

@@ -124,7 +124,7 @@ def is_forward_status(from_status: str, target: str) -> bool:

    - 流程链内：目标阶段序号 **≥ 当前** 就是向前（含原地重复设置，幂等）；
    - `void`（作废）：任意流程内状态都能进；
-    - `failed`（兑换失败）：流程内任意状态都能进（兑换记录查出来没有就是没有）；
+    - `failed`（抢购失败）：流程内任意状态都能进（兑换记录查出来没有就是没有）；
    - 从 `void` / `failed` 回到流程内：**必须** rollback（这两步是"要人工再确认一次"的）。
    """
    if target == STATUS_VOID or target == STATUS_FAILED:
@@ -1268,7 +1268,7 @@ def query_order_activity(
    | 情况 | verdict | 业务状态 |
    | --- | --- | --- |
    | 兑换记录里有这一单的礼包 | ``success`` | 「已上脚本」的单 → 自动「抢购成功」 |
-    | 接口通了，但记录里没有这个礼包 | ``failed`` | 「已上脚本」的单 → 自动「兑换失败」 |
+    | 接口通了，但记录里没有这个礼包 | ``failed`` | 「已上脚本」的单 → 自动「抢购失败」 |
    | 接口没通 / 这单没填礼包名 | ``unknown`` | **不动**（数据不够，不许瞎判） |

    只有 ``已上脚本`` 的单会被自动改状态 —— 抢购是上脚本之后的事，其它阶段去改属于误判；
@@ -51,12 +51,12 @@ const STATUS_META: Record<HuyaCollabStatus, { label: string; color: string }> =
  scripted: { label: '已上脚本', color: 'purple' },
  // 抢购成功（枚举值仍是 done）：从「已上脚本」查到兑换记录 → 自动进这一步
  done: { label: '抢购成功', color: 'success' },
-  // 旁路终态：抢购后查兑换记录没查到这一单的礼包
-  failed: { label: '兑换失败', color: 'red' },
+  // 旁路终态：抢购后查兑换记录没查到这一单的礼包（枚举值仍是 failed）
+  failed: { label: '抢购失败', color: 'red' },
  void: { label: '已作废', color: 'error' },
 };

-/** 判定结论的配色（生命周期时间线用） */
+/** 判定结论的配色（生命周期时间线用）：与「业务状态名」分开，这里说的是"兑换记录里查到没有" */
 const VERDICT_META: Record<string, { label: string; color: string }> = {
  success: { label: '兑换成功', color: 'success' },
  failed: { label: '兑换失败', color: 'error' },
@@ -70,11 +70,11 @@ const STATUS_ORDER_OPTIONS: { value: HuyaCollabStatus; label: string }[] = [
  { value: 'recharged', label: '已充值' },
  { value: 'scripted', label: '已上脚本' },
  { value: 'done', label: '抢购成功' },
-  { value: 'failed', label: '兑换失败' },
+  { value: 'failed', label: '抢购失败' },
  { value: 'void', label: '已作废' },
 ];

-/** 「回退」能选的目标：只在流程链里选（要进「已作废 / 兑换失败」走「改状态」或「作废」入口） */
+/** 「回退」能选的目标：只在流程链里选（要进「已作废 / 抢购失败」走「改状态」或「作废」入口） */
 const FLOW_STATUS_OPTIONS = STATUS_ORDER_OPTIONS.filter(
  (option) => option.value !== 'failed' && option.value !== 'void',
 );
@@ -1172,7 +1172,7 @@ export default function HuyaCollabPage() {

  return (
    <Space direction="vertical" size={12} style={{ width: '100%' }}>
-      {/* 卡片用 flex 平分：状态多了一个「兑换失败」，固定 span=4 会换行参差不齐 */}
+      {/* 卡片用 flex 平分：状态多了一个「抢购失败」，固定 span=4 会换行参差不齐 */}
      <Row gutter={12}>
        <Col flex="1"><Card size="small"><Statistic title="全部" value={summary?.total ?? 0} /></Card></Col>
        <Col flex="1">
@@ -1505,7 +1505,7 @@ export default function HuyaCollabPage() {
                )}
                <Button icon={<SwapOutlined />} disabled={busy}
                  onClick={() => {
-                    // 默认给「下一步」，终点态（抢购成功 / 已作废 / 兑换失败）退回当前状态，让人自己挑
+                    // 默认给「下一步」，终点态（抢购成功 / 已作废 / 抢购失败）退回当前状态，让人自己挑
                    setRollbackTarget(detail.next_status ?? detail.status);
                    setStatusReason('');
                    setStatusAction({ order: detail, mode: 'set' });
@@ -1557,7 +1557,7 @@ export default function HuyaCollabPage() {
                </Button>
              )}
              <Text type="secondary" style={{ fontSize: 12 }}>
-                每次查询都会追加一条快照（只追加、不修改）；「已上脚本」的单会按结论自动改成「抢购成功」或「兑换失败」。
+                每次查询都会追加一条快照（只追加、不修改）；「已上脚本」的单会按结论自动改成「抢购成功」或「抢购失败」。
              </Text>
            </Space>
            {!detail.has_cookie && (