---
name: Free Credits 老用户隐藏评审
overview: EventBus 写库确定参加、status 只读展示；在此基础上用环境变量 FREE_CREDITS_ENROLL_REG_AFTER 做注册时间门槛——regTime 晚于该时间的用户才有资格参加，否则一律 status=-1 且 EventBus 跳过写池。
todos:
  - id: env-reg-cutoff
    content: 新增 FREE_CREDITS_ENROLL_REG_AFTER 环境变量与 FreeCreditsLogic::isEligibleByRegTime(uid) 统一门禁
    status: completed
  - id: apply-gate-all-paths
    content: 在 status、syncHomeWithdrawUnlocked、handleFreeCreditInit、advanceAfterRecharge、claim、firstCashout 入口应用注册时间门禁
    status: completed
  - id: fix-docs-lobby
    content: 修正 FreeCreditsController PHPDoc（含 status=-1 含老用户/未达注册门槛）；LobbyController 清理无用 import
    status: completed
  - id: guard-claim-cashout
    content: 无资格或无 player 时 claim/firstCashout 返回明确业务错误
    status: completed
  - id: verify-reg-cutoff
    content: 联调：regTime 早于门槛 status=-1 且 EventBus 不建池；晚于门槛走 win/首充完整流程
    status: completed
isProject: false
---

# Free Credits 老用户隔离：注册时间门槛（计划）

## 目标

C 端全量更新后，**注册时间早于活动上线节点的用户视为老用户，不参加、不展示**；**注册时间晚于该节点的新用户**，在现有「EventBus 写库 = 参加」模型下正常走活动。

「默认参加」含义：**有资格参加**（EventBus 允许建池、status 可读），**不是**无需 EventBus 自动插入 `free_credits_player`。

---

## 分层架构（保持不变）

```mermaid
flowchart TB
  gate{regTime > FREE_CREDITS_ENROLL_REG_AFTER?}
  gate -->|否| block[不参加: status=-1 EventBus return]
  gate -->|是| eligible[有资格]
  eligible --> win[EventBus syncHomeWithdrawUnlocked]
  eligible --> init[EventBus free_credit_init]
  eligible --> api[status 只读 player 行]
  win --> pool[(free_credits_player)]
  init --> pool
  api --> pool
```

| 路径 | 行为 |
| --- | --- |
| **读** `status()` | 未达注册门槛 → `status=-1`；达门槛且无 player 行 → `-1`；有行 → `buildStatus` |
| **写** EventBus | 未达注册门槛 → 各 Logic 方法开头直接 return，不建池、不定格、不推进 |

---

## 实现要点

### 1. 环境变量

在 [`.env`](slot_console/.env) / 部署说明中增加（示例）：

```env
# 用户注册时间（Unix 或 Y-m-d H:i:s，建议与 TIMEZONE 一致）晚于此值才可参加 Free Credits
FREE_CREDITS_ENROLL_REG_AFTER=2026-05-20 00:00:00
```

- 在 [`config/app.php`](slot_console/config/app.php) 或新建 `config/free_credits.php` 读取：`getenv('FREE_CREDITS_ENROLL_REG_AFTER')`，`strtotime` 解析为 `enroll_reg_after_ts`（启动时或首次调用缓存）。
- **未配置时的默认策略（已确认）**：`FREE_CREDITS_ENROLL_REG_AFTER` 为空或未配置 → **全员不参加**（`isEligibleByRegTime` 恒 false，`status=-1`，EventBus 不写池）。

### 2. 统一门禁方法（建议放在 [`FreeCreditsLogic`](slot_console/app/api/logic/FreeCreditsLogic.php)）

```php
/**
 * 是否具备 Free Credits 参与资格（注册时间晚于环境变量门槛）。
 */
protected function isEligibleByRegTime(int $uid): bool
{
    $cutoff = self::enrollRegAfterTimestamp(); // 0 表示未配置
    if ($cutoff <= 0) {
        return false;
    }

    $userInfo = \app\service\user\UserService::getUserInfoEntity($uid);
    if ($userInfo === null || $userInfo->create_at === '') {
        return false;
    }

    $regTime = strtotime($userInfo->create_at);
    return $regTime !== false && $regTime > $cutoff; // 严格「晚于」
}
```

- **数据来源**：[`app\service\user\UserService::getUserInfoEntity`](slot_console/app/service/user/UserService.php)（调 user 服 `/innerapi/user/info`），与 [`EventBus::registerEvent`](slot_console/app/command/EventBus.php) 等同用法。
- **注册时间字段**：[`app\entity\UserInfoEntity::$create_at`](slot_console/app/entity/UserInfoEntity.php)（`Y-m-d H:i:s`），比较前 `strtotime` 为 Unix 秒。
- **不用** `UserTagService::tagInfo->regTime`（标签缓存，与账号创建时间可能不一致）。
- 备选：若 Logic 内已大量使用 slotLib，可用 `\slotLib\services\UserService::getInstance()->setUid($uid)->getUserInfo()?->regTime`（构造函数内由 `create_at` 解析），但 console 侧优先统一 `app\service\user\UserService`。

### 3. 调用点（读写对称）

| 方法 | 未达门槛时 |
| --- | --- |
| `status()` | 直接 `return ['status' => -1]` |
| `syncHomeWithdrawUnlocked()` | `return null` |
| `handleFreeCreditInit()` | `return` |
| `advanceAfterRecharge()` | `return` |
| `claim()` / `firstCashout()` | `throw BusinessException('...')` 或统一文案 |

**说明**：已达门槛、但库中无 player 行 → 仍为 `status=-1`（尚未被 EventBus 纳入）；达门槛且 win 后 → EventBus 建池 → status 非 `-1`。

### 4. 与「已首充」的关系

- 注册门槛解决：**老账号 / 老注册** 不进入活动。
- 钱包侧 [`maybeSendFreeCreditInit`](slot_wallet/app/api/logic/WalletLogic.php) 仍仅 **首充** 发定格，二者叠加，互不替代。

### 5. 撤销项

- 不再单独做 `total_deposit == 0` 的 EventBus 门禁（由注册时间门槛覆盖「老用户」定义）。
- 不再要求 `frozen_amount > 0` 才展示（保留 HOME_UNLOCKED 阶段）。

### 6. 文档与测试

- 更新 [`FreeCreditsController`](slot_console/app/api/controller/FreeCreditsController.php)：`status=-1` = 未参加 / 活动关 / **注册时间早于门槛**。
- 单测：mock `regTime` 与 env cutoff，覆盖 eligible / ineligible 的 status 与 freeze 是否被调用。
- 联调矩阵见下。

---

## 联调矩阵

| regTime vs 门槛 | win 达门槛 | 首充定格 | status | EventBus 建池 |
| --- | --- | --- | --- | --- |
| 早于 | - | - | `-1` | 否 |
| 晚于 | 否 | 否 | `-1` | 否 |
| 晚于 | 是 | 否 | `1` | sync 建池 |
| 晚于 | - | 是 | `3/4` + packages | freeze |

---

## 新 C 端约定（不变）

- **`status === -1`**：隐藏（含老用户、未达注册门槛、未参加）。
- **`status !== -1`**：已参加，按 `FreeCreditsPlayerModel` 状态渲染。