cursor/plans/free_credits_后台统计页_9d6edc45.plan.md

---
name: free credits 后台统计页
overview: 实现需求 §18 的 Free Credits 后台统计与展示：在 slot_console 增强 innerapi（加筛选、加列表字段、富化累计充值与档位聚合），slot_lib 新增 FreeCreditsService 并给 WalletService 补一个 statistics 批量方法，slot_admin 新增 FreeCreditsStatsController 代理，slot_admin_vue 新增 views/game/freeCreditsStats/index.vue 一页搞定，顶部统计走 sa-table 的 otherData 模式。
todos:
  - id: slot-console-stats-logic
    content: slot_console 新建 innerapi/logic/FreeCreditsStatsLogic.php，封装 statistics + list 的查询编排（含 status>=2 口径、批量 package 聚合 SQL）
    status: completed
  - id: slot-console-list-enrich
    content: slot_console FreeCreditsController::list 加筛选 + 字段富化（first_cash_status / progress / claimed / first_cashout / remaining / total_recharge）
    status: completed
  - id: slot-console-stats-filter
    content: slot_console FreeCreditsController::statistics 加 source / first_recharge_time / status 等筛选；frozen_user_count 改为 status>=2
    status: completed
  - id: slot-lib-wallet-stats
    content: slot_lib WalletService 新增 statistics(uids, currency) 方法 → 调 /api/wallet/statistics
    status: completed
  - id: slot-lib-free-credits-service
    content: slot_lib 新建 FreeCreditsService（basePath=innerapi/free-credits，含 list + statistics）
    status: completed
  - id: slot-admin-controller
    content: slot_admin 新建 game/controller/FreeCreditsStatsController.php，index 一次调两个 service 合并 otherData 返回
    status: completed
  - id: slot-admin-vue-api
    content: slot_admin_vue 新建 api/game/freeCreditsStats.js，导出 getPageList
    status: completed
  - id: slot-admin-vue-page
    content: "slot_admin_vue 新建 views/game/freeCreditsStats/index.vue：sa-table + #tableAfterButtons 顶部 7 统计 + 12 列表 + 筛选 + 排序白名单"
    status: completed
  - id: menu-permission
    content: 在 sm_system_menu 加 1 条 L 菜单 + 1 条 B 按钮码（/game/freeCreditsStats/index），并分配角色
    status: completed
  - id: manual-verify
    content: docker 内 A/B/C 三种玩家手测：默认排序、7 项统计、筛选联动、排序白名单、权限拦截
    status: completed
isProject: false
---

## 数据流

```mermaid
flowchart LR
  vue[freeCreditsStats/index.vue sa-table]
  vue -->|"POST /game/FreeCreditsStats/index"| ctrl[FreeCreditsStatsController]
  ctrl -->|"FreeCreditsService::list"| svc[slot_lib FreeCreditsService]
  ctrl -->|"FreeCreditsService::statistics"| svc
  svc -->|"POST innerapi/free-credits/list"| console[slot_console FreeCreditsController]
  svc -->|"POST innerapi/free-credits/statistics"| console
  console -->|"WalletService statistics uids currency"| wallet["slot_wallet api/wallet/statistics"]
  console -->|"sum on free_credits_package"| db[(s_common.free_credits_player + free_credits_package)]
```

slot_admin Controller 一次代理两个 innerapi，合并成 `{ data, total, otherData: <statistics> }` 给 sa-table，避免前端两次请求。

## 字段契约（最终对外）

### `/game/FreeCreditsStats/index` 请求

筛选（与 §18.3 对齐）

- `uid` 精确
- `source` 字符串（沿用 channel_game_model + source 二级选择）
- `activity_id` 可选（默认取当前生效的 type=11 活动）
- `first_recharge_time` 范围 `[start, end]` → `whereBetween`
- `status` 数组（player.status：0/1/2/3/4/5/6/7/10）
- `first_cash_status` 数组（package.status：0/1/2/3/4/5，限定 `package_no=1`）
- `is_completed` 0/1（status=10 与否）
- `page`, `limit`, `orderBy`, `orderType`

排序

- DB 可排序：`frozen_amount_qf`、`first_recharge_time`（默认 `first_recharge_time desc`）
- 其它字段（进度、剩余、累计充值）派生，前端不开启排序

### 响应

```json
{
  "data": [{
    "uid": 123,
    "source": "us_01",
    "frozen_amount_qf": 78500,
    "first_cash_amount_qf": 20000,
    "total_recharge_amount_qf": 30000,
    "first_cash_status": 3,
    "progress_done": 3,
    "progress_total": 7,
    "status": 7,
    "remaining_amount_qf": 28500,
    "claimed_amount_qf": 30000,
    "first_recharge_time": "2026-05-12 11:23:01",
    "completed_time": null
  }],
  "total": 240,
  "otherData": {
    "frozen_user_count": 240,
    "first_cashout_user_count": 180,
    "completed_user_count": 35,
    "frozen_amount_qf": 18650000,
    "first_cashout_amount_qf": 3520000,
    "claimed_amount_qf": 8800000,
    "pending_amount_qf": 6330000
  }
}
```

金额字段一律以 `*_qf`（千分位整数）传到 Vue，Vue 用 `/ 1000` + `toFixed(2)` 显示（与 edit.vue 同口径）。

---

## 改动清单

### 1. slot_console — 增强 innerapi

文件：[slot_console/app/innerapi/controller/FreeCreditsController.php](slot_console/app/innerapi/controller/FreeCreditsController.php)

#### 1.1 `statistics()` 加筛选

参照需求 §18.1，新增可选参数并贯穿到所有子查询：

- `activity_id`、`source`、`first_recharge_time_start`、`first_recharge_time_end`、`uid`
- 子查询 `frozenTotal / completedCount / firstCashoutCount / firstCashoutAmount / claimedAmount` 全部基于同一个 `playerIds` 数组（按筛选后取出）
- `frozen_user_count` 口径改为 `status >= STATUS_FROZEN(2)` 的玩家数（与需求 "已创建 Free Credits Pool" 一致；当前实现把 status=1 也计入，定义不准）

#### 1.2 `list()` 加筛选 + 字段富化

- 新增筛选参数：`source`、`first_recharge_time` 范围、`status[]`、`first_cash_status[]`、`is_completed`、`orderBy/orderType`（白名单：`first_recharge_time`, `frozen_amount_qf`）
- 输出每行追加：
  - `first_cash_status`：对应 `free_credits_package.status` where `player_id=? AND package_no=1`
  - `progress_done` / `progress_total`：`SUM(CASE WHEN status=3 THEN 1 ELSE 0 END)` / `COUNT(*)`，一次 `GROUP BY player_id` 跑完
  - `claimed_amount_qf`：`SUM(amount_qf) WHERE package_type=2 AND status=3 GROUP BY player_id`
  - `first_cashout_amount_qf`：`SUM(amount_qf) WHERE package_type=1 AND status=3 GROUP BY player_id`
  - `remaining_amount_qf`：`frozen_amount_qf - first_cashout_amount_qf - claimed_amount_qf`
  - `total_recharge_amount_qf`：调用 `WalletService::statistics(uids, currency='USD')`，把 `total_deposit` 映射进来。currency 默认 'USD'（活动只面向美国 RMG，currency 字段后续如多币种再扩展）
- 一次性聚合查询，避免 N+1：

```text
SELECT player_id,
  SUM(CASE WHEN status=3 THEN 1 ELSE 0 END) AS progress_done,
  COUNT(*) AS progress_total,
  SUM(CASE WHEN package_type=1 AND status=3 THEN amount_qf ELSE 0 END) AS first_cashout_amount_qf,
  SUM(CASE WHEN package_type=2 AND status=3 THEN amount_qf ELSE 0 END) AS claimed_amount_qf,
  MAX(CASE WHEN package_no=1 THEN status END) AS first_cash_status
FROM s_common.free_credits_package
WHERE player_id IN (...)
GROUP BY player_id
```

#### 1.3 控制器分层

按 backend-layering 规则，把 1.1 / 1.2 的查询编排沉到 Logic：新增 [slot_console/app/innerapi/logic/FreeCreditsStatsLogic.php](slot_console/app/innerapi/logic/FreeCreditsStatsLogic.php)（或直接挂在已有 `api/logic/FreeCreditsLogic.php`，建议新建避免膨胀），Controller 只负责接参 / 调 Logic / 返回。

---

### 2. slot_lib — 新增 FreeCreditsService + 补 WalletService

#### 2.1 [slot_lib/src/services/FreeCreditsService.php](slot_lib/src/services/FreeCreditsService.php) 新建

```php
class FreeCreditsService extends BaseApiService
{
    use SingletonService;
    protected $hostKey = 'consoleApiHost';
    protected $basePath = 'innerapi/free-credits';

    public function statistics(array $params) { return $this->postAction('statistics', $params); }
    public function list(array $params) { return $this->postAction('list', $params); }
}
```

理由：不与既有 `ActivityService::join/add/update` 混杂；basePath 完全独立，匹配 slot_console 的路由。

#### 2.2 [slot_lib/src/services/WalletService.php](slot_lib/src/services/WalletService.php) 补 `statistics`

```php
public function statistics(array $uids, string $currency)
{
    return $this->postAction('statistics', ['uids' => $uids, 'currency' => $currency]);
}
```

action 名 `statistics`，URL `{walletApiHost}/api/wallet/statistics`，对应 slot_wallet `WalletController::statistics`。slot_console 侧 `FreeCreditsStatsLogic` 调用此方法。

---

### 3. slot_admin — 新增代理 Controller

文件：[backend/slot_admin/app/game/controller/FreeCreditsStatsController.php](backend/slot_admin/app/game/controller/FreeCreditsStatsController.php)

只做接参 + Service 调用 + 合并：

```php
class FreeCreditsStatsController extends AdminController
{
    public function index(Request $request): Response
    {
        $params = $request->all();
        $params['page']  = (int)$request->get('page', 1);
        $params['limit'] = (int)$request->get('limit', 20);

        $list  = FreeCreditsService::getInstance()->list($params);
        $stats = FreeCreditsService::getInstance()->statistics($params);

        $list['otherData'] = $stats;
        return $this->success($list);
    }
}
```

- 不需要 Validate（参数全部可选；非法值 slot_console 侧拦）
- 自动路由路径 `/game/freeCreditsStats/index`
- 不新增 `export()` action（V1 不做导出）

---

### 4. slot_admin_vue — 新页 + API

#### 4.1 [backend/slot_admin_vue/src/api/game/freeCreditsStats.js](backend/slot_admin_vue/src/api/game/freeCreditsStats.js) 新建

```js
import request from '@/utils/request'
const url = '/game/freeCreditsStats'
export default {
  getPageList: (params) => request.get(`${url}/index`, params),
}
```

#### 4.2 [backend/slot_admin_vue/src/views/game/freeCreditsStats/index.vue](backend/slot_admin_vue/src/views/game/freeCreditsStats/index.vue) 新建

骨架仿 `views/game/order/recharge/index.vue`：

- `defineOptions({ name: 'game/freeCreditsStats/index' })`
- `<sa-table>` `options.api = api.getPageList`，`options.add` / `options.delete` 关闭
- `searchForm`：`uid`、`source`（用 `commonStore.allSourcesOptionsNoAll`）、`first_recharge_time`（`a-range-picker`）、`status`、`first_cash_status`、`is_completed`
- 顶部统计走 `#tableAfterButtons`：

```vue
<template #tableAfterButtons>
  <a-space>
    <a-typography-text>定格人数：{{ stats.frozen_user_count }}</a-typography-text>
    <a-typography-text>完成提现人数：{{ stats.first_cashout_user_count }}</a-typography-text>
    <a-typography-text>全部完成人数：{{ stats.completed_user_count }}</a-typography-text>
    <a-typography-text>定格总金额：${{ qfToDollar(stats.frozen_amount_qf) }}</a-typography-text>
    <a-typography-text>已提现金额：${{ qfToDollar(stats.first_cashout_amount_qf) }}</a-typography-text>
    <a-typography-text>已领取金额：${{ qfToDollar(stats.claimed_amount_qf) }}</a-typography-text>
    <a-typography-text>待释放金额：${{ qfToDollar(stats.pending_amount_qf) }}</a-typography-text>
  </a-space>
</template>
```

- `stats = computed(() => crudRef.value?.getTableOtherData() ?? {})`
- 列定义：12 列对齐 §18.2；`status`、`first_cash_status` 直接用前端 map 表（不新建字典）：

```js
const PLAYER_STATUS_MAP = {
  0: '未触发', 1: 'Home Withdraw 已解锁', 2: '已定格', 3: '充值进行中',
  4: '第一档可提现', 5: '第一档处理中', 6: '第一档已提现',
  7: '后续档释放中', 10: '全部完成',
}
const PACKAGE_STATUS_MAP = {
  0: '未解锁', 1: '可操作', 2: '处理中', 3: '已完成', 4: '失败', 5: '已拒绝',
}
```

- `qfToDollar = (v) => ((Number(v||0))/1000).toFixed(2)`
- 不再调单独的 stats 接口，`tableAfterButtons` 数据从 `otherData` 取

---

### 5. 字典与菜单

#### 5.1 字典：不新增

`status` / `first_cash_status` 直接走前端 map 表，避免与 `RechargeGiftConfigModel` 共用字典污染。

#### 5.2 菜单：DB 表 `sm_system_menu` 追加（运营在「系统管理 → 菜单管理」操作即可）

需要的 2 条数据（指引性 SQL，实际可走 UI）：

```sql
INSERT INTO sm_system_menu (parent_id, type, title, name, path, component, sort)
  VALUES (<game_parent_id>, 'L', 'Free Credits 统计',
          'game/freeCreditsStats/index', '/game/freeCreditsStats',
          'game/freeCreditsStats/index', 50);
INSERT INTO sm_system_menu (parent_id, type, title, code)
  VALUES (<leaf_id>, 'B', '列表', '/game/freeCreditsStats/index');
```

写完后给「超级管理员 / 运营」角色分配该菜单与按钮码。

---

## 不动的地方

- `slot_console` 既有 `FreeCreditsLogic` C 端逻辑、`free_credits_player` / `free_credits_package` 表结构、`ext_config` 配置读取等不动
- `s_recharge_gift_config` 不需要新增列
- `slot_pay` 不新增 innerapi（不需要订单表精确口径，wallet `total_deposit` 已足够）
- 现有 `ActivityController` 编辑表单（type=11 分支）已落地，不动
- `RechargeOrderController` / `withdrawal` 等无关模块不动

## 验收（手测）

按 [dev-environment](.cursor/rules/dev-environment.mdc) 在 docker 内调试：

1. 准备 3 个测试账号：A 未定格、B 已定格未提现首档、C 全部完成；各 source 至少一个
2. 访问 `/game/freeCreditsStats` 列表：
   - 不传参 → 默认按 `first_recharge_time desc`，A 不出现（status<2 被过滤），B / C 都在
   - 顶部 7 个统计数字与逐条手算结果一致
   - 列表里 `total_recharge_amount_qf` 与 `slot_wallet.api/wallet/statistics` 直接拉的 `total_deposit` 一致
   - `progress_done/total` 等于 DB 中 `free_credits_package` 实际行数
3. 筛选：
   - 选 `source=us_01` 列表与统计同步收敛
   - 选 `first_recharge_time` 范围，统计 7 项随之变化
   - 选 `is_completed=1`，列表只剩 C
   - 选 `first_cash_status=3`，列表只剩第一档已成功的玩家
4. 排序：分别点击「定格金额」「定格时间」列头，order 切换；其它字段不可排序
5. 权限：用未授权账号访问 → 403；授权后正常
6. 仅改活动状态时（已存在的活动编辑场景）回归一遍，确认未触发 type=11 ext 校验路径回归