---
name: 定格列表盈利阈值
overview: 在管理后台首充定格统计列表中，按当前页 UID 调用与 game/pop/index 相同的养客配置接口（PopService → slot_pwa getDPByPlayers），为每行补充 profitthreshold（及可选 hasprofitthreshold）字段，前端新增对应列。
todos:
  - id: pop-service-batch
    content: PopService 新增 mapDevelopPlayerByUids，按 uid 调用 getPageList 并容错
    status: completed
  - id: logic-enrich
    content: FreeCreditsStatsLogic.list 合并 profitthreshold（及可选 hasprofitthreshold）
    status: completed
  - id: vue-columns
    content: freeCreditsStats/index.vue 增加盈利阈值列与展示格式化
    status: completed
  - id: verify-pop-parity
    content: 抽 1～2 个 UID 对比养客配置页与定格列表字段一致
    status: completed
isProject: false
---

# 首充定格列表增加盈利阈值

## 背景

- 首充定格统计已迁入 [`slot_admin`](backend/slot_admin/app/game/logic/FreeCreditsStatsLogic.php)，接口 `GET /game/freeCreditsStats/index` 返回列表 + 顶部汇总。
- 养客配置页 [`game/pop/index`](backend/slot_admin_vue/src/views/game/pop/config/index.vue) 通过 [`PopController::index`](backend/slot_admin/app/game/controller/PopController.php) → [`PopService::getPageList`](backend/slot_admin/app/service/game/PopService.php) → `slot_pwa` `pop/admin/getDPByPlayers` → 游戏侧 `/api/v2/dp/getDPByPlayers`，列表含 `profitthreshold`、`hasprofitthreshold` 等字段。
- 需求文档 §18.2 未写盈利阈值，属运营侧补充字段；数据源应与养客页一致，**不用** `UserTag.popBalance` 等本地 tag。

## 数据流

```mermaid
flowchart LR
  vue[freeCreditsStats/index.vue] --> api["/game/freeCreditsStats/index"]
  api --> logic[FreeCreditsStatsLogic.list]
  logic --> db[(s_common free_credits_*)]
  logic --> wallet[WalletService statistic]
  logic --> pop[PopService getPageList]
  pop --> pwa[slot_pwa getDPByPlayers]
  pwa --> game["/api/v2/dp/getDPByPlayers"]
```

## 实现要点

### 1. PopService：按 UID 批量取养客配置（公共封装）

在 [`PopService.php`](backend/slot_admin/app/service/game/PopService.php) 新增方法，例如 `mapDevelopPlayerByUids(array $uids): array<int, array>`：

- 对每个 `uid` 调用现有 `getPageList(['userid' => $uid, 'page' => 1, 'limit' => 1])`（与 pop/index 单用户筛选一致；`starttime`/`endtime` 不传，与养客页默认「全量」查询一致）。
- 从返回 `data[0]` 取行；无记录或接口异常时该 uid 映射为 `null`（Logic 展示 `-` / 空）。
- 单 uid 失败只 `logger()->warning`，**不**拖垮整页列表（与 `fetchTotalRecharge` 容错一致）。

**说明**：`getDPByPlayers` 仅支持单 `userid`，每页最多 100 条 ≈ 最多 100 次 HTTP（经 pwa 到游戏 API）。当前 `limit` 上限 100，可接受；若后续性能不足，再与游戏侧协商批量接口，不在本次范围。

### 2. FreeCreditsStatsLogic：列表富化

在 [`FreeCreditsStatsLogic::list`](backend/slot_admin/app/game/logic/FreeCreditsStatsLogic.php) 中，在已有 `fetchTotalRecharge` 之后：

- 调用 `PopService` 批量映射；
- 为每行写入（字段名与 pop/index 保持一致，便于前端复用展示逻辑）：
  - `profitthreshold`：`int|null`，配置值（养客页原样展示，**不**除 10000）
  - 若产品确认需要第二列：`hasprofitthreshold`，游戏侧为千分位类整数，展示时与养客页 [`toNum`](backend/slot_admin_vue/src/views/game/pop/config/index.vue) 一致：`Number((val / 10000).toFixed(2))`

无养客配置的用户：`profitthreshold` 为 `null`，前端显示 `-`。

**分层**：跨服务 HTTP 封装在 `PopService`；`FreeCreditsStatsLogic` 只编排，不直接拼 `pwaApiHost` URL。

### 3. 前端：新增列

修改 [`freeCreditsStats/index.vue`](backend/slot_admin_vue/src/views/game/freeCreditsStats/index.vue)：

- 在「累计充值金额」后（或渠道后）增加列：
  - `盈利阈值` → `profitthreshold`
  - （若选两列）`已达盈利阈值` → `hasprofitthreshold`，slot 内 `/10000` 格式化
- 无自定义 slot 时直接显示；`null`/`undefined` 显示 `-`

路由、API 文件 [`freeCreditsStats.js`](backend/slot_admin_vue/src/api/game/freeCreditsStats.js) **不变**。

### 4. 不改动的部分

- `statistics` 顶部 7 项汇总不加盈利阈值（无聚合口径）。
- Validate / DTO 无新筛选项。
- `slot_console` innerapi、`slot_sdk` 无需改动（统计已在 admin）。

## 验证

- 某 UID 在「养客配置」页能查到 `profitthreshold` 时，定格列表同 UID 显示相同值。
- 无养客配置 UID 显示 `-`，列表其余字段正常。
- pop/pwa 不可用时：列表仍可出数，盈利阈值为空；日志有 warning。
- 与迁前对比：除新增列外，筛选、排序、汇总、累计充值口径不变。

## 涉及文件

| 仓库 | 文件 |
|------|------|
| slot_admin | [`PopService.php`](backend/slot_admin/app/service/game/PopService.php)、[`FreeCreditsStatsLogic.php`](backend/slot_admin/app/game/logic/FreeCreditsStatsLogic.php) |
| slot_admin_vue | [`freeCreditsStats/index.vue`](backend/slot_admin_vue/src/views/game/freeCreditsStats/index.vue) |