107 lines
5.2 KiB
Markdown
107 lines
5.2 KiB
Markdown
---
|
||
name: status 配置与未充值
|
||
overview: 修复 slot_console FreeCreditsLogic::status：无玩家池时返回 status=0 及活动配置；C 端新增 win_threshold（不含 initial_amount、home_withdraw_unlocked）。Logic 已按需求变更实现，待对齐单测与 PHPDoc。
|
||
todos:
|
||
- id: logic-pre-enrollment
|
||
content: FreeCreditsLogic：buildPreEnrollmentStatus；status() 无 player 时返回配置态（已完成）
|
||
status: completed
|
||
- id: logic-build-status-fields
|
||
content: buildStatus / buildConfigClientFields 仅透出 win_threshold（不含 initial_amount、home_withdraw_unlocked）（已完成）
|
||
status: completed
|
||
- id: align-phpdoc
|
||
content: FreeCreditsController PHPDoc 与 buildConfigClientFields 注释：删除 initial_amount、home_withdraw_unlocked；移除无用 DEFAULT_INITIAL_AMOUNT
|
||
status: completed
|
||
- id: align-unit-tests
|
||
content: FreeCreditsClientStatusTest / FreeCreditsEligibilityTest 白名单与断言与现实现一致
|
||
status: completed
|
||
isProject: false
|
||
---
|
||
|
||
# Free Credits status 接口修复计划（需求变更版）
|
||
|
||
## 需求确认（2026-05-21）
|
||
|
||
**C 端 `GET /api/free-credits/status` 约定：**
|
||
|
||
- **包含**：`win_threshold`（来自 `ext_config.win_threshold_qf`）
|
||
- **不包含**：`initial_amount`、`home_withdraw_unlocked`
|
||
- 注册赠送金额：仍由 `game_base.user_register_reward` 等其它接口提供
|
||
- 首页 Withdraw 解锁：C 端用 `status`（如 `STATUS_HOME_UNLOCKED=1`）或钱包余额 + `win_threshold` 自行判断；库表 `home_withdraw_unlocked` 仍由 `syncHomeWithdrawUnlocked` 维护，仅不下发 API
|
||
|
||
后台 type=11 的 `initial_amount_qf` 配置保留（运营后台用），**不**经 status 透出。
|
||
|
||
## 问题根因
|
||
|
||
[`FreeCreditsLogic::status()`](slot_console/app/api/logic/FreeCreditsLogic.php) 原逻辑在无 `free_credits_player` 时返回 `{ status: -1 }`，导致首充前 C 端无法展示活动（`status !== -1` 为展示开关）。
|
||
|
||
## 目标行为
|
||
|
||
| 场景 | status | 返回顶层字段 |
|
||
| --- | --- | --- |
|
||
| 无资格 / 无 type=11 配置 | `-1` | 仅 `status` |
|
||
| 有资格 + 有配置 + **无 player** | `0` | `status`, `frozen_amount`, `first_cash_amount`, `win_threshold`, `recharge_unlock_amount`, `help`, `packages`（空数组） |
|
||
| 有资格 + 有配置 + **有 player** | 玩家真实值 | 同上 + 玩家 `frozen_amount` / `first_cash_amount` / `packages` |
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
statusReq[GET status] --> eligible{资格+活动配置?}
|
||
eligible -->|否| notVisible["status=-1"]
|
||
eligible -->|是| player{有 player 行?}
|
||
player -->|无| preConfig["status=0 + win_threshold 等"]
|
||
player -->|有| fullStatus["buildStatus 玩家态"]
|
||
```
|
||
|
||
## 已实现 Logic（当前代码，无需再改字段集）
|
||
|
||
[`FreeCreditsLogic.php`](slot_console/app/api/logic/FreeCreditsLogic.php) 已与上表一致：
|
||
|
||
- `status()`：无 player → `buildPreEnrollmentStatus($config)`
|
||
- `buildConfigClientFields()`：仅 `win_threshold`、`recharge_unlock_amount`、`help`
|
||
- `buildStatus()` / `buildPreEnrollmentStatus()`：**不**返回 `initial_amount`、`home_withdraw_unlocked`
|
||
|
||
## 待办：对齐文档与单测
|
||
|
||
### 1. PHPDoc — [`FreeCreditsController.php`](slot_console/app/api/controller/FreeCreditsController.php)
|
||
|
||
- 删除 `initial_amount`、`home_withdraw_unlocked` 字段说明
|
||
- 明确 `status=0` 时仍返回 `win_threshold`、`recharge_unlock_amount`、`help`
|
||
|
||
### 2. 清理 Logic 注释/死代码 — [`FreeCreditsLogic.php`](slot_console/app/api/logic/FreeCreditsLogic.php)
|
||
|
||
- 删除未使用的 `DEFAULT_INITIAL_AMOUNT` 常量（若仍保留）
|
||
- `buildConfigClientFields` 的 `@return` 改为仅含 `win_threshold`、`recharge_unlock_amount`、`help`
|
||
|
||
### 3. 单测
|
||
|
||
| 文件 | 改动 |
|
||
| --- | --- |
|
||
| [`FreeCreditsClientStatusTest.php`](slot_console/tests/Unit/FreeCreditsClientStatusTest.php) | `PLAYER_TOP_KEYS` 改为：`status`, `frozen_amount`, `first_cash_amount`, `win_threshold`, `recharge_unlock_amount`, `help`, `packages`；移除 `initial_amount`、`home_withdraw_unlocked` 断言 |
|
||
| [`FreeCreditsEligibilityTest.php`](slot_console/tests/Unit/FreeCreditsEligibilityTest.php) | `testStatusReturnsPreEnrollmentConfigWhenNoPlayer`：断言 `win_threshold=50`，**不**断言 `initial_amount` / `home_withdraw_unlocked` |
|
||
|
||
运行：
|
||
|
||
```bash
|
||
docker exec -w /app/www/slot/slot_console php82 vendor/bin/phpunit tests/Unit/FreeCreditsClientStatusTest.php tests/Unit/FreeCreditsEligibilityTest.php
|
||
```
|
||
|
||
## C 端约定（供联调）
|
||
|
||
- **展示开关**：`data.status !== -1`；首充前为 `status === 0`
|
||
- **进度条上限**：`win_threshold`
|
||
- **注册赠送**：**不要**从 status 取；走注册/大厅配置接口
|
||
- **Withdraw 解锁**：**不要**依赖 `home_withdraw_unlocked` 字段；用 `status` 或余额逻辑
|
||
|
||
## 不在本次范围
|
||
|
||
- status 返回 `initial_amount` / `home_withdraw_unlocked`
|
||
- 注册发奖改读 `ext_config.initial_amount_qf`
|
||
- slot_pwa / gateway 前端改动
|
||
- backend 后台 `initial_amount_qf` 编辑能力（已存在）
|
||
|
||
## 验收清单
|
||
|
||
1. 无 player：`status=0`，含 `win_threshold`、`recharge_unlock_amount`、`help`，`packages=[]`，**无** `initial_amount`、`home_withdraw_unlocked` 键
|
||
2. 有 player：含玩家态金额 + 同上配置字段
|
||
3. 无资格/无配置：`status=-1`
|
||
4. 单测全部通过
|