---
name: 定格统计迁入 admin
overview: 将「首充剩余定格列表」的查询与汇总逻辑从 slot_console innerapi 迁入 slot_admin，与用户列表等后台能力一致：直连 s_common + WalletService，前端路由不变。
todos:
  - id: add-models
    content: 在 slot_admin 新增 FreeCreditsPlayer/Package Model（s_common）
    status: completed
  - id: migrate-logic
    content: 迁入 FreeCreditsStatsLogic + Validate/DTO，fetchTotalRecharge 改用 WalletService + UserModel
    status: completed
  - id: wire-controller
    content: 改造 FreeCreditsStatsController，移除 ConsoleClient 透传
    status: completed
  - id: cleanup-bff
    content: 删除 console innerapi 与 slot_sdk ConsoleService 中 freeCredits* 方法
    status: in_progress
  - id: verify-api
    content: 对比迁前后列表/汇总与用户列表充值金额口径
    status: pending
isProject: false
---

# 首充定格统计迁入 slot_admin（去掉 console BFF）

## 结论：建议做

当前链路多一跳、职责错位：

```mermaid
flowchart LR
  vue[slot_admin_vue] --> admin[slot_admin FreeCreditsStatsController]
  admin --> sdk[slot_sdk ConsoleClient]
  sdk --> console[slot_console innerapi]
  console --> db[(s_common free_credits_*)]
  console --> wallet[slot_wallet statistics]
```

[`FreeCreditsStatsController.php`](backend/slot_admin/app/game/controller/FreeCreditsStatsController.php) 注释已写明「仅透传 slot_console innerapi」；[`FreeCreditsController`](slot_console/app/innerapi/controller/FreeCreditsController.php) 也标注「仅供 slot_admin 代理调用」——本质是 **admin 专用 BFF**，与 C 端 `FreeCreditsLogic` 无关。

同仓库内后台惯例是 **admin 自己查库 + 按需调钱包**，例如：

- [`UserLogic`](backend/slot_admin/app/game/logic/UserLogic.php)：`WalletService::statistic` + `getNumberFormat`
- [`UserProfitDailyLogic`](backend/slot_admin/app/game/logic/UserProfitDailyLogic.php)：同上
- [`RechargeGiftPlayerLogic`](backend/slot_admin/app/game/logic/RechargeGiftPlayerLogic.php)：直连 `s_common` 活动表

`slot_admin` 已配置 [`s_common`](backend/slot_admin/config/thinkorm.php) 连接，具备迁回条件。

目标链路：

```mermaid
flowchart LR
  vue[slot_admin_vue] --> admin[slot_admin Controller]
  admin --> logic[FreeCreditsStatsLogic]
  logic --> db[(s_common)]
  logic --> wallet[WalletService statistic]
```

**不迁**：C 端定格/提现/领取仍在 [`slot_console` `FreeCreditsLogic`](slot_console/app/api/logic/FreeCreditsLogic.php)，避免动业务写路径。

---

## 实施范围

### 1. slot_admin 新增分层（对齐 backend-layering）

| 层 | 文件 | 职责 |
|---|---|---|
| Validate | `app/game/validate/FreeCreditsStatsValidate.php` | `page/limit`、筛选字段类型与枚举 |
| DTO | `app/game/dto/FreeCreditsStatsQueryDTO.php` | 承接已校验参数 |
| Logic | `app/game/logic/FreeCreditsStatsLogic.php` | 从 console 迁入（以当前 [`FreeCreditsStatsLogic.php`](slot_console/app/innerapi/logic/FreeCreditsStatsLogic.php) 为基准，含近期前端改动：无 activity_id/status 筛选、`total_deposit` 按用户 currency + `getNumberFormat`） |
| Model | `app/game/model/common/FreeCreditsPlayerModel.php`、`FreeCreditsPackageModel.php` | `connection = s_common`，表名与 console 一致，常量 `STATUS_*` / `TYPE_*` 复制 |
| Controller | 改造 [`FreeCreditsStatsController.php`](backend/slot_admin/app/game/controller/FreeCreditsStatsController.php) | Validate → DTO → Logic；`index` 一次返回 `data/total/otherData`（Logic 内 `statistics` + `list`） |

**累计充值**：在 admin Logic 内用已有 [`WalletService::statistic`](backend/slot_admin/app/service/WalletService.php) + [`UserModel`](backend/slot_admin/app/model/UserModel.php) 按用户 `currency` 分组（与用户列表口径一致），**不再**经 console 调 wallet SDK。

**对外契约**：保持 `GET/POST /game/freeCreditsStats/index` 与字段名不变 → [`slot_admin_vue`](backend/slot_admin_vue/src/views/game/freeCreditsStats/index.vue) **无需改路由**。

### 2. 从 console / SDK 下线 admin 专用 BFF

迁移验证通过后删除或标记废弃：

- [`slot_console/app/innerapi/logic/FreeCreditsStatsLogic.php`](slot_console/app/innerapi/logic/FreeCreditsStatsLogic.php)
- [`slot_console/app/innerapi/controller/FreeCreditsController.php`](slot_console/app/innerapi/controller/FreeCreditsController.php)（若仅服务 stats）
- [`slot_sdk` `ConsoleService::freeCreditsList/statistics`](slot_sdk/src/service/console/ConsoleService.php)
- admin Controller 中 `ConsoleClient` / `buildConsoleClient`

### 3. 不做的项

- 不把 C 端 `FreeCreditsLogic` 抽到 `slot_lib`（范围过大，与本次 admin 统计无关）
- 不为两张表单独建 Service 中转层（Logic 内私有方法即可）

---

## 风险与注意点

1. **DB 权限**：确认 `slot_admin` 运行账号对 `s_common.free_credits_player/package` 有读权限（与 console 相同库）。
2. **双份 Model**：console 仍保留 C 端用的 Model；admin 侧独立 Model 类，表结构变更需两处同步常量（可接受，与现有 `RechargeGift*` 模式一致）。
3. **一次请求两次查询**：`statistics` + `list` 仍在单次 `index` 内完成；若后续数据量大，再在 Logic 内优化共用 `filteredPlayerIds`，不必回退 BFF。
4. **UserProfitDaily 的 currency**：其用 `GameServerModel` 固定币种；本功能应继续用 **每用户 `UserModel.currency`**（与 `UserLogic` 一致），避免回退到固定 USD。

---

## 验证清单

- 列表筛选（uid/source/定格时间/第一档状态/全部完成）与汇总 7 项与迁前一致
- 某 UID「累计充值」与后台用户列表 `wallet.r` / `total_deposit` 一致
- 去掉对 `consoleApiHost` 的依赖后，`/game/freeCreditsStats/index` 仍可正常访问
- console innerapi 无其它调用方后再删 SDK 方法