# 技术设计文档: 套餐系统升级 ## Context ### 背景 当前套餐系统仅支持简单的按月计算模式，所有套餐立即生效，流量管理粗糙。新需求引入了代理商囤货场景（后台为未实名设备预购套餐，等待首次实名时自动激活）、灵活的套餐类型（自然月套餐、按天套餐）、多套餐管理（主套餐排队、加油包生命周期）、精细化流量统计（客户视图、套餐维度详单）等复杂业务逻辑。 ### 当前状态 **已有实现**: - 套餐模型 (`Package`, `PackageUsage`)：支持基础流量限额和使用统计 - 轮询系统 (`Scheduler`)：支持千万级卡规模的实名检查、流量检查、套餐检查 - 订单服务：支持套餐购买并立即激活（`activatePackage`） **现有限制**: - `Package.DurationMonths` 只支持按月计算，无法区分自然月和按天 - `PackageUsage.Status` 只有 1-生效中、2-已用完、3-已过期，无"待生效"和"已失效"状态 - 无流量重置周期概念（联通27号重置、日重置/月重置需求无法支持） - 无主套餐排队机制，同时可存在多个生效中的主套餐 - 无加油包生命周期管理，加油包与主套餐无关联关系 - 流量扣减无优先级，停机条件只检查单一套餐 - 流量统计只有卡维度详单，无套餐维度详单和客户视图 ### 约束条件 - 必须遵循 Handler → Service → Store → Model 分层架构 - 禁止外键约束和 GORM 关联关系（foreignKey, hasMany, belongsTo） - 所有常量定义在 `pkg/constants/`，禁止硬编码 - 性能要求：套餐激活延迟 < 1分钟、API P95 < 200ms、千万级卡规模支持不退化 - 异步任务使用 Asynq，必须支持重试和幂等性 ### 涉众 - **代理商**：需要囤货功能（提前为未实名设备低价采购套餐） - **客户（企业/个人）**：需要区分主套餐和加油包用量、查看流量详单 - **运营团队**：需要精细化流量统计、套餐生命周期管理 - **开发团队**：负责实施和维护升级后的套餐系统 --- ## Goals / Non-Goals ### Goals 1. **支持灵活的套餐类型**：自然月套餐（按月边界）、按天套餐（精确天数） 2. **支持流量重置周期**：日重置、月重置（联通27号/其他1号）、年重置、不重置 3. **支持首次实名激活**：代理商囤货场景，后台可为未实名设备购买套餐，等待实名时触发激活 4. **支持主套餐排队**：同时只能有一个生效中主套餐，后续购买自动排队，当前过期后自动激活下一个 5. **支持加油包生命周期**：加油包依附于主套餐，主套餐过期时级联失效 6. **支持流量扣减优先级**：优先扣减加油包（按 priority），再扣主套餐；全部用完才停机 7. **支持套餐流量详单**：按套餐维度记录每日流量增量，支持按日期查询 8. **支持客户视图流量查询**：区分主套餐和加油包用量，显示总计流量 ### Non-Goals 1. **不支持加油包继承**：主套餐过期时，加油包统一失效（status=4），不转移到下一个主套餐 2. **不支持加油包跨主套餐共享**：加油包只为当前主套餐服务 3. **不支持套餐暂停/恢复**：套餐生命周期是单向的（待生效 → 生效中 → 已用完/已过期/已失效） 4. **不支持套餐流量转移**：套餐间流量不可转移或合并 5. **不修改现有卡流量详单逻辑**：卡维度详单 (`DataUsageRecord`) 保持不变 6. **不修改订单服务的分佣逻辑**：分佣计算逻辑不在本次改造范围内 --- ## Decisions ### 1. 数据库 Schema 设计 #### 1.1 Package 表扩展 **方案**: 在 `tb_package` 表新增 3 个字段 ```go type Package struct { // ... 现有字段 ... // 新增字段 CalendarType string `gorm:"column:calendar_type;type:varchar(20);not null;default:'by_day';comment:周期类型 natural_month-自然月 by_day-按天" json:"calendar_type"` DataResetCycle string `gorm:"column:data_reset_cycle;type:varchar(20);not null;default:'none';comment:流量重置周期 daily-每日 monthly-每月 yearly-每年 none-不重置" json:"data_reset_cycle"` EnableRealnameActivation bool `gorm:"column:enable_realname_activation;type:boolean;default:false;comment:是否需要首次实名激活（后台囤货场景）" json:"enable_realname_activation"` } ``` **决策理由**: - `calendar_type` 和 `data_reset_cycle` 是两个独立维度（套餐类型 vs 流量重置周期） - `calendar_type=natural_month` 时必须提供 `duration_months`，`by_day` 时可提供 `duration_days`（如缺失则从 `duration_months` 转换） - `enable_realname_activation=true` 的套餐，后台购买时创建 `PackageUsage(status=0, pending_realname_activation=true)` **替代方案**: - ~~使用 `JSONB` 字段存储扩展配置~~：不利于 SQL 查询和索引，违背"优先使用结构化字段"原则 #### 1.2 PackageUsage 表扩展 **方案**: 扩展 `tb_package_usage` 表状态和新增 7 个字段 ```go type PackageUsage struct { // ... 现有字段 ... // status 扩展：0-待生效, 1-生效中, 2-已用完, 3-已过期, 4-已失效 Status int `gorm:"column:status;type:int;default:1;not null;comment:状态 0-待生效 1-生效中 2-已用完 3-已过期 4-已失效" json:"status"` // 新增字段 Priority int `gorm:"column:priority;type:int;index;comment:优先级（主套餐排队顺序，数字越小优先级越高）" json:"priority"` MasterUsageID *uint `gorm:"column:master_usage_id;index;comment:主套餐ID（加油包关联主套餐）" json:"master_usage_id"` HasIndependentExpiry bool `gorm:"column:has_independent_expiry;type:boolean;default:false;comment:加油包是否有独立有效期" json:"has_independent_expiry"` PendingRealnameActivation bool `gorm:"column:pending_realname_activation;type:boolean;default:false;comment:是否等待首次实名激活" json:"pending_realname_activation"` DataResetCycle string `gorm:"column:data_reset_cycle;type:varchar(20);not null;default:'none';comment:流量重置周期（从 Package 复制）" json:"data_reset_cycle"` LastResetAt *time.Time `gorm:"column:last_reset_at;comment:最后一次流量重置时间" json:"last_reset_at"` NextResetAt *time.Time `gorm:"column:next_reset_at;comment:下次流量重置时间" json:"next_reset_at"` } ``` **决策理由**: - **priority**: 主套餐排队顺序，数字越小优先级越高（1 > 2 > 3） - **master_usage_id**: 加油包关联主套餐 ID，实现生命周期管理（主套餐过期时级联失效） - **has_independent_expiry**: 加油包有效期模式（true=独立有效期，false=跟随主套餐） - **pending_realname_activation**: 标识是否等待首次实名激活（后台囤货场景） - **data_reset_cycle**: 从 `Package.DataResetCycle` 复制，避免 JOIN 查询 - **last_reset_at / next_reset_at**: 支持流量重置调度 **索引策略**: - `priority` 索引：支持主套餐排队查询（`WHERE status=0 AND priority=MIN(priority)`） - `master_usage_id` 索引：支持加油包级联失效查询（`WHERE master_usage_id=?`） **替代方案**: - ~~使用单独的 `PackageQueue` 表管理主套餐排队~~：增加复杂度，状态分散在两个表中，不利于一致性保证 #### 1.3 IoT卡表扩展 **方案**: 在 `tb_iot_card` 表新增幂等字段 ```go type IotCard struct { // ... 现有字段 ... // 新增字段 FirstRealnameAt *time.Time `gorm:"column:first_realname_at;comment:首次实名时间，NULL=未实名，非NULL=已实名（幂等标记）" json:"first_realname_at"` } ``` **决策理由**： - 比 `realname_status` 字段更可靠（状态可能被重置，时间戳不可逆） - 可追溯首次实名时间 - 数据库层面保证唯一更新（`UPDATE SET first_realname_at=NOW() WHERE id=? AND first_realname_at IS NULL`） - 支持幂等性：NULL=未实名，非NULL=已处理 **使用方式**： ```sql -- 首次实名触发时 UPDATE tb_iot_card SET first_realname_at = NOW() WHERE id = ? AND first_realname_at IS NULL; -- 判断是否首次实名 SELECT first_realname_at FROM tb_iot_card WHERE id = ?; -- NULL = 首次，执行激活逻辑 -- 非NULL = 已处理，跳过 ``` #### 1.4 运营商表扩展 **方案**: 在 `tb_carrier` 表新增计费日配置字段 ```go type Carrier struct { // ... 现有字段 ... // 新增字段 BillingDay *int `gorm:"column:billing_day;comment:计费日（1-31），NULL=默认1号，27=联通" json:"billing_day"` } ``` **决策理由**： - 可配置化，无需硬编码联通27号规则 - 支持运营商策略变更 - 便于新运营商接入 - 便于测试（可模拟不同计费日） **数据初始化**： ```sql UPDATE tb_carrier SET billing_day = 27 WHERE name = '中国联通'; UPDATE tb_carrier SET billing_day = 1 WHERE name IN ('中国移动', '中国电信'); ``` #### 1.5 新增卡日流量详单表 **方案**: 创建卡维度日流量统计表 ```go type CardDailyUsage struct { gorm.Model CardID uint `gorm:"column:card_id;index:idx_card_date;not null;comment:卡ID" json:"card_id"` UsageDate time.Time `gorm:"column:usage_date;type:date;index:idx_card_date;not null;comment:使用日期" json:"usage_date"` TotalDataUsage int64 `gorm:"column:total_data_usage;type:bigint;not null;comment:总流量使用（字节），聚合该卡当日所有套餐的用量" json:"total_data_usage"` CarrierID int `gorm:"column:carrier_id;comment:运营商ID（冗余，便于查询）" json:"carrier_id"` } // 唯一索引 CREATE UNIQUE INDEX idx_card_date ON tb_card_daily_usage(card_id, usage_date) WHERE deleted_at IS NULL; // 日期索引（便于按日期范围查询） CREATE INDEX idx_usage_date ON tb_card_daily_usage(usage_date); ``` **决策理由**： - **支持卡维度流量统计查询**：不需要聚合多个套餐记录 - **简化账单生成**：直接查询卡日流量，无需JOIN套餐表 - **提升查询性能**：避免复杂的GROUP BY和SUM操作 - **流量告警触发**：快速查询卡当日总流量 **数据来源**： ``` 卡日总流量 = SUM(该卡所有生效套餐当日增量) ``` **与 PackageUsageDailyRecord 的关系**： - `PackageUsageDailyRecord`：套餐维度详单（区分主套餐和加油包） - `CardDailyUsage`：卡维度汇总（所有套餐总和） - 两者互补，不重复 #### 1.6 新增 PackageUsageDailyRecord 表 **方案**: 创建套餐流量日记录表 ```go type PackageUsageDailyRecord struct { gorm.Model BaseModel `gorm:"embedded"` PackageUsageID uint `gorm:"column:package_usage_id;index:idx_usage_date;not null;comment:套餐使用记录ID" json:"package_usage_id"` Date time.Time `gorm:"column:date;type:date;index:idx_usage_date;not null;comment:日期" json:"date"` DailyUsageMB int64 `gorm:"column:daily_usage_mb;type:bigint;not null;comment:当日流量增量(MB)" json:"daily_usage_mb"` CumulativeUsageMB int64 `gorm:"column:cumulative_usage_mb;type:bigint;not null;comment:累计流量(MB)" json:"cumulative_usage_mb"` } // 唯一索引 CREATE UNIQUE INDEX idx_package_usage_date ON tb_package_usage_daily_record(package_usage_id, date) WHERE deleted_at IS NULL; ``` **决策理由**: - **按套餐维度记录**：每个 `PackageUsage` 每天一条记录 - **daily_usage_mb**: 当天流量增量（基于上游累计流量计算） - **cumulative_usage_mb**: 截至当天的累计流量 - **联合唯一索引**：确保同一套餐同一天只有一条记录 **数据来源**: ``` 今日增量 = max(上游返回累计流量 - 昨日 cumulative_usage_mb, 0) ``` **替代方案**: - ~~复用现有 `DataUsageRecord` 表~~：`DataUsageRecord` 按卡维度记录，无法区分主套餐和加油包，需要独立表 --- ### 2. 业务流程设计 #### 2.1 首次实名激活流程 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 后台订单服务（Order Service） │ ├─────────────────────────────────────────────────────────────────┤ │ 1. 代理商为未实名设备购买套餐（enable_realname_activation=true）│ │ 2. 创建 PackageUsage(status=0, pending_realname_activation=true)│ │ activated_at=NULL, expires_at=NULL │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ 轮询系统 - 实名检查任务（Realname Handler） │ ├─────────────────────────────────────────────────────────────────┤ │ 3. 检测到首次实名（realname_status: 0/1 → 2） │ │ 4. 查询该卡/设备是否有待激活套餐 │ │ WHERE pending_realname_activation=true AND status=0 │ │ 5. 提交 Asynq 任务: TaskTypePackageFirstActivation │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ Asynq Handler - 套餐首次实名激活任务 │ ├─────────────────────────────────────────────────────────────────┤ │ 6. 根据 calendar_type 计算 activated_at 和 expires_at │ │ - natural_month: 激活时间=当前时间，过期时间=月末23:59:59 │ │ - by_day: 激活时间=当前时间，过期时间=激活时间+N天 │ │ 7. 更新 PackageUsage │ │ status=1, pending_realname_activation=false, │ │ activated_at=计算值, expires_at=计算值 │ │ 8. 记录操作日志 │ └─────────────────────────────────────────────────────────────────┘ ``` **幂等性保证**: - 任务处理前检查 `pending_realname_activation=false`，已激活则直接返回成功 - 使用数据库事务更新 `PackageUsage` **重试策略**: - 最大重试 3 次（Asynq `MaxRetry(3)`） - 超时时间 30 秒（Asynq `Timeout(30s)`） **性能目标**: - 实名检测到激活延迟 < 30 秒（取决于轮询间隔 + 队列延迟） --- #### 2.2 主套餐排队生效流程 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 订单服务（Order Service） │ ├─────────────────────────────────────────────────────────────────┤ │ 1. 用户购买主套餐（package_type=formal） │ │ 2. 查询该载体当前生效中主套餐 │ │ WHERE usage_type=? AND (iot_card_id/device_id)=? AND │ │ status=1 AND master_usage_id IS NULL │ │ 3. 如果有生效中主套餐: │ │ - 新套餐 status=0, priority=MAX(priority)+1 │ │ - activated_at=NULL, expires_at=NULL │ │ 如果无生效中主套餐: │ │ - 新套餐 status=1, priority=1, 立即激活 │ │ - 根据 calendar_type 计算 activated_at 和 expires_at │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ 轮询系统 - 套餐激活检查任务（每 10 秒调度一次） │ ├─────────────────────────────────────────────────────────────────┤ │ 4. 查询已过期主套餐（status=1 AND expires_at <= NOW） │ │ 5. 更新过期主套餐 status=3 │ │ 6. 查询该载体下一个待生效主套餐 │ │ WHERE usage_type=? AND (iot_card_id/device_id)=? AND │ │ status=0 AND master_usage_id IS NULL │ │ ORDER BY priority ASC LIMIT 1 │ │ 7. 提交 Asynq 任务: TaskTypePackageQueueActivation │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ Asynq Handler - 主套餐排队激活任务 │ ├─────────────────────────────────────────────────────────────────┤ │ 8. 根据 calendar_type 计算 activated_at 和 expires_at │ │ 9. 更新 PackageUsage status=1, activated_at, expires_at │ │ 10. 记录操作日志 │ └─────────────────────────────────────────────────────────────────┘ ``` **激活延迟保证**: - 目标: 主套餐过期后 1 分钟内激活下一个 - 调度间隔: 10 秒（`Scheduler.scheduleLoop` 每 10 秒执行一次） - 性能分析: - 过期检查: 10 秒（最差情况，刚好错过本次调度） - 队列延迟: < 1 秒（Asynq 队列延迟） - 激活处理: < 5 秒（数据库更新 + 日志记录） - **总延迟 < 20 秒**（满足 < 1 分钟要求） **幂等性保证**: - 任务处理前检查 `status=1`，已激活则直接返回成功 - 使用数据库事务 + 乐观锁（`WHERE status=0`）防止重复激活 --- #### 2.3 加油包生命周期管理 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 订单服务（Order Service） │ ├─────────────────────────────────────────────────────────────────┤ │ 1. 用户购买加油包（package_type=addon） │ │ 2. 检查该载体是否有生效中或待生效主套餐 │ │ WHERE usage_type=? AND (iot_card_id/device_id)=? AND │ │ status IN (0,1) AND master_usage_id IS NULL │ │ 3. 如果无主套餐: 返回错误 "必须有主套餐才能购买加油包" │ │ 4. 创建 PackageUsage: │ │ - master_usage_id=主套餐ID │ │ - status=1, priority=MAX(priority)+1 (同一主套餐下) │ │ - has_independent_expiry=套餐配置的独立有效期模式 │ │ - 根据 has_independent_expiry 计算 expires_at │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ 轮询系统 - 套餐激活检查任务 │ ├─────────────────────────────────────────────────────────────────┤ │ 5. 查询已过期主套餐（status=1 AND expires_at <= NOW） │ │ 6. 更新主套餐 status=3 │ │ 7. 查询该主套餐下的所有加油包 │ │ WHERE master_usage_id=主套餐ID │ │ 8. 批量更新加油包 status=4（已失效） │ │ 9. 记录操作日志 │ └─────────────────────────────────────────────────────────────────┘ ``` **有效期计算**: - `has_independent_expiry=true`: 根据加油包套餐的 `calendar_type` 和 `duration_*` 计算 - `has_independent_expiry=false`: `expires_at=主套餐.expires_at` **级联失效**: - 主套餐过期时（`status=3`），批量更新关联加油包 `status=4` - 不支持加油包转移到下一个主套餐 --- #### 2.4 流量扣减优先级流程 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 轮询系统 - 流量检查任务（Carddata Handler） │ ├─────────────────────────────────────────────────────────────────┤ │ 1. 查询上游流量（ICCID → 累计流量） │ │ 2. 查询该卡当前生效套餐（status=1 的主套餐和加油包） │ │ 3. 按优先级排序：加油包（按 priority ASC）→ 主套餐 │ │ 4. 依次扣减流量: │ │ FOR EACH 套餐 IN 优先级列表: │ │ 剩余额度 = data_limit_mb - data_usage_mb │ │ IF 剩余额度 > 0: │ │ 扣减量 = MIN(本次增量, 剩余额度) │ │ UPDATE data_usage_mb += 扣减量 │ │ 本次增量 -= 扣减量 │ │ 记录到 PackageUsageDailyRecord │ │ IF data_usage_mb >= data_limit_mb: │ │ UPDATE status=2 (已用完) │ │ IF 本次增量 == 0: │ │ BREAK │ │ 5. 检查停机条件: │ │ IF 所有套餐 data_usage_mb >= data_limit_mb: │ │ 触发停机操作 │ └─────────────────────────────────────────────────────────────────┘ ``` **停机条件**: - 旧逻辑: 单一套餐流量用完即停机 - 新逻辑: 主套餐 + 所有加油包流量全部用完才停机 **性能优化**: - 批量查询套餐（一次 SQL 获取主套餐和所有加油包） - 批量更新套餐（使用事务提交） --- #### 2.5 流量重置调度流程 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 轮询系统 - 流量重置调度任务（每 10 秒调度一次） │ ├─────────────────────────────────────────────────────────────────┤ │ 1. 每日 0 点触发日重置: │ │ WHERE data_reset_cycle='daily' AND next_reset_at <= NOW │ │ UPDATE data_usage_mb=0, last_reset_at=NOW, │ │ next_reset_at=明天 00:00:00 │ │ │ │ 2. 每月 1 号（非联通）或 27 号（联通）触发月重置: │ │ WHERE data_reset_cycle='monthly' AND next_reset_at <= NOW │ │ UPDATE data_usage_mb=0, last_reset_at=NOW, │ │ next_reset_at=下月 1号/27号 00:00:00 │ │ │ │ 3. 每年 1 月 1 日触发年重置: │ │ WHERE data_reset_cycle='yearly' AND next_reset_at <= NOW │ │ UPDATE data_usage_mb=0, last_reset_at=NOW, │ │ next_reset_at=明年 1月 1日 00:00:00 │ └─────────────────────────────────────────────────────────────────┘ ``` **重置时间计算**: - `daily`: 每天 00:00:00 - `monthly`: - 联通卡（`carrier_id=CUCC`）: 每月 27 号 00:00:00 - 其他运营商: 每月 1 号 00:00:00 - `yearly`: 每年 1 月 1 日 00:00:00 - `none`: 不重置（`next_reset_at=NULL`） **分批处理**: - 每次最多处理 10000 条记录（避免长事务） - 使用游标分批查询（`WHERE id > last_id`） **幂等性保证**: - 使用 `next_reset_at <= NOW` 条件查询，已重置的记录 `next_reset_at` 已更新到未来时间 --- ### 3. 状态机设计 #### 3.1 PackageUsage 状态转换图 ``` ┌────────────────┐ │ 0-待生效 │ │ (Pending) │ └────────────────┘ │ ┌─────────────┼─────────────┐ │ │ 首次实名激活 / 主套餐排队激活 过期前删除订单 │ │ ↓ ↓ ┌────────────────┐ ┌────────────────┐ │ 1-生效中 │ │ 已删除 │ │ (Active) │ │ (Deleted) │ └────────────────┘ └────────────────┘ │ ┌───────┴───────┐ │ │ 流量用完 有效期过期 │ │ ↓ ↓ ┌────────────────┐ ┌────────────────┐ │ 2-已用完 │ │ 3-已过期 │ │ (Depleted) │ │ (Expired) │ └────────────────┘ └────────────────┘ │ │ └───────┬───────┘ │ (仅加油包) 主套餐过期 │ ↓ ┌────────────────┐ │ 4-已失效 │ │ (Invalidated) │ └────────────────┘ ``` **状态说明**: - **0-待生效**: 套餐已购买但未激活（等待首次实名或主套餐排队） - **1-生效中**: 套餐正在生效，流量可用 - **2-已用完**: 流量已耗尽但未过期（可续费加油包） - **3-已过期**: 有效期已过（主套餐过期触发下一个激活） - **4-已失效**: 加油包跟随主套餐失效（仅加油包） **不可逆性**: 状态转换是单向的，不支持反向转换（如已过期 → 生效中） --- ### 4. API 设计 #### 4.1 套餐管理 API 改造 **创建套餐 API** ```http POST /api/admin/packages Content-Type: application/json { "package_code": "PACKAGE-001", "package_name": "联通月卡30GB", "series_id": 1, "package_type": "formal", // 新增字段 "calendar_type": "natural_month", // 必填: natural_month | by_day "duration_months": 1, // calendar_type=natural_month 时必填 "duration_days": null, // calendar_type=by_day 时必填 "data_reset_cycle": "monthly", // 必填: daily | monthly | yearly | none "enable_realname_activation": true, // 可选，默认 false "real_data_mb": 30720, "virtual_data_mb": 0, "enable_virtual_data": false, "cost_price": 1500, "suggested_retail_price": 3000 } ``` **响应**: ```json { "code": 200, "msg": "success", "data": { "id": 123, "package_code": "PACKAGE-001", "calendar_type": "natural_month", "data_reset_cycle": "monthly", "enable_realname_activation": true, // ... 其他字段 } } ``` **更新套餐 API**: - 支持更新 `calendar_type`、`data_reset_cycle`、`enable_realname_activation` - `package_code` 不可修改 --- #### 4.2 客户视图流量查询 API（新增） ```http GET /api/h5/packages/my-usage Authorization: Bearer ``` **响应**: ```json { "code": 200, "msg": "success", "data": { "main_package": { "package_usage_id": 1, "package_name": "联通月卡30GB", "used_mb": 8192, "total_mb": 30720, "status": 1, "expires_at": "2026-02-28T23:59:59Z" }, "addon_packages": [ { "package_usage_id": 2, "package_name": "流量加油包10GB", "used_mb": 3072, "total_mb": 10240, "status": 1, "expires_at": "2026-02-28T23:59:59Z" }, { "package_usage_id": 3, "package_name": "流量加油包5GB", "used_mb": 1024, "total_mb": 5120, "status": 1, "expires_at": "2026-03-15T23:59:59Z" } ], "total": { "used_mb": 12288, "total_mb": 46080 } } } ``` **性能要求**: P95 < 200ms **查询逻辑**: 1. 根据 token 获取 `user_id` 和载体信息（`iot_card_id` 或 `device_id`） 2. 查询生效中或已用完的套餐（`WHERE status IN (1,2)`） 3. 区分主套餐（`master_usage_id IS NULL`）和加油包（`master_usage_id IS NOT NULL`） 4. 计算总计流量（主套餐 + 所有加油包） --- #### 4.3 套餐流量详单 API（新增） ```http GET /api/admin/package-usage/:id/daily-records?start_date=2026-02-01&end_date=2026-02-10 Authorization: Bearer ``` **响应**: ```json { "code": 200, "msg": "success", "data": { "package_usage_id": 1, "package_name": "联通月卡30GB", "records": [ { "date": "2026-02-01", "daily_usage_mb": 1024, "cumulative_usage_mb": 1024 }, { "date": "2026-02-02", "daily_usage_mb": 2048, "cumulative_usage_mb": 3072 } // ... ], "total_usage_mb": 3072 } } ``` **查询逻辑**: 1. 验证越权（使用 `middleware.CanManageShop` 或 `middleware.CanManageEnterprise`） 2. 查询日记录表（`WHERE package_usage_id=? AND date BETWEEN ? AND ?`） 3. 按 `date ASC` 排序 --- ### 5. 常量管理 在 `pkg/constants/constants.go` 新增以下常量: ```go // 套餐周期类型 const ( PackageCalendarTypeNaturalMonth = "natural_month" // 自然月 PackageCalendarTypeByDay = "by_day" // 按天 ) // 套餐流量重置周期 const ( PackageDataResetDaily = "daily" // 每日 PackageDataResetMonthly = "monthly" // 每月 PackageDataResetYearly = "yearly" // 每年 PackageDataResetNone = "none" // 不重置 ) // 套餐使用状态 const ( PackageUsageStatusPending = 0 // 待生效 PackageUsageStatusActive = 1 // 生效中 PackageUsageStatusDepleted = 2 // 已用完 PackageUsageStatusExpired = 3 // 已过期 PackageUsageStatusInvalidated = 4 // 已失效（加油包跟随主套餐） ) // 任务类型 const ( TaskTypePackageFirstActivation = "package:first_activation" // 首次实名激活 TaskTypePackageQueueActivation = "package:queue_activation" // 主套餐排队激活 TaskTypePackageDataReset = "package:data_reset" // 流量重置 ) // Redis 键函数 func RedisPackageActivationLockKey(usageID uint) string { return fmt.Sprintf("package:activation:lock:%d", usageID) } ``` --- ### 6. 依赖注入设计 #### 6.1 Store 层 ```go // internal/store/postgres/package.go type PackageStore struct { db *gorm.DB redis *redis.Client } func NewPackageStore(db *gorm.DB, redis *redis.Client) *PackageStore { return &PackageStore{db: db, redis: redis} } // internal/store/postgres/package_usage.go type PackageUsageStore struct { db *gorm.DB redis *redis.Client } func NewPackageUsageStore(db *gorm.DB, redis *redis.Client) *PackageUsageStore { return &PackageUsageStore{db: db, redis: redis} } // internal/store/postgres/package_usage_daily_record.go type PackageUsageDailyRecordStore struct { db *gorm.DB } func NewPackageUsageDailyRecordStore(db *gorm.DB) *PackageUsageDailyRecordStore { return &PackageUsageDailyRecordStore{db: db} } ``` #### 6.2 Service 层 ```go // internal/service/package/service.go type Service struct { packageStore *postgres.PackageStore packageUsageStore *postgres.PackageUsageStore packageSeriesStore *postgres.PackageSeriesStore logger *zap.Logger } func NewService( packageStore *postgres.PackageStore, packageUsageStore *postgres.PackageUsageStore, packageSeriesStore *postgres.PackageSeriesStore, logger *zap.Logger, ) *Service { return &Service{ packageStore: packageStore, packageUsageStore: packageUsageStore, packageSeriesStore: packageSeriesStore, logger: logger, } } // internal/service/order/service.go type Service struct { // ... 现有依赖 ... packageUsageStore *postgres.PackageUsageStore queueClient *asynq.Client } ``` #### 6.3 Handler 层 ```go // internal/handler/admin/package.go type PackageHandler struct { packageService *package_service.Service logger *zap.Logger } func NewPackageHandler( packageService *package_service.Service, logger *zap.Logger, ) *PackageHandler { return &PackageHandler{ packageService: packageService, logger: logger, } } // internal/handler/h5/package_usage.go（新增） type PackageUsageHandler struct { packageUsageService *package_service.Service logger *zap.Logger } func NewPackageUsageHandler( packageUsageService *package_service.Service, logger *zap.Logger, ) *PackageUsageHandler { return &PackageUsageHandler{ packageUsageService: packageUsageService, logger: logger, } } ``` --- ### 7. 事务处理设计 #### 7.1 主套餐排队激活事务 ```go func (s *Service) ActivateQueuedPackage(ctx context.Context, usageID uint) error { // 使用 Redis 分布式锁避免并发激活 lockKey := constants.RedisPackageActivationLockKey(usageID) lock := s.redis.SetNX(ctx, lockKey, 1, 30*time.Second) if !lock.Val() { return errors.New(errors.CodeConflict, "套餐正在激活中，请稍后重试") } defer s.redis.Del(ctx, lockKey) // 开启事务 return s.db.Transaction(func(tx *gorm.DB) error { // 1. 查询待激活套餐（加行锁） var usage model.PackageUsage err := tx.Where("id = ? AND status = ?", usageID, 0). Clauses(clause.Locking{Strength: "UPDATE"}). First(&usage).Error if err != nil { return errors.Wrap(errors.CodeNotFound, err, "套餐不存在或已激活") } // 2. 查询套餐配置 var pkg model.Package if err := tx.First(&pkg, usage.PackageID).Error; err != nil { return errors.Wrap(errors.CodeInternal, err, "查询套餐配置失败") } // 3. 计算激活时间和过期时间 activatedAt := time.Now() expiresAt := s.calculateExpiryTime(activatedAt, pkg.CalendarType, pkg.DurationMonths, pkg.DurationDays) // 4. 更新 PackageUsage err = tx.Model(&usage).Updates(map[string]interface{}{ "status": 1, "activated_at": activatedAt, "expires_at": expiresAt, }).Error if err != nil { return errors.Wrap(errors.CodeInternal, err, "更新套餐状态失败") } // 5. 记录操作日志 s.logger.Info("主套餐排队激活成功", zap.Uint("usage_id", usageID), zap.Time("activated_at", activatedAt), zap.Time("expires_at", expiresAt)) return nil }) } ``` #### 7.2 加油包级联失效事务 ```go func (s *Service) CascadeInvalidateAddons(ctx context.Context, masterUsageID uint) error { return s.db.Transaction(func(tx *gorm.DB) error { // 1. 查询主套餐下的所有加油包 var addons []*model.PackageUsage err := tx.Where("master_usage_id = ? AND status IN (1,2)", masterUsageID). Find(&addons).Error if err != nil { return errors.Wrap(errors.CodeInternal, err, "查询加油包失败") } if len(addons) == 0 { return nil // 无加油包，直接返回 } // 2. 批量更新加油包状态为"已失效" addonIDs := make([]uint, len(addons)) for i, addon := range addons { addonIDs[i] = addon.ID } err = tx.Model(&model.PackageUsage{}). Where("id IN ?", addonIDs). Update("status", 4).Error if err != nil { return errors.Wrap(errors.CodeInternal, err, "更新加油包状态失败") } // 3. 记录操作日志 s.logger.Info("加油包级联失效完成", zap.Uint("master_usage_id", masterUsageID), zap.Int("invalidated_count", len(addons))) return nil }) } ``` --- ## 现有代码修正清单 本章节列出套餐系统升级中需要修改的现有代码缺陷和不兼容逻辑。 ### 1. 数据重置日期计算逻辑修正 **文件位置**: `internal/service/iot_card/traffic_utils.go` 或类似文件（需确认实际位置） **问题描述**: - 当前代码硬编码按自然月重置（每月1号） - 不支持 `by_day` 类型（购买日周期） - 不支持联通卡特殊规则（27号重置） **修改方案**: ```go // 旧代码（需删除或重构） func calculateResetDate(activatedAt time.Time) time.Time { return time.Date(activatedAt.Year(), activatedAt.Month()+1, 1, 0, 0, 0, 0, time.UTC) } // 新代码（支持多种重置周期） func calculateResetDate(pkg *model.Package, activatedAt time.Time, carrierID int) time.Time { switch pkg.DataResetCycle { case constants.PackageDataResetDaily: // 每日：明天 00:00:00 return time.Date(activatedAt.Year(), activatedAt.Month(), activatedAt.Day()+1, 0, 0, 0, 0, time.UTC) case constants.PackageDataResetMonthly: // 每月：根据运营商确定计费日 billingDay := 1 if carrierID == constants.CarrierCUCC { // 联通 billingDay = 27 } // 计算下个计费日 year, month := activatedAt.Year(), activatedAt.Month()+1 if month > 12 { year++ month = 1 } // 处理月末边界（如31号在2月不存在） lastDayOfMonth := time.Date(year, month+1, 0, 0, 0, 0, 0, time.UTC).Day() if billingDay > lastDayOfMonth { billingDay = lastDayOfMonth } return time.Date(year, month, billingDay, 0, 0, 0, 0, time.UTC) case constants.PackageDataResetYearly: // 每年：明年 1月1日 00:00:00 return time.Date(activatedAt.Year()+1, 1, 1, 0, 0, 0, 0, time.UTC) case constants.PackageDataResetNone: // 不重置 return time.Time{} default: // 默认按月 return time.Date(activatedAt.Year(), activatedAt.Month()+1, 1, 0, 0, 0, 0, time.UTC) } } ``` **影响范围**: - 订单服务创建套餐时计算 `next_reset_at` - 轮询系统流量重置调度 - 单元测试需新增联通卡、按天套餐测试用例 --- ### 2. 流量扣减逻辑重构 **文件位置**: `internal/handler/worker/iot_card_traffic.go` 或 `internal/service/iot_card/traffic_deduction.go` **问题描述**: - 当前按套餐激活顺序扣减 - 不支持"加油包优先"规则 - 未区分主套餐和加油包 **修改方案**: ```go // 旧代码（需删除） func (s *Service) DeductTraffic(ctx context.Context, cardID uint, increment int64) error { // 查询生效套餐，按 activated_at ASC 排序 packages := s.store.GetActivePackages(cardID) // 问题：不区分主套餐和加油包 for _, pkg := range packages { // 按激活时间顺序扣减（错误逻辑） ... } } // 新代码（支持优先级扣减） func (s *Service) DeductTraffic(ctx context.Context, cardID uint, increment int64) error { // 1. 查询卡的所有生效套餐 packages, err := s.store.GetActivePackagesByPriority(ctx, cardID) if err != nil { return errors.Wrap(errors.CodeInternal, err, "查询生效套餐失败") } // 2. 按优先级排序（加油包优先，再按 priority ASC, expires_at ASC, activated_at ASC） // Store 层已排序，此处直接使用 // 3. 依次扣减 remainingIncrement := increment for _, pkg := range packages { if remainingIncrement <= 0 { break } availableData := pkg.DataLimitMB - pkg.DataUsageMB if availableData <= 0 { continue // 已用完，跳过 } deductAmount := min(remainingIncrement, availableData) // 更新套餐用量 err := s.store.UpdateDataUsage(ctx, pkg.ID, deductAmount) if err != nil { return errors.Wrap(errors.CodeInternal, err, "更新套餐用量失败") } // 记录日记录 err = s.recordDailyUsage(ctx, pkg.ID, deductAmount) if err != nil { // 日记录失败不影响扣减（仅记录日志） s.logger.Error("记录日用量失败", zap.Error(err)) } remainingIncrement -= deductAmount // 检查套餐是否用完 if pkg.DataUsageMB+deductAmount >= pkg.DataLimitMB { err := s.store.UpdatePackageStatus(ctx, pkg.ID, constants.PackageUsageStatusDepleted) if err != nil { s.logger.Error("更新套餐状态失败", zap.Error(err)) } } } // 4. 检查停机条件 if remainingIncrement > 0 || s.shouldStopCard(ctx, cardID) { return s.stopCard(ctx, cardID) } return nil } // Store 层查询方法（新增） func (s *Store) GetActivePackagesByPriority(ctx context.Context, cardID uint) ([]*model.PackageUsage, error) { var packages []*model.PackageUsage err := s.db.WithContext(ctx). Where("iot_card_id = ? AND status = ?", cardID, constants.PackageUsageStatusActive). Order("(master_usage_id IS NOT NULL) DESC, priority ASC, expires_at ASC, activated_at ASC"). Find(&packages).Error return packages, err } ``` **影响范围**: - 轮询系统流量检查任务 - Store 层新增 `GetActivePackagesByPriority` 方法 - 单元测试需覆盖多加油包扣减场景 --- ### 3. 轮询系统套餐激活入口 **文件位置**: `internal/handler/worker/iot_card_polling.go` **问题描述**: - 当前轮询仅处理卡状态同步 - 不处理待激活套餐队列 - 不处理主套餐过期检测 **修改方案**: ```go // 旧代码 func (h *Handler) HandleIotCardPolling(ctx context.Context, task *asynq.Task) error { // 解析任务参数 var payload IotCardPollingPayload if err := json.Unmarshal(task.Payload(), &payload); err != nil { return err } // 1. 同步卡状态 err := h.syncCardStatus(ctx, payload.CardID) if err != nil { return err } // 2. 同步流量 err = h.syncCardTraffic(ctx, payload.CardID) if err != nil { return err } // 3. 同步费用 err = h.syncCardBalance(ctx, payload.CardID) if err != nil { return err } return nil // 缺少套餐激活检查 } // 新代码（增加套餐激活检查） func (h *Handler) HandleIotCardPolling(ctx context.Context, task *asynq.Task) error { // ... 现有逻辑：同步卡状态、流量、费用 // 4. 新增：检查并激活排队套餐 card, err := h.iotCardStore.GetByID(ctx, payload.CardID) if err != nil { return err } if card.Status == constants.IotCardStatusActive { // 检查是否有待激活套餐 err := h.packageActivationService.CheckAndActivateQueuedPackages(ctx, card.ID) if err != nil { // 不中断轮询，记录日志继续 h.logger.Error("激活排队套餐失败", zap.Uint("card_id", card.ID), zap.Error(err)) } } // 5. 新增：检查主套餐是否过期 err = h.packageActivationService.CheckExpiredPackages(ctx, card.ID) if err != nil { h.logger.Error("检查过期套餐失败", zap.Uint("card_id", card.ID), zap.Error(err)) } return nil } ``` **影响范围**: - 轮询系统 Handler 层 - 新增 `PackageActivationService` 依赖注入 - 集成测试需验证完整轮询流程 --- ### 4. 加油包过期级联处理 **位置**: 新增功能，无现有代码需修改 **说明**: - 当前系统无加油包概念，这是全新功能 - 需在套餐过期处理流程中增加级联失效逻辑 - 详见 `addon-package-lifecycle/spec.md` **新增代码位置**: - `internal/service/package/lifecycle_service.go`（新建） - `internal/handler/worker/package_expiry.go`（新建或扩展） **核心逻辑**: ```go func (s *Service) HandleMainPackageExpiry(ctx context.Context, mainPackageID uint) error { tx := s.db.BeginTx(ctx) defer tx.Rollback() // 1. 更新主套餐状态为已过期 err := s.store.UpdatePackageStatus(ctx, tx, mainPackageID, constants.PackageUsageStatusExpired) if err != nil { return err } // 2. 查询关联的加油包 addons, err := s.store.GetAddonsByMasterID(ctx, mainPackageID) if err != nil { return err } // 3. 批量级联失效加油包 if len(addons) > 0 { addonIDs := extractIDs(addons) err = s.store.BatchUpdateStatus(ctx, tx, addonIDs, constants.PackageUsageStatusInvalidated) if err != nil { return err } } // 4. 提交事务 if err := tx.Commit().Error; err != nil { return err } // 5. 记录审计日志 s.auditService.LogOperation(ctx, &model.OperationLog{ OperationType: "cascade_invalidate", OperationDesc: fmt.Sprintf("主套餐ID=%d过期，级联失效%d个加油包", mainPackageID, len(addons)), }) return nil } ``` --- ### 5. 停机条件更新 **文件位置**: `internal/service/iot_card/stop_service.go` 或类似文件 **问题描述**: - 旧逻辑：单一套餐流量用完即停机 - 新逻辑：主套餐 + 所有加油包流量全部用完才停机 **修改方案**: ```go // 旧代码（需删除） func (s *Service) CheckStopCondition(ctx context.Context, cardID uint) (bool, error) { // 查询生效中套餐 pkg, err := s.store.GetActiveMainPackage(ctx, cardID) if err != nil { return false, err } // 旧逻辑：主套餐用完即停机（错误） if pkg.DataUsageMB >= pkg.DataLimitMB { return true, nil } return false, nil } // 新代码（检查所有套餐） func (s *Service) CheckStopCondition(ctx context.Context, cardID uint) (bool, error) { // 查询所有生效中的套餐（包括主套餐和加油包） count, err := s.store.CountAvailablePackages(ctx, cardID) if err != nil { return false, err } // 新逻辑：所有套餐都用完才停机 return count == 0, nil } // Store 层查询方法（新增） func (s *Store) CountAvailablePackages(ctx context.Context, cardID uint) (int64, error) { var count int64 err := s.db.WithContext(ctx). Model(&model.PackageUsage{}). Where("iot_card_id = ? AND status = ? AND data_usage_mb < data_limit_mb", cardID, constants.PackageUsageStatusActive). Count(&count).Error return count, err } ``` **影响范围**: - 轮询系统流量检查后的停机判断 - 单元测试需覆盖"加油包剩余流量不停机"场景 --- ## Risks / Trade-offs ### 1. [性能] 套餐激活调度频率 vs 激活延迟 **Risk**: - 调度间隔 10 秒，最差情况下主套餐过期后 20 秒内激活下一个 - 如果同时有大量套餐过期，可能出现队列堆积 **Mitigation**: - 调度间隔可配置（默认 10 秒），支持运行时调整 - 套餐激活任务使用独立队列（优先级高于其他任务） - 监控 Asynq 队列长度和处理延迟，告警阈值设置为 1 分钟 --- ### 2. [复杂度] 流量扣减优先级逻辑的边界条件 **Risk**: - 多个加油包 + 主套餐的流量扣减逻辑复杂，容易出现边界问题（如负数流量、扣减不完全） - 并发场景下可能出现流量扣减不一致 **Mitigation**: - 流量扣减使用数据库事务 + 行锁（`SELECT FOR UPDATE`） - 单元测试覆盖所有边界条件： - 流量刚好用完 - 流量超出剩余额度 - 多个加油包同时用完 - 主套餐和加油包同时用完 - 代码层面强制约束 `data_usage_mb >= 0` --- ### 3. [迁移] 历史数据兼容性 **Risk**: - 现有 `PackageUsage` 数据没有 `priority`、`master_usage_id` 等新字段 - 现有套餐没有 `calendar_type`、`data_reset_cycle` 字段 **Mitigation**: - 数据库迁移脚本为新字段设置默认值： - `Package.calendar_type` 默认 `by_day` - `Package.data_reset_cycle` 默认 `none` - `PackageUsage.priority` 默认 `1`（历史主套餐） - `PackageUsage.master_usage_id` 默认 `NULL`（历史主套餐） - 迁移后运行数据校验脚本，确保历史数据一致性 --- ### 4. [兼容性] 客户端未实名购买限制 **Risk**: - 现有 H5 端允许未实名客户购买套餐，新限制可能导致用户体验下降 **Mitigation**: - 前端在购买按钮前置提示"请先完成实名认证" - API 返回清晰的错误消息："设备/卡必须先完成实名认证才能购买套餐" - 后台管理端不受限制，代理商可为未实名设备囤货 --- ### 5. [数据一致性] 流量重置可能丢失部分流量记录 **Risk**: - 流量重置时 `data_usage_mb=0`，如果在重置前有流量增量未记录到日记录表，会导致数据丢失 **Mitigation**: - 流量重置前先触发一次流量检查，确保最新流量已记录 - 流量重置和流量检查不在同一事务中，避免长事务 - 监控流量重置任务的执行日志，告警异常情况 --- ## Migration Plan ### 阶段 1: 数据库迁移 1. **创建迁移脚本**: ```bash make create-migration name=package_system_upgrade ``` 2. **迁移内容**: - 修改 `tb_package` 表（新增 3 个字段） - 修改 `tb_package_usage` 表（扩展 status 枚举，新增 7 个字段） - 创建 `tb_package_usage_daily_record` 表 - 创建索引（priority, master_usage_id, package_usage_id+date） 3. **回滚策略**: - 删除新增表 `tb_package_usage_daily_record` - 删除新增字段（使用 `ALTER TABLE DROP COLUMN`） - 注意：状态枚举扩展无法回滚（已写入的 status=0/4 数据会保留） --- ### 阶段 2: 代码实施 1. **Model 层**: - 扩展 `Package` 和 `PackageUsage` 模型 - 创建 `PackageUsageDailyRecord` 模型 2. **Store 层**: - 扩展 `PackageStore` 和 `PackageUsageStore` 查询方法 - 创建 `PackageUsageDailyRecordStore` 3. **Service 层**: - 扩展 `package.Service` 支持新字段 - 改造 `order.Service` 的 `activatePackage` 函数（主套餐排队、加油包限制） - 创建套餐激活 Service（首次实名激活、排队激活） 4. **Handler 层**: - 改造 `admin.PackageHandler` 支持新字段 - 创建 `h5.PackageUsageHandler` 提供客户视图 API 5. **轮询系统**: - 扩展 `HandleCarddataCheck` 支持流量扣减优先级和停机条件 - 创建 `HandlePackageActivation` 套餐激活检查任务 - 创建 `HandleDataReset` 流量重置调度任务 6. **Asynq Handler**: - 创建 `HandlePackageFirstActivation` 首次实名激活任务 - 创建 `HandlePackageQueueActivation` 主套餐排队激活任务 --- ### 阶段 3: 测试和验证 1. **单元测试**: - 套餐有效期计算逻辑（自然月 vs 按天） - 流量扣减优先级逻辑（边界条件） - 流量重置时间计算（联通27号 vs 其他1号） 2. **集成测试**: - 首次实名激活流程（囤货 → 实名 → 激活） - 主套餐排队流程（购买 → 排队 → 过期 → 激活） - 加油包生命周期（购买 → 主套餐过期 → 加油包失效） - 流量扣减和停机（加油包优先 → 主套餐 → 停机） 3. **性能测试**: - 套餐激活延迟（目标 < 1 分钟） - 客户视图 API 性能（P95 < 200ms） - 轮询系统千万级卡规模支持不退化 --- ### 阶段 4: 部署和回滚策略 1. **灰度发布**: - 先在测试环境部署，完整验证所有流程 - 生产环境先部署代码（特性开关关闭） - 执行数据库迁移 - 开启特性开关，观察日志和监控 2. **回滚策略**: - **代码回滚**: 关闭特性开关 → 回滚代码 - **数据库回滚**: 执行回滚迁移脚本（注意状态枚举扩展无法回滚） - **数据修复**: 如有脏数据（status=0/4），手动修正或保留（不影响现有功能） 3. **监控指标**: - Asynq 任务队列长度和处理延迟 - 套餐激活延迟（从过期到激活的时间） - API 响应时间（客户视图 API P95） - 流量扣减错误率（日志错误数） --- ## Open Questions 1. **加油包优先级分配策略**：是否需要支持手动调整加油包的扣减顺序？还是严格按购买顺序（priority）？ - **当前决策**: 严格按 priority（购买顺序），不支持手动调整 - **未来扩展**: 可考虑在 API 中支持更新 priority（需要验证业务必要性） 2. **流量重置时的日记录处理**：流量重置后，是否需要在日记录表中新增一条"重置记录"（daily_usage_mb=0）？ - **当前决策**: 不新增重置记录，日记录只记录实际流量增量 - **原因**: 避免日记录表膨胀，重置信息可从 `PackageUsage.last_reset_at` 获取 3. **客户端实名校验的异常场景**：如果用户在支付成功后、订单完成前完成实名，是否允许购买？ - **当前决策**: 订单创建时检查实名状态，支付完成后不再检查 - **原因**: 简化逻辑，避免状态不一致（支付成功但订单失败） 4. **套餐激活失败的重试策略**：如果 Asynq 任务重试 3 次后仍失败，套餐是否永久停留在"待生效"状态？ - **当前决策**: 是，需要人工介入修复 - **监控**: 告警通知 + 日志记录，运营团队定期检查 5. **历史套餐的 data_reset_cycle 默认值**：现有套餐迁移后 `data_reset_cycle=none`，如需调整为 `monthly`，是否需要批量更新？ - **当前决策**: 不批量更新，仅对新套餐生效 - **原因**: 避免影响历史套餐的流量统计（用户预期不重置）