ok

plans/首充定格已解锁列_3c8b7cb9.plan.md

@@ -0,0 +1,101 @@
+---
+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 | — | 无（数据已返回） |