---
name: Free Credits 验收核查
overview: 「首充前免费余额定格与分档释放」的后端核心链路（定格、分档、首档提现、后续 Claim、充值事件、钱包账务）已在 slot_console / slot_wallet / slot_pay / slot_lib 落地约 70–80%，但尚未达到需求文档 V1.0 全量验收标准；运营后台、客户端 UI、广播、异常风控、部分 API 字段与自动化测试仍缺失或未对齐。
todos:
  - id: p0-wallet-atomicity
    content: 补齐 Claim+Y1 原子性/回滚；确认是否需要 Deposit Lot
    status: pending
  - id: p0-status-api-fields
    content: status/buildStatus 增加 total_recharge、show_home_status_bar、show_activity_entry
    status: pending
  - id: p0-peak-balance
    content: 首页解锁「曾达到门槛」：增加峰值记录或可靠触发点
    status: pending
  - id: p1-admin-config-stats
    content: slot_admin 增加 type=11 配置页与统计页（对接 innerapi）
    status: pending
  - id: p1-refund-risk
    content: 实现充值退款/拒付暂停未释放档位（文档 20.1）
    status: pending
  - id: p2-frontend-broadcast
    content: 前端仓实现 UI/广播；本仓可增加 broadcast API
    status: pending
  - id: p2-tests
    content: 按文档 22.1/22.2 补充自动化或验收用例
    status: pending
isProject: false
---

# 首充前免费余额定格与分档释放 — 实现完成度核查

**结论：未实现完。** 后端主流程可联调，但对照 [需求文档](file:///Users/ray/Documents/project/www/slot/docs/requirements/首充前免费余额定格与分档释放需求文档.md) 第 22 节验收标准，仍有若干 **P0 账务/规则缺口** 与大量 **前端/运营/统计** 范围未覆盖。

---

## 实现分布（已落地）

```mermaid
flowchart TB
  subgraph console [slot_console]
    RechargeEvent --> FreeCreditsLogic
    EventBus --> FreeCreditsLogic
    FreeCreditsLogic --> DB[(free_credits_player/package)]
    ApiCtrl[FreeCreditsController] --> FreeCreditsLogic
    Lobby[LobbyController.frontData] --> FreeCreditsLogic
    Inner[innerapi FreeCreditsController] --> DB
  end
  subgraph wallet [slot_wallet]
    FreeCreditsLogic --> WalletLogic
    WalletLogic --> freeze[freeCreditsFreeze]
    WalletLogic --> claim[freeCreditsClaim]
    claim --> Y1[createTask SOURCE_TYPE_FREE]
  end
  subgraph pay [slot_pay]
    firstCashout[firstCashout API] --> WithdrawalOrder
    WithdrawalOrder --> MQ[FreeCreditsFirstCashout*]
    MQ --> EventBus
  end
```

| 模块 | 关键文件 | 覆盖的需求章节 |
|------|----------|----------------|
| 领域与状态机 | [FreeCreditsLogic.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/api/logic/FreeCreditsLogic.php) | 5.3–5.9 核心规则 |
| 数据表 | [install.sql](file:///Users/ray/Documents/project/www/slot/slot_console/db/install.sql) L36–86 | 活动池 + 档位 |
| 活动配置 | [RechargeGiftConfigModel.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/model/common/RechargeGiftConfigModel.php) `TYPE_FREE_CREDITS=11` | 17 配置（读库） |
| 客户端 API | [FreeCreditsController.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/api/controller/FreeCreditsController.php) | status / claim / firstCashout |
| 大厅聚合 | [LobbyController.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/napi/controller/LobbyController.php) `free_credits` | 7 状态条数据源（部分） |
| 充值事件 | [RechargeEvent.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/command/event/RechargeEvent.php) | 5.3 首充定格、5.5 累计充值解锁 |
| 首页解锁 | [EventBus.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/command/EventBus.php) win/bonus 等 → `syncHomeWithdrawUnlocked` | 5.2 |
| 钱包原子能力 | [WalletLogic.php](file:///Users/ray/Documents/project/www/slot/slot_wallet/app/api/logic/WalletLogic.php) | 15.2–15.4 |
| 首档提现 | [WithdrawalOrderEntity.php](file:///Users/ray/Documents/project/www/slot/slot_pay/app/entity/WithdrawalOrderEntity.php) + [EventWithdrawal.php](file:///Users/ray/Documents/project/www/slot/slot_pay/app/command/EventWithdrawal.php) | 5.6、15.3、20.2 |
| 运营统计 API | [innerapi/FreeCreditsController.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/innerapi/controller/FreeCreditsController.php) | 18.1–18.2（简化版） |

---

## 按需求章节对照（22.1 核心规则）

| 验收项（文档 22.1） | 实现情况 | 说明 |
|---------------------|----------|------|
| 未达 $50 点 Withdraw 提示 | **前端** | 后端 `status` 返回 `win_threshold` / `home_withdraw_unlocked`，无专用提示 API |
| 曾达 $50 后输回仍解锁 | **部分** | 已解锁用户靠 `home_withdraw_unlocked=1` 保持；**未持久化历史峰值**，仅在 MQ 事件时若 `balance >= threshold` 才写库，存在漏解锁边界（例如达峰后无 win/bonus 类事件即输掉） |
| 任意入口首充定格 | **是** | `RechargeEvent` + `handleRecharge`，`frozenAmount = balance_after - wallet_amount` |
| 首充失败不定格 | **是** | 仅充值成功 MQ 触发 |
| 定格后余额扣除、活动展示 | **是** | `freeCreditsFreeze` + player/package 记录 |
| 累计未满 $50 第一档不可提现 | **是** | 首包 `STATUS_LOCKED` 直至 `wallet.r >= recharge_unlock_amount` |
| 累计满 $50 第一档可提现 | **是** | `advanceByRecharge` 解锁 package_no=1 |
| 定格 < $20 时第一档=定格额 | **是** | `min(frozen, first_cash_amount)` |
| 第一档提现成功后关首页状态条 | **后端未显式字段** | 有 `STATUS_FIRST_CASH_DONE`，但 `buildStatus` **未返回** `show_home_status_bar` 等 UI 开关，需前端自行推断 |
| 后续充值只解锁下一档 | **是** | `max_unlock_per_recharge` + `nextLockedReleasePackage` |
| Claim 入 Deposit + Y1 | **部分** | 入 deposit_balance + `createTask(SOURCE_TYPE_FREE)`；**无 Deposit Lot**（文档 15.4、22.2） |
| 全部完成关活动入口 | **部分** | `STATUS_COMPLETED=10`；API 未返回 `show_activity_entry` 布尔字段 |

---

## 按需求章节对照（22.2 账务）

| 验收项 | 实现情况 | 风险 |
|--------|----------|------|
| 定格有钱包流水 | **是** | `BIZ_TYPE_FREE_CREDITS_FREEZE` |
| 定格前后余额正确 | **是** | `addLog` 记录 |
| 第一档不进普通钱包 | **是** | 独立 `free_credit_first_cashout`，跳过 `withdrawFrozen` |
| Claim 创建 Deposit Lot | **否** | 全仓库无 `DepositLot`/`deposit_lot` 实现 |
| Claim 创建 Y1 | **是** | 但 `createTask` 在钱包事务 **commit 之后**；失败仅打日志，**不满足** 文档 20.3「流水任务失败整体回滚」 |
| 重复回调不重复定格 | **是** | `frozen_amount_qf > 0` 跳过 |
| 重复 Claim 不重复入账 | **部分** | package 状态 + `claim_biz_id` 唯一；钱包层 **未见 biz_id 幂等查重** |

---

## 明确未实现 / 未对齐项

### P0（影响验收或资金一致性）

1. **Deposit Lot**：文档 15.4 / 22.2 要求 Claim 后创建；当前仅 `inc` deposit + Y1 task。
2. **Claim 与 Y1 原子性**：`freeCreditsClaim` 先 commit 入账，再 `createTask`；与 20.3 冲突。
3. **充值退款/拒付暂停档位**（文档 20.1）：`FreeCreditsLogic` 无 refund/chargeback 处理。
4. **status API 缺累计充值进度**：定格后 UI 需要 `$9.99 / $50`（文档 6.3、7.3），`buildStatus` 未返回 `total_recharge`（内部用 `wallet.r`，未透出）。
5. **「曾经达到 $50」**：无 `peak_balance` 字段；依赖事件驱动 `syncHomeWithdrawUnlocked`，与 5.2 字面规则不完全一致。

### P1（运营与配置）

6. **后台配置模块**（文档 17）：`backend/slot_admin` / `slot_admin_vue` **无** `TYPE_FREE_CREDITS=11` 的 CRUD 页面；仅能手工维护 `s_recharge_gift_config.ext_config`。
7. **后台统计页**（文档 18）：仅有 [innerapi](file:///Users/ray/Documents/project/www/slot/slot_console/app/innerapi/controller/FreeCreditsController.php) 简化接口；列表缺 **渠道、时间范围、第一档状态、排序项、累计充值、完成进度** 等字段/筛选项。
8. **可配置 Y1 倍数**（文档 17 `后续档打码倍数`）：代码写死 `createTask(0, fee, SOURCE_TYPE_FREE)`，未读 `ext_config`。
9. **状态机 `STATUS_FROZEN=2`**：模型定义了但 Logic **从未赋值**（定格后直接 `DEPOSIT_PENDING` / `FIRST_CASH_READY`）。

### P2（产品体验 / 文档其他章节）

10. **客户端 UI**（文档 6–14）：`slot_pwa` 等仓库 **零引用** `free_credits`；首页状态条、Free Play to Go、独立提现页、广播模块均未实现（原开发计划也标明前端另仓）。
11. **广播模块**（文档 13）：无最近 10 条提现/领取记录 API。
12. **注册赠送改 $30**（文档 19）：与本活动解耦，**未在本需求代码变更中验证**是否已改配置/落地页。
13. **自动化测试**：无 FreeCredits 相关单测/集成测试。

---

## 与现有开发计划的一致性

[free_credits_release 计划](file:///Users/ray/.cursor/plans/free_credits_release_902566c9.plan.md) 中 `implement-console-core` 仍为 **pending**，与代码现状（Logic 已较完整）不一致；`test-acceptance` 标 completed 但仓库内 **无测试文件**，建议以文档 22 节手工/自动化用例重新验收。

---

## 建议验收顺序（若需补齐）

1. **手工走通 P0 账务用例**：首充定格幂等、满 $50 解锁、首档提现回调、顺序 Claim、重复 Claim/回调。
2. **补齐 status 字段**：`total_recharge`、`show_home_status_bar`、`show_activity_entry`、`current_balance`。
3. **对齐钱包**：Deposit Lot（若钱包规范要求）、Claim+Y1 同事务或补偿回滚。
4. **运营**：slot_admin 增加 type=11 配置页 + 统计页对接 innerapi。
5. **前端仓**：按文档 6–14 接 API（本 monorepo 外）。
6. **补测试**：覆盖 22.1 / 22.2 表格各行。

---

## 总览评分（仅供沟通）

| 范围 | 完成度（估） |
|------|-------------|
| 后端核心状态机 + 充值/提现/Claim 链路 | ~75–85% |
| 钱包账务与文档完全一致 | ~60% |
| 客户端 API 字段/UI 支撑 | ~50% |
| 运营后台配置与统计 | ~25% |
| 前端 UI / 文案 / 广播 | ~0%（本仓库） |
| 自动化测试 | ~0% |

**综合：需求文档 V1.0 不能判定为「已全部实现」；可判定为「后端 MVP 已具备，待补齐账务细节、运营与前端后全量验收」。**