first commit

plans/status_配置与未充值_f37679fd.plan.md

@@ -0,0 +1,106 @@
+---
+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. 单测全部通过