7.2 KiB
7.2 KiB
name, overview, todos, isProject
| name | overview | todos | isProject | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Free Credits 部署文档 | 为「后续档瀑布拆分 + 每档新增累计充值解锁」编写上线部署文档，覆盖 DB 迁移、服务发布顺序、存量兼容、验收与回滚。 |
|
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
- 单测已通过：
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
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 执行方式
# 示例：容器内 MySQL
docker exec -i goMysql mysql -uroot -p<password> < migrate_free_credits_release_tiers.sql
3.2 迁移后校验
-- 列存在且默认 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（已含两列） - 迁移幂等：若列已存在会报错，勿重复执行；可用
information_schema先查再执行
4. 代码发布顺序
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 新用户定格（核心）
- 测试账号：注册 → 赢取门槛 → 首充定格（如定格 $78.50，第一档 $20）
- 查库：
SELECT package_no, amount_qf, unlock_recharge_qf, status FROM s_common.free_credits_package WHERE player_id = ? ORDER BY package_no; - 期望 release 档：
10000×3, 20000, 8500；unlock：9000, 9000, 9000, 19000, 8000 - 查 player：
recharge_baseline_qf= 定格时 wallet 累计充值
6.2 解锁链路
- 累计充满 $50 → 第一档变 ready（规则未变）
- 第一档解锁后
recharge_baseline_qf更新为当前 totalR - 再新增累计 $9 → 第一个 $10 release 档变 ready；baseline 再次前移
- 尾档：面额 $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§5.7、§5.8 - 实现计划：首充剩余分档规则
10. 落盘路径
slot_console/doc/FreeCredits瀑布分档部署说明.md
同目录已有 slot_console/doc/首充前免费余额定格与分档释放需求部署说明.md（首版上线 checklist），本文档专述瀑布分档 + 增量解锁增量变更，二者并存。