---
name: 首充定格已解锁列
overview: 在 Free Credits 统计（首充定格）列表页增加「已解锁金额」列；后端 `claimed_amount_qf` 已按第二档及以后 release 档已完成金额聚合，主要改 slot_admin_vue 展示即可。
todos:
  - id: vue-column
    content: 在 freeCreditsStats/index.vue 增加 claimed_amount_qf 列（标题：已解锁金额）及金额展示模板
    status: completed
  - id: verify-ui
    content: 本地打开页面核对列值与 remaining_amount_qf 公式；跑 verify-slot-backend.sh
    status: completed
isProject: false
---

# 首充定格列表增加「已解锁金额」列

## 背景

目标页面为 **Free Credits 统计**（菜单：活动管理 → Free Credits 统计）：

- 前端：[slot_admin_vue/src/views/game/freeCreditsStats/index.vue](backend/slot_admin_vue/src/views/game/freeCreditsStats/index.vue)
- 后端：[slot_admin/app/game/controller/FreeCreditsStatsController.php](backend/slot_admin/app/game/controller/FreeCreditsStatsController.php) → [FreeCreditsStatsLogic](backend/slot_admin/app/game/logic/FreeCreditsStatsLogic.php)

需求文档 §18.2 中对应字段为 **「已领取金额」**（后续已 Claim 金额）；产品侧列名为 **「已解锁金额」**，语义一致：**第二档（`package_type=release`）起用户已成功领取的金额**，不含第一档免打码提现。

## 现状（无需重复造数）

后端 `list()` 已在每行返回 `claimed_amount_qf`，聚合逻辑在 `aggregatePackages()`：

```231:232:backend/slot_admin/app/game/logic/FreeCreditsStatsLogic.php
                SUM(CASE WHEN package_type = {$typeFirstCash} AND status = {$statusCompleted} THEN amount_qf ELSE 0 END) AS first_cashout_amount_qf,
                SUM(CASE WHEN package_type = {$typeRelease} AND status = {$statusCompleted} THEN amount_qf ELSE 0 END) AS claimed_amount_qf,
```

- `TYPE_FIRST_CASH = 1`：第一档提现
- `TYPE_RELEASE = 2`：第二档及以后 Claim
- 仅 `status = STATUS_COMPLETED` 计入

`remaining_amount_qf` 已用该字段参与计算：`frozen - first_cashout - claimed`。

顶部汇总区已有「已领取金额」展示 `stats.claimed_amount_qf`，与行字段同源。

```mermaid
flowchart LR
  subgraph api [GET /game/freeCreditsStats/index]
    list[list.data]
    stats[otherData.statistics]
  end
  subgraph agg [aggregatePackages]
    release["SUM release completed amount_qf"]
  end
  release --> claimed["claimed_amount_qf per row"]
  claimed --> list
  release --> stats
```

## 实现方案

### 1. slot_admin_vue（主要改动）

文件：[index.vue](backend/slot_admin_vue/src/views/game/freeCreditsStats/index.vue)

在 `columns` 中 **「完成进度」与「剩余未释放金额」之间** 插入一列：

| 列标题 | dataIndex | 说明 |
|--------|-----------|------|
| 已解锁金额 | `claimed_amount_qf` | 千分位转美元，与定格金额等列一致 |

新增 slot 模板（复用现有 `qfToDollar`）：

```vue
<template #claimed_amount_qf="{ record }">
  ${{ qfToDollar(record.claimed_amount_qf) }}
</template>
```

无需改 [freeCreditsStats.js](backend/slot_admin_vue/src/api/game/freeCreditsStats.js) API 封装。

### 2. slot_admin 后端（可选 / 建议不改）

[FreeCreditsStatsLogic.php](backend/slot_admin/app/game/logic/FreeCreditsStatsLogic.php) **已满足需求**，无需新增接口或 SQL。

若希望 API 字段名与列标题一致，可额外返回别名 `unlocked_amount_qf`（与 `claimed_amount_qf` 同值），但会增加前后端两套字段，**不建议**，前端直接用 `claimed_amount_qf` 即可。

### 3. 命名对齐（可选）

- 列表列名：**已解锁金额**（按产品要求）
- 顶部汇总仍为「已领取金额」；与需求文档 §18.1 一致。若产品要求顶部也改名，可一并改为「已解锁金额」，本次可只做列表列。

## 验证

1. 打开 Free Credits 统计页，确认新列有值；未领取第二档的用户为 `$0.00`。
2. 抽查：某用户第二档及以后 `free_credits_package` 中 `package_type=2` 且 `status=3` 的 `amount_qf` 之和 = 列表「已解锁金额」× 1000。
3. 确认「剩余未释放金额」= 定格金额 − 第一档已提现 − 已解锁金额（与现有公式一致）。
4. 执行 `~/.cursor/hooks/verify-slot-backend.sh`（若仅改 Vue，预期 `PASS (no changed files)` 或仅前端相关检查）。

## 改动范围小结

| 仓库 | 文件 | 改动 |
|------|------|------|
| slot_admin_vue | `src/views/game/freeCreditsStats/index.vue` | 新增列 + 金额模板 |
| slot_admin | — | 无（数据已返回） |