---
name: Free Credits 部署文档
overview: 为「后续档瀑布拆分 + 每档新增累计充值解锁」编写上线部署文档，覆盖 DB 迁移、服务发布顺序、存量兼容、验收与回滚。
todos:
  - id: write-deploy-md
    content: 确认后将本文档写入 slot_console/doc/FreeCredits瀑布分档部署说明.md
    status: completed
  - id: commit-and-pr
    content: slot_console / slot_admin / slot_admin_vue 提交并提 PR merge
    status: pending
  - id: run-db-migrate
    content: 各环境先执行 migrate_free_credits_release_tiers.sql 再发 console
    status: pending
  - id: post-deploy-verify
    content: 按 §6 验收新定格 + 存量 grandfather + 后台配置
    status: pending
isProject: false
---

# Free Credits 瀑布分档 — 部署文档

## 1. 变更摘要

| 项 | 说明 |
|---|---|
| 需求 | 首充定格后，剩余金额按 10/20/30/50/100 瀑布拆分；后续档按「每档新增累计充值」解锁 |
| 影响服务 | **slot_console**（核心）、**slot_admin** + **slot_admin_vue**（后台配置文案/校验） |
| 不影响 | slot_wallet（定格/冻结/Claim）、slot_pay（第一档提现）、第一档 $20 / 累计 $50 解锁规则 |
| 分支 | `fix/upActivity`（待 merge） |

---

## 2. 发布前检查

- [ ] 代码已 merge 到目标分支并通过 CI
- [ ] 单测已通过：
  ```bash
  docker exec -w /app/www/slot/slot_console php82 \
    ./vendor/bin/phpunit tests/Unit/FreeCreditsLogicAmountTest.php \
    tests/Unit/FreeCreditsAdvanceUnlockTest.php
  ```
- [ ] 确认线上是否存在**在途 Free Credits 用户**（已定格、未完成全部档位）
- [ ] 与产品确认：存量用户走 grandfather（`unlock_recharge_qf=0` 仍用旧单笔解锁规则）

---

## 3. 数据库迁移（必须先于代码）

**库**：`s_common`  
**脚本**：[`slot_console/db/migrate_free_credits_release_tiers.sql`](slot_console/db/migrate_free_credits_release_tiers.sql)

```sql
ALTER TABLE s_common.free_credits_package
    ADD COLUMN unlock_recharge_qf bigint unsigned NOT NULL DEFAULT 0
        COMMENT '解锁本档所需新增累计真实充值（千分位），自上一档解锁后起算'
        AFTER amount_qf;

ALTER TABLE s_common.free_credits_player
    ADD COLUMN recharge_baseline_qf bigint unsigned NOT NULL DEFAULT 0
        COMMENT '后续档计数起点：wallet.totalRecharge 快照（千分位）'
        AFTER first_cash_amount_qf;
```

### 3.1 执行方式

```bash
# 示例：容器内 MySQL
docker exec -i goMysql mysql -uroot -p<password> < migrate_free_credits_release_tiers.sql
```

### 3.2 迁移后校验

```sql
-- 列存在且默认 0
SHOW COLUMNS FROM s_common.free_credits_package LIKE 'unlock_recharge_qf';
SHOW COLUMNS FROM s_common.free_credits_player LIKE 'recharge_baseline_qf';

-- 存量数据应为 0（旧规则兼容）
SELECT COUNT(*) FROM s_common.free_credits_package WHERE unlock_recharge_qf != 0;
-- 上线前应为 0；新定格用户上线后才会有非 0 值
```

### 3.3 注意事项

- **先 DDL、后发代码**：新代码会读写 `unlock_recharge_qf` / `recharge_baseline_qf`；缺列会导致定格/解锁失败
- 新装环境直接用 [`slot_console/db/install.sql`](slot_console/db/install.sql)（已含两列）
- 迁移**幂等**：若列已存在会报错，勿重复执行；可用 `information_schema` 先查再执行

---

## 4. 代码发布顺序

```mermaid
flowchart LR
  db[1_DB迁移]
  console[2_slot_console]
  admin[3_slot_admin]
  vue[4_slot_admin_vue]
  db --> console --> admin --> vue
```

| 顺序 | 仓库 | 变更要点 |
|---|---|---|
| 1 | DB | 执行 §3 迁移 |
| 2 | **slot_console** | `FreeCreditsLogic` 瀑布拆分 + 增量解锁；Model；`install.sql` |
| 3 | **slot_admin** | `ActivityValidate::checkFreeCreditsExt` — `package_amount` / `subsequent_min_recharge` 改为可选 |
| 4 | **slot_admin_vue** | 活动编辑页废弃提示；列表页展示「10/20/30/50/100 瀑布」 |

**无需重启/发布**：slot_wallet、slot_pay、slot_pwa（本次无接口字段变更；C 端 `unlock_recharge_amount` 为可选增强，未做）

---

## 5. 存量用户兼容（Grandfather）

| 用户类型 | 拆分规则 | 解锁规则 |
|---|---|---|
| **上线前已定格** | 保持原档位行不变 | `unlock_recharge_qf=0` → 仍按 `subsequent_min_recharge` **单笔**解锁 |
| **上线后新定格** | `buildReleasePackages()` 瀑布拆分 | 按 `unlock_recharge_qf` + `recharge_baseline_qf` 增量累计解锁 |

无需对存量数据做 backfill。  
若运营希望存量也切新规则，需单独产品决策 + 数据修复脚本（**不在本次范围**）。

---

## 6. 上线后验收

### 6.1 新用户定格（核心）

1. 测试账号：注册 → 赢取门槛 → 首充定格（如定格 $78.50，第一档 $20）
2. 查库：
   ```sql
   SELECT package_no, amount_qf, unlock_recharge_qf, status
   FROM s_common.free_credits_package
   WHERE player_id = ?
   ORDER BY package_no;
   ```
3. 期望 release 档：`10000×3, 20000, 8500`；unlock：`9000, 9000, 9000, 19000, 8000`
4. 查 player：`recharge_baseline_qf` = 定格时 wallet 累计充值

### 6.2 解锁链路

1. 累计充满 $50 → 第一档变 ready（规则未变）
2. 第一档解锁后 `recharge_baseline_qf` 更新为当前 totalR
3. 再新增累计 $9 → 第一个 $10 release 档变 ready；baseline 再次前移
4. 尾档：面额 $8.50 时 unlock 为 $8（8000 qf）

### 6.3 后台

- 新建/编辑 Free Credits 活动：可不填「解锁拆分金额」「后续解锁最小充值」
- 活动列表显示「分档规则: 10/20/30/50/100 瀑布（新定格）」

### 6.4 回归

- 存量用户（`unlock_recharge_qf=0`）单笔充值解锁仍正常
- Claim 入账、第一档提现、金额守恒 `sum(release) = frozen - first_cash` 不变

---

## 7. 回滚方案

| 场景 | 操作 |
|---|---|
| **代码有问题、DB 已迁移** | 回滚 slot_console 到上一版本；**保留 DB 新列**（默认 0，旧代码忽略即可） |
| **仅后台有问题** | 单独回滚 slot_admin / slot_admin_vue |
| **误发新代码但未迁移** | 立即补跑 §3 迁移，或回滚代码 |

**不建议** DROP 新列（除非确认无新定格用户且已回滚代码）。

---

## 8. 监控与告警

上线后关注：

- slot_console 日志：Free Credits 定格失败、解锁异常
- 业务指标：新定格用户的 package 行数分布（应与瀑布规则一致，不再全是 $10 均分）
- 客诉：「再充多少解锁下一档」— 当前 C 端未返回 `unlock_recharge_amount`，需 help 文案说明

---

## 9. 相关文档

- 需求：[`docs/requirements/首充前免费余额定格与分档释放需求文档.md`](docs/requirements/首充前免费余额定格与分档释放需求文档.md) §5.7、§5.8
- 实现计划：[首充剩余分档规则](/Users/ray/.cursor/plans/首充剩余分档规则_509262bd.plan.md)

---

## 10. 落盘路径

[`slot_console/doc/FreeCredits瀑布分档部署说明.md`](slot_console/doc/FreeCredits瀑布分档部署说明.md)

同目录已有 [`slot_console/doc/首充前免费余额定格与分档释放需求部署说明.md`](slot_console/doc/首充前免费余额定格与分档释放需求部署说明.md)（首版上线 checklist），本文档专述**瀑布分档 + 增量解锁**增量变更，二者并存。