155 lines
6.7 KiB
Markdown
155 lines
6.7 KiB
Markdown
---
|
||
name: 移除 RELEASING 状态
|
||
overview: 移除 Free Credits 玩家主状态 `STATUS_RELEASING(7)`，并同步实现「跨档领取 + 解锁不等待上一档 claim」：后续档进度仅由 package 表表达，玩家主状态停留在第一档生命周期（4/5/6）直至全部完成（10）。
|
||
todos:
|
||
- id: remove-releasing-status
|
||
content: FreeCreditsPlayerModel 删除 STATUS_RELEASING；advanceByRecharge 去掉写入 status=7
|
||
status: completed
|
||
- id: cross-claim-logic
|
||
content: claim() 去掉顺序校验；advanceByRecharge 去掉 nextReadyReleasePackage 解锁门槛
|
||
status: completed
|
||
- id: update-docs-comments
|
||
content: 同步 FreeCreditsLogic/Controller PHPDoc 与 install.sql status 注释
|
||
status: completed
|
||
- id: admin-vue-status-map
|
||
content: slot_admin_vue freeCreditsStats 删除 status=7 映射与筛选项
|
||
status: completed
|
||
- id: migrate-legacy-7
|
||
content: 提供/执行 status=7 历史数据 SQL 修正
|
||
status: completed
|
||
- id: add-tests
|
||
content: 补充跨档 claim 与解锁不等待 claim 的单测/集成测
|
||
status: completed
|
||
isProject: false
|
||
---
|
||
|
||
# 移除 STATUS_RELEASING 并支持跨档领取
|
||
|
||
## 结论
|
||
|
||
**是的，应去掉** [`FreeCreditsLogic.php`](slot_console/app/api/logic/FreeCreditsLogic.php) 第 709 行的 `$player->save(['status' => STATUS_RELEASING])`。
|
||
|
||
**是的，后台展示要改**：[`slot_admin_vue`](backend/slot_admin_vue/src/views/game/freeCreditsStats/index.vue) 的 `PLAYER_STATUS_MAP` 需删除 `7: '后续档释放中'`。
|
||
|
||
**`slot_admin` PHP 无需改**：[`FreeCreditsStatsController.php`](backend/slot_admin/app/game/controller/FreeCreditsStatsController.php) 仅透传 `slot_console` innerapi，不做 status 映射。
|
||
|
||
## 背景：为何 status=7 已无意义
|
||
|
||
原设计里，玩家主状态在「第一档生命周期」之后还有一个独立阶段 `releasing(7)`：
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
direction LR
|
||
firstCashReady: 4 第一档可提现
|
||
firstCashProcessing: 5 第一档处理中
|
||
firstCashDone: 6 第一档已提现
|
||
releasing: 7 后续档释放中
|
||
completed: 10 全部完成
|
||
|
||
firstCashReady --> firstCashProcessing
|
||
firstCashProcessing --> firstCashDone
|
||
firstCashDone --> releasing: 解锁后续档时写入7
|
||
releasing --> completed
|
||
```
|
||
|
||
跨档领取后：
|
||
|
||
- **后续档是否可领、已领多少** → 由 [`free_credits_package.status`](slot_console/app/model/common/FreeCreditsPackageModel.php) 表达（后台已有 `progress_done/total`、`claimed_amount_qf`）
|
||
- **玩家主状态** → 只描述「第一档相关阶段」，全部档位完成时由现有 [`refreshPlayerCompletion()`](slot_console/app/api/logic/FreeCreditsLogic.php) 置为 `10`
|
||
|
||
`STATUS_RELEASING` 在全仓库**仅写入、从未被读取**做分支判断，C 端 [`buildStatus()`](slot_console/app/api/logic/FreeCreditsLogic.php) 原样透出 `player.status`，去掉后不影响 package 列表展示。
|
||
|
||
## 代码改动（slot_console）
|
||
|
||
### 1. 删除 RELEASING 常量与写入
|
||
|
||
文件：[`FreeCreditsPlayerModel.php`](slot_console/app/model/common/FreeCreditsPlayerModel.php)
|
||
|
||
- 删除 `const STATUS_RELEASING = 7` 及注释
|
||
|
||
文件：[`FreeCreditsLogic.php`](slot_console/app/api/logic/FreeCreditsLogic.php) `advanceByRecharge()`
|
||
|
||
- 删除循环内 `$player->save(['status' => STATUS_RELEASING])`
|
||
- 解锁 release 档时**不再改玩家主状态**（保持 4/5/6 等既有值）
|
||
|
||
### 2. 跨档领取：去掉顺序限制
|
||
|
||
文件：[`FreeCreditsLogic.php`](slot_console/app/api/logic/FreeCreditsLogic.php)
|
||
|
||
**claim()** — 删除顺序校验块（约 295–298 行）：
|
||
|
||
```php
|
||
$nextReady = FreeCreditsPackageModel::nextReadyReleasePackage($player->id);
|
||
if (is_null($nextReady) || intval($nextReady->id) !== intval($package->id)) {
|
||
throw new BusinessException('Please claim credits in order');
|
||
}
|
||
```
|
||
|
||
保留：`package_type=release`、归属 uid、`status=ready`、幂等 biz_id、失败回滚 ready。
|
||
|
||
**advanceByRecharge()** — 去掉「存在 ready 后续档则不再解锁」门槛（约 695 行）：
|
||
|
||
```php
|
||
// 改前
|
||
if ($rechargeAmount < $minRecharge || !is_null(FreeCreditsPackageModel::nextReadyReleasePackage($player->id))) {
|
||
return;
|
||
}
|
||
// 改后：仅校验单笔充值下限
|
||
if ($rechargeAmount < $minRecharge) {
|
||
return;
|
||
}
|
||
```
|
||
|
||
`nextReadyReleasePackage()` 方法可保留（暂无其它引用，后续若 C 端需要「推荐下一档」可复用）。
|
||
|
||
### 3. 文档注释同步
|
||
|
||
- [`FreeCreditsLogic::claim()`](slot_console/app/api/logic/FreeCreditsLogic.php) PHPDoc：去掉「须按 package_no 顺序」
|
||
- [`FreeCreditsController::claim()`](slot_console/app/api/controller/FreeCreditsController.php) PHPDoc：去掉「须为当前可领的下一档 / claim in order」
|
||
- [`install.sql`](slot_console/db/install.sql) `free_credits_player.status` 字段 comment：删除 `7后续释放中`
|
||
|
||
### 4. 历史数据修正（建议一次性 SQL）
|
||
|
||
线上若已有 `status=7` 的记录，应按第一档 package 还原为主状态，避免后台筛选项去掉 7 后显示裸数字：
|
||
|
||
```sql
|
||
UPDATE s_common.free_credits_player p
|
||
INNER JOIN s_common.free_credits_package fp
|
||
ON fp.player_id = p.id AND fp.package_no = 1
|
||
SET p.status = CASE fp.status
|
||
WHEN 2 THEN 5 -- 第一档处理中
|
||
WHEN 3 THEN 6 -- 第一档已完成
|
||
WHEN 1 THEN 4 -- 第一档可提现
|
||
ELSE 6
|
||
END
|
||
WHERE p.status = 7;
|
||
```
|
||
|
||
（若首档 package 不存在，默认 `6` 或按业务确认。）
|
||
|
||
## 后台展示改动（slot_admin_vue）
|
||
|
||
文件：[`freeCreditsStats/index.vue`](backend/slot_admin_vue/src/views/game/freeCreditsStats/index.vue)
|
||
|
||
- 从 `PLAYER_STATUS_MAP` 删除 `7: '后续档释放中'`
|
||
- `playerStatusOptions` 自动随之更新（由 map 生成）
|
||
- **可选兼容**：保留只读展示 `7: '第一档已提现（历史）'` 不加入筛选项，避免迁移前偶发裸数字；迁移 SQL 执行后可删
|
||
|
||
列表「当前状态」列继续读 `record.status`；后续档进度看已有的「完成进度」「已领取金额」「待释放金额」，不再依赖 releasing 主状态。
|
||
|
||
## 测试
|
||
|
||
在 [`slot_console/tests`](slot_console/tests) 补充/调整：
|
||
|
||
| 场景 | 预期 |
|
||
|------|------|
|
||
| 两档均为 ready，claim 较高 package_no | 成功，不再抛 `Please claim credits in order` |
|
||
| 上一档 ready 未 claim，满足充值条件 | `advanceByRecharge` 仍可解锁下一 locked 档 |
|
||
| 解锁 release 档后 | `player.status` 不变（如仍为 `STATUS_FIRST_CASH_DONE`） |
|
||
| 全部 package completed | `player.status` → `10` |
|
||
|
||
## 不在本次范围
|
||
|
||
- [`docs/requirements/首充前免费余额定格与分档释放需求文档.md`](docs/requirements/首充前免费余额定格与分档释放需求文档.md) §16/§20.3 仍写顺序领取与 releasing — 若需文档对齐可另开任务
|
||
- C 端前端（slot_pwa 等）若曾按 `status===7` 做 UI 分支需自查；当前仓库内无引用
|