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

name, overview, todos, isProject

name	overview	todos	isProject
status 配置与未充值	修复 slot_console FreeCreditsLogic::status：无玩家池时返回 status=0 及活动配置；C 端新增 win_threshold（不含 initial_amount、home_withdraw_unlocked）。Logic 已按需求变更实现，待对齐单测与 PHPDoc。	id content status logic-pre-enrollment FreeCreditsLogic：buildPreEnrollmentStatus；status() 无 player 时返回配置态（已完成） completed id content status logic-build-status-fields buildStatus / buildConfigClientFields 仅透出 win_threshold（不含 initial_amount、home_withdraw_unlocked）（已完成） completed id content status align-phpdoc FreeCreditsController PHPDoc 与 buildConfigClientFields 注释：删除 initial_amount、home_withdraw_unlocked；移除无用 DEFAULT_INITIAL_AMOUNT completed id content status align-unit-tests FreeCreditsClientStatusTest / FreeCreditsEligibilityTest 白名单与断言与现实现一致 completed	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() 原逻辑在无 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

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 已与上表一致：

• status()：无 player → buildPreEnrollmentStatus($config)
• buildConfigClientFields()：仅 win_threshold、recharge_unlock_amount、help
• buildStatus() / buildPreEnrollmentStatus()：不返回 initial_amount、home_withdraw_unlocked

待办：对齐文档与单测

1. PHPDoc — FreeCreditsController.php

• 删除 initial_amount、home_withdraw_unlocked 字段说明
• 明确 status=0 时仍返回 win_threshold、recharge_unlock_amount、help

2. 清理 Logic 注释/死代码 — FreeCreditsLogic.php

• 删除未使用的 DEFAULT_INITIAL_AMOUNT 常量（若仍保留）
• buildConfigClientFields 的 @return 改为仅含 win_threshold、recharge_unlock_amount、help

3. 单测

文件	改动
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	testStatusReturnsPreEnrollmentConfigWhenNoPlayer：断言 win_threshold=50，不断言 initial_amount / home_withdraw_unlocked

运行：

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. 单测全部通过