feat: grant transition plan to existing users

docs/deployment.md

@@ -516,3 +516,32 @@ python3.12 manage.py smoke_ai_generation image
 - 真实支付 SDK 与商户配置齐全后，`PAYMENT_CALLBACK_MODE=sdk`。
 - 真实图片生成耗时已记录并用于设置超时链路；若未记录，发布说明必须标注风险。
 - `manage.py check`、迁移、静态文件、关键测试和 smoke 均有记录。
+
+## 十一、存量用户批量授予过渡套餐
+
+仅在运营已创建并确认目标套餐后使用。先用套餐数据库 ID 预演，默认不会写数据：
+
+```bash
+python3.12 manage.py grant_existing_users_plan \
+  --plan-id 2 \
+  --reason "存量用户测试套餐过渡"
+```
+
+确认输出中的 `grant_count`、套餐 ID 和产品代码，并完成数据库备份后，再把预演人数原样传给执行命令：
+
+```bash
+python3.12 manage.py grant_existing_users_plan \
+  --plan-id 2 \
+  --reason "存量用户测试套餐过渡" \
+  --execute \
+  --expected-grant-count 30
+```
+
+安全规则：
+
+- 默认只处理启用的非后台、非超级用户账号。
+- 同产品已有有效或宽限期权益的用户会跳过，不用测试套餐覆盖正式会员。
+- `--expected-grant-count` 与执行时重新计算的人数不一致时整批拒绝。
+- 实际授予在一个事务中执行，任一失败整批回滚，并为每个新权益写带原因的授权事件。
+- 执行后再次运行预演，正常应得到 `grant_count=0`；再核对权益、授权事件、后台账号和订阅状态接口。
+- 示例中的套餐 ID 和人数只表示一次部署记录，每次操作都必须重新从 admin 和预演结果确认，不能照抄。