ok

2026-06-29 14:51:55 +08:00
parent 225fb2bd28
commit 2dd9f17da9
319 changed files with 29461 additions and 9412 deletions
--- a/plans/free_credits_部署文档_149ece64.plan.md
+++ b/plans/free_credits_部署文档_149ece64.plan.md
@@ -0,0 +1,192 @@
+---
+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），本文档专述**瀑布分档 + 增量解锁**增量变更，二者并存。