cmhub/docs/tasks/T-633.md

T-633 存量用户批量授予过渡测试套餐

背景

线上已创建用于开发和联调阶段的“测试”会员套餐。当前订阅仍运行在 shadow 模式，存量用户不会被强制拦截，但在正式切换到 enforce 前，需要用真实 SoftwareEntitlement 验证桌面端会员状态、到期时间和后续套餐切换流程。

直接在数据库批量插入权益会绕过套餐快照、席位和 LicenseEvent，逐个在 admin 操作又容易漏发或重复发放。因此需要一个默认只预演、显式确认后才执行的批量命令。

目标

1. 给执行时已有的启用非后台账号批量授予指定测试套餐。
2. 复用现有授权服务，完整生成权益快照、席位和授权事件。
3. 提供预演、人数校验、事务回滚和重复执行保护，降低生产批处理风险。
4. 不影响已有正式会员、API Key、点数、充值、软件订单和生成任务。

范围

批量命令

• 新增 grant_existing_users_plan management command。
• 套餐必须通过数据库 plan_id 精确指定，且执行时仍为启用状态；不按可能重名的套餐名称模糊匹配。
• 默认只输出预演统计，不写数据库。
• 实际执行必须同时传入 --execute 和预演得到的 --expected-grant-count；人数不一致时整批拒绝。
• --reason 必填并写入每一条授权事件，不能生成无原因的批量权益。

用户范围和幂等

• 默认只处理 is_active=True、is_staff=False、is_superuser=False 的账号。
• 对指定套餐所属产品，用户只要已有仍处于有效期或宽限期的权益，就跳过本次授予；不得用测试套餐覆盖或制造与正式套餐并存的有效权益。
• 已过期或已撤销权益不阻止重新授予。
• 执行阶段锁定套餐和目标用户，并在同一数据库事务内重新计算范围；任何一名用户授予失败都必须整批回滚。

授权与留痕

• 每名实际授予用户必须复用 grant_software_entitlement()，不得直接创建 SoftwareEntitlement。
• 权益继续复制套餐名称、价格、时长、设备数和宽限期快照，并按既有服务生成席位。
• 每项授予写 LicenseEvent(granted)，记录统一的非空批处理原因。
• 命令输出只给出符合条件、跳过和实际授予数量，不输出邮箱、API Key 或其他敏感数据。

实施约束

• 不修改 CMSHOPEE_SUBSCRIPTION_MODE，本任务执行期间线上继续保持 shadow。
• 不撤销、续期或改写用户已有权益。
• 不修改 UserWallet、PointsLedger、RechargeOrder、SoftwareOrder 或生成记录。
• 不新增数据迁移，不直接运行原始 SQL。
• 本任务只完成测试套餐的安全批量授予；测试结束后的正式套餐切换另行落任务，不通过编辑套餐反向修改权益快照。

验收条件

1. 默认预演不创建权益、席位或授权事件，并返回待授予和跳过数量。
2. 未提供 --execute 时不能写数据；执行时缺少或错误的预期授予人数必须拒绝且不产生部分数据。
3. 启用的普通用户获得指定套餐；后台账号、停用账号和已有同产品有效权益用户不受影响。
4. 每个新权益具有正确套餐快照、到期时间和宽限截止时间，并存在对应 granted 授权事件。
5. 同一命令重复执行时已获有效权益用户被跳过，不重复授予。
6. 任一授予失败时整批回滚。
7. manage.py check、目标测试、迁移一致性、编译检查和 git diff --check 通过。
8. 线上执行前完成数据库备份；预演人数与实际执行人数一致；执行后权益数、事件数和订阅状态接口抽样验收通过。

状态

DOING。