193 lines
7.2 KiB
Markdown
193 lines
7.2 KiB
Markdown
---
|
||
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），本文档专述**瀑布分档 + 增量解锁**增量变更，二者并存。
|