---
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 分支需自查；当前仓库内无引用