177 lines
8.2 KiB
Markdown
177 lines
8.2 KiB
Markdown
---
|
||
name: 第一档提现或保留余额
|
||
overview: 为 Free Credits 第一档（定格后首笔金额）增加用户二选一：沿用现有独立提现，或新增「保留到可提现余额」（withdraw_balance、不创建打码任务）。涉及 slot_wallet 新钱包原子能力、slot_lib RPC、slot_console 新 C 端接口与档位状态同步。
|
||
todos:
|
||
- id: wallet-first-keep
|
||
content: slot_wallet：WalletLogModel + WalletLogic::freeCreditsFirstCashKeep（withdraw 入账、无 createTask）+ 单测
|
||
status: completed
|
||
- id: slot-lib-rpc
|
||
content: slot_lib WalletService 增加 freeCreditsFirstCashKeep RPC
|
||
status: completed
|
||
- id: console-keep-api
|
||
content: slot_console：FreeCreditsLogic::keepFirstCash + Validator + Controller + 路由
|
||
status: completed
|
||
- id: console-tests
|
||
content: slot_console 单测 FreeCreditsKeepFirstCashTest；必要时调整 broadcast action
|
||
status: completed
|
||
- id: run-phpunit
|
||
content: php82 容器跑 console + wallet 相关单测
|
||
status: completed
|
||
isProject: false
|
||
---
|
||
|
||
# 第一档：提现或保留到可提现余额
|
||
|
||
## 背景与现状
|
||
|
||
当前第一档（`package_type=TYPE_FIRST_CASH`）在累计充值解锁后**仅支持**走 [`WithdrawService::applyFreeCreditsFirstCashout`](slot_console/app/service/WithdrawService.php) → Pay 独立提现（`bizType=free_credit_first_cashout`），**不经过钱包余额**（需求文档 §15.3）。
|
||
|
||
后续释放档走 [`FreeCreditsLogic::claim`](slot_console/app/api/logic/FreeCreditsLogic.php) → [`WalletLogic::freeCreditsClaim`](slot_wallet/app/api/logic/WalletLogic.php)：入账 **deposit_balance** 并 **创建 Y1 打码任务**。
|
||
|
||
新需求：第一档金额用户可二选一：
|
||
|
||
| 选项 | 行为 |
|
||
| --- | --- |
|
||
| **Withdraw** | 保持现有 `/api/withdraw/apply` + `package_id` |
|
||
| **Keep to balance** | 入账 **withdraw_balance**，**不** `createTask`，金额立即可参与普通提现规则（无其它未完成打码任务时） |
|
||
|
||
已确认：保留余额入账 **withdraw_balance**（非 deposit）。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
firstReady[第一档 status=ready]
|
||
firstReady --> withdrawPath["POST /api/withdraw/apply"]
|
||
firstReady --> keepPath["POST /api/free-credits/keep-first-cash"]
|
||
withdrawPath --> payOrder[Pay 独立提现单]
|
||
payOrder --> busCallback[EventBus 提现结果]
|
||
busCallback --> pkgDone[package completed]
|
||
keepPath --> walletKeep[wallet freeCreditsFirstCashKeep]
|
||
walletKeep --> pkgDone
|
||
pkgDone --> playerDone[player STATUS_FIRST_CASH_DONE]
|
||
```
|
||
|
||
## 目标契约
|
||
|
||
### 新接口（slot_console）
|
||
|
||
- **路径**：`POST /api/free-credits/keep-first-cash`（与现有 `claim` 命名风格一致）
|
||
- **入参**：`package_id`（必填，`free_credits_package.id`，须为第一档且 `status=ready`）
|
||
- **成功**：`data` 结构同 `status()` / `claim`（`buildStatus`）
|
||
- **幂等**：`bizId = free_credits_first_keep:{packageId}`；重复请求不重复入账
|
||
- **互斥**：同一第一档 `processing/completed` 后不可再提现或 keep；提现处理中不可 keep
|
||
|
||
### 档位与玩家状态（与提现成功对齐）
|
||
|
||
完成后与 [`handleFirstCashoutResult(success)`](slot_console/app/api/logic/FreeCreditsLogic.php) 一致：
|
||
|
||
- package → `STATUS_COMPLETED`，写 `completed_time`，`claim_biz_id` 存幂等键（复用字段，无需改表）
|
||
- player → `STATUS_FIRST_CASH_DONE`
|
||
- 调用 `refreshPlayerCompletion`
|
||
- 首页状态条关闭逻辑与「第一档提现成功」相同（C 端仍用 `status` / packages[0] completed）
|
||
|
||
### 钱包（slot_wallet）
|
||
|
||
新增 **`freeCreditsFirstCashKeep`**（`WalletLogic::run` 按 `type` 分发）：
|
||
|
||
- `inc(withdraw=fee, deposit=0, bonus=0)` 增加 **withdraw_balance**
|
||
- **不**调用 `createTask`
|
||
- 流水：`BIZ_TYPE_FREE_CREDITS_FIRST_KEEP = 'freeCreditsFirstCashKeep'`，`WALLET_TYPE_GIFT`（与 freeze/claim 一致）
|
||
- 事务内完成入账 + `addLog`；成功后 `sendConsoleBus`（可选，用于统计/通知，类型建议 `freeCreditsFirstCashKeep`）
|
||
|
||
对比现有实现：
|
||
|
||
| 能力 | 入账 | 打码任务 |
|
||
| --- | --- | --- |
|
||
| `freeCreditsClaim`（后续档） | deposit | Y1 `createTask` |
|
||
| **`freeCreditsFirstCashKeep`（新）** | **withdraw** | **无** |
|
||
|
||
### slot_lib
|
||
|
||
[`WalletService`](slot_lib/src/services/WalletService.php) 增加常量与方法：
|
||
|
||
```php
|
||
const WALLET_TYPE_FREE_CREDITS_FIRST_KEEP = 'freeCreditsFirstCashKeep';
|
||
public function freeCreditsFirstCashKeep($amount, $bizId = ''): Wallet
|
||
```
|
||
|
||
## 实现步骤
|
||
|
||
### 1. slot_wallet
|
||
|
||
| 文件 | 改动 |
|
||
| --- | --- |
|
||
| [`WalletLogModel.php`](slot_wallet/app/model/multi/WalletLogModel.php) | `BIZ_TYPE_FREE_CREDITS_FIRST_KEEP` |
|
||
| [`WalletLogic.php`](slot_wallet/app/api/logic/WalletLogic.php) | `freeCreditsFirstCashKeep()`：镜像 `freeCreditsClaim` 事务结构，改为 `inc(fee,0,0)`，**删除** `createTask` 调用 |
|
||
| 单测 | 新增 `WalletFreeCreditsFirstKeepTest`（或扩展现有 wallet 单测）：断言 withdraw 增加、无 task 创建（可 mock `createTask` 不被调用） |
|
||
|
||
### 2. slot_lib
|
||
|
||
- [`WalletService.php`](slot_lib/src/services/WalletService.php)：常量 + `freeCreditsFirstCashKeep($amount, $bizId)`
|
||
|
||
### 3. slot_console — Logic
|
||
|
||
[`FreeCreditsLogic.php`](slot_console/app/api/logic/FreeCreditsLogic.php) 新增 `keepFirstCash(int $uid, int $packageId): array`：
|
||
|
||
1. `assertEligibleParticipant`
|
||
2. 查询 package：`uid`、`TYPE_FIRST_CASH`、`STATUS_READY`
|
||
3. `bizId = 'free_credits_first_keep:' . $packageId`
|
||
4. package → `STATUS_PROCESSING`，写 `claim_biz_id`
|
||
5. `walletService->freeCreditsFirstCashKeep($package->amount_qf, $bizId)`
|
||
6. 成功 → package `COMPLETED` + 时间戳；player `STATUS_FIRST_CASH_DONE`；`refreshPlayerCompletion`
|
||
7. 失败 → package 回滚 `READY`（同 `claim`）
|
||
8. 返回 `buildStatus`
|
||
|
||
**不**改 `advanceByRecharge` / 定格冻结逻辑。
|
||
|
||
### 4. slot_console — API 层
|
||
|
||
| 文件 | 改动 |
|
||
| --- | --- |
|
||
| [`FreeCreditsValidator.php`](slot_console/app/api/validator/FreeCreditsValidator.php) | `SCENE_KEEP_FIRST_CASH`：`package_id` require\|integer |
|
||
| [`FreeCreditsController.php`](slot_console/app/api/controller/FreeCreditsController.php) | `keepFirstCash()` + PHPDoc；类注释补充第二路径 |
|
||
| 路由配置 | 注册 `POST /api/free-credits/keep-first-cash`（查项目现有 `route` / `config` 中 `free-credits` 注册方式，与 `claim` 并列） |
|
||
|
||
### 5. 广播 / 统计（小改）
|
||
|
||
- [`buildBroadcastList`](slot_console/app/api/logic/FreeCreditsLogic.php)：第一档 completed 若走 keep，广播 `action` 可新增 `keep`（或复用 `claim`）；与产品确认文案前可先 `keep`
|
||
- [`FreeCreditsStatsLogic`](slot_console/app/innerapi/logic/FreeCreditsStatsLogic.php)：`first_cashout_*` 按「第一档 completed」统计，**keep 与 withdraw 均计入**（无需区分，除非运营后续要拆指标）
|
||
|
||
### 6. 单测（slot_console）
|
||
|
||
| 文件 | 内容 |
|
||
| --- | --- |
|
||
| 新增 `FreeCreditsKeepFirstCashTest` | harness 注入 mock `WalletService`；断言状态迁移、幂等、非 ready 抛错 |
|
||
| 可选集成测 | keep 后 package completed + player `FIRST_CASH_DONE` |
|
||
|
||
运行：
|
||
|
||
```bash
|
||
docker exec -w /app/www/slot/slot_console php82 ./vendor/bin/phpunit tests/Unit/FreeCreditsKeepFirstCashTest.php
|
||
docker exec -w /app/www/slot/slot_wallet php82 ./vendor/bin/phpunit tests/Unit/WalletFreeCreditsFirstKeepTest.php
|
||
```
|
||
|
||
## C 端约定（供联调，本次可不改 PWA）
|
||
|
||
第一档 `packages[0].status === 1` 时展示两个入口：
|
||
|
||
- **Withdraw** → 现有 `POST /api/withdraw/apply` + `package_id`
|
||
- **Keep to Balance** → `POST /api/free-credits/keep-first-cash` + `package_id`
|
||
|
||
完成后 `packages[0].status === 3`，与提现成功 UI 一致（按钮隐藏 / 成功态）。
|
||
|
||
## 不在本次范围
|
||
|
||
- slot_pwa / gateway 前端页面与文案
|
||
- 需求文档 §10–11 全文修订（可后续补「Add to Balance」分支）
|
||
- 修改后续档 `claim` 的打码规则
|
||
- 第一档金额改由后台配置动态展示（仍从 `packages[0].amount` 读取）
|
||
|
||
## 验收清单
|
||
|
||
1. 第一档 ready：keep 成功 → withdraw_balance 增加对应千分位，**无**新 WagerTask
|
||
2. 同一 package 重复 keep：幂等，不重复加钱
|
||
3. keep 成功后：package/player 状态与提现成功一致；`status` 接口 packages[0] 为 completed
|
||
4. 第一档 processing（提现中）：keep 拒绝
|
||
5. 第一档 completed：withdraw / keep 均拒绝
|
||
6. 相关单测通过
|