ok

plans/定格列表盈利阈值_5a7a1ed2.plan.md

@@ -0,0 +1,95 @@
+---
+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) |