feat: 套餐系统升级 - Worker 重构、流量重置、文档与规范更新
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m54s
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m54s
- 重构 Worker 启动流程，引入 bootstrap 模块统一管理依赖注入 - 实现套餐流量重置服务（日/月/年周期重置） - 新增套餐激活排队、加油包绑定、囤货待实名激活逻辑 - 新增订单创建幂等性防重（Redis 业务键 + 分布式锁） - 更新 AGENTS.md/CLAUDE.md：新增注释规范、幂等性规范，移除测试要求 - 添加套餐系统升级完整文档（API文档、使用指南、功能总结、运维指南） - 归档 OpenSpec package-system-upgrade 变更，同步 specs 到主目录 - 新增 queue types 抽象和 Redis 常量定义
This commit is contained in:
@@ -234,20 +234,20 @@
|
||||
|
||||
## 26. 最终检查
|
||||
|
||||
- [ ] 26.1 运行 lsp_diagnostics，确认无编译错误和类型错误
|
||||
- [ ] 26.2 生成 OpenAPI 文档，确认新 API 出现在文档中
|
||||
- [ ] 26.3 代码审查（检查是否遵循分层架构、Go 惯用法、性能要求）
|
||||
- [x] 26.1 运行 lsp_diagnostics，确认无编译错误和类型错误
|
||||
- [x] 26.2 生成 OpenAPI 文档，确认新 API 出现在文档中
|
||||
- [x] 26.3 代码审查（检查是否遵循分层架构、Go 惯用法、性能要求）
|
||||
|
||||
## 27. 文档更新
|
||||
|
||||
- [ ] 27.1 更新 README.md（新增套餐系统升级功能说明）
|
||||
- [ ] 27.2 在 docs/package-system-upgrade/ 创建功能总结文档
|
||||
- [ ] 27.3 编写套餐系统升级用户指南（囤货、排队、加油包、流量查询）
|
||||
- [ ] 27.4 更新 API 文档（新增 API 端点和字段说明）
|
||||
- [x] 27.1 更新 README.md（新增套餐系统升级功能说明）
|
||||
- [x] 27.2 在 docs/package-system-upgrade/ 创建功能总结文档
|
||||
- [x] 27.3 编写套餐系统升级用户指南（囤货、排队、加油包、流量查询）
|
||||
- [x] 27.4 更新 API 文档（新增 API 端点和字段说明）
|
||||
|
||||
## 28. 部署准备
|
||||
|
||||
- [ ] 28.1 编写数据库迁移回滚脚本
|
||||
- [ ] 28.2 配置监控指标（Asynq 队列长度、套餐激活延迟、API 响应时间）
|
||||
- [ ] 28.3 配置告警规则（套餐激活延迟 > 1 分钟、队列堆积 > 1000 个任务）
|
||||
- [ ] 28.4 编写回滚预案（代码回滚、数据库回滚、数据修复脚本）
|
||||
- [x] 28.1 编写数据库迁移回滚脚本
|
||||
- [x] 28.2 配置监控指标（Asynq 队列长度、套餐激活延迟、API 响应时间）
|
||||
- [x] 28.3 配置告警规则（套餐激活延迟 > 1 分钟、队列堆积 > 1000 个任务）
|
||||
- [x] 28.4 编写回滚预案（代码回滚、数据库回滚、数据修复脚本）
|
||||
753
openspec/specs/addon-package-lifecycle/spec.md
Normal file
753
openspec/specs/addon-package-lifecycle/spec.md
Normal file
@@ -0,0 +1,753 @@
|
||||
# Spec: 加油包生命周期管理
|
||||
|
||||
## 业务背景
|
||||
|
||||
### 为什么需要加油包生命周期管理
|
||||
|
||||
**现状问题**：
|
||||
- 加油包与主套餐无明确关联，导致主套餐过期后加油包仍可使用（业务逻辑混乱）
|
||||
- 加油包有效期管理不清晰，无法区分"独立有效期"和"跟随主套餐"两种模式
|
||||
- 主套餐切换时，旧加油包是否继承到新主套餐无明确规则
|
||||
- 用户购买加油包时无主套餐检查，可能导致加油包无法使用
|
||||
|
||||
**业务目标**：
|
||||
- 加油包必须依附于主套餐才能购买和使用
|
||||
- 主套餐过期时，其关联的加油包自动失效（级联失效）
|
||||
- 支持两种有效期模式：独立有效期（固定时长）和跟随主套餐（与主套餐同时到期）
|
||||
- 主套餐切换时，旧加油包不继承到新主套餐（用户需重新购买）
|
||||
|
||||
---
|
||||
|
||||
## 业务规则
|
||||
|
||||
### 1. 依附规则
|
||||
|
||||
加油包必须在有主套餐的情况下才能购买：
|
||||
|
||||
```
|
||||
购买加油包前置检查：
|
||||
1. 查询载体当前是否有主套餐（package_type=formal AND status IN (0待生效, 1生效中)）
|
||||
2. 如果无主套餐 → 返回错误 400："必须有主套餐才能购买加油包"
|
||||
3. 如果有主套餐 → 允许购买
|
||||
```
|
||||
|
||||
### 2. 关联规则
|
||||
|
||||
加油包创建时自动关联到当前生效中的主套餐：
|
||||
|
||||
```
|
||||
确定 master_usage_id 的逻辑：
|
||||
1. 查询载体当前生效中的主套餐（package_type=formal AND status=1）
|
||||
2. 如果有生效中主套餐 → master_usage_id = 该主套餐ID
|
||||
3. 如果无生效中主套餐，但有待生效主套餐（status=0）→ master_usage_id = priority 最小的待生效主套餐ID
|
||||
4. 创建 PackageUsage 记录：
|
||||
- package_type = addon
|
||||
- master_usage_id = 上述确定的主套餐ID
|
||||
- status = 0（待生效）
|
||||
- has_independent_expiry = 根据套餐配置
|
||||
```
|
||||
|
||||
### 3. 有效期模式
|
||||
|
||||
加油包支持两种有效期模式：
|
||||
|
||||
| 模式 | has_independent_expiry | 计算规则 | 过期条件 |
|
||||
|------|------------------------|----------|----------|
|
||||
| **独立有效期** | true | `expires_at = activated_at + duration_days` | 自身到期时间到达 |
|
||||
| **跟随主套餐** | false | `expires_at = master套餐.expires_at` | 主套餐到期时间到达 |
|
||||
|
||||
**独立有效期加油包**：
|
||||
- 激活时计算自己的 `expires_at`
|
||||
- 可能在主套餐之前过期
|
||||
- 到期后 `status=3`（已过期）
|
||||
|
||||
**跟随主套餐加油包**：
|
||||
- 激活时 `expires_at = master套餐.expires_at`
|
||||
- 主套餐 `expires_at` 更新时，同步更新所有跟随的加油包
|
||||
- 与主套餐同时到期
|
||||
|
||||
### 4. 级联失效规则
|
||||
|
||||
主套餐过期时，级联失效其所有关联的加油包：
|
||||
|
||||
```
|
||||
主套餐过期触发级联失效：
|
||||
1. 主套餐 status 变为 3（已过期）时触发
|
||||
2. 查询所有 master_usage_id = 主套餐ID 的加油包
|
||||
3. 批量更新这些加油包 status = 4（已失效）
|
||||
4. 不管加油包是否有独立有效期、是否已用完
|
||||
5. 记录级联失效日志
|
||||
```
|
||||
|
||||
**失效状态说明**：
|
||||
- `status=3`（已过期）：自身有效期到达
|
||||
- `status=4`（已失效）：主套餐过期导致的级联失效
|
||||
|
||||
### 5. 不继承规则
|
||||
|
||||
旧主套餐过期后，其加油包不继承到新主套餐：
|
||||
|
||||
```
|
||||
新主套餐激活时：
|
||||
1. 不更新旧加油包的 master_usage_id
|
||||
2. 旧加油包保持 status=4（已失效）
|
||||
3. 用户需为新主套餐重新购买加油包
|
||||
4. 新加油包 master_usage_id = 新主套餐ID
|
||||
```
|
||||
|
||||
### 6. 订单购买限制
|
||||
|
||||
**同订单禁止混买正式套餐和加油包**：
|
||||
|
||||
```
|
||||
订单创建校验规则：
|
||||
1. 检查订单项中是否同时包含 package_type=formal 和 package_type=addon
|
||||
2. 如果混买 → 返回错误 400："同订单不能同时购买正式套餐和加油包"
|
||||
3. 原因：加油包依赖主套餐激活，订单处理时序无法保证主套餐先激活
|
||||
4. 解决方案：前端购物车分类展示，提示用户分两单购买
|
||||
```
|
||||
|
||||
**技术实现**：
|
||||
```go
|
||||
// 订单创建时校验
|
||||
func (s *OrderService) ValidateOrderItems(items []*OrderItem) error {
|
||||
hasMainPackage := false
|
||||
hasAddonPackage := false
|
||||
|
||||
for _, item := range items {
|
||||
pkg, err := s.packageStore.GetByID(item.PackageID)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
if pkg.PackageType == constants.PackageTypeFormal {
|
||||
hasMainPackage = true
|
||||
} else if pkg.PackageType == constants.PackageTypeAddon {
|
||||
hasAddonPackage = true
|
||||
}
|
||||
}
|
||||
|
||||
if hasMainPackage && hasAddonPackage {
|
||||
return errors.New(errors.CodeInvalidParam, "同订单不能同时购买正式套餐和加油包")
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 加油包必须依附于主套餐
|
||||
|
||||
系统 SHALL 禁止在无主套餐（无 package_type=formal status=1 或 status=0 的套餐）时购买加油包。
|
||||
|
||||
#### Scenario: 无主套餐时购买加油包失败
|
||||
- **GIVEN** 载体 ICCID=123456，无任何主套餐（无 package_type=formal status IN (0,1)）
|
||||
- **WHEN** 用户尝试购买加油包（package_type=addon）
|
||||
- **THEN** 系统返回错误 400，错误码 `ADDON_REQUIRES_MASTER`，错误消息："必须有主套餐才能购买加油包"
|
||||
|
||||
#### Scenario: 有主套餐时可购买加油包
|
||||
- **GIVEN** 载体有生效中主套餐（ID=123, status=1）
|
||||
- **WHEN** 用户购买加油包（package_id=456）
|
||||
- **THEN** 系统创建订单成功，PackageUsage master_usage_id=123, package_type=addon, status=0
|
||||
|
||||
#### Scenario: 只有待生效主套餐时可购买加油包
|
||||
- **GIVEN** 载体有待生效主套餐（ID=123, status=0, priority=1）
|
||||
- **WHEN** 用户购买加油包
|
||||
- **THEN** 系统创建订单成功，加油包 master_usage_id=123
|
||||
|
||||
### Requirement: 加油包关联主套餐
|
||||
|
||||
系统 SHALL 在创建加油包使用记录时，将其 master_usage_id 设置为当前生效中或最高优先级待生效的主套餐ID。
|
||||
|
||||
#### Scenario: 加油包关联当前生效中主套餐
|
||||
- **GIVEN** 载体有生效中主套餐（ID=123, status=1）
|
||||
- **WHEN** 用户购买加油包
|
||||
- **THEN** 系统创建 PackageUsage：
|
||||
- master_usage_id=123
|
||||
- package_type=addon
|
||||
- status=0
|
||||
|
||||
#### Scenario: 多个主套餐时关联生效中的主套餐
|
||||
- **GIVEN** 载体有：
|
||||
- 生效中主套餐（ID=123, status=1, priority=1）
|
||||
- 待生效主套餐（ID=124, status=0, priority=2）
|
||||
- 待生效主套餐（ID=125, status=0, priority=3）
|
||||
- **WHEN** 用户购买加油包
|
||||
- **THEN** 加油包 master_usage_id=123（优先关联生效中的主套餐）
|
||||
|
||||
#### Scenario: 只有待生效主套餐时关联优先级最高的
|
||||
- **GIVEN** 载体有：
|
||||
- 待生效主套餐（ID=124, status=0, priority=1）
|
||||
- 待生效主套餐（ID=125, status=0, priority=2）
|
||||
- **WHEN** 用户购买加油包
|
||||
- **THEN** 加油包 master_usage_id=124（priority=1 最高）
|
||||
|
||||
### Requirement: 支持独立有效期加油包
|
||||
|
||||
系统 SHALL 支持加油包配置 has_independent_expiry=true，拥有独立的有效期。
|
||||
|
||||
#### Scenario: 独立有效期加油包激活时计算过期时间
|
||||
- **GIVEN** 加油包 has_independent_expiry=true，duration_days=30
|
||||
- **WHEN** 加油包在 2026-02-01 00:00:00 激活
|
||||
- **THEN** 系统计算 expires_at=2026-03-02 23:59:59（+30天）
|
||||
|
||||
#### Scenario: 独立有效期加油包过期
|
||||
- **GIVEN** 加油包 has_independent_expiry=true，expires_at=2026-02-28 23:59:59，data_usage_mb=50（未用完）
|
||||
- **WHEN** 系统时间到达 2026-03-01 00:00:00
|
||||
- **THEN** 定时任务将加油包 status 更新为 3（已过期）
|
||||
|
||||
#### Scenario: 独立有效期加油包在主套餐有效期内过期
|
||||
- **GIVEN** 主套餐有效期到 2026-12-31 23:59:59
|
||||
- **AND** 加油包 has_independent_expiry=true，expires_at=2026-03-31 23:59:59
|
||||
- **WHEN** 系统时间到达 2026-04-01 00:00:00
|
||||
- **THEN** 加油包 status=3（已过期），主套餐仍为 status=1（生效中）
|
||||
|
||||
#### Scenario: 独立有效期加油包在主套餐过期后仍失效
|
||||
- **GIVEN** 加油包 has_independent_expiry=true，expires_at=2026-12-31 23:59:59（未到期）
|
||||
- **AND** 主套餐 expires_at=2026-11-30 23:59:59
|
||||
- **WHEN** 主套餐在 2026-12-01 00:00:00 过期（status=3）
|
||||
- **THEN** 加油包被级联失效（status=4），不管自身 expires_at
|
||||
|
||||
### Requirement: 支持跟随主套餐的加油包
|
||||
|
||||
系统 SHALL 支持加油包配置 has_independent_expiry=false，跟随主套餐有效期。
|
||||
|
||||
#### Scenario: 跟随主套餐的加油包激活时同步到期时间
|
||||
- **GIVEN** 加油包 has_independent_expiry=false，master 主套餐 expires_at=2026-12-31 23:59:59
|
||||
- **WHEN** 加油包在 2026-02-01 00:00:00 激活
|
||||
- **THEN** 系统设置加油包 expires_at=2026-12-31 23:59:59（与主套餐相同）
|
||||
|
||||
#### Scenario: 主套餐更新有效期时同步加油包
|
||||
- **GIVEN** 主套餐 ID=123，expires_at=2026-12-31 23:59:59
|
||||
- **AND** 有3个加油包 master_usage_id=123，has_independent_expiry=false
|
||||
- **WHEN** 主套餐 expires_at 被更新为 2027-01-31 23:59:59
|
||||
- **THEN** 系统批量更新这3个加油包 expires_at=2027-01-31 23:59:59
|
||||
|
||||
#### Scenario: 主套餐有效期更新时不影响独立有效期加油包
|
||||
- **GIVEN** 主套餐 ID=123，expires_at=2026-12-31 23:59:59
|
||||
- **AND** 加油包A：has_independent_expiry=true，expires_at=2026-06-30 23:59:59
|
||||
- **AND** 加油包B：has_independent_expiry=false，expires_at=2026-12-31 23:59:59
|
||||
- **WHEN** 主套餐 expires_at 更新为 2027-01-31 23:59:59
|
||||
- **THEN** 加油包A expires_at 保持 2026-06-30 23:59:59（不变）
|
||||
- **AND** 加油包B expires_at 更新为 2027-01-31 23:59:59
|
||||
|
||||
#### Scenario: 跟随主套餐的加油包与主套餐同时过期
|
||||
- **GIVEN** 主套餐 expires_at=2026-12-31 23:59:59
|
||||
- **AND** 加油包 has_independent_expiry=false，expires_at=2026-12-31 23:59:59
|
||||
- **WHEN** 系统时间到达 2027-01-01 00:00:00
|
||||
- **THEN** 定时任务将主套餐和加油包 status 都更新为 3（已过期）
|
||||
|
||||
### Requirement: 主套餐过期时级联失效加油包
|
||||
|
||||
系统 SHALL 在主套餐过期（status 变为 3）时，将其所有关联加油包的 status 设置为 4（已失效）。
|
||||
|
||||
#### Scenario: 主套餐过期触发加油包失效
|
||||
- **GIVEN** 主套餐 ID=123，expires_at=2026-12-31 23:59:59
|
||||
- **AND** 有3个加油包 master_usage_id=123：
|
||||
- 加油包A：data_usage_mb=50（未用完）
|
||||
- 加油包B：data_usage_mb=200（已用完）
|
||||
- 加油包C：has_independent_expiry=true，expires_at=2027-06-30（未到期）
|
||||
- **WHEN** 系统时间到达 2027-01-01 00:00:00，主套餐 status=3
|
||||
- **THEN** 系统批量更新这3个加油包 status=4（已失效）
|
||||
|
||||
#### Scenario: 独立有效期加油包也会级联失效
|
||||
- **GIVEN** 主套餐 expires_at=2026-11-30 23:59:59
|
||||
- **AND** 加油包 has_independent_expiry=true，expires_at=2026-12-31 23:59:59（晚于主套餐）
|
||||
- **WHEN** 主套餐在 2026-12-01 00:00:00 过期
|
||||
- **THEN** 加油包 status=4（已失效），不管自身还有30天才到期
|
||||
|
||||
#### Scenario: 已过期加油包不重复失效
|
||||
- **GIVEN** 主套餐 expires_at=2026-12-31 23:59:59
|
||||
- **AND** 加油包 has_independent_expiry=true，expires_at=2026-11-30 23:59:59，status=3（已过期）
|
||||
- **WHEN** 主套餐在 2027-01-01 00:00:00 过期
|
||||
- **THEN** 加油包 status 保持 3（已过期），不更新为 4
|
||||
|
||||
#### Scenario: 级联失效记录到审计日志
|
||||
- **GIVEN** 主套餐 ID=123 过期，有5个关联加油包
|
||||
- **WHEN** 系统执行级联失效
|
||||
- **THEN** 系统记录审计日志：
|
||||
- operation_type=cascade_invalidate
|
||||
- operation_desc="主套餐ID=123过期，级联失效5个加油包"
|
||||
- before_data=加油包列表及原状态
|
||||
- after_data=加油包列表及新状态（status=4）
|
||||
|
||||
### Requirement: 加油包不继承到新主套餐
|
||||
|
||||
系统 SHALL 确保旧主套餐过期后，其加油包不会自动关联到新激活的主套餐。
|
||||
|
||||
#### Scenario: 新主套餐激活后加油包不关联
|
||||
- **GIVEN** 主套餐A（ID=123）在 2026-12-31 过期，其加油包已失效（status=4）
|
||||
- **WHEN** 主套餐B（ID=124）在 2027-01-01 激活（priority=2 → status=1）
|
||||
- **THEN** 主套餐A的加油包 master_usage_id 保持 123，status 保持 4
|
||||
- **AND** 主套餐B 无关联加油包
|
||||
|
||||
#### Scenario: 用户需为新主套餐重新购买加油包
|
||||
- **GIVEN** 主套餐B（ID=124）刚激活（status=1）
|
||||
- **WHEN** 用户购买新加油包
|
||||
- **THEN** 新加油包 master_usage_id=124，status=0
|
||||
|
||||
#### Scenario: 旧加油包不可重新激活
|
||||
- **GIVEN** 主套餐A的加油包（ID=999）已失效（status=4）
|
||||
- **WHEN** 用户尝试手动激活这个加油包
|
||||
- **THEN** 系统返回错误 400，错误码 `ADDON_MASTER_EXPIRED`，错误消息："关联的主套餐已过期，无法激活加油包"
|
||||
|
||||
---
|
||||
|
||||
## 边界条件
|
||||
|
||||
### 1. 主套餐失效但加油包未用完
|
||||
|
||||
- **场景**：主套餐过期时，加油包流量只用了10%
|
||||
- **处理**：仍然级联失效（status=4），剩余流量不可用
|
||||
- **业务规则**：加油包依附于主套餐，主套餐失效则加油包失效
|
||||
|
||||
### 2. 多个主套餐同时存在
|
||||
|
||||
- **场景**：有1个生效中主套餐 + 2个待生效主套餐
|
||||
- **购买加油包时**：关联到生效中的主套餐
|
||||
- **主套餐A过期后**：加油包随A失效，不继承到主套餐B
|
||||
|
||||
### 3. 并发购买加油包
|
||||
|
||||
- **场景**：两个请求同时为同一载体购买加油包
|
||||
- **处理**：
|
||||
- 使用事务 + 行锁：`SELECT * FROM package_usage WHERE carrier_id=? AND package_type=formal AND status IN (0,1) ORDER BY status DESC, priority ASC FOR UPDATE`
|
||||
- 确保两个加油包关联到同一个主套餐
|
||||
|
||||
### 4. 主套餐有效期更新失败
|
||||
|
||||
- **场景**：主套餐 expires_at 更新时，同步跟随加油包失败
|
||||
- **处理**：
|
||||
- 使用事务包裹主套餐更新和加油包批量更新
|
||||
- 更新失败则回滚，返回错误 500
|
||||
- 记录错误日志，包含主套餐ID和失败原因
|
||||
|
||||
### 5. 级联失效失败
|
||||
|
||||
- **场景**：主套餐过期时，批量更新加油包失败（数据库连接断开）
|
||||
- **处理**：
|
||||
- 使用 Asynq 重试机制（最多3次）
|
||||
- 每次重试前检查加油包当前状态，避免重复更新
|
||||
- 3次失败后写入死信队列，发送告警
|
||||
|
||||
---
|
||||
|
||||
## 并发场景
|
||||
|
||||
### Scenario: 并发购买加油包
|
||||
- **GIVEN** 载体有生效中主套餐（ID=123）
|
||||
- **WHEN** 两个请求 req1 和 req2 同时购买加油包
|
||||
- **THEN** 系统使用行锁：
|
||||
```sql
|
||||
SELECT * FROM package_usage
|
||||
WHERE carrier_id=? AND package_type='formal' AND status IN (0,1)
|
||||
ORDER BY status DESC, priority ASC
|
||||
FOR UPDATE
|
||||
```
|
||||
- **AND** req1 和 req2 创建的加油包 master_usage_id 都为 123
|
||||
|
||||
### Scenario: 并发主套餐过期和购买加油包
|
||||
- **GIVEN** 主套餐A（ID=123）即将过期，主套餐B（ID=124）待生效
|
||||
- **WHEN** 时间到达过期时刻：
|
||||
- 请求1：定时任务将主套餐A status=3，触发级联失效
|
||||
- 请求2：用户购买加油包
|
||||
- **THEN** 使用事务隔离：
|
||||
- 如果请求2先获取锁 → 加油包 master_usage_id=123，然后被级联失效（status=4）
|
||||
- 如果请求1先获取锁 → 主套餐A已无生效中，加油包 master_usage_id=124
|
||||
|
||||
### Scenario: 并发更新主套餐有效期和级联失效
|
||||
- **GIVEN** 主套餐 ID=123，有5个跟随的加油包（has_independent_expiry=false）
|
||||
- **WHEN** 同时发生：
|
||||
- 请求1：主套餐 expires_at 更新为 2027-12-31
|
||||
- 请求2：主套餐到期，触发级联失效
|
||||
- **THEN** 使用行锁 `SELECT * FROM package_usage WHERE id=123 FOR UPDATE`
|
||||
- **AND** 先完成的操作生效，后完成的操作基于新状态执行
|
||||
|
||||
---
|
||||
|
||||
## 异常处理
|
||||
|
||||
### 1. 级联失效失败
|
||||
|
||||
- **错误场景**：主套餐过期时，批量更新加油包 SQL 执行失败
|
||||
- **处理流程**：
|
||||
1. 捕获错误，记录 Error 日志（包含主套餐ID、加油包数量、错误信息）
|
||||
2. Asynq 自动重试（最多3次，间隔 10s/30s/60s）
|
||||
3. 重试前检查加油包当前状态（避免重复更新）
|
||||
4. 3次失败后写入死信队列，发送告警通知
|
||||
- **返回错误**：不返回给用户（异步任务），仅记录日志
|
||||
|
||||
### 2. master_usage_id 不存在
|
||||
|
||||
- **错误场景**：加油包的 master_usage_id 指向的主套餐被删除
|
||||
- **处理流程**：
|
||||
1. 加油包激活时检查 `SELECT id FROM package_usage WHERE id=master_usage_id`
|
||||
2. 如果不存在 → 返回错误 500，错误码 `MASTER_NOT_FOUND`
|
||||
3. 记录 Error 日志（包含加油包ID、master_usage_id、载体信息）
|
||||
- **返回错误**：`{"code": "MASTER_NOT_FOUND", "msg": "关联的主套餐不存在，请联系管理员"}`
|
||||
|
||||
### 3. 同步有效期失败
|
||||
|
||||
- **错误场景**：主套餐 expires_at 更新时，批量更新跟随加油包失败
|
||||
- **处理流程**：
|
||||
1. 使用事务包裹主套餐更新和加油包批量更新
|
||||
2. 加油包更新失败 → 事务回滚，主套餐 expires_at 不更新
|
||||
3. 记录 Error 日志（包含主套餐ID、加油包数量、错误信息）
|
||||
4. 返回错误 500，错误码 `SYNC_EXPIRY_FAILED`
|
||||
- **返回错误**：`{"code": "SYNC_EXPIRY_FAILED", "msg": "更新套餐有效期失败，请稍后重试"}`
|
||||
|
||||
### 4. 购买加油包时无主套餐
|
||||
|
||||
- **错误场景**：用户购买加油包时，载体无任何主套餐
|
||||
- **处理流程**：
|
||||
1. 查询载体主套餐：`SELECT id FROM package_usage WHERE carrier_id=? AND package_type='formal' AND status IN (0,1) LIMIT 1`
|
||||
2. 如果无结果 → 返回错误 400，错误码 `ADDON_REQUIRES_MASTER`
|
||||
- **返回错误**：`{"code": "ADDON_REQUIRES_MASTER", "msg": "必须有主套餐才能购买加油包"}`
|
||||
|
||||
---
|
||||
|
||||
## 数据一致性保证
|
||||
|
||||
### 1. 事务边界
|
||||
|
||||
- **主套餐过期 + 级联失效**：使用单个事务，确保原子性
|
||||
- **主套餐更新有效期 + 同步加油包**：使用单个事务，更新失败则回滚
|
||||
- **购买加油包 + 关联主套餐**：使用事务，确保 master_usage_id 正确
|
||||
|
||||
### 2. 行锁机制
|
||||
|
||||
- **查询主套餐时加锁**：`SELECT * FROM package_usage WHERE carrier_id=? AND package_type='formal' AND status IN (0,1) FOR UPDATE`
|
||||
- **更新主套餐有效期时加锁**：`SELECT * FROM package_usage WHERE id=? FOR UPDATE`
|
||||
- **级联失效时加锁**：`SELECT * FROM package_usage WHERE master_usage_id=? FOR UPDATE`
|
||||
|
||||
### 3. 唯一索引
|
||||
|
||||
- 已有索引：`idx_carrier_package_type_priority`（carrier_id + package_type + priority）
|
||||
- 已有索引：`idx_master_usage_id`（master_usage_id）
|
||||
|
||||
### 4. 数据校验
|
||||
|
||||
- **购买加油包前**：校验 has_independent_expiry 与 duration_days 的一致性
|
||||
- **激活加油包时**：校验 master_usage_id 是否存在
|
||||
- **级联失效时**：仅更新 status NOT IN (3, 4) 的加油包（避免重复更新）
|
||||
|
||||
---
|
||||
|
||||
## 性能指标
|
||||
|
||||
| 操作 | 目标响应时间 | 并发要求 | 数据量 |
|
||||
|------|-------------|---------|--------|
|
||||
| 购买加油包（主套餐检查） | < 50ms | 100 QPS | 单载体查询 |
|
||||
| 关联主套餐（查询+插入） | < 100ms | 100 QPS | 单载体查询 + 单条插入 |
|
||||
| 主套餐过期级联失效 | < 500ms | 10 QPS | 批量更新（平均10个加油包） |
|
||||
| 主套餐更新有效期同步 | < 300ms | 50 QPS | 批量更新（平均5个加油包） |
|
||||
|
||||
---
|
||||
|
||||
## 错误码定义
|
||||
|
||||
| 错误码 | HTTP 状态码 | 错误消息 | 场景 |
|
||||
|--------|------------|---------|------|
|
||||
| `ADDON_REQUIRES_MASTER` | 400 | 必须有主套餐才能购买加油包 | 购买加油包时无主套餐 |
|
||||
| `MASTER_NOT_FOUND` | 500 | 关联的主套餐不存在，请联系管理员 | master_usage_id 不存在 |
|
||||
| `ADDON_MASTER_EXPIRED` | 400 | 关联的主套餐已过期，无法激活加油包 | 尝试激活已失效加油包 |
|
||||
| `SYNC_EXPIRY_FAILED` | 500 | 更新套餐有效期失败，请稍后重试 | 同步加油包有效期失败 |
|
||||
| `CASCADE_INVALIDATE_FAILED` | 500 | 级联失效加油包失败，请稍后重试 | 级联失效批量更新失败 |
|
||||
|
||||
---
|
||||
|
||||
## 数据迁移策略
|
||||
|
||||
**激进策略**（开发阶段，保证干净性）：
|
||||
|
||||
### 1. ❌ 要删除的字段
|
||||
|
||||
目前 `package_usage` 表中可能存在的冗余字段（需确认后删除）：
|
||||
- 如果有 `parent_usage_id` 字段（旧的父级关联） → **删除**
|
||||
- 如果有 `linked_usage_ids` 字段（旧的关联列表） → **删除**
|
||||
- 如果有 `inherit_to_next` 字段（旧的继承标志） → **删除**
|
||||
|
||||
### 2. ✅ 新增的字段
|
||||
|
||||
在 `package_usage` 表中新增：
|
||||
```sql
|
||||
ALTER TABLE package_usage
|
||||
ADD COLUMN master_usage_id BIGINT DEFAULT NULL COMMENT '主套餐ID（加油包专用）',
|
||||
ADD COLUMN has_independent_expiry BOOLEAN DEFAULT false COMMENT '是否有独立有效期（加油包专用）';
|
||||
|
||||
CREATE INDEX idx_master_usage_id ON package_usage(master_usage_id);
|
||||
```
|
||||
|
||||
在 `package` 表中新增：
|
||||
```sql
|
||||
ALTER TABLE package
|
||||
ADD COLUMN has_independent_expiry BOOLEAN DEFAULT false COMMENT '加油包是否有独立有效期（仅 package_type=addon 时有效）';
|
||||
```
|
||||
|
||||
### 3. ❌ 要废弃的逻辑
|
||||
|
||||
- **废弃旧的加油包关联逻辑**：如果代码中存在通过 `parent_usage_id` 或其他字段关联主套餐的逻辑，全部删除
|
||||
- **废弃旧的继承逻辑**：如果代码中存在"主套餐切换时加油包继承到新主套餐"的逻辑，全部删除
|
||||
- **废弃旧的有效期计算逻辑**：如果加油包有效期计算不区分"独立有效期"和"跟随主套餐"，全部重构
|
||||
|
||||
### 4. ✅ 历史数据强制转换
|
||||
|
||||
```sql
|
||||
-- Step 1: 历史加油包数据强制关联到当前主套餐
|
||||
UPDATE package_usage pu_addon
|
||||
SET master_usage_id = (
|
||||
SELECT pu_master.id
|
||||
FROM package_usage pu_master
|
||||
WHERE pu_master.carrier_id = pu_addon.carrier_id
|
||||
AND pu_master.package_type = 'formal'
|
||||
AND pu_master.status IN (0, 1)
|
||||
ORDER BY pu_master.status DESC, pu_master.priority ASC
|
||||
LIMIT 1
|
||||
)
|
||||
WHERE pu_addon.package_type = 'addon'
|
||||
AND pu_addon.master_usage_id IS NULL;
|
||||
|
||||
-- Step 2: 无主套餐的历史加油包强制失效
|
||||
UPDATE package_usage
|
||||
SET status = 4,
|
||||
invalidated_at = NOW()
|
||||
WHERE package_type = 'addon'
|
||||
AND master_usage_id IS NULL;
|
||||
|
||||
-- Step 3: 历史加油包默认为独立有效期模式
|
||||
UPDATE package_usage
|
||||
SET has_independent_expiry = true
|
||||
WHERE package_type = 'addon'
|
||||
AND has_independent_expiry IS NULL;
|
||||
|
||||
-- Step 4: 已过期主套餐的加油包全部级联失效
|
||||
UPDATE package_usage pu_addon
|
||||
SET status = 4,
|
||||
invalidated_at = NOW()
|
||||
FROM package_usage pu_master
|
||||
WHERE pu_addon.master_usage_id = pu_master.id
|
||||
AND pu_master.package_type = 'formal'
|
||||
AND pu_master.status = 3 -- 已过期
|
||||
AND pu_addon.status NOT IN (3, 4);
|
||||
```
|
||||
|
||||
### 5. ❌ 删除遗留表/字段（确认后执行）
|
||||
|
||||
```sql
|
||||
-- 如果存在旧的关联表，删除
|
||||
-- DROP TABLE IF EXISTS package_usage_relations;
|
||||
|
||||
-- 如果存在冗余字段，删除
|
||||
-- ALTER TABLE package_usage DROP COLUMN IF EXISTS parent_usage_id;
|
||||
-- ALTER TABLE package_usage DROP COLUMN IF EXISTS linked_usage_ids;
|
||||
-- ALTER TABLE package_usage DROP COLUMN IF EXISTS inherit_to_next;
|
||||
```
|
||||
|
||||
### 6. 验证步骤
|
||||
|
||||
```sql
|
||||
-- 验证1：所有加油包都有 master_usage_id（除了已失效的）
|
||||
SELECT COUNT(*)
|
||||
FROM package_usage
|
||||
WHERE package_type = 'addon'
|
||||
AND status NOT IN (3, 4)
|
||||
AND master_usage_id IS NULL;
|
||||
-- 预期结果：0
|
||||
|
||||
-- 验证2：所有加油包的 master_usage_id 都指向有效的主套餐
|
||||
SELECT COUNT(*)
|
||||
FROM package_usage pu_addon
|
||||
LEFT JOIN package_usage pu_master ON pu_addon.master_usage_id = pu_master.id
|
||||
WHERE pu_addon.package_type = 'addon'
|
||||
AND pu_addon.master_usage_id IS NOT NULL
|
||||
AND pu_master.id IS NULL;
|
||||
-- 预期结果：0
|
||||
|
||||
-- 验证3：已过期主套餐的加油包都已失效
|
||||
SELECT COUNT(*)
|
||||
FROM package_usage pu_addon
|
||||
JOIN package_usage pu_master ON pu_addon.master_usage_id = pu_master.id
|
||||
WHERE pu_master.status = 3
|
||||
AND pu_addon.status NOT IN (3, 4);
|
||||
-- 预期结果：0
|
||||
|
||||
-- 验证4：检查是否还有遗留字段（需根据实际情况调整）
|
||||
-- SELECT column_name FROM information_schema.columns
|
||||
-- WHERE table_name = 'package_usage'
|
||||
-- AND column_name IN ('parent_usage_id', 'linked_usage_ids', 'inherit_to_next');
|
||||
-- 预期结果：0 rows
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试场景矩阵
|
||||
|
||||
| 场景分类 | 测试用例 | 预期结果 |
|
||||
|---------|---------|---------|
|
||||
| **依附检查** | 无主套餐购买加油包 | 返回错误 400：ADDON_REQUIRES_MASTER |
|
||||
| | 有生效中主套餐购买加油包 | 创建成功，master_usage_id=生效中主套餐ID |
|
||||
| | 只有待生效主套餐购买加油包 | 创建成功，master_usage_id=priority最小的待生效主套餐ID |
|
||||
| **关联逻辑** | 多个主套餐时购买加油包 | 优先关联生效中主套餐 |
|
||||
| | 并发购买加油包 | 使用行锁，两个加油包关联到同一主套餐 |
|
||||
| **独立有效期** | 独立有效期加油包激活 | expires_at = activated_at + duration_days |
|
||||
| | 独立有效期加油包到期 | status=3（已过期） |
|
||||
| | 独立有效期加油包未到期但主套餐过期 | status=4（已失效） |
|
||||
| **跟随主套餐** | 跟随主套餐的加油包激活 | expires_at = master套餐.expires_at |
|
||||
| | 主套餐更新有效期 | 跟随加油包同步更新 expires_at |
|
||||
| | 主套餐更新有效期时独立有效期加油包不变 | 独立有效期加油包 expires_at 不变 |
|
||||
| **级联失效** | 主套餐过期触发级联失效 | 所有关联加油包 status=4 |
|
||||
| | 独立有效期加油包未到期但主套餐过期 | status=4（已失效） |
|
||||
| | 已过期加油包不重复失效 | status 保持 3 |
|
||||
| | 级联失效失败重试 | Asynq 重试3次，失败后进入死信队列 |
|
||||
| **不继承** | 新主套餐激活后旧加油包不关联 | 旧加油包 master_usage_id 和 status 保持不变 |
|
||||
| | 为新主套餐购买新加油包 | 新加油包 master_usage_id=新主套餐ID |
|
||||
| | 尝试激活已失效加油包 | 返回错误 400：ADDON_MASTER_EXPIRED |
|
||||
| **并发** | 并发购买加油包 | 使用行锁，确保关联到同一主套餐 |
|
||||
| | 并发主套餐过期和购买加油包 | 事务隔离，先完成的操作生效 |
|
||||
| **异常** | master_usage_id 不存在 | 返回错误 500：MASTER_NOT_FOUND |
|
||||
| | 同步有效期失败 | 事务回滚，返回错误 500：SYNC_EXPIRY_FAILED |
|
||||
| | 级联失效失败 | Asynq 重试，记录日志，发送告警 |
|
||||
|
||||
---
|
||||
|
||||
## 实现参考
|
||||
|
||||
### 购买加油包时的主套餐检查
|
||||
|
||||
```go
|
||||
// Service 层：CheckMasterPackageForAddon
|
||||
func (s *Service) CheckMasterPackageForAddon(ctx context.Context, carrierID uint) (uint, error) {
|
||||
// 查询生效中或待生效的主套餐
|
||||
masterUsage, err := s.store.FindMasterPackage(ctx, carrierID)
|
||||
if err != nil {
|
||||
return 0, errors.Wrap(errors.CodeInternalError, err, "查询主套餐失败")
|
||||
}
|
||||
if masterUsage == nil {
|
||||
return 0, errors.New(errors.CodeInvalidParam, "必须有主套餐才能购买加油包")
|
||||
}
|
||||
return masterUsage.ID, nil
|
||||
}
|
||||
|
||||
// Store 层：FindMasterPackage
|
||||
func (s *Store) FindMasterPackage(ctx context.Context, carrierID uint) (*model.PackageUsage, error) {
|
||||
var usage model.PackageUsage
|
||||
err := s.db.WithContext(ctx).
|
||||
Where("carrier_id = ? AND package_type = ? AND status IN (?, ?)",
|
||||
carrierID, constants.PackageTypeFormal,
|
||||
constants.PackageStatusPending, constants.PackageStatusActive).
|
||||
Order("status DESC, priority ASC"). // 优先生效中，然后按 priority
|
||||
First(&usage).Error
|
||||
if errors.Is(err, gorm.ErrRecordNotFound) {
|
||||
return nil, nil
|
||||
}
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &usage, nil
|
||||
}
|
||||
```
|
||||
|
||||
### 主套餐过期时级联失效加油包
|
||||
|
||||
```go
|
||||
// Service 层：CascadeInvalidateAddons
|
||||
func (s *Service) CascadeInvalidateAddons(ctx context.Context, masterUsageID uint) error {
|
||||
tx := s.store.BeginTx(ctx)
|
||||
defer tx.Rollback()
|
||||
|
||||
// 批量更新加油包状态
|
||||
count, err := s.store.InvalidateAddonsByMaster(ctx, tx, masterUsageID)
|
||||
if err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "级联失效加油包失败")
|
||||
}
|
||||
|
||||
if err := tx.Commit().Error; err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "提交事务失败")
|
||||
}
|
||||
|
||||
// 记录审计日志（异步）
|
||||
s.auditService.LogOperation(ctx, &model.OperationLog{
|
||||
OperationType: "cascade_invalidate",
|
||||
OperationDesc: fmt.Sprintf("主套餐ID=%d过期，级联失效%d个加油包", masterUsageID, count),
|
||||
TargetID: masterUsageID,
|
||||
})
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// Store 层：InvalidateAddonsByMaster
|
||||
func (s *Store) InvalidateAddonsByMaster(ctx context.Context, tx *gorm.DB, masterUsageID uint) (int64, error) {
|
||||
result := tx.WithContext(ctx).
|
||||
Model(&model.PackageUsage{}).
|
||||
Where("master_usage_id = ? AND status NOT IN (?, ?)",
|
||||
masterUsageID,
|
||||
constants.PackageStatusExpired,
|
||||
constants.PackageStatusInvalidated).
|
||||
Updates(map[string]interface{}{
|
||||
"status": constants.PackageStatusInvalidated,
|
||||
"invalidated_at": time.Now(),
|
||||
})
|
||||
if result.Error != nil {
|
||||
return 0, result.Error
|
||||
}
|
||||
return result.RowsAffected, nil
|
||||
}
|
||||
```
|
||||
|
||||
### 主套餐更新有效期时同步跟随加油包
|
||||
|
||||
```go
|
||||
// Service 层：SyncAddonExpiry
|
||||
func (s *Service) SyncAddonExpiry(ctx context.Context, masterUsageID uint, newExpiresAt time.Time) error {
|
||||
tx := s.store.BeginTx(ctx)
|
||||
defer tx.Rollback()
|
||||
|
||||
// 更新主套餐有效期
|
||||
if err := s.store.UpdateExpiry(ctx, tx, masterUsageID, newExpiresAt); err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "更新主套餐有效期失败")
|
||||
}
|
||||
|
||||
// 批量更新跟随的加油包
|
||||
count, err := s.store.SyncFollowingAddonExpiry(ctx, tx, masterUsageID, newExpiresAt)
|
||||
if err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "同步加油包有效期失败")
|
||||
}
|
||||
|
||||
if err := tx.Commit().Error; err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "提交事务失败")
|
||||
}
|
||||
|
||||
s.logger.Info("同步加油包有效期成功",
|
||||
zap.Uint("master_usage_id", masterUsageID),
|
||||
zap.Int64("count", count),
|
||||
zap.Time("new_expires_at", newExpiresAt))
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// Store 层：SyncFollowingAddonExpiry
|
||||
func (s *Store) SyncFollowingAddonExpiry(ctx context.Context, tx *gorm.DB, masterUsageID uint, expiresAt time.Time) (int64, error) {
|
||||
result := tx.WithContext(ctx).
|
||||
Model(&model.PackageUsage{}).
|
||||
Where("master_usage_id = ? AND has_independent_expiry = ?", masterUsageID, false).
|
||||
Update("expires_at", expiresAt)
|
||||
if result.Error != nil {
|
||||
return 0, result.Error
|
||||
}
|
||||
return result.RowsAffected, nil
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**本 Spec 完成**，包含：
|
||||
- ✅ 业务背景和业务规则
|
||||
- ✅ 详细场景（依附、关联、独立有效期、跟随主套餐、级联失效、不继承）
|
||||
- ✅ 边界条件和并发场景
|
||||
- ✅ 异常处理和数据一致性保证
|
||||
- ✅ 性能指标和错误码定义
|
||||
- ✅ **激进的数据迁移策略**（明确删除字段、废弃逻辑、强制转换）
|
||||
- ✅ 测试场景矩阵和实现参考
|
||||
391
openspec/specs/auto-stop-resume/spec.md
Normal file
391
openspec/specs/auto-stop-resume/spec.md
Normal file
@@ -0,0 +1,391 @@
|
||||
# Spec: 自动停复机机制
|
||||
|
||||
## 业务背景
|
||||
|
||||
### 为什么需要自动停复机
|
||||
|
||||
**现状问题**：
|
||||
- 当前系统流量耗尽后手动停机,用户购买加油包后需手动复机
|
||||
- 停复机时机不精确,可能出现流量已耗尽但仍可上网的情况
|
||||
- 用户购买加油包后不知道需要复机,导致流量无法使用
|
||||
|
||||
**业务目标**：
|
||||
- 所有套餐流量耗尽时自动停机,避免超额使用
|
||||
- 购买新套餐(正式/加油包)后自动复机,提升用户体验
|
||||
- 停复机延迟 < 2分钟,确保及时性
|
||||
|
||||
---
|
||||
|
||||
## 业务规则
|
||||
|
||||
### 1. 停机触发条件
|
||||
|
||||
```
|
||||
停机条件 = (所有生效套餐流量 = 0) AND (卡当前状态 = active)
|
||||
```
|
||||
|
||||
**详细逻辑**：
|
||||
```sql
|
||||
-- 检查是否有剩余流量
|
||||
SELECT COUNT(*) FROM tb_package_usage
|
||||
WHERE iot_card_id = ?
|
||||
AND status = 1 -- 生效中
|
||||
AND data_usage_mb < data_limit_mb;
|
||||
|
||||
-- 如果 COUNT = 0,触发停机
|
||||
```
|
||||
|
||||
### 2. 复机触发条件
|
||||
|
||||
```
|
||||
复机条件 = (存在可用流量套餐) AND (卡当前状态 = stopped)
|
||||
```
|
||||
|
||||
**可用流量套餐定义**：
|
||||
```sql
|
||||
status='active' AND remaining_data_amount > 0
|
||||
```
|
||||
|
||||
### 3. 停复机延迟要求
|
||||
|
||||
- **目标延迟**：< 2分钟(从触发条件到完成停复机)
|
||||
- **实现方式**：流量检查后同步调用停复机接口(不走异步队列)
|
||||
|
||||
### 4. 运营商接口容错
|
||||
|
||||
- 停机/复机失败时：
|
||||
- 重试3次(间隔 1s, 2s, 4s)
|
||||
- 仍失败：记录错误日志,人工介入
|
||||
- **不阻塞**套餐激活流程
|
||||
|
||||
---
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 流量耗尽自动停机
|
||||
|
||||
系统 SHALL 在主套餐和所有加油包流量都用完时,调用运营商接口停机。
|
||||
|
||||
#### Scenario: 所有套餐流量耗尽触发停机
|
||||
- **GIVEN** 卡 C1 有主套餐(剩余0MB)和加油包(剩余0MB),卡状态为 active
|
||||
- **WHEN** 轮询系统检查停机条件
|
||||
- **THEN** 系统执行停机操作：
|
||||
1. 调用运营商停机接口
|
||||
2. 更新 IotCard.network_status=0(已停机)
|
||||
3. 记录 stopped_at 时间
|
||||
4. 记录 stop_reason="traffic_exhausted"
|
||||
5. 记录操作日志
|
||||
|
||||
#### Scenario: 有剩余流量时不停机
|
||||
- **GIVEN** 主套餐流量用完,但加油包剩余1GB
|
||||
- **WHEN** 轮询系统检查停机条件
|
||||
- **THEN** 系统查询到有剩余流量,不触发停机
|
||||
|
||||
#### Scenario: 停机接口调用失败重试
|
||||
- **GIVEN** 所有套餐流量用完,需要停机
|
||||
- **WHEN** 调用运营商停机接口失败(网络超时)
|
||||
- **THEN** 系统重试3次(间隔1s/2s/4s)
|
||||
- **AND** 3次都失败后记录 Error 日志,告警通知运维
|
||||
|
||||
#### Scenario: 停机幂等性
|
||||
- **GIVEN** 卡已停机(network_status=0)
|
||||
- **WHEN** 轮询系统再次检测到流量用完
|
||||
- **THEN** 系统检测到已停机,跳过停机调用
|
||||
|
||||
### Requirement: 购买套餐自动复机
|
||||
|
||||
系统 SHALL 在购买新套餐(正式/加油包)激活后,自动调用运营商接口复机。
|
||||
|
||||
#### Scenario: 购买加油包自动复机
|
||||
- **GIVEN** 卡 C1 已停机(network_status=0,stopped_at=2026-02-10 10:00)
|
||||
- **WHEN** 用户购买加油包,激活成功(status=active)
|
||||
- **THEN** 系统执行复机操作：
|
||||
1. 调用运营商复机接口
|
||||
2. 更新 IotCard.network_status=1(正常)
|
||||
3. 记录 resumed_at 时间
|
||||
4. 清空 stopped_at
|
||||
5. 记录操作日志
|
||||
|
||||
#### Scenario: 复机幂等性
|
||||
- **GIVEN** 卡 C1 已停机
|
||||
- **WHEN** 用户快速购买2个加油包
|
||||
- **THEN** 第1个加油包激活 → 触发复机成功
|
||||
- **AND** 第2个加油包激活 → 检测到已是 active 状态,跳过复机
|
||||
- **AND** 运营商复机接口调用仅1次
|
||||
|
||||
#### Scenario: 购买主套餐自动复机
|
||||
- **GIVEN** 卡 C1 已停机,主套餐过期
|
||||
- **WHEN** 用户购买新主套餐,激活成功
|
||||
- **THEN** 系统自动触发复机
|
||||
|
||||
#### Scenario: 复机失败容错
|
||||
- **GIVEN** 卡已停机
|
||||
- **WHEN** 购买加油包激活,但运营商复机接口返回失败
|
||||
- **THEN** 系统重试3次
|
||||
- **AND** 仍失败后：
|
||||
- 套餐激活成功(status=active)
|
||||
- 卡状态仍为 stopped
|
||||
- 错误日志已记录
|
||||
- 告警通知运维
|
||||
|
||||
### Requirement: 复机延迟 < 2分钟
|
||||
|
||||
系统 SHALL 确保从套餐激活到卡复机完成的延迟 < 2分钟。
|
||||
|
||||
#### Scenario: 复机延迟达标
|
||||
- **GIVEN** 加油包在 2026-02-10 10:00:00 激活成功
|
||||
- **WHEN** 系统同步调用复机接口
|
||||
- **THEN** 复机完成时间 < 2026-02-10 10:02:00(延迟 < 2分钟)
|
||||
|
||||
#### Scenario: 复机失败后重试延迟
|
||||
- **GIVEN** 加油包激活,第1次复机调用失败
|
||||
- **WHEN** 系统重试3次(间隔1s/2s/4s)
|
||||
- **THEN** 复机在第3次重试成功,总延迟约7秒
|
||||
|
||||
---
|
||||
|
||||
## 数据模型变更
|
||||
|
||||
### tb_iot_card 新增字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| stopped_at | timestamp | 停机时间,NULL=未停机 |
|
||||
| resumed_at | timestamp | 最近复机时间 |
|
||||
| stop_reason | varchar(50) | 停机原因：`traffic_exhausted`, `manual`, `arrears` |
|
||||
|
||||
**索引**：
|
||||
- 无需索引(非查询字段,仅用于审计)
|
||||
|
||||
---
|
||||
|
||||
## 业务流程
|
||||
|
||||
### 流程1：流量耗尽停机
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[流量上报] --> B{所有套餐流量=0?}
|
||||
B -->|是| C{卡状态=active?}
|
||||
B -->|否| Z[结束]
|
||||
C -->|是| D[调用运营商停机接口]
|
||||
C -->|否| Z
|
||||
D --> E{停机成功?}
|
||||
E -->|是| F[更新卡状态=stopped]
|
||||
E -->|否| G[重试3次]
|
||||
F --> H[记录stopped_at]
|
||||
G --> E
|
||||
```
|
||||
|
||||
### 流程2：购买加油包复机
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[加油包激活成功] --> B{卡状态=stopped?}
|
||||
B -->|是| C[调用运营商复机接口]
|
||||
B -->|否| Z[跳过复机]
|
||||
C --> D{复机成功?}
|
||||
D -->|是| E[更新卡状态=active]
|
||||
D -->|否| F[重试3次]
|
||||
E --> G[清空stopped_at]
|
||||
F --> D
|
||||
F -->|3次失败| H[记录错误日志]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 并发场景
|
||||
|
||||
### Scenario: 并发停复机
|
||||
- **GIVEN** 卡流量刚好用完,同时用户购买加油包
|
||||
- **WHEN** 停机任务和复机任务并发执行
|
||||
- **THEN** 使用数据库行锁：
|
||||
```sql
|
||||
SELECT * FROM iot_card WHERE id=? FOR UPDATE
|
||||
```
|
||||
- **AND** 后执行的操作覆盖前一个操作的状态
|
||||
|
||||
### Scenario: 复机任务重复执行
|
||||
- **GIVEN** 用户购买2个加油包,触发2次复机
|
||||
- **WHEN** 第1次复机成功,卡状态=active
|
||||
- **THEN** 第2次复机检测到卡状态=active,跳过调用
|
||||
|
||||
---
|
||||
|
||||
## 异常处理
|
||||
|
||||
### 1. 停机接口超时
|
||||
|
||||
- **场景**：运营商停机接口响应超时(>5秒)
|
||||
- **处理**：
|
||||
1. 记录 Error 日志(包含卡号、超时时间)
|
||||
2. 重试3次,间隔1s/2s/4s
|
||||
3. 3次都失败：记录到死信队列,告警通知
|
||||
- **用户影响**：卡可能仍可上网(停机未成功)
|
||||
|
||||
### 2. 复机接口失败
|
||||
|
||||
- **场景**：运营商复机接口返回业务错误(如卡状态异常)
|
||||
- **处理**：
|
||||
1. 记录 Error 日志(包含卡号、错误码、错误消息)
|
||||
2. 重试3次
|
||||
3. 3次都失败：套餐激活成功,但卡保持停机状态
|
||||
4. 告警通知运维人工介入
|
||||
- **用户影响**：购买加油包后仍无法上网
|
||||
|
||||
### 3. 停复机状态不一致
|
||||
|
||||
- **场景**：系统记录已停机,但运营商侧仍正常
|
||||
- **处理**：
|
||||
1. 轮询系统定期同步卡状态
|
||||
2. 检测到不一致时记录 Warning 日志
|
||||
3. 自动修正系统状态(以运营商侧为准)
|
||||
- **修正频率**：每小时同步一次
|
||||
|
||||
---
|
||||
|
||||
## 性能指标
|
||||
|
||||
| 操作 | 目标响应时间 | 监控指标 |
|
||||
|------|------------|---------|
|
||||
| 停机接口调用 | < 5秒 | 运营商API耗时 |
|
||||
| 复机接口调用 | < 5秒 | 运营商API耗时 |
|
||||
| 停机条件检查 | < 50ms | SELECT COUNT查询耗时 |
|
||||
| 端到端停机延迟 | < 2分钟 | 流量用完到停机完成 |
|
||||
| 端到端复机延迟 | < 2分钟 | 套餐激活到复机完成 |
|
||||
|
||||
---
|
||||
|
||||
## 错误码定义
|
||||
|
||||
| 错误码 | HTTP 状态码 | 错误消息 | 场景 |
|
||||
|--------|------------|---------|------|
|
||||
| CodeInternal | 500 | 停机操作失败,请重试 | 运营商停机接口失败 |
|
||||
| CodeInternal | 500 | 复机操作失败,请重试 | 运营商复机接口失败 |
|
||||
|
||||
---
|
||||
|
||||
## 测试场景矩阵
|
||||
|
||||
| 维度 | 场景 | 预期结果 |
|
||||
|------|------|---------|
|
||||
| **停机** | 所有套餐流量用完 | 自动停机 |
|
||||
| | 主套餐用完+加油包剩余 | 不停机 |
|
||||
| | 停机接口失败 | 重试3次,失败告警 |
|
||||
| | 已停机重复检测 | 跳过停机 |
|
||||
| **复机** | 购买加油包 | 自动复机 |
|
||||
| | 购买主套餐 | 自动复机 |
|
||||
| | 复机接口失败 | 重试3次,套餐激活成功,卡保持停机 |
|
||||
| | 并发购买2个加油包 | 复机接口调用1次 |
|
||||
| **延迟** | 复机延迟 | < 2分钟 |
|
||||
| | 停机延迟 | < 2分钟 |
|
||||
| **异常** | 停机超时 | 重试后告警 |
|
||||
| | 状态不一致 | 轮询同步修正 |
|
||||
|
||||
---
|
||||
|
||||
## 实现参考
|
||||
|
||||
### Service 层：CheckAndStop
|
||||
|
||||
```go
|
||||
func (s *Service) CheckAndStopCard(ctx context.Context, cardID uint) error {
|
||||
// 1. 查询卡信息
|
||||
card, err := s.iotCardStore.GetByID(ctx, cardID)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// 2. 检查卡状态
|
||||
if card.NetworkStatus != constants.NetworkStatusActive {
|
||||
return nil // 已停机,跳过
|
||||
}
|
||||
|
||||
// 3. 检查是否有剩余流量
|
||||
hasAvailableData, err := s.packageUsageStore.HasAvailableData(ctx, cardID)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
if hasAvailableData {
|
||||
return nil // 有剩余流量,不停机
|
||||
}
|
||||
|
||||
// 4. 调用运营商停机接口(带重试)
|
||||
err = s.carrierClient.StopCard(ctx, card.ICCID, 3)
|
||||
if err != nil {
|
||||
s.logger.Error("停机失败",
|
||||
zap.Uint("card_id", cardID),
|
||||
zap.Error(err))
|
||||
return err
|
||||
}
|
||||
|
||||
// 5. 更新卡状态
|
||||
err = s.iotCardStore.UpdateStopStatus(ctx, cardID, time.Now(), "traffic_exhausted")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// 6. 记录审计日志
|
||||
s.auditService.LogOperation(ctx, &model.OperationLog{
|
||||
OperationType: "card_stop",
|
||||
OperationDesc: "流量耗尽自动停机",
|
||||
TargetID: cardID,
|
||||
})
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### Service 层：ResumeCard
|
||||
|
||||
```go
|
||||
func (s *Service) ResumeCardIfStopped(ctx context.Context, cardID uint) error {
|
||||
// 1. 查询卡信息
|
||||
card, err := s.iotCardStore.GetByID(ctx, cardID)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// 2. 检查卡状态
|
||||
if card.NetworkStatus != constants.NetworkStatusStopped {
|
||||
return nil // 未停机,跳过
|
||||
}
|
||||
|
||||
// 3. 调用运营商复机接口(带重试)
|
||||
err = s.carrierClient.ResumeCard(ctx, card.ICCID, 3)
|
||||
if err != nil {
|
||||
s.logger.Error("复机失败",
|
||||
zap.Uint("card_id", cardID),
|
||||
zap.Error(err))
|
||||
// 复机失败不阻塞套餐激活
|
||||
return nil
|
||||
}
|
||||
|
||||
// 4. 更新卡状态
|
||||
err = s.iotCardStore.UpdateResumeStatus(ctx, cardID, time.Now())
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// 5. 记录审计日志
|
||||
s.auditService.LogOperation(ctx, &model.OperationLog{
|
||||
OperationType: "card_resume",
|
||||
OperationDesc: "购买套餐自动复机",
|
||||
TargetID: cardID,
|
||||
})
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**本 Spec 完成**，包含：
|
||||
- ✅ 业务背景和业务规则
|
||||
- ✅ 详细场景(停机、复机、幂等性、容错)
|
||||
- ✅ 数据模型变更
|
||||
- ✅ 业务流程图
|
||||
- ✅ 并发场景和异常处理
|
||||
- ✅ 性能指标和错误码定义
|
||||
- ✅ 测试场景矩阵和实现参考
|
||||
@@ -578,3 +578,49 @@ This capability supports:
|
||||
- **WHEN** 管理员查询设备绑定的物联网卡列表
|
||||
- **THEN** 响应中的 carrier_name 直接来自 IotCard 记录的冗余字段
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 流量检查任务支持新的扣减优先级
|
||||
系统 SHALL 在轮询系统的流量检查任务（HandleCarddataCheck）中，实现新的流量扣减优先级机制。
|
||||
|
||||
#### Scenario: 优先扣减加油包流量
|
||||
- **WHEN** 轮询系统检测到卡流量增加，卡有主套餐和加油包
|
||||
- **THEN** 系统优先更新加油包的 data_usage_mb，再更新主套餐
|
||||
|
||||
#### Scenario: 按 Priority 顺序扣减多个加油包
|
||||
- **WHEN** 卡有多个加油包，流量增加
|
||||
- **THEN** 系统按 priority 从小到大顺序扣减流量
|
||||
|
||||
### Requirement: 停机条件检查调整
|
||||
系统 SHALL 在轮询系统中，仅当主套餐和所有加油包流量都用完时触发停机。
|
||||
|
||||
#### Scenario: 主套餐用完但加油包有剩余不停机
|
||||
- **WHEN** 主套餐 data_usage_mb >= data_limit_mb，但加油包有剩余流量
|
||||
- **THEN** 系统不触发停机操作
|
||||
|
||||
#### Scenario: 所有套餐流量用完触发停机
|
||||
- **WHEN** 主套餐和所有加油包 data_usage_mb >= data_limit_mb
|
||||
- **THEN** 系统触发停机操作
|
||||
|
||||
### Requirement: 套餐激活检查任务
|
||||
系统 SHALL 新增套餐激活检查任务（HandlePackageActivation），定期检查待激活的主套餐。
|
||||
|
||||
#### Scenario: 定期检查待激活主套餐
|
||||
- **WHEN** 轮询系统每分钟执行一次套餐激活检查
|
||||
- **THEN** 系统查询所有已过期主套餐，激活 priority 最小的待生效主套餐
|
||||
|
||||
#### Scenario: 激活延迟小于1分钟
|
||||
- **WHEN** 主套餐在 00:00:00 过期
|
||||
- **THEN** 系统在 00:01:00 之前完成下一个主套餐的激活
|
||||
|
||||
### Requirement: 流量重置调度任务
|
||||
系统 SHALL 新增流量重置调度任务（HandleDataReset），根据套餐的 data_reset_cycle 定期重置流量。
|
||||
|
||||
#### Scenario: 每日0点触发日重置任务
|
||||
- **WHEN** 系统时间到达 00:00:00
|
||||
- **THEN** 系统重置所有 data_reset_cycle=daily 的套餐 data_usage_mb=0
|
||||
|
||||
#### Scenario: 每月1号触发月重置任务
|
||||
- **WHEN** 系统时间到达每月1号 00:00:00
|
||||
- **THEN** 系统重置所有 data_reset_cycle=monthly 的套餐 data_usage_mb=0
|
||||
|
||||
|
||||
@@ -189,3 +189,38 @@
|
||||
#### Scenario: 代购订单不更新累计充值
|
||||
- **WHEN** 代购订单支付成功
|
||||
- **THEN** 系统 MUST NOT 更新卡/设备的 accumulated_recharge 字段
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 主套餐购买时自动排队
|
||||
系统 SHALL 在用户购买主套餐时，如果已有生效中的主套餐，自动将新套餐设置为待生效状态并分配 priority。
|
||||
|
||||
#### Scenario: 首个主套餐立即生效
|
||||
- **WHEN** 载体首次购买主套餐
|
||||
- **THEN** PackageUsage status=1, priority=1, activated_at=支付完成时间
|
||||
|
||||
#### Scenario: 第二个主套餐自动排队
|
||||
- **WHEN** 载体已有生效中主套餐，购买第2个主套餐
|
||||
- **THEN** PackageUsage status=0, priority=2, pending_realname_activation=false
|
||||
|
||||
### Requirement: 加油包购买前检查主套餐
|
||||
系统 SHALL 在用户购买加油包前，检查是否有生效中或待生效的主套餐。
|
||||
|
||||
#### Scenario: 无主套餐时购买加油包失败
|
||||
- **WHEN** 用户购买加油包，但载体无主套餐
|
||||
- **THEN** 系统返回错误 400 "必须有主套餐才能购买加油包"
|
||||
|
||||
#### Scenario: 有主套餐时可购买加油包
|
||||
- **WHEN** 用户购买加油包，载体有生效中主套餐
|
||||
- **THEN** 系统创建订单成功，PackageUsage master_usage_id=主套餐ID
|
||||
|
||||
### Requirement: 客户端未实名时禁止购买套餐
|
||||
系统 SHALL 在客户端购买套餐时，检查载体的实名状态。
|
||||
|
||||
#### Scenario: 客户端未实名购买返回错误
|
||||
- **WHEN** 客户通过 H5 端购买套餐，载体未实名
|
||||
- **THEN** 系统返回错误 403 "设备/卡必须先完成实名认证才能购买套餐"
|
||||
|
||||
#### Scenario: 后台管理端可为未实名载体购买
|
||||
- **WHEN** 管理员通过后台为未实名载体购买套餐
|
||||
- **THEN** 系统创建订单成功，PackageUsage status=0, pending_realname_activation=true
|
||||
|
||||
375
openspec/specs/package-calendar-type/spec.md
Normal file
375
openspec/specs/package-calendar-type/spec.md
Normal file
@@ -0,0 +1,375 @@
|
||||
# Spec: 套餐周期类型管理
|
||||
|
||||
## 业务背景
|
||||
|
||||
现有套餐系统仅支持简单的按月计算模式（通过 `duration_months` 字段），无法区分"自然月套餐"和"按天套餐"的业务需求。本规范引入 `calendar_type` 字段，支持两种套餐类型：
|
||||
|
||||
1. **自然月套餐（natural_month）**：按月边界计算有效期，适合"月卡"、"季卡"、"年卡"等场景
|
||||
2. **按天套餐（by_day）**：按天数精确计算有效期，适合"7天卡"、"30天卡"、"90天卡"等场景
|
||||
|
||||
两种类型的核心差异在于**有效期计算方式**：
|
||||
- 自然月套餐：激活后到当前月份 + N 个月的**月末 23:59:59**
|
||||
- 按天套餐：激活后 + N 天的 **23:59:59**
|
||||
|
||||
## 业务规则
|
||||
|
||||
1. **calendar_type 是必填字段**，默认值为 `by_day`（向后兼容）
|
||||
2. **duration_months 和 duration_days 互斥但至少提供一个**：
|
||||
- `calendar_type=natural_month` 时，必须提供 `duration_months`
|
||||
- `calendar_type=by_day` 时，必须提供 `duration_days`（如缺失，可从 `duration_months * 30` 转换）
|
||||
3. **有效期计算时区统一使用服务器时区**（Asia/Shanghai）
|
||||
4. **套餐激活时才计算 expires_at**，创建订单时不计算
|
||||
5. **自然月套餐的月末处理**：
|
||||
- 2月 → 28/29日（闰年判断）
|
||||
- 其他小月（4/6/9/11月）→ 30日
|
||||
- 大月（1/3/5/7/8/10/12月）→ 31日
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 支持自然月套餐类型
|
||||
系统 SHALL 支持自然月套餐（calendar_type=natural_month），套餐有效期按自然月边界计算。
|
||||
|
||||
**业务价值**：满足运营商月卡业务需求，例如"联通月卡"在当月任意时间激活，均在月末过期，避免用户困惑。
|
||||
|
||||
**技术约束**：
|
||||
- 有效期必须精确到秒（23:59:59）
|
||||
- 闰年判断必须准确（2月29日处理）
|
||||
- 跨年处理必须正确（12月 + 1个月 = 次年1月）
|
||||
|
||||
#### Scenario: 月中购买自然月套餐
|
||||
- **GIVEN** 系统时间为 2026-01-15 10:00:00
|
||||
- **WHEN** 用户购买自然月套餐（calendar_type=natural_month, duration_months=1）并激活
|
||||
- **THEN** 套餐 activated_at=2026-01-15 10:00:00，expires_at=2026-01-31 23:59:59
|
||||
|
||||
#### Scenario: 月末购买自然月套餐（边界条件）
|
||||
- **GIVEN** 系统时间为 2026-01-30 23:00:00
|
||||
- **WHEN** 用户购买自然月套餐（calendar_type=natural_month, duration_months=1）并激活
|
||||
- **THEN** 套餐 activated_at=2026-01-30 23:00:00，expires_at=2026-01-31 23:59:59
|
||||
- **AND** 实际有效期仅剩约 25 小时（业务允许，用户自行承担）
|
||||
|
||||
#### Scenario: 自然月年套餐
|
||||
- **GIVEN** 系统时间为 2026-02-15 10:00:00
|
||||
- **WHEN** 用户购买自然月年套餐（calendar_type=natural_month, duration_months=12）并激活
|
||||
- **THEN** 套餐 activated_at=2026-02-15 10:00:00，expires_at=2027-02-28 23:59:59
|
||||
- **AND** 因为 2027 年不是闰年，2月为 28 日
|
||||
|
||||
#### Scenario: 闰年自然月套餐（边界条件）
|
||||
- **GIVEN** 系统时间为 2028-02-15 10:00:00（2028 年是闰年）
|
||||
- **WHEN** 用户购买自然月年套餐（calendar_type=natural_month, duration_months=12）并激活
|
||||
- **THEN** 套餐 expires_at=2029-02-28 23:59:59
|
||||
- **AND** 因为 2029 年不是闰年，2月为 28 日
|
||||
|
||||
#### Scenario: 闰年2月购买1个月套餐（边界条件）
|
||||
- **GIVEN** 系统时间为 2028-02-15 10:00:00（2028 年是闰年）
|
||||
- **WHEN** 用户购买自然月套餐（calendar_type=natural_month, duration_months=1）并激活
|
||||
- **THEN** 套餐 expires_at=2028-02-29 23:59:59
|
||||
- **AND** 因为 2028 年是闰年，2月为 29 日
|
||||
|
||||
#### Scenario: 跨年自然月套餐（边界条件）
|
||||
- **GIVEN** 系统时间为 2026-12-15 10:00:00
|
||||
- **WHEN** 用户购买自然月套餐（calendar_type=natural_month, duration_months=2）并激活
|
||||
- **THEN** 套餐 expires_at=2027-02-28 23:59:59
|
||||
- **AND** 正确跨年计算（12月 + 2个月 = 次年2月）
|
||||
|
||||
#### Scenario: 自然月季卡（90天 vs 3个月差异）
|
||||
- **GIVEN** 系统时间为 2026-01-31 10:00:00
|
||||
- **WHEN** 用户购买自然月季卡（calendar_type=natural_month, duration_months=3）并激活
|
||||
- **THEN** 套餐 expires_at=2026-04-30 23:59:59
|
||||
- **AND** 实际天数 = 31（1月剩余）+ 28（2月）+ 31（3月）+ 30（4月）= 120 天
|
||||
- **AND** 比按天套餐（90天）多 30 天，体现自然月优势
|
||||
|
||||
### Requirement: 支持按天套餐类型
|
||||
系统 SHALL 支持按天套餐（calendar_type=by_day），套餐有效期按天数精确计算。
|
||||
|
||||
**业务价值**：满足灵活天数套餐需求，例如"7天卡"、"30天卡"、"90天卡"，用户在任意时间激活，都获得完整的天数。
|
||||
|
||||
**技术约束**：
|
||||
- 有效期计算公式：`expires_at = activated_at + duration_days 天 - 1秒`（例如：10:00:00 激活 + 1天 = 次日 09:59:59，但为了用户体验，统一为 23:59:59）
|
||||
- 实际实现：`expires_at = (activated_at 日期 + duration_days 天) 的 23:59:59`
|
||||
- 自动处理闰年、大小月、跨年
|
||||
|
||||
#### Scenario: 购买30天套餐
|
||||
- **GIVEN** 系统时间为 2026-01-15 10:00:00
|
||||
- **WHEN** 用户购买30天套餐（calendar_type=by_day, duration_days=30）并激活
|
||||
- **THEN** 套餐 activated_at=2026-01-15 10:00:00，expires_at=2026-02-13 23:59:59
|
||||
- **AND** 实际天数 = 30 天（含激活当天）
|
||||
|
||||
#### Scenario: 购买90天套餐
|
||||
- **GIVEN** 系统时间为 2026-12-01 10:00:00
|
||||
- **WHEN** 用户购买90天套餐（calendar_type=by_day, duration_days=90）并激活
|
||||
- **THEN** 套餐 activated_at=2026-12-01 10:00:00，expires_at=2027-02-28 23:59:59
|
||||
- **AND** 正确跨年计算
|
||||
|
||||
#### Scenario: 跨年购买按天套餐（边界条件）
|
||||
- **GIVEN** 系统时间为 2026-12-20 10:00:00
|
||||
- **WHEN** 用户购买20天套餐（calendar_type=by_day, duration_days=20）并激活
|
||||
- **THEN** 套餐 activated_at=2026-12-20 10:00:00，expires_at=2027-01-08 23:59:59
|
||||
- **AND** 正确跨年计算（12月20日 + 20天 = 1月8日）
|
||||
|
||||
#### Scenario: 闰年按天套餐（边界条件）
|
||||
- **GIVEN** 系统时间为 2028-02-15 10:00:00（2028 年是闰年）
|
||||
- **WHEN** 用户购买30天套餐（calendar_type=by_day, duration_days=30）并激活
|
||||
- **THEN** 套餐 expires_at=2028-03-15 23:59:59
|
||||
- **AND** 正确处理闰年 2月有 29 天
|
||||
|
||||
#### Scenario: 按天套餐与自然月套餐对比（业务理解）
|
||||
- **GIVEN** 系统时间为 2026-01-31 10:00:00
|
||||
- **WHEN** 用户购买30天套餐（calendar_type=by_day, duration_days=30）并激活
|
||||
- **THEN** 套餐 expires_at=2026-03-01 23:59:59
|
||||
- **AND** 如果购买自然月套餐（duration_months=1），expires_at=2026-01-31 23:59:59
|
||||
- **AND** 按天套餐用户获得完整 30 天，更公平
|
||||
|
||||
#### Scenario: 1天套餐（边界条件）
|
||||
- **GIVEN** 系统时间为 2026-01-15 23:30:00
|
||||
- **WHEN** 用户购买1天套餐（calendar_type=by_day, duration_days=1）并激活
|
||||
- **THEN** 套餐 activated_at=2026-01-15 23:30:00，expires_at=2026-01-15 23:59:59
|
||||
- **AND** 实际有效期仅剩 29 分钟（业务允许，用户自行承担）
|
||||
|
||||
#### Scenario: 365天套餐（年卡）
|
||||
- **GIVEN** 系统时间为 2026-01-01 00:00:00
|
||||
- **WHEN** 用户购买365天套餐（calendar_type=by_day, duration_days=365）并激活
|
||||
- **THEN** 套餐 expires_at=2026-12-31 23:59:59
|
||||
- **AND** 精确一年有效期
|
||||
|
||||
### Requirement: 套餐周期类型可配置
|
||||
系统 SHALL 允许管理员在创建套餐时指定 calendar_type，可选值为 natural_month 或 by_day。
|
||||
|
||||
**业务规则**：
|
||||
- calendar_type 必填，默认值为 `by_day`（向后兼容）
|
||||
- natural_month 时必须提供 duration_months（1-120）
|
||||
- by_day 时必须提供 duration_days（1-3650）
|
||||
- 不允许同时指定 duration_months 和 duration_days（冗余）
|
||||
|
||||
**数据验证**：
|
||||
- calendar_type ∈ {natural_month, by_day}
|
||||
- duration_months ∈ [1, 120]（最长10年）
|
||||
- duration_days ∈ [1, 3650]（最长10年）
|
||||
|
||||
#### Scenario: 创建自然月套餐（成功）
|
||||
- **GIVEN** 管理员已登录后台系统
|
||||
- **WHEN** 管理员通过 POST /api/admin/packages 创建套餐
|
||||
- **AND** 请求体包含 calendar_type=natural_month, duration_months=3, package_name="联通季卡"
|
||||
- **THEN** 系统返回 200，响应数据包含 calendar_type=natural_month, duration_months=3
|
||||
- **AND** 数据库 tb_package 表新增一条记录，calendar_type=natural_month
|
||||
|
||||
#### Scenario: 创建按天套餐（成功）
|
||||
- **GIVEN** 管理员已登录后台系统
|
||||
- **WHEN** 管理员通过 POST /api/admin/packages 创建套餐
|
||||
- **AND** 请求体包含 calendar_type=by_day, duration_days=60, package_name="60天卡"
|
||||
- **THEN** 系统返回 200，响应数据包含 calendar_type=by_day, duration_days=60
|
||||
- **AND** 数据库 tb_package 表新增一条记录，calendar_type=by_day, duration_days=60
|
||||
|
||||
#### Scenario: 自然月套餐缺少 duration_months（参数验证失败）
|
||||
- **GIVEN** 管理员已登录后台系统
|
||||
- **WHEN** 管理员通过 POST /api/admin/packages 创建套餐
|
||||
- **AND** 请求体包含 calendar_type=natural_month 但未提供 duration_months
|
||||
- **THEN** 系统返回错误 400，错误消息："自然月套餐必须指定 duration_months"
|
||||
- **AND** 数据库无新增记录
|
||||
|
||||
#### Scenario: 按天套餐缺少 duration_days（参数验证失败）
|
||||
- **GIVEN** 管理员已登录后台系统
|
||||
- **WHEN** 管理员通过 POST /api/admin/packages 创建套餐
|
||||
- **AND** 请求体包含 calendar_type=by_day 但未提供 duration_days
|
||||
- **THEN** 系统返回错误 400，错误消息："按天套餐必须指定 duration_days"
|
||||
- **AND** 数据库无新增记录
|
||||
|
||||
#### Scenario: calendar_type 非法值（参数验证失败）
|
||||
- **GIVEN** 管理员已登录后台系统
|
||||
- **WHEN** 管理员通过 POST /api/admin/packages 创建套餐
|
||||
- **AND** 请求体包含 calendar_type=weekly（非法值）
|
||||
- **THEN** 系统返回错误 400，错误消息："calendar_type 只能为 natural_month 或 by_day"
|
||||
- **AND** 数据库无新增记录
|
||||
|
||||
#### Scenario: duration_months 超出范围（参数验证失败）
|
||||
- **GIVEN** 管理员已登录后台系统
|
||||
- **WHEN** 管理员通过 POST /api/admin/packages 创建套餐
|
||||
- **AND** 请求体包含 calendar_type=natural_month, duration_months=150（超出范围）
|
||||
- **THEN** 系统返回错误 400，错误消息："duration_months 必须在 1-120 之间"
|
||||
- **AND** 数据库无新增记录
|
||||
|
||||
#### Scenario: duration_days 超出范围（参数验证失败）
|
||||
- **GIVEN** 管理员已登录后台系统
|
||||
- **WHEN** 管理员通过 POST /api/admin/packages 创建套餐
|
||||
- **AND** 请求体包含 calendar_type=by_day, duration_days=5000（超出范围）
|
||||
- **THEN** 系统返回错误 400，错误消息："duration_days 必须在 1-3650 之间"
|
||||
- **AND** 数据库无新增记录
|
||||
|
||||
#### Scenario: 同时提供 duration_months 和 duration_days（参数冗余）
|
||||
- **GIVEN** 管理员已登录后台系统
|
||||
- **WHEN** 管理员通过 POST /api/admin/packages 创建套餐
|
||||
- **AND** 请求体包含 calendar_type=natural_month, duration_months=3, duration_days=90
|
||||
- **THEN** 系统返回错误 400，错误消息："不允许同时指定 duration_months 和 duration_days"
|
||||
- **AND** 数据库无新增记录
|
||||
|
||||
### Requirement: 套餐激活时根据类型计算到期时间
|
||||
系统 SHALL 在套餐激活时，根据 calendar_type 自动计算并设置 expires_at。
|
||||
|
||||
**计算时机**：
|
||||
- 订单创建时不计算（activated_at 和 expires_at 均为 NULL）
|
||||
- 套餐激活时才计算（首次实名激活、主套餐排队激活、立即激活）
|
||||
|
||||
**计算公式**：
|
||||
- 自然月：`expires_at = (activated_at 月份 + duration_months) 的月末 23:59:59`
|
||||
- 按天：`expires_at = (activated_at 日期 + duration_days) 的 23:59:59`
|
||||
|
||||
**幂等性保证**：
|
||||
- 同一套餐多次调用激活接口，expires_at 不变（使用已有的 activated_at 计算）
|
||||
|
||||
#### Scenario: 激活自然月套餐
|
||||
- **GIVEN** PackageUsage 记录 status=0, package.calendar_type=natural_month, package.duration_months=1
|
||||
- **WHEN** 套餐激活，activated_at 设置为 2026-02-15 10:00:00
|
||||
- **THEN** 系统计算 expires_at=2026-02-28 23:59:59
|
||||
- **AND** PackageUsage.status 更新为 1（生效中）
|
||||
|
||||
#### Scenario: 激活按天套餐
|
||||
- **GIVEN** PackageUsage 记录 status=0, package.calendar_type=by_day, package.duration_days=30
|
||||
- **WHEN** 套餐激活，activated_at 设置为 2026-02-15 10:00:00
|
||||
- **THEN** 系统计算 expires_at=2026-03-16 23:59:59
|
||||
- **AND** PackageUsage.status 更新为 1（生效中）
|
||||
|
||||
#### Scenario: 激活时处理闰年（自然月）
|
||||
- **GIVEN** PackageUsage 记录 status=0, package.calendar_type=natural_month, package.duration_months=1
|
||||
- **WHEN** 套餐激活，activated_at 设置为 2028-02-15 10:00:00（闰年）
|
||||
- **THEN** 系统计算 expires_at=2028-02-29 23:59:59
|
||||
- **AND** 正确识别闰年，2月为 29 日
|
||||
|
||||
#### Scenario: 激活时处理跨年（自然月）
|
||||
- **GIVEN** PackageUsage 记录 status=0, package.calendar_type=natural_month, package.duration_months=3
|
||||
- **WHEN** 套餐激活，activated_at 设置为 2026-11-15 10:00:00
|
||||
- **THEN** 系统计算 expires_at=2027-02-28 23:59:59
|
||||
- **AND** 正确跨年计算（11月 + 3个月 = 次年2月）
|
||||
|
||||
#### Scenario: 重复激活请求（幂等性保证）
|
||||
- **GIVEN** PackageUsage 记录 status=1, activated_at=2026-02-15 10:00:00, expires_at=2026-02-28 23:59:59
|
||||
- **WHEN** 再次调用激活接口（重试或并发请求）
|
||||
- **THEN** 系统检测到 status=1，直接返回成功，不重新计算 expires_at
|
||||
- **AND** expires_at 保持不变
|
||||
|
||||
#### Scenario: 激活失败回滚（异常处理）
|
||||
- **GIVEN** PackageUsage 记录 status=0
|
||||
- **WHEN** 套餐激活过程中数据库更新失败（例如网络中断）
|
||||
- **THEN** 系统事务回滚，PackageUsage.status 保持为 0
|
||||
- **AND** activated_at 和 expires_at 均为 NULL
|
||||
- **AND** 返回错误消息："套餐激活失败，请重试"
|
||||
|
||||
### Requirement: 套餐类型信息可查询
|
||||
系统 SHALL 在套餐详情和列表 API 中返回 calendar_type 和对应的 duration 字段。
|
||||
|
||||
**API 响应格式**：
|
||||
- 自然月套餐：返回 `calendar_type`, `duration_months`, `duration_days=null`
|
||||
- 按天套餐：返回 `calendar_type`, `duration_days`, `duration_months=null`
|
||||
|
||||
**性能要求**：
|
||||
- 套餐详情查询 P95 < 50ms
|
||||
- 套餐列表查询 P95 < 200ms（分页，每页最多 100 条）
|
||||
|
||||
#### Scenario: 查询自然月套餐详情
|
||||
- **GIVEN** 数据库存在套餐 ID=123，calendar_type=natural_month, duration_months=12
|
||||
- **WHEN** 用户通过 GET /api/admin/packages/123 查询套餐
|
||||
- **THEN** 系统返回 200，响应 JSON 包含：
|
||||
```json
|
||||
{
|
||||
"id": 123,
|
||||
"calendar_type": "natural_month",
|
||||
"duration_months": 12,
|
||||
"duration_days": null
|
||||
}
|
||||
```
|
||||
|
||||
#### Scenario: 查询按天套餐详情
|
||||
- **GIVEN** 数据库存在套餐 ID=456，calendar_type=by_day, duration_days=90
|
||||
- **WHEN** 用户通过 GET /api/admin/packages/456 查询套餐
|
||||
- **THEN** 系统返回 200，响应 JSON 包含：
|
||||
```json
|
||||
{
|
||||
"id": 456,
|
||||
"calendar_type": "by_day",
|
||||
"duration_days": 90,
|
||||
"duration_months": null
|
||||
}
|
||||
```
|
||||
|
||||
#### Scenario: 套餐列表显示类型
|
||||
- **GIVEN** 数据库存在 50 个套餐，包含自然月和按天两种类型
|
||||
- **WHEN** 管理员通过 GET /api/admin/packages?page=1&page_size=20 获取套餐列表
|
||||
- **THEN** 系统返回 200，响应包含 20 个套餐数据
|
||||
- **AND** 每个套餐数据包含 calendar_type 字段
|
||||
- **AND** 响应时间 < 200ms（P95）
|
||||
|
||||
#### Scenario: 查询不存在的套餐（错误处理）
|
||||
- **GIVEN** 数据库不存在套餐 ID=999
|
||||
- **WHEN** 用户通过 GET /api/admin/packages/999 查询套餐
|
||||
- **THEN** 系统返回 404，错误消息："套餐不存在"
|
||||
|
||||
### Requirement: 套餐类型可更新
|
||||
系统 SHALL 允许管理员更新套餐的 calendar_type 和 duration 字段（仅限未生效的套餐）。
|
||||
|
||||
**更新限制**：
|
||||
- 已有生效中 PackageUsage 记录的套餐，禁止修改 calendar_type 和 duration
|
||||
- 只允许修改处于"下架"状态（shelf_status=2）且无生效中使用记录的套餐
|
||||
|
||||
#### Scenario: 更新下架套餐的类型（成功）
|
||||
- **GIVEN** 套餐 ID=123, shelf_status=2（下架），无生效中 PackageUsage 记录
|
||||
- **WHEN** 管理员通过 PUT /api/admin/packages/123 更新套餐
|
||||
- **AND** 请求体包含 calendar_type=by_day, duration_days=60（从自然月改为按天）
|
||||
- **THEN** 系统返回 200，套餐更新成功
|
||||
- **AND** 数据库 calendar_type 更新为 by_day, duration_days=60, duration_months=null
|
||||
|
||||
#### Scenario: 更新已上架套餐（禁止）
|
||||
- **GIVEN** 套餐 ID=123, shelf_status=1（上架），有生效中 PackageUsage 记录
|
||||
- **WHEN** 管理员通过 PUT /api/admin/packages/123 更新套餐
|
||||
- **AND** 请求体包含 calendar_type=by_day
|
||||
- **THEN** 系统返回错误 400，错误消息："该套餐有生效中的使用记录，禁止修改类型"
|
||||
- **AND** 数据库不更新
|
||||
|
||||
#### Scenario: 更新套餐其他字段（允许）
|
||||
- **GIVEN** 套餐 ID=123, shelf_status=1（上架），有生效中 PackageUsage 记录
|
||||
- **WHEN** 管理员通过 PUT /api/admin/packages/123 更新套餐
|
||||
- **AND** 请求体仅包含 suggested_retail_price=5000（修改价格，不修改类型）
|
||||
- **THEN** 系统返回 200，价格更新成功
|
||||
- **AND** calendar_type 和 duration 保持不变
|
||||
|
||||
## 数据一致性保证
|
||||
|
||||
1. **套餐激活时的并发控制**：使用 Redis 分布式锁（key: `package:activation:lock:{usage_id}`），TTL=30s
|
||||
2. **expires_at 精度要求**：数据库字段类型为 `timestamp`，精确到秒
|
||||
3. **时区统一**：所有时间计算使用服务器时区（Asia/Shanghai）
|
||||
4. **闰年判断准确性**：使用 Go 标准库 `time.Date()` 自动处理闰年
|
||||
|
||||
## 性能指标
|
||||
|
||||
| 操作 | 性能要求 | 监控指标 |
|
||||
|------|---------|---------|
|
||||
| 套餐创建 API | P95 < 100ms | API 响应时间 |
|
||||
| 套餐查询 API | P95 < 50ms | 数据库查询时间 |
|
||||
| 套餐激活计算 | < 10ms | 有效期计算耗时 |
|
||||
| 套餐列表 API | P95 < 200ms | API 响应时间 |
|
||||
|
||||
## 错误码定义
|
||||
|
||||
| 错误码 | HTTP 状态码 | 错误消息 | 场景 |
|
||||
|--------|------------|---------|------|
|
||||
| CodeInvalidParam | 400 | 自然月套餐必须指定 duration_months | 参数验证失败 |
|
||||
| CodeInvalidParam | 400 | 按天套餐必须指定 duration_days | 参数验证失败 |
|
||||
| CodeInvalidParam | 400 | calendar_type 只能为 natural_month 或 by_day | 参数验证失败 |
|
||||
| CodeInvalidParam | 400 | duration_months 必须在 1-120 之间 | 参数验证失败 |
|
||||
| CodeInvalidParam | 400 | duration_days 必须在 1-3650 之间 | 参数验证失败 |
|
||||
| CodeForbidden | 403 | 该套餐有生效中的使用记录，禁止修改类型 | 业务规则限制 |
|
||||
| CodeNotFound | 404 | 套餐不存在 | 资源不存在 |
|
||||
|
||||
## 数据迁移策略
|
||||
|
||||
**激进策略**（开发阶段）：
|
||||
1. **历史套餐数据强制转换**：
|
||||
- 现有套餐统一设置 `calendar_type=by_day`
|
||||
- 根据 `duration_months` 计算 `duration_days = duration_months * 30`
|
||||
- 数据迁移后，所有套餐都有明确的 `calendar_type` 和对应的 `duration` 字段
|
||||
|
||||
2. **历史 PackageUsage 数据处理**：
|
||||
- 保留 `activated_at` 和 `expires_at`（不重新计算）
|
||||
- 新增 `calendar_type`, `data_reset_cycle` 字段，从关联的 Package 复制
|
||||
|
||||
3. **API 破坏性变更**：
|
||||
- `calendar_type` 字段**必填**，无默认值
|
||||
- 创建套餐时必须明确指定 `calendar_type` 和对应的 `duration` 字段
|
||||
- 不支持只提供 `duration_months` 而不指定 `calendar_type` 的旧请求
|
||||
809
openspec/specs/package-data-reset/spec.md
Normal file
809
openspec/specs/package-data-reset/spec.md
Normal file
@@ -0,0 +1,809 @@
|
||||
# Spec: 套餐流量重置周期管理
|
||||
|
||||
## 业务背景
|
||||
|
||||
### 为什么需要流量重置周期管理
|
||||
|
||||
**现状问题**：
|
||||
- 运营商套餐的流量重置规则多样：按日、按月、按年、不重置
|
||||
- 套餐有效期与流量重置周期是两个独立维度（如12个月套餐可按月重置流量）
|
||||
- 不同运营商有特殊规则（如联通按27号重置，而非1号）
|
||||
- 用户需要清晰知道流量何时重置，避免超额使用
|
||||
|
||||
**业务目标**：
|
||||
- 支持灵活配置流量重置周期（daily/monthly/yearly/none）
|
||||
- 流量重置周期独立于套餐有效期类型
|
||||
- 自动调度流量重置任务（定时任务）
|
||||
- 保留历史流量使用记录，仅重置当前累计值
|
||||
|
||||
---
|
||||
|
||||
## 业务规则
|
||||
|
||||
### 1. 重置周期类型
|
||||
|
||||
| data_reset_cycle | 说明 | 重置时间点 | 适用场景 |
|
||||
|------------------|------|-----------|---------|
|
||||
| `daily` | 按日重置 | 每天 00:00:00 | 日租卡、按日计费套餐 |
|
||||
| `monthly` | 按月重置 | 每月1号 00:00:00（联通27号） | 月租套餐、年套餐按月清零 |
|
||||
| `yearly` | 按年重置 | 每年1月1日 00:00:00 | 年度套餐 |
|
||||
| `none` | 不重置 | 永不重置 | 一次性流量包 |
|
||||
|
||||
### 2. 重置时间点规则
|
||||
|
||||
**通用规则**：
|
||||
```
|
||||
每日重置：
|
||||
- 触发时间：每天 00:00:00
|
||||
- 重置对象：data_reset_cycle=daily AND status=1（生效中）
|
||||
|
||||
每月重置：
|
||||
- 通用触发时间：每月1号 00:00:00
|
||||
- 联通特殊规则：每月27号 00:00:00
|
||||
- 重置对象：data_reset_cycle=monthly AND status=1（生效中）
|
||||
|
||||
每年重置：
|
||||
- 触发时间：每年1月1日 00:00:00
|
||||
- 重置对象：data_reset_cycle=yearly AND status=1（生效中）
|
||||
```
|
||||
|
||||
**联通特殊规则**：
|
||||
- 如果套餐的 `isp=unicom`（联通），`data_reset_cycle=monthly` → 每月27号00:00:00重置
|
||||
- 其他运营商按1号重置
|
||||
|
||||
### 3. 重置逻辑
|
||||
|
||||
重置流量时的操作：
|
||||
|
||||
```
|
||||
重置流程：
|
||||
1. 查询需要重置的套餐（根据 data_reset_cycle 和 status=1）
|
||||
2. 批量更新：
|
||||
- data_usage_mb = 0
|
||||
- last_reset_at = 当前时间
|
||||
3. 不删除 PackageUsageDailyRecord 历史记录
|
||||
4. 记录重置日志
|
||||
```
|
||||
|
||||
**不重置的内容**：
|
||||
- ❌ PackageUsageDailyRecord 历史记录（保留）
|
||||
- ❌ 套餐有效期（expires_at 不变）
|
||||
- ❌ 套餐状态（status 不变）
|
||||
- ✅ 仅重置 data_usage_mb = 0
|
||||
|
||||
### 4. 重置条件
|
||||
|
||||
仅对以下套餐执行重置：
|
||||
- `status=1`（生效中）
|
||||
- `data_reset_cycle != none`
|
||||
- `expires_at > 当前时间`（未过期）
|
||||
|
||||
**不重置的套餐**：
|
||||
- status=0（待生效）
|
||||
- status=2（已用完）
|
||||
- status=3（已过期）
|
||||
- status=4（已失效）
|
||||
- data_reset_cycle=none（不重置）
|
||||
|
||||
### 5. 流量重置与套餐有效期独立
|
||||
|
||||
流量重置周期与套餐有效期类型独立：
|
||||
|
||||
| 套餐配置 | 流量重置行为 | 举例 |
|
||||
|---------|-------------|------|
|
||||
| 12个月套餐 + monthly | 每月1号重置流量，共重置12次 | 年套餐按月清零 |
|
||||
| 12个月套餐 + yearly | 激活时清零，12个月内不重置 | 年度总量套餐 |
|
||||
| 30天套餐 + daily | 每天0点重置流量，共重置30次 | 日租卡 |
|
||||
| 30天套餐 + none | 30天内累计使用，不重置 | 一次性流量包 |
|
||||
|
||||
---
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 支持流量重置周期配置
|
||||
|
||||
系统 SHALL 支持为套餐配置流量重置周期（data_reset_cycle），可选值为 daily、monthly、yearly、none。
|
||||
|
||||
#### Scenario: 创建按日重置的套餐
|
||||
- **WHEN** 管理员创建套餐时指定 data_reset_cycle=daily
|
||||
- **THEN** 系统创建成功，套餐的 data_reset_cycle=daily
|
||||
|
||||
#### Scenario: 创建按月重置的套餐
|
||||
- **WHEN** 管理员创建套餐时指定 data_reset_cycle=monthly
|
||||
- **THEN** 系统创建成功，套餐的 data_reset_cycle=monthly
|
||||
|
||||
#### Scenario: 创建按年重置的套餐
|
||||
- **WHEN** 管理员创建套餐时指定 data_reset_cycle=yearly
|
||||
- **THEN** 系统创建成功，套餐的 data_reset_cycle=yearly
|
||||
|
||||
#### Scenario: 创建不重置流量的套餐
|
||||
- **WHEN** 管理员创建套餐时指定 data_reset_cycle=none
|
||||
- **THEN** 系统创建成功，套餐的 data_reset_cycle=none
|
||||
|
||||
#### Scenario: 更新套餐的重置周期配置
|
||||
- **GIVEN** 套餐 ID=123，data_reset_cycle=monthly
|
||||
- **WHEN** 管理员更新套餐配置为 data_reset_cycle=daily
|
||||
- **THEN** 系统更新成功，该套餐后续流量重置遵循新配置
|
||||
- **AND** 已有的 PackageUsage 不受影响（仍按原配置重置）
|
||||
|
||||
### Requirement: 流量重置周期独立于套餐有效期
|
||||
|
||||
系统 SHALL 允许套餐的流量重置周期与套餐有效期类型独立配置。
|
||||
|
||||
#### Scenario: 12个月套餐按月重置流量
|
||||
- **GIVEN** 套餐配置为 duration_months=12, data_reset_cycle=monthly
|
||||
- **WHEN** 套餐在 2026-02-01 激活
|
||||
- **THEN** 套餐有效期到 2027-01-31，流量在每月1号重置（共12次）
|
||||
|
||||
#### Scenario: 12个月套餐按年重置流量
|
||||
- **GIVEN** 套餐配置为 duration_months=12, data_reset_cycle=yearly
|
||||
- **WHEN** 套餐在 2026-02-01 激活
|
||||
- **THEN** 套餐有效期到 2027-01-31，流量仅在激活时清零，12个月内不重置
|
||||
|
||||
#### Scenario: 30天套餐按日重置流量
|
||||
- **GIVEN** 套餐配置为 duration_days=30, data_reset_cycle=daily
|
||||
- **WHEN** 套餐在 2026-02-01 激活
|
||||
- **THEN** 套餐有效期到 2026-03-02，流量每天0点重置（共30次）
|
||||
|
||||
#### Scenario: 自然月套餐按月重置
|
||||
- **GIVEN** 套餐配置为 calendar_type=natural_month, duration_months=1, data_reset_cycle=monthly
|
||||
- **WHEN** 套餐在 2026-02-15 激活
|
||||
- **THEN** 套餐有效期到 2026-02-28，流量在3月1日不重置（因为套餐已过期）
|
||||
|
||||
### Requirement: 每日流量重置调度
|
||||
|
||||
系统 SHALL 每天 00:00:00 自动重置所有 data_reset_cycle=daily 的生效中套餐的 data_usage_mb 为 0。
|
||||
|
||||
#### Scenario: 每日流量重置成功
|
||||
- **GIVEN** 系统时间到达 2026-02-11 00:00:00
|
||||
- **AND** 存在3个 data_reset_cycle=daily 且 status=1 的套餐
|
||||
- **WHEN** 定时任务执行
|
||||
- **THEN** 系统批量更新这3个套餐：
|
||||
- data_usage_mb = 0
|
||||
- last_reset_at = 2026-02-11 00:00:00
|
||||
|
||||
#### Scenario: 非每日重置套餐不受影响
|
||||
- **GIVEN** 系统时间到达 2026-02-11 00:00:00
|
||||
- **AND** 存在 data_reset_cycle=monthly 的套餐
|
||||
- **WHEN** 定时任务执行
|
||||
- **THEN** 这些套餐的 data_usage_mb 不变
|
||||
|
||||
#### Scenario: 待生效和已过期套餐不重置
|
||||
- **GIVEN** 系统时间到达 2026-02-11 00:00:00
|
||||
- **AND** 存在 data_reset_cycle=daily 但 status=0（待生效）的套餐
|
||||
- **AND** 存在 data_reset_cycle=daily 但 status=3（已过期）的套餐
|
||||
- **WHEN** 定时任务执行
|
||||
- **THEN** 这些套餐不被重置
|
||||
|
||||
#### Scenario: 每日重置记录到日志
|
||||
- **GIVEN** 系统时间到达 2026-02-11 00:00:00
|
||||
- **AND** 重置了5个套餐
|
||||
- **WHEN** 定时任务执行完成
|
||||
- **THEN** 系统记录 Info 日志：
|
||||
- "每日流量重置完成，重置套餐数量：5"
|
||||
|
||||
### Requirement: 每月流量重置调度
|
||||
|
||||
系统 SHALL 每月1号 00:00:00 自动重置所有 data_reset_cycle=monthly 的生效中套餐的 data_usage_mb 为 0。
|
||||
|
||||
#### Scenario: 每月流量重置成功
|
||||
- **GIVEN** 系统时间到达 2026-03-01 00:00:00
|
||||
- **AND** 存在5个 data_reset_cycle=monthly 且 status=1 的套餐（非联通）
|
||||
- **WHEN** 定时任务执行
|
||||
- **THEN** 系统批量更新这5个套餐：
|
||||
- data_usage_mb = 0
|
||||
- last_reset_at = 2026-03-01 00:00:00
|
||||
|
||||
#### Scenario: 联通运营商特殊重置周期
|
||||
- **GIVEN** 系统时间到达 2026-02-27 00:00:00
|
||||
- **AND** 存在3个 data_reset_cycle=monthly 且 isp=unicom 且 status=1 的套餐
|
||||
- **WHEN** 定时任务执行
|
||||
- **THEN** 系统批量更新这3个套餐：
|
||||
- data_usage_mb = 0
|
||||
- last_reset_at = 2026-02-27 00:00:00
|
||||
|
||||
#### Scenario: 跨月边界流量统计
|
||||
- **GIVEN** 套餐在 2026-01-31 23:50:00 使用了 5GB 流量
|
||||
- **AND** data_usage_mb = 5GB
|
||||
- **WHEN** 系统时间到达 2026-02-01 00:00:00，触发重置
|
||||
- **THEN** 套餐的 data_usage_mb 重置为 0
|
||||
- **AND** 1月31日的 PackageUsageDailyRecord 仍存在（data_usage_mb=5GB）
|
||||
|
||||
#### Scenario: 跨年边界流量重置
|
||||
- **GIVEN** 套餐在 2026-12-31 使用了 10GB 流量
|
||||
- **WHEN** 系统时间到达 2027-01-01 00:00:00，触发重置
|
||||
- **THEN** 套餐的 data_usage_mb 重置为 0
|
||||
- **AND** 2026年12月的日记录仍存在
|
||||
|
||||
### Requirement: 每年流量重置调度
|
||||
|
||||
系统 SHALL 每年1月1日 00:00:00 自动重置所有 data_reset_cycle=yearly 的生效中套餐的 data_usage_mb 为 0。
|
||||
|
||||
#### Scenario: 每年流量重置成功
|
||||
- **GIVEN** 系统时间到达 2027-01-01 00:00:00
|
||||
- **AND** 存在2个 data_reset_cycle=yearly 且 status=1 的套餐
|
||||
- **WHEN** 定时任务执行
|
||||
- **THEN** 系统批量更新这2个套餐：
|
||||
- data_usage_mb = 0
|
||||
- last_reset_at = 2027-01-01 00:00:00
|
||||
|
||||
#### Scenario: 12个月套餐按年重置
|
||||
- **GIVEN** 套餐在 2026-06-15 激活，duration_months=12，data_reset_cycle=yearly
|
||||
- **AND** expires_at=2027-06-15
|
||||
- **WHEN** 系统时间到达 2027-01-01 00:00:00
|
||||
- **THEN** 套餐流量重置（因为仍在有效期内）
|
||||
|
||||
#### Scenario: 已过期的年套餐不重置
|
||||
- **GIVEN** 套餐在 2025-06-15 激活，duration_months=12，data_reset_cycle=yearly
|
||||
- **AND** expires_at=2026-06-15（已过期）
|
||||
- **WHEN** 系统时间到达 2027-01-01 00:00:00
|
||||
- **THEN** 套餐不被重置（status=3）
|
||||
|
||||
### Requirement: 不重置流量的套餐
|
||||
|
||||
系统 SHALL 对 data_reset_cycle=none 的套餐，在整个有效期内不重置 data_usage_mb。
|
||||
|
||||
#### Scenario: 套餐有效期内流量不重置
|
||||
- **GIVEN** 套餐 data_reset_cycle=none，duration_days=30
|
||||
- **AND** 套餐在 2026-02-01 激活
|
||||
- **WHEN** 套餐在30天内使用了 80GB 流量
|
||||
- **THEN** data_usage_mb 累计为 80GB，期间从未重置
|
||||
|
||||
#### Scenario: 新激活时流量清零
|
||||
- **GIVEN** 套餐 data_reset_cycle=none
|
||||
- **WHEN** 套餐首次激活
|
||||
- **THEN** data_usage_mb 初始化为 0
|
||||
|
||||
#### Scenario: 不重置套餐不被定时任务影响
|
||||
- **GIVEN** 系统时间到达每日/每月/每年重置时刻
|
||||
- **AND** 存在 data_reset_cycle=none 的套餐
|
||||
- **WHEN** 定时任务执行
|
||||
- **THEN** 这些套餐不被查询，不执行任何操作
|
||||
|
||||
### Requirement: 流量重置周期信息可查询
|
||||
|
||||
系统 SHALL 在套餐详情和使用记录 API 中返回 data_reset_cycle 和 last_reset_at。
|
||||
|
||||
#### Scenario: 查询套餐流量重置配置
|
||||
- **WHEN** 用户通过 GET /api/admin/packages/:id 查询套餐
|
||||
- **THEN** 响应包含：
|
||||
```json
|
||||
{
|
||||
"data_reset_cycle": "monthly",
|
||||
"isp": "unicom"
|
||||
}
|
||||
```
|
||||
|
||||
#### Scenario: 查询套餐使用记录的重置信息
|
||||
- **WHEN** 用户通过 GET /api/admin/package-usage/:id 查询套餐使用记录
|
||||
- **THEN** 响应包含：
|
||||
```json
|
||||
{
|
||||
"data_reset_cycle": "monthly",
|
||||
"last_reset_at": "2026-02-27T00:00:00Z",
|
||||
"data_usage_mb": 1024
|
||||
}
|
||||
```
|
||||
|
||||
#### Scenario: 客户端查询流量重置信息
|
||||
- **WHEN** 客户通过 GET /api/customer/package-usage 查询自己的套餐
|
||||
- **THEN** 响应包含 data_reset_cycle 和 last_reset_at，方便用户知道下次重置时间
|
||||
|
||||
### Requirement: 流量重置不影响日记录
|
||||
|
||||
系统 SHALL 在流量重置时保留历史日记录（PackageUsageDailyRecord），仅重置当前 data_usage_mb。
|
||||
|
||||
#### Scenario: 重置后历史记录可查
|
||||
- **GIVEN** 套餐在 2026-02-28 使用了 10GB 流量
|
||||
- **AND** PackageUsageDailyRecord 记录了 2026-02-28 的 10GB 使用量
|
||||
- **WHEN** 系统时间到达 2026-03-01 00:00:00，触发重置
|
||||
- **THEN** 套餐的 data_usage_mb 重置为 0
|
||||
- **AND** 2026-02-28 的 PackageUsageDailyRecord 记录仍存在且可查询
|
||||
|
||||
#### Scenario: 重置后新的流量使用
|
||||
- **GIVEN** 套餐在 2026-03-01 00:00:00 重置后，data_usage_mb=0
|
||||
- **WHEN** 2026-03-01 10:00:00 使用了 2GB 流量
|
||||
- **THEN** 套餐的 data_usage_mb=2GB
|
||||
- **AND** 写入新的 PackageUsageDailyRecord（date=2026-03-01, data_usage_mb=2GB）
|
||||
|
||||
---
|
||||
|
||||
## 边界条件
|
||||
|
||||
### 1. 跨月边界
|
||||
|
||||
- **场景**：套餐在月末23:59:59使用流量，次月0:00:00触发重置
|
||||
- **处理**：
|
||||
- 重置任务在 00:00:00 执行
|
||||
- 月末最后一笔流量扣减已提交（日记录已写入）
|
||||
- 重置时仅清零 data_usage_mb，不影响日记录
|
||||
|
||||
### 2. 跨年边界
|
||||
|
||||
- **场景**：套餐在12月31日使用流量，1月1日触发年度重置
|
||||
- **处理**：
|
||||
- 与跨月边界相同
|
||||
- 年度重置只重置 data_reset_cycle=yearly 的套餐
|
||||
- 月度重置套餐不受年度重置影响
|
||||
|
||||
### 3. 并发流量扣减和重置
|
||||
|
||||
- **场景**：重置任务执行的同时，有流量扣减请求
|
||||
- **处理**：
|
||||
- 使用行锁：`SELECT * FROM package_usage WHERE id=? FOR UPDATE`
|
||||
- 先完成的操作生效，后完成的操作基于新值执行
|
||||
- 如果重置先完成 → 流量扣减从0开始累加
|
||||
- 如果扣减先完成 → 重置清零后续扣减继续
|
||||
|
||||
### 4. 定时任务执行延迟
|
||||
|
||||
- **场景**：定时任务因系统负载延迟到 00:05:00 才执行
|
||||
- **处理**：
|
||||
- 仍按计划重置所有符合条件的套餐
|
||||
- last_reset_at 记录实际重置时间（00:05:00）
|
||||
- 不影响下次重置周期（仍按 00:00:00 计算）
|
||||
|
||||
### 5. 套餐过期与重置时间重合
|
||||
|
||||
- **场景**：套餐在 2026-03-01 00:00:00 过期，同时触发月度重置
|
||||
- **处理**：
|
||||
- 过期任务将套餐 status=3
|
||||
- 重置任务查询时排除 status=3 的套餐
|
||||
- 不执行重置操作
|
||||
|
||||
---
|
||||
|
||||
## 并发场景
|
||||
|
||||
### Scenario: 并发流量扣减和重置
|
||||
- **GIVEN** 套餐 ID=123，data_usage_mb=5GB
|
||||
- **WHEN** 同时发生：
|
||||
- 请求1：流量扣减 1GB
|
||||
- 请求2：定时任务重置流量
|
||||
- **THEN** 使用行锁：
|
||||
```sql
|
||||
SELECT * FROM package_usage WHERE id=123 FOR UPDATE
|
||||
```
|
||||
- **AND** 如果请求1先完成：
|
||||
- data_usage_mb = 6GB
|
||||
- 请求2重置 → data_usage_mb = 0
|
||||
- **AND** 如果请求2先完成：
|
||||
- data_usage_mb = 0
|
||||
- 请求1扣减 → data_usage_mb = 1GB
|
||||
|
||||
### Scenario: 并发多套餐重置
|
||||
- **GIVEN** 有1000个 data_reset_cycle=daily 的套餐
|
||||
- **WHEN** 定时任务批量重置
|
||||
- **THEN** 系统：
|
||||
- 分批处理（每批100个）
|
||||
- 每批使用单独事务
|
||||
- 失败批次记录日志，不影响其他批次
|
||||
|
||||
---
|
||||
|
||||
## 异常处理
|
||||
|
||||
### 1. 重置任务失败
|
||||
|
||||
- **错误场景**：定时任务执行时数据库连接失败
|
||||
- **处理流程**：
|
||||
1. 捕获错误，记录 Error 日志（包含失败原因、影响套餐数量）
|
||||
2. 使用 Asynq 重试机制（最多3次，间隔 10s/30s/60s）
|
||||
3. 重试前检查套餐 last_reset_at（避免重复重置）
|
||||
4. 3次失败后写入死信队列，发送告警
|
||||
- **返回错误**：不返回给用户（定时任务），仅记录日志
|
||||
|
||||
### 2. 批量重置部分失败
|
||||
|
||||
- **错误场景**：批量重置1000个套餐，第500个套餐更新失败
|
||||
- **处理流程**：
|
||||
1. 分批处理（每批100个），每批独立事务
|
||||
2. 失败批次回滚，其他批次正常提交
|
||||
3. 记录失败批次的套餐ID列表
|
||||
4. Asynq 重试失败批次
|
||||
- **返回错误**：不返回给用户（定时任务），仅记录日志
|
||||
|
||||
### 3. last_reset_at 更新失败
|
||||
|
||||
- **错误场景**：data_usage_mb 重置成功，但 last_reset_at 更新失败
|
||||
- **处理流程**：
|
||||
1. 使用事务包裹两个更新操作
|
||||
2. 任何一个失败 → 事务回滚，全部不更新
|
||||
3. 记录 Error 日志
|
||||
4. Asynq 重试
|
||||
- **返回错误**：不返回给用户（定时任务），仅记录日志
|
||||
|
||||
---
|
||||
|
||||
## 数据一致性保证
|
||||
|
||||
### 1. 事务边界
|
||||
|
||||
- **批量重置套餐**：每批使用单独事务，确保原子性
|
||||
- **流量扣减 + 重置并发**：使用行锁，确保顺序执行
|
||||
|
||||
### 2. 行锁机制
|
||||
|
||||
- **重置套餐时加锁**：`SELECT * FROM package_usage WHERE id IN (...) FOR UPDATE`
|
||||
- **流量扣减时加锁**：`SELECT * FROM package_usage WHERE id=? FOR UPDATE`
|
||||
|
||||
### 3. 幂等性保证
|
||||
|
||||
- **重置任务幂等**：重试前检查 last_reset_at，如果已是今日则跳过
|
||||
- **示例**：
|
||||
```sql
|
||||
UPDATE package_usage
|
||||
SET data_usage_mb = 0, last_reset_at = NOW()
|
||||
WHERE data_reset_cycle = 'daily'
|
||||
AND status = 1
|
||||
AND (last_reset_at IS NULL OR DATE(last_reset_at) < CURDATE());
|
||||
```
|
||||
|
||||
### 4. 数据校验
|
||||
|
||||
- **重置前**：校验套餐 status=1（生效中）
|
||||
- **重置前**：校验套餐 expires_at > 当前时间（未过期）
|
||||
- **重置后**：校验 data_usage_mb=0 且 last_reset_at 已更新
|
||||
|
||||
---
|
||||
|
||||
## 性能指标
|
||||
|
||||
| 操作 | 目标响应时间 | 并发要求 | 数据量 |
|
||||
|------|-------------|---------|--------|
|
||||
| 每日流量重置（单批） | < 500ms | 定时任务 | 批量更新（100个套餐/批） |
|
||||
| 每月流量重置（单批） | < 500ms | 定时任务 | 批量更新（100个套餐/批） |
|
||||
| 每年流量重置（单批） | < 500ms | 定时任务 | 批量更新（100个套餐/批） |
|
||||
| 查询重置周期配置 | < 50ms | 100 QPS | 单套餐查询 |
|
||||
|
||||
---
|
||||
|
||||
## 错误码定义
|
||||
|
||||
| 错误码 | HTTP 状态码 | 错误消息 | 场景 |
|
||||
|--------|------------|---------|------|
|
||||
| `RESET_TASK_FAILED` | 500 | 流量重置任务失败，请联系管理员 | 定时任务执行失败 |
|
||||
| `INVALID_RESET_CYCLE` | 400 | 无效的重置周期配置 | data_reset_cycle 值不合法 |
|
||||
| `LAST_RESET_AT_UPDATE_FAILED` | 500 | 更新重置时间失败 | last_reset_at 更新失败 |
|
||||
|
||||
---
|
||||
|
||||
## 数据迁移策略
|
||||
|
||||
**激进策略**（开发阶段，保证干净性）：
|
||||
|
||||
### 1. ❌ 要删除的字段
|
||||
|
||||
目前 `package` 表中可能存在的冗余字段（需确认后删除）：
|
||||
- 如果有 `reset_interval` 字段（旧的重置间隔） → **删除**
|
||||
- 如果有 `reset_day` 字段（旧的重置日期） → **删除**
|
||||
|
||||
目前 `package_usage` 表中可能存在的冗余字段（需确认后删除）：
|
||||
- 如果有 `last_reset_date` 字段（旧的重置日期，非时间戳） → **删除**
|
||||
|
||||
### 2. ✅ 新增的字段
|
||||
|
||||
在 `package` 表中新增：
|
||||
```sql
|
||||
ALTER TABLE package
|
||||
ADD COLUMN data_reset_cycle VARCHAR(10) DEFAULT 'none' COMMENT '流量重置周期（daily/monthly/yearly/none）',
|
||||
ADD COLUMN isp VARCHAR(20) DEFAULT NULL COMMENT '运营商（unicom/mobile/telecom，用于特殊重置规则）';
|
||||
|
||||
CREATE INDEX idx_data_reset_cycle ON package(data_reset_cycle);
|
||||
```
|
||||
|
||||
在 `package_usage` 表中新增：
|
||||
```sql
|
||||
ALTER TABLE package_usage
|
||||
ADD COLUMN last_reset_at DATETIME DEFAULT NULL COMMENT '最后一次流量重置时间';
|
||||
|
||||
CREATE INDEX idx_last_reset_at ON package_usage(last_reset_at);
|
||||
```
|
||||
|
||||
### 3. ❌ 要废弃的逻辑
|
||||
|
||||
- **废弃旧的重置逻辑**：如果代码中存在通过 `reset_interval` 或 `reset_day` 字段计算重置的逻辑，全部删除
|
||||
- **废弃旧的定时任务**：如果存在旧的流量重置定时任务，全部删除
|
||||
- **废弃旧的重置时间字段**：统一使用 `last_reset_at`（DATETIME），删除其他相关字段
|
||||
|
||||
### 4. ✅ 历史数据强制转换
|
||||
|
||||
```sql
|
||||
-- Step 1: 历史套餐的重置周期初始化
|
||||
-- 假设历史套餐默认为按月重置（需根据实际业务规则调整）
|
||||
UPDATE package
|
||||
SET data_reset_cycle = 'monthly'
|
||||
WHERE data_reset_cycle IS NULL;
|
||||
|
||||
-- 如果历史有特殊类型，可以根据 duration 或其他字段推断：
|
||||
-- 例如：duration_days=1 → data_reset_cycle='daily'
|
||||
UPDATE package
|
||||
SET data_reset_cycle = 'daily'
|
||||
WHERE duration_days = 1
|
||||
AND data_reset_cycle IS NULL;
|
||||
|
||||
-- Step 2: 历史套餐的运营商初始化
|
||||
-- 假设历史套餐默认为移动（需根据实际业务规则调整）
|
||||
UPDATE package
|
||||
SET isp = 'mobile'
|
||||
WHERE isp IS NULL;
|
||||
|
||||
-- Step 3: 历史 PackageUsage 的 last_reset_at 初始化
|
||||
-- 如果有旧的 last_reset_date 字段，转换为 last_reset_at
|
||||
-- UPDATE package_usage
|
||||
-- SET last_reset_at = STR_TO_DATE(last_reset_date, '%Y-%m-%d')
|
||||
-- WHERE last_reset_date IS NOT NULL;
|
||||
|
||||
-- 如果没有旧字段，根据 activated_at 推断：
|
||||
-- 按月重置：last_reset_at = 当前月的1号
|
||||
-- 按日重置：last_reset_at = 今天0点
|
||||
-- 按年重置：last_reset_at = 今年1月1日
|
||||
-- 不重置：last_reset_at = NULL
|
||||
|
||||
UPDATE package_usage pu
|
||||
JOIN package p ON pu.package_id = p.id
|
||||
SET pu.last_reset_at = DATE_FORMAT(CURDATE(), '%Y-%m-01 00:00:00')
|
||||
WHERE p.data_reset_cycle = 'monthly'
|
||||
AND pu.status = 1
|
||||
AND pu.last_reset_at IS NULL;
|
||||
|
||||
UPDATE package_usage pu
|
||||
JOIN package p ON pu.package_id = p.id
|
||||
SET pu.last_reset_at = DATE_FORMAT(CURDATE(), '%Y-%m-%d 00:00:00')
|
||||
WHERE p.data_reset_cycle = 'daily'
|
||||
AND pu.status = 1
|
||||
AND pu.last_reset_at IS NULL;
|
||||
|
||||
UPDATE package_usage pu
|
||||
JOIN package p ON pu.package_id = p.id
|
||||
SET pu.last_reset_at = DATE_FORMAT(CURDATE(), '%Y-01-01 00:00:00')
|
||||
WHERE p.data_reset_cycle = 'yearly'
|
||||
AND pu.status = 1
|
||||
AND pu.last_reset_at IS NULL;
|
||||
|
||||
-- Step 4: data_reset_cycle=none 的套餐不设置 last_reset_at
|
||||
-- （保持 NULL）
|
||||
```
|
||||
|
||||
### 5. ❌ 删除遗留表/字段（确认后执行）
|
||||
|
||||
```sql
|
||||
-- 如果存在旧的重置相关字段，删除
|
||||
-- ALTER TABLE package DROP COLUMN IF EXISTS reset_interval;
|
||||
-- ALTER TABLE package DROP COLUMN IF EXISTS reset_day;
|
||||
-- ALTER TABLE package_usage DROP COLUMN IF EXISTS last_reset_date;
|
||||
```
|
||||
|
||||
### 6. 验证步骤
|
||||
|
||||
```sql
|
||||
-- 验证1：所有套餐都有 data_reset_cycle
|
||||
SELECT COUNT(*)
|
||||
FROM package
|
||||
WHERE data_reset_cycle IS NULL;
|
||||
-- 预期结果：0
|
||||
|
||||
-- 验证2：data_reset_cycle 值合法
|
||||
SELECT COUNT(*)
|
||||
FROM package
|
||||
WHERE data_reset_cycle NOT IN ('daily', 'monthly', 'yearly', 'none');
|
||||
-- 预期结果：0
|
||||
|
||||
-- 验证3：生效中套餐的 last_reset_at 不为空（除了 data_reset_cycle=none）
|
||||
SELECT COUNT(*)
|
||||
FROM package_usage pu
|
||||
JOIN package p ON pu.package_id = p.id
|
||||
WHERE pu.status = 1
|
||||
AND p.data_reset_cycle != 'none'
|
||||
AND pu.last_reset_at IS NULL;
|
||||
-- 预期结果：0
|
||||
|
||||
-- 验证4：检查是否还有遗留字段（需根据实际情况调整）
|
||||
-- SELECT column_name FROM information_schema.columns
|
||||
-- WHERE table_name = 'package'
|
||||
-- AND column_name IN ('reset_interval', 'reset_day');
|
||||
-- 预期结果：0 rows
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试场景矩阵
|
||||
|
||||
| 场景分类 | 测试用例 | 预期结果 |
|
||||
|---------|---------|---------|
|
||||
| **配置重置周期** | 创建按日重置套餐 | data_reset_cycle=daily |
|
||||
| | 创建按月重置套餐 | data_reset_cycle=monthly |
|
||||
| | 创建按年重置套餐 | data_reset_cycle=yearly |
|
||||
| | 创建不重置套餐 | data_reset_cycle=none |
|
||||
| **每日重置** | 每日0点重置 | data_usage_mb=0, last_reset_at=今日0点 |
|
||||
| | 非每日重置套餐不受影响 | data_usage_mb 不变 |
|
||||
| | 待生效/已过期套餐不重置 | data_usage_mb 不变 |
|
||||
| **每月重置** | 每月1号重置 | data_usage_mb=0, last_reset_at=本月1号0点 |
|
||||
| | 联通特殊规则（27号重置） | data_usage_mb=0, last_reset_at=本月27号0点 |
|
||||
| | 跨月边界流量统计 | 日记录保留，data_usage_mb 重置 |
|
||||
| **每年重置** | 每年1月1日重置 | data_usage_mb=0, last_reset_at=今年1月1日0点 |
|
||||
| | 已过期年套餐不重置 | data_usage_mb 不变 |
|
||||
| **不重置** | 有效期内流量累计 | data_usage_mb 持续累加 |
|
||||
| | 定时任务不影响 | data_usage_mb 不变 |
|
||||
| **历史记录** | 重置后历史记录可查 | PackageUsageDailyRecord 存在 |
|
||||
| | 重置后新流量使用 | 新日记录写入 |
|
||||
| **并发** | 并发流量扣减和重置 | 使用行锁，顺序执行 |
|
||||
| | 并发多套餐重置 | 分批处理，失败批次不影响其他 |
|
||||
| **异常** | 重置任务失败 | Asynq 重试，记录日志 |
|
||||
| | 批量重置部分失败 | 失败批次回滚，其他批次正常 |
|
||||
|
||||
---
|
||||
|
||||
## 实现参考
|
||||
|
||||
### 每日流量重置定时任务
|
||||
|
||||
```go
|
||||
// Handler: HandleDailyReset
|
||||
func (h *DataResetHandler) HandleDailyReset(ctx context.Context, task *asynq.Task) error {
|
||||
const batchSize = 100
|
||||
|
||||
// 1. 查询需要重置的套餐ID列表
|
||||
usageIDs, err := h.packageUsageStore.ListDailyResetUsageIDs(ctx)
|
||||
if err != nil {
|
||||
return fmt.Errorf("list daily reset usage ids failed: %w", err)
|
||||
}
|
||||
|
||||
if len(usageIDs) == 0 {
|
||||
h.logger.Info("无需要每日重置的套餐")
|
||||
return nil
|
||||
}
|
||||
|
||||
// 2. 分批重置
|
||||
totalCount := 0
|
||||
failedCount := 0
|
||||
|
||||
for i := 0; i < len(usageIDs); i += batchSize {
|
||||
end := i + batchSize
|
||||
if end > len(usageIDs) {
|
||||
end = len(usageIDs)
|
||||
}
|
||||
|
||||
batchIDs := usageIDs[i:end]
|
||||
|
||||
// 使用独立事务
|
||||
tx := h.db.Begin()
|
||||
err := h.resetUsageBatch(ctx, tx, batchIDs)
|
||||
if err != nil {
|
||||
tx.Rollback()
|
||||
failedCount += len(batchIDs)
|
||||
h.logger.Error("批量重置失败", zap.Error(err), zap.Ints("batch_ids", batchIDs))
|
||||
continue
|
||||
}
|
||||
|
||||
if err := tx.Commit().Error; err != nil {
|
||||
failedCount += len(batchIDs)
|
||||
h.logger.Error("提交事务失败", zap.Error(err))
|
||||
continue
|
||||
}
|
||||
|
||||
totalCount += len(batchIDs)
|
||||
}
|
||||
|
||||
h.logger.Info("每日流量重置完成",
|
||||
zap.Int("total_count", totalCount),
|
||||
zap.Int("failed_count", failedCount))
|
||||
|
||||
if failedCount > 0 {
|
||||
return fmt.Errorf("部分套餐重置失败，失败数量：%d", failedCount)
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// Store 层：ListDailyResetUsageIDs
|
||||
func (s *Store) ListDailyResetUsageIDs(ctx context.Context) ([]int, error) {
|
||||
var ids []int
|
||||
err := s.db.WithContext(ctx).
|
||||
Table("package_usage pu").
|
||||
Select("pu.id").
|
||||
Joins("JOIN package p ON pu.package_id = p.id").
|
||||
Where("p.data_reset_cycle = ?", constants.DataResetCycleDaily).
|
||||
Where("pu.status = ?", constants.PackageStatusActive).
|
||||
Where("pu.expires_at > ?", time.Now()).
|
||||
Where("(pu.last_reset_at IS NULL OR DATE(pu.last_reset_at) < CURDATE())"). // 幂等性
|
||||
Pluck("pu.id", &ids).Error
|
||||
return ids, err
|
||||
}
|
||||
|
||||
// Store 层：resetUsageBatch
|
||||
func (h *DataResetHandler) resetUsageBatch(ctx context.Context, tx *gorm.DB, ids []int) error {
|
||||
return tx.WithContext(ctx).
|
||||
Model(&model.PackageUsage{}).
|
||||
Where("id IN (?)", ids).
|
||||
Updates(map[string]interface{}{
|
||||
"data_usage_mb": 0,
|
||||
"last_reset_at": time.Now(),
|
||||
}).Error
|
||||
}
|
||||
```
|
||||
|
||||
### 每月流量重置定时任务（含联通特殊规则）
|
||||
|
||||
```go
|
||||
// Handler: HandleMonthlyReset
|
||||
func (h *DataResetHandler) HandleMonthlyReset(ctx context.Context, task *asynq.Task) error {
|
||||
// 判断今天是几号
|
||||
today := time.Now().Day()
|
||||
|
||||
// 1. 重置非联通套餐（每月1号）
|
||||
if today == 1 {
|
||||
if err := h.resetMonthlyUsages(ctx, ""); err != nil {
|
||||
h.logger.Error("非联通套餐每月重置失败", zap.Error(err))
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
// 2. 重置联通套餐（每月27号）
|
||||
if today == 27 {
|
||||
if err := h.resetMonthlyUsages(ctx, constants.ISPUnicom); err != nil {
|
||||
h.logger.Error("联通套餐每月重置失败", zap.Error(err))
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// resetMonthlyUsages: 重置按月重置的套餐
|
||||
func (h *DataResetHandler) resetMonthlyUsages(ctx context.Context, isp string) error {
|
||||
const batchSize = 100
|
||||
|
||||
// 查询需要重置的套餐ID列表
|
||||
usageIDs, err := h.packageUsageStore.ListMonthlyResetUsageIDs(ctx, isp)
|
||||
if err != nil {
|
||||
return fmt.Errorf("list monthly reset usage ids failed: %w", err)
|
||||
}
|
||||
|
||||
if len(usageIDs) == 0 {
|
||||
h.logger.Info("无需要每月重置的套餐", zap.String("isp", isp))
|
||||
return nil
|
||||
}
|
||||
|
||||
// 分批重置（逻辑与每日重置相同）
|
||||
// ...
|
||||
return nil
|
||||
}
|
||||
|
||||
// Store 层：ListMonthlyResetUsageIDs
|
||||
func (s *Store) ListMonthlyResetUsageIDs(ctx context.Context, isp string) ([]int, error) {
|
||||
query := s.db.WithContext(ctx).
|
||||
Table("package_usage pu").
|
||||
Select("pu.id").
|
||||
Joins("JOIN package p ON pu.package_id = p.id").
|
||||
Where("p.data_reset_cycle = ?", constants.DataResetCycleMonthly).
|
||||
Where("pu.status = ?", constants.PackageStatusActive).
|
||||
Where("pu.expires_at > ?", time.Now())
|
||||
|
||||
if isp != "" {
|
||||
// 联通特殊规则
|
||||
query = query.Where("p.isp = ?", isp)
|
||||
} else {
|
||||
// 非联通套餐
|
||||
query = query.Where("p.isp != ?", constants.ISPUnicom)
|
||||
}
|
||||
|
||||
// 幂等性：避免重复重置
|
||||
query = query.Where("(pu.last_reset_at IS NULL OR DATE(pu.last_reset_at) < CURDATE())")
|
||||
|
||||
var ids []int
|
||||
err := query.Pluck("pu.id", &ids).Error
|
||||
return ids, err
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**本 Spec 完成**，包含：
|
||||
- ✅ 业务背景和业务规则
|
||||
- ✅ 详细场景（每日/每月/每年重置、不重置、联通特殊规则）
|
||||
- ✅ 边界条件和并发场景
|
||||
- ✅ 异常处理和数据一致性保证
|
||||
- ✅ 性能指标和错误码定义
|
||||
- ✅ **激进的数据迁移策略**（明确删除字段、废弃逻辑、强制转换）
|
||||
- ✅ 测试场景矩阵和实现参考
|
||||
@@ -1,24 +1,53 @@
|
||||
## ADDED Requirements
|
||||
## Requirements
|
||||
|
||||
### Requirement: 创建套餐
|
||||
|
||||
系统 SHALL 允许平台管理员创建套餐，包含套餐编码、套餐名称、所属系列、套餐类型、时长、流量配置、价格和建议价格。套餐编码 MUST 全局唯一（排除已删除记录）。新创建的套餐默认为启用状态(1)和下架状态(2)。
|
||||
系统 SHALL 允许平台管理员创建套餐，包含套餐编码、套餐名称、所属系列、套餐类型、时长、**周期类型（calendar_type）、流量重置周期（data_reset_cycle）、是否需要实名激活（enable_realname_activation）**、流量配置、价格和建议价格。套餐编码 MUST 全局唯一（排除已删除记录）。新创建的套餐默认为启用状态(1)和下架状态(2)。
|
||||
|
||||
#### Scenario: 成功创建套餐
|
||||
- **WHEN** 管理员提交有效的套餐信息
|
||||
- **THEN** 系统创建套餐记录，状态为启用(1)，上架状态为下架(2)，返回创建的套餐详情
|
||||
#### Scenario: 成功创建自然月套餐
|
||||
- **GIVEN** 管理员提供套餐信息，calendar_type=natural_month，duration_months=1
|
||||
- **WHEN** 提交创建请求
|
||||
- **THEN** 系统创建套餐，状态=1，上架状态=2，calendar_type=natural_month
|
||||
|
||||
#### Scenario: 成功创建按天套餐
|
||||
- **GIVEN** 管理员提供套餐信息，calendar_type=by_day，duration_days=30
|
||||
- **WHEN** 提交创建请求
|
||||
- **THEN** 系统创建套餐，calendar_type=by_day，duration_days=30
|
||||
|
||||
#### Scenario: 套餐编码重复
|
||||
- **WHEN** 管理员提交的套餐编码已存在（未删除）
|
||||
- **GIVEN** 数据库中存在套餐编码为 "PKG001" 的套餐（未删除）
|
||||
- **WHEN** 管理员创建套餐，编码为 "PKG001"
|
||||
- **THEN** 系统返回错误 "套餐编码已存在"
|
||||
|
||||
#### Scenario: 关联不存在的套餐系列
|
||||
- **WHEN** 管理员指定的系列 ID 不存在
|
||||
- **GIVEN** 管理员指定 series_id=999，但系列不存在
|
||||
- **WHEN** 提交创建请求
|
||||
- **THEN** 系统返回错误 "套餐系列不存在"
|
||||
|
||||
#### Scenario: 缺少必填字段
|
||||
- **WHEN** 管理员未提供必填字段（套餐编码、套餐名称、套餐类型、时长、价格）
|
||||
- **THEN** 系统返回参数验证错误
|
||||
- **GIVEN** 管理员未提供套餐编码
|
||||
- **WHEN** 提交创建请求
|
||||
- **THEN** 系统返回参数验证错误 "套餐编码为必填项"
|
||||
|
||||
#### Scenario: 创建自然月套餐时必须提供 duration_months
|
||||
- **GIVEN** 管理员创建套餐，calendar_type=natural_month，但未提供 duration_months
|
||||
- **WHEN** 提交创建请求
|
||||
- **THEN** 系统返回错误 "自然月套餐必须指定 duration_months"
|
||||
|
||||
#### Scenario: 创建按天套餐时必须提供 duration_days
|
||||
- **GIVEN** 管理员创建套餐，calendar_type=by_day，但未提供 duration_days
|
||||
- **WHEN** 提交创建请求
|
||||
- **THEN** 系统返回错误 "按天套餐必须指定 duration_days"
|
||||
|
||||
#### Scenario: 默认 data_reset_cycle 为 monthly
|
||||
- **GIVEN** 管理员创建主套餐，未指定 data_reset_cycle
|
||||
- **WHEN** 提交创建请求
|
||||
- **THEN** 系统自动设置 data_reset_cycle=monthly
|
||||
|
||||
#### Scenario: 默认 enable_realname_activation 为 true
|
||||
- **GIVEN** 管理员创建主套餐，未指定 enable_realname_activation
|
||||
- **WHEN** 提交创建请求
|
||||
- **THEN** 系统自动设置 enable_realname_activation=true
|
||||
|
||||
---
|
||||
|
||||
@@ -54,38 +83,84 @@
|
||||
|
||||
### Requirement: 查询套餐详情
|
||||
|
||||
系统 SHALL 允许管理员查询单个套餐的详细信息。
|
||||
系统 SHALL 允许管理员查询单个套餐的详细信息，**响应包含新增字段（calendar_type, data_reset_cycle, enable_realname_activation）**。
|
||||
|
||||
#### Scenario: 查询存在的套餐
|
||||
- **WHEN** 管理员请求指定 ID 的套餐详情
|
||||
- **THEN** 系统返回该套餐的完整信息
|
||||
- **GIVEN** 数据库中存在套餐 ID=1
|
||||
- **WHEN** 管理员请求套餐详情
|
||||
- **THEN** 系统返回该套餐的完整信息，包含所有新增字段
|
||||
|
||||
#### Scenario: 查询不存在的套餐
|
||||
- **WHEN** 管理员请求不存在或已删除的套餐 ID
|
||||
- **GIVEN** 管理员请求套餐 ID=999，但套餐不存在
|
||||
- **WHEN** 提交查询请求
|
||||
- **THEN** 系统返回 "套餐不存在" 错误
|
||||
|
||||
#### Scenario: 响应包含周期类型信息
|
||||
- **GIVEN** 套餐 calendar_type=natural_month，duration_months=1
|
||||
- **WHEN** 管理员查询套餐详情
|
||||
- **THEN** 响应包含 calendar_type=natural_month，duration_months=1
|
||||
|
||||
#### Scenario: 响应包含流量重置周期信息
|
||||
- **GIVEN** 套餐 data_reset_cycle=monthly
|
||||
- **WHEN** 管理员查询套餐详情
|
||||
- **THEN** 响应包含 data_reset_cycle=monthly
|
||||
|
||||
#### Scenario: 响应包含实名激活配置
|
||||
- **GIVEN** 套餐 enable_realname_activation=true
|
||||
- **WHEN** 管理员查询套餐详情
|
||||
- **THEN** 响应包含 enable_realname_activation=true
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 更新套餐
|
||||
|
||||
系统 SHALL 允许管理员更新套餐的基本信息。套餐编码创建后 MUST NOT 允许修改。
|
||||
系统 SHALL 允许管理员更新套餐的基本信息，**包括周期类型、流量重置周期、实名激活配置等新增字段**。套餐编码创建后 MUST NOT 允许修改。
|
||||
|
||||
#### Scenario: 成功更新套餐
|
||||
- **WHEN** 管理员提交有效的更新信息
|
||||
#### Scenario: 成功更新套餐基本信息
|
||||
- **GIVEN** 管理员更新套餐名称和价格
|
||||
- **WHEN** 提交更新请求
|
||||
- **THEN** 系统更新套餐记录，返回更新后的详情
|
||||
|
||||
#### Scenario: 尝试修改套餐编码
|
||||
- **WHEN** 管理员尝试修改套餐编码
|
||||
- **GIVEN** 管理员尝试修改套餐编码
|
||||
- **WHEN** 提交更新请求
|
||||
- **THEN** 系统忽略套餐编码字段，不进行修改
|
||||
|
||||
#### Scenario: 更新不存在的套餐
|
||||
- **WHEN** 管理员更新不存在的套餐
|
||||
- **GIVEN** 管理员更新套餐 ID=999，但套餐不存在
|
||||
- **WHEN** 提交更新请求
|
||||
- **THEN** 系统返回 "套餐不存在" 错误
|
||||
|
||||
#### Scenario: 关联不存在的套餐系列
|
||||
- **WHEN** 管理员将套餐关联到不存在的系列
|
||||
- **GIVEN** 管理员将套餐的 series_id 改为 999，但系列不存在
|
||||
- **WHEN** 提交更新请求
|
||||
- **THEN** 系统返回错误 "套餐系列不存在"
|
||||
|
||||
#### Scenario: 更新套餐周期类型（从自然月改为按天）
|
||||
- **GIVEN** 套餐当前 calendar_type=natural_month，duration_months=1
|
||||
- **WHEN** 管理员更新 calendar_type=by_day，duration_days=30
|
||||
- **THEN** 系统更新成功，calendar_type=by_day，duration_days=30
|
||||
|
||||
#### Scenario: 更新套餐周期类型（从按天改为自然月）
|
||||
- **GIVEN** 套餐当前 calendar_type=by_day，duration_days=30
|
||||
- **WHEN** 管理员更新 calendar_type=natural_month，duration_months=1
|
||||
- **THEN** 系统更新成功，calendar_type=natural_month，duration_months=1
|
||||
|
||||
#### Scenario: 更新周期类型但未提供对应时长字段
|
||||
- **GIVEN** 套餐当前 calendar_type=by_day
|
||||
- **WHEN** 管理员更新 calendar_type=natural_month，但未提供 duration_months
|
||||
- **THEN** 系统返回错误 "自然月套餐必须指定 duration_months"
|
||||
|
||||
#### Scenario: 更新 data_reset_cycle
|
||||
- **GIVEN** 套餐当前 data_reset_cycle=monthly
|
||||
- **WHEN** 管理员更新 data_reset_cycle=daily
|
||||
- **THEN** 系统更新成功，data_reset_cycle=daily
|
||||
|
||||
#### Scenario: 更新 enable_realname_activation
|
||||
- **GIVEN** 套餐当前 enable_realname_activation=true
|
||||
- **WHEN** 管理员更新 enable_realname_activation=false
|
||||
- **THEN** 系统更新成功，enable_realname_activation=false
|
||||
|
||||
---
|
||||
|
||||
### Requirement: 删除套餐
|
||||
|
||||
383
openspec/specs/package-queue-activation/spec.md
Normal file
383
openspec/specs/package-queue-activation/spec.md
Normal file
@@ -0,0 +1,383 @@
|
||||
# Spec: 主套餐排队生效机制
|
||||
|
||||
## 业务背景
|
||||
|
||||
现有套餐系统允许同一载体(设备/卡)同时存在多个生效中的主套餐,导致流量统计混乱、停机条件不明确等问题。本规范引入主套餐排队机制,确保:
|
||||
|
||||
1. **同一时刻只能有一个生效中主套餐**:避免多套餐并存的业务混乱
|
||||
2. **后续购买自动排队**:用户提前购买多个主套餐(囤货),按购买顺序自动激活
|
||||
3. **无缝衔接**:当前主套餐过期后,系统自动激活下一个,无需人工干预
|
||||
|
||||
## 业务规则
|
||||
|
||||
### 主套餐识别规则
|
||||
- **主套餐定义**:`package_type=formal` 且 `master_usage_id IS NULL`
|
||||
- **加油包定义**:`package_type=addon` 或 `master_usage_id IS NOT NULL`
|
||||
|
||||
### Priority 分配规则
|
||||
1. **首个主套餐**:priority=1,立即激活(status=1)
|
||||
2. **后续主套餐**:priority=MAX(当前主套餐 priority)+1,待生效(status=0)
|
||||
3. **Priority 全局唯一**:同一载体的所有主套餐 priority 不重复
|
||||
|
||||
### 激活顺序规则
|
||||
1. **按 priority 升序激活**:priority=1 → priority=2 → priority=3 ...
|
||||
2. **跨状态查询**:轮询系统查询 status=0 且 priority 最小的待生效主套餐
|
||||
3. **过期检测频率**:每 10 秒执行一次过期检测
|
||||
|
||||
### 激活延迟要求
|
||||
- **目标延迟**:主套餐过期后 1 分钟内完成下一个套餐的激活
|
||||
- **实际延迟组成**:
|
||||
- 过期检测:< 10 秒(轮询间隔)
|
||||
- 队列延迟:< 1 秒(Asynq 队列延迟)
|
||||
- 激活处理:< 5 秒(数据库更新 + 日志记录)
|
||||
- **总延迟** < 20 秒(满足 < 1 分钟要求)
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 同时只能有一个生效中的主套餐
|
||||
系统 SHALL 确保载体(设备/卡)同一时刻只能有一个 package_type=formal 且 status=1 的套餐。
|
||||
|
||||
**数据一致性保证**:
|
||||
- 购买时检查:查询 `WHERE usage_type=? AND (iot_card_id/device_id)=? AND status=1 AND master_usage_id IS NULL`
|
||||
- 并发控制:使用数据库事务 + 唯一索引(usage_type, carrier_id, status=1)避免并发插入多个生效中主套餐
|
||||
- 激活时二次检查:激活前再次查询是否有生效中主套餐,避免并发激活
|
||||
|
||||
#### Scenario: 首次购买主套餐立即生效
|
||||
- **GIVEN** 载体无任何主套餐记录
|
||||
- **WHEN** 用户通过 POST /api/admin/orders 购买主套餐(package_type=formal)
|
||||
- **THEN** 系统创建 PackageUsage:
|
||||
- status=1(生效中)
|
||||
- priority=1
|
||||
- activated_at=支付完成时间
|
||||
- expires_at=根据 calendar_type 计算
|
||||
- master_usage_id=NULL
|
||||
- **AND** 订单状态更新为 completed
|
||||
|
||||
#### Scenario: 购买第二个主套餐自动排队
|
||||
- **GIVEN** 载体已有1个生效中的主套餐(priority=1, status=1)
|
||||
- **WHEN** 用户购买第2个主套餐
|
||||
- **THEN** 系统创建 PackageUsage:
|
||||
- status=0(待生效)
|
||||
- priority=2
|
||||
- activated_at=NULL
|
||||
- expires_at=NULL
|
||||
- master_usage_id=NULL
|
||||
- **AND** 订单状态更新为 completed
|
||||
|
||||
#### Scenario: 购买第三个主套餐继续排队
|
||||
- **GIVEN** 载体已有1个生效中主套餐(priority=1, status=1) + 1个待生效主套餐(priority=2, status=0)
|
||||
- **WHEN** 用户购买第3个主套餐
|
||||
- **THEN** 系统创建 PackageUsage:
|
||||
- status=0(待生效)
|
||||
- priority=3
|
||||
- activated_at=NULL
|
||||
- expires_at=NULL
|
||||
|
||||
#### Scenario: 并发购买两个主套餐(并发控制)
|
||||
- **GIVEN** 载体无任何主套餐记录
|
||||
- **WHEN** 两个用户同时(< 1秒内)购买主套餐
|
||||
- **THEN** 第一个请求创建 PackageUsage priority=1, status=1(生效中)
|
||||
- **AND** 第二个请求创建 PackageUsage priority=2, status=0(待生效)
|
||||
- **AND** 使用数据库事务保证数据一致性,不会出现两个 priority=1 或两个 status=1
|
||||
|
||||
#### Scenario: 查询生效中主套餐(接口验证)
|
||||
- **GIVEN** 载体有1个 status=1 的主套餐和2个 status=0 的待生效主套餐
|
||||
- **WHEN** 系统查询生效中主套餐(WHERE status=1 AND master_usage_id IS NULL)
|
||||
- **THEN** 返回唯一的 status=1 主套餐记录
|
||||
- **AND** 查询结果数量 = 1
|
||||
|
||||
#### Scenario: 违规创建两个生效中主套餐(数据库约束)
|
||||
- **GIVEN** 数据库有唯一索引(usage_type, iot_card_id, status=1, deleted_at IS NULL)
|
||||
- **WHEN** 系统尝试插入第二个 status=1 的主套餐(绕过业务逻辑)
|
||||
- **THEN** 数据库返回唯一约束冲突错误
|
||||
- **AND** 事务回滚,数据不插入
|
||||
|
||||
### Requirement: 主套餐按购买顺序排队
|
||||
系统 SHALL 为待生效主套餐分配递增的 priority,priority 数字越小优先级越高。
|
||||
|
||||
**Priority 计算逻辑**:
|
||||
```
|
||||
new_priority = MAX(当前载体所有主套餐的 priority) + 1
|
||||
```
|
||||
|
||||
**边界条件**:
|
||||
- 首个主套餐 priority=1
|
||||
- 删除中间 priority 的套餐后,priority 不重新排序(例如删除 priority=2,后续仍从 priority=4 开始)
|
||||
- priority 最大值不超过 999(业务限制,避免异常)
|
||||
|
||||
#### Scenario: Priority 自动递增
|
||||
- **GIVEN** 载体当前主套餐最大 priority=5
|
||||
- **WHEN** 用户购买新主套餐
|
||||
- **THEN** 系统创建 PackageUsage priority=6, status=0
|
||||
|
||||
#### Scenario: 首个主套餐 Priority 为 1
|
||||
- **GIVEN** 载体无任何主套餐记录
|
||||
- **WHEN** 用户首次购买主套餐
|
||||
- **THEN** 系统创建 PackageUsage priority=1, status=1(生效中)
|
||||
|
||||
#### Scenario: 删除待生效套餐后 Priority 不重排
|
||||
- **GIVEN** 载体有主套餐 priority=1(status=1), priority=2(status=0), priority=3(status=0)
|
||||
- **WHEN** 用户删除 priority=2 的待生效套餐(软删除,设置 deleted_at)
|
||||
- **AND** 再购买新主套餐
|
||||
- **THEN** 新套餐 priority=4(不重新排序为 priority=2)
|
||||
- **AND** 激活顺序为 priority=1 → priority=3 → priority=4
|
||||
|
||||
#### Scenario: Priority 超过限制(业务异常)
|
||||
- **GIVEN** 载体当前主套餐最大 priority=999
|
||||
- **WHEN** 用户尝试购买新主套餐
|
||||
- **THEN** 系统返回错误 400,错误消息:"主套餐排队数量已达上限(999个),请联系客服"
|
||||
- **AND** 订单创建失败
|
||||
|
||||
#### Scenario: 并发分配 Priority(并发控制)
|
||||
- **GIVEN** 载体当前主套餐最大 priority=5
|
||||
- **WHEN** 两个用户同时购买主套餐
|
||||
- **THEN** 第一个请求分配 priority=6
|
||||
- **AND** 第二个请求分配 priority=7
|
||||
- **AND** 使用数据库事务 + SELECT FOR UPDATE 避免 priority 重复
|
||||
|
||||
### Requirement: 当前主套餐过期后自动激活下一个
|
||||
系统 SHALL 在主套餐过期(expires_at < now)时,自动激活 priority 最小的待生效主套餐。
|
||||
|
||||
**实现机制**:
|
||||
1. **轮询调度**:Scheduler 每 10 秒执行一次过期检测
|
||||
2. **过期检测**:查询 `WHERE status=1 AND expires_at <= NOW() AND master_usage_id IS NULL`
|
||||
3. **状态更新**:将过期主套餐 status 更新为 3(已过期)
|
||||
4. **查询下一个**:查询 `WHERE status=0 AND master_usage_id IS NULL ORDER BY priority ASC LIMIT 1`
|
||||
5. **提交任务**:创建 Asynq 任务 `TaskTypePackageQueueActivation`
|
||||
6. **异步激活**:Asynq Handler 更新 status=1, 计算 activated_at 和 expires_at
|
||||
|
||||
**幂等性保证**:
|
||||
- 任务处理前检查 `status=0`,已激活则直接返回成功
|
||||
- 使用 Redis 分布式锁(key: `package:activation:lock:{usage_id}`,TTL=30s)
|
||||
|
||||
#### Scenario: 自动激活下一个主套餐
|
||||
- **GIVEN** 当前主套餐 priority=1, status=1, expires_at=2026-02-28 23:59:59
|
||||
- **AND** 存在待生效主套餐 priority=2, status=0
|
||||
- **WHEN** 系统时间到达 2026-03-01 00:00:00,轮询系统检测到过期
|
||||
- **THEN** 系统执行以下操作:
|
||||
1. 更新 priority=1 的套餐 status=3(已过期)
|
||||
2. 查询 priority=2 的待生效套餐
|
||||
3. 提交 Asynq 任务(payload: {usage_id: priority=2的ID})
|
||||
4. Asynq Handler 激活 priority=2 套餐:
|
||||
- status=1
|
||||
- activated_at=2026-03-01 00:00:10(激活时间,约为 00:00:00 + 10秒延迟)
|
||||
- expires_at=根据 calendar_type 计算
|
||||
- **AND** 激活延迟 < 1 分钟
|
||||
|
||||
#### Scenario: 无待生效套餐时不激活
|
||||
- **GIVEN** 当前主套餐 priority=1, status=1, expires_at=2026-02-28 23:59:59
|
||||
- **AND** 不存在 status=0 的待生效主套餐
|
||||
- **WHEN** 系统时间到达 2026-03-01 00:00:00,轮询系统检测到过期
|
||||
- **THEN** 系统仅更新 priority=1 的套餐 status=3(已过期)
|
||||
- **AND** 不提交激活任务
|
||||
- **AND** 载体进入无主套餐状态
|
||||
|
||||
#### Scenario: 过期检测批量处理
|
||||
- **GIVEN** 系统有 10000 个主套餐在 2026-02-28 23:59:59 过期
|
||||
- **WHEN** 系统时间到达 2026-03-01 00:00:00,轮询系统检测到过期
|
||||
- **THEN** 系统分批处理(每批 10000 个):
|
||||
1. 批量更新过期主套餐 status=3
|
||||
2. 批量查询下一个待生效主套餐(每个载体一个)
|
||||
3. 批量提交 Asynq 任务(最多 10000 个任务)
|
||||
- **AND** 所有任务在 1 分钟内完成激活
|
||||
|
||||
#### Scenario: 激活任务失败重试
|
||||
- **GIVEN** 待生效主套餐 priority=2, status=0
|
||||
- **WHEN** 轮询系统提交激活任务,但 Asynq Handler 第一次执行失败(例如数据库连接超时)
|
||||
- **THEN** Asynq 自动重试(MaxRetry=3,间隔 10 秒)
|
||||
- **AND** 第二次重试成功,套餐激活
|
||||
- **AND** 总延迟 < 2 分钟(10秒检测 + 10秒首次失败 + 10秒重试成功)
|
||||
|
||||
#### Scenario: 激活任务重试耗尽(异常处理)
|
||||
- **GIVEN** 待生效主套餐 priority=2, status=0
|
||||
- **WHEN** 轮询系统提交激活任务,Asynq Handler 重试 3 次均失败
|
||||
- **THEN** Asynq 任务进入死信队列(DLQ)
|
||||
- **AND** 套餐保持 status=0(待生效)
|
||||
- **AND** 系统记录 Error 日志,包含完整错误信息和 usage_id
|
||||
- **AND** 告警通知运维团队,人工介入修复
|
||||
|
||||
#### Scenario: 轮询系统重复检测(幂等性保证)
|
||||
- **GIVEN** 主套餐过期,已提交激活任务,但任务尚未执行完成
|
||||
- **WHEN** 10 秒后轮询系统再次检测(任务仍在队列中)
|
||||
- **THEN** 系统查询 status=1 的过期主套餐,结果为空(已更新为 status=3)
|
||||
- **AND** 不重复提交激活任务
|
||||
|
||||
#### Scenario: 激活任务并发执行(幂等性保证)
|
||||
- **GIVEN** 同一套餐的激活任务被重复提交(例如手动触发 + 自动调度)
|
||||
- **WHEN** 两个 Asynq Handler 同时执行
|
||||
- **THEN** 第一个 Handler 获取 Redis 锁,执行激活
|
||||
- **AND** 第二个 Handler 获取锁失败,等待 30 秒后超时,检查 status=1,直接返回成功
|
||||
- **AND** 套餐只激活一次
|
||||
|
||||
### Requirement: 激活时根据套餐类型计算有效期
|
||||
系统 SHALL 在排队激活主套餐时,根据 calendar_type 计算 expires_at。
|
||||
|
||||
**计算时机**:Asynq Handler 执行激活任务时
|
||||
|
||||
**计算逻辑**:
|
||||
- 自然月套餐:`expires_at = (activated_at 月份 + duration_months) 的月末 23:59:59`
|
||||
- 按天套餐:`expires_at = (activated_at 日期 + duration_days) 的 23:59:59`
|
||||
|
||||
#### Scenario: 排队激活自然月套餐
|
||||
- **GIVEN** 待生效主套餐 calendar_type=natural_month, duration_months=1
|
||||
- **WHEN** 2026-03-01 00:00:10 激活
|
||||
- **THEN** 套餐更新:
|
||||
- status=1
|
||||
- activated_at=2026-03-01 00:00:10
|
||||
- expires_at=2026-03-31 23:59:59
|
||||
- **AND** 有效期 = 30 天 23 小时 59 分 50 秒
|
||||
|
||||
#### Scenario: 排队激活按天套餐
|
||||
- **GIVEN** 待生效主套餐 calendar_type=by_day, duration_days=30
|
||||
- **WHEN** 2026-03-01 00:00:10 激活
|
||||
- **THEN** 套餐更新:
|
||||
- status=1
|
||||
- activated_at=2026-03-01 00:00:10
|
||||
- expires_at=2026-03-30 23:59:59
|
||||
- **AND** 有效期 = 29 天 23 小时 59 分 49 秒
|
||||
|
||||
#### Scenario: 激活时处理闰年(自然月)
|
||||
- **GIVEN** 待生效主套餐 calendar_type=natural_month, duration_months=1
|
||||
- **WHEN** 2028-02-01 00:00:10 激活(闰年)
|
||||
- **THEN** expires_at=2028-02-29 23:59:59(正确识别闰年)
|
||||
|
||||
#### Scenario: 激活时处理跨年(自然月)
|
||||
- **GIVEN** 待生效主套餐 calendar_type=natural_month, duration_months=2
|
||||
- **WHEN** 2026-12-01 00:00:10 激活
|
||||
- **THEN** expires_at=2027-02-28 23:59:59(正确跨年)
|
||||
|
||||
### Requirement: 主套餐排队调度延迟小于1分钟
|
||||
系统 SHALL 确保主套餐过期后,待生效套餐在1分钟内完成激活。
|
||||
|
||||
**性能指标**:
|
||||
| 指标 | 目标 | 监控方式 |
|
||||
|------|------|---------|
|
||||
| 过期检测延迟 | < 10 秒 | 轮询间隔配置 |
|
||||
| 任务提交延迟 | < 1 秒 | Asynq 入队时间 |
|
||||
| 激活处理延迟 | < 5 秒 | Asynq Handler 执行时间 |
|
||||
| **端到端延迟** | **< 20 秒** | 从过期到激活完成 |
|
||||
|
||||
**监控告警**:
|
||||
- 激活延迟 > 1 分钟:Critical 告警,通知运维团队
|
||||
- Asynq 队列堆积 > 1000:Warning 告警,检查 Worker 数量
|
||||
- 激活任务失败率 > 5%:Warning 告警,检查数据库连接
|
||||
|
||||
#### Scenario: 排队激活性能达标
|
||||
- **GIVEN** 主套餐在 2026-02-28 23:59:59 过期
|
||||
- **WHEN** 轮询系统在 00:00:00 - 00:00:10 之间检测到过期
|
||||
- **AND** 在 00:00:11 提交 Asynq 任务
|
||||
- **AND** Asynq Handler 在 00:00:12 - 00:00:17 执行激活
|
||||
- **THEN** 套餐在 2026-03-01 00:00:17 完成激活
|
||||
- **AND** 端到端延迟 = 17 秒 < 60 秒
|
||||
|
||||
#### Scenario: 高负载下激活延迟(压力测试)
|
||||
- **GIVEN** 10000 个主套餐同时过期
|
||||
- **WHEN** 轮询系统检测到过期并提交 10000 个任务
|
||||
- **AND** Asynq Worker 并发数 = 50
|
||||
- **THEN** 所有任务在 4 分钟内完成(10000 / 50 / 5秒 ≈ 4 分钟)
|
||||
- **AND** P99 激活延迟 < 5 分钟(可接受)
|
||||
|
||||
#### Scenario: 轮询系统宕机恢复(容错性)
|
||||
- **GIVEN** 主套餐在 2026-02-28 23:59:59 过期
|
||||
- **WHEN** 轮询系统在 00:00:00 - 00:10:00 期间宕机
|
||||
- **AND** 轮询系统在 00:10:01 恢复
|
||||
- **THEN** 轮询系统检测到过期主套餐(expires_at < 00:10:01)
|
||||
- **AND** 在 00:10:02 - 00:10:20 完成激活
|
||||
- **AND** 延迟 = 10 分钟 20 秒(超过目标,但系统自动恢复)
|
||||
|
||||
## 数据一致性保证
|
||||
|
||||
### 1. 并发购买主套餐
|
||||
- **机制**:数据库事务 + 唯一索引(usage_type, iot_card_id/device_id, status=1, deleted_at IS NULL)
|
||||
- **保证**:同一载体同一时刻只能有一个 status=1 的主套餐
|
||||
|
||||
### 2. 并发分配 Priority
|
||||
- **机制**:数据库事务 + SELECT FOR UPDATE
|
||||
- **伪代码**:
|
||||
```sql
|
||||
BEGIN TRANSACTION;
|
||||
SELECT MAX(priority) FROM tb_package_usage WHERE ... FOR UPDATE;
|
||||
INSERT INTO tb_package_usage (priority) VALUES (max_priority + 1);
|
||||
COMMIT;
|
||||
```
|
||||
|
||||
### 3. 并发激活同一套餐
|
||||
- **机制**:Redis 分布式锁(key: `package:activation:lock:{usage_id}`,TTL=30s)
|
||||
- **保证**:同一套餐只能被激活一次
|
||||
|
||||
### 4. 过期检测重复触发
|
||||
- **机制**:更新 status=3 后,WHERE 条件不再匹配(status=1)
|
||||
- **保证**:过期主套餐不会重复提交激活任务
|
||||
|
||||
## 性能优化策略
|
||||
|
||||
### 1. 过期检测分批处理
|
||||
```sql
|
||||
-- 每次最多处理 10000 个过期套餐
|
||||
SELECT id FROM tb_package_usage
|
||||
WHERE status=1 AND expires_at <= NOW() AND master_usage_id IS NULL
|
||||
ORDER BY expires_at ASC
|
||||
LIMIT 10000;
|
||||
```
|
||||
|
||||
### 2. 批量提交 Asynq 任务
|
||||
- 使用 `Enqueue` 批量提交(每批 1000 个)
|
||||
- 减少 Redis 往返次数
|
||||
|
||||
### 3. Asynq Worker 并发数
|
||||
- 默认并发数:10
|
||||
- 高负载时可调整为 50-100
|
||||
- 监控队列长度动态调整
|
||||
|
||||
### 4. 数据库索引优化
|
||||
```sql
|
||||
-- 过期检测索引
|
||||
CREATE INDEX idx_package_usage_expires ON tb_package_usage(status, expires_at, master_usage_id) WHERE deleted_at IS NULL;
|
||||
|
||||
-- Priority 查询索引
|
||||
CREATE INDEX idx_package_usage_priority ON tb_package_usage(iot_card_id, status, priority) WHERE deleted_at IS NULL;
|
||||
```
|
||||
|
||||
## 错误码定义
|
||||
|
||||
| 错误码 | HTTP 状态码 | 错误消息 | 场景 |
|
||||
|--------|------------|---------|------|
|
||||
| CodeConflict | 409 | 套餐正在激活中,请稍后重试 | 并发激活冲突 |
|
||||
| CodeForbidden | 403 | 主套餐排队数量已达上限(999个),请联系客服 | Priority 超限 |
|
||||
| CodeInternal | 500 | 套餐激活失败,请重试 | 数据库更新失败 |
|
||||
|
||||
## 数据迁移策略
|
||||
|
||||
**激进策略**(开发阶段):
|
||||
1. **历史主套餐数据重新排序**:
|
||||
- 查询每个载体的所有主套餐(按 `created_at ASC`)
|
||||
- 重新分配 `priority`:第一个=1,第二个=2,以此类推
|
||||
- 只保留第一个主套餐 `status=1`(生效中),其余设置为 `status=0`(待生效)
|
||||
- 为待生效主套餐清空 `activated_at` 和 `expires_at`
|
||||
|
||||
2. **订单服务彻底重构**:
|
||||
- **删除** 现有 `activatePackage` 函数中的立即激活逻辑
|
||||
- 所有主套餐购买统一走排队逻辑(首个除外)
|
||||
- 不保留旧的激活方式
|
||||
|
||||
3. **API 破坏性变更**:
|
||||
- 订单创建接口行为变更:后续主套餐购买不再立即生效
|
||||
- 响应中新增 `priority` 和 `estimated_activation_time` 字段
|
||||
- 客户端必须适配新的"待生效"状态展示
|
||||
|
||||
## 测试场景矩阵
|
||||
|
||||
| 维度 | 场景 | 预期结果 |
|
||||
|------|------|---------|
|
||||
| **基础功能** | 首次购买主套餐 | priority=1, status=1 |
|
||||
| | 购买第2个主套餐 | priority=2, status=0 |
|
||||
| | 购买第3个主套餐 | priority=3, status=0 |
|
||||
| **过期激活** | 主套餐过期 + 有待生效套餐 | status=3 → 激活 priority=2 |
|
||||
| | 主套餐过期 + 无待生效套餐 | status=3,载体无主套餐 |
|
||||
| **并发场景** | 并发购买两个主套餐 | priority=1(status=1) + priority=2(status=0) |
|
||||
| | 并发激活同一套餐 | 只激活一次,第二个请求幂等返回 |
|
||||
| **异常场景** | 激活任务失败 | 重试 3 次,失败进入 DLQ |
|
||||
| | Priority 超限(999) | 返回错误,拒绝购买 |
|
||||
| | 轮询系统宕机 | 恢复后自动激活过期套餐 |
|
||||
| **性能场景** | 单个套餐激活延迟 | < 20 秒 |
|
||||
| | 10000 个套餐同时过期 | P99 < 5 分钟 |
|
||||
972
openspec/specs/package-realname-activation/spec.md
Normal file
972
openspec/specs/package-realname-activation/spec.md
Normal file
@@ -0,0 +1,972 @@
|
||||
# Spec: 首次实名激活机制
|
||||
|
||||
## 业务背景
|
||||
|
||||
### 为什么需要首次实名激活机制
|
||||
|
||||
**现状问题**：
|
||||
- 运营商要求 IoT 卡必须实名认证后才能使用，但用户购买套餐时可能尚未实名
|
||||
- 后台管理员需要为客户提前购买套餐（批量配置），但客户设备可能尚未实名
|
||||
- 客户端购买套餐时强制实名会影响用户体验（需要先跳转实名流程再回来购买）
|
||||
- 套餐立即生效但设备未实名会导致浪费（无法使用流量，有效期却在流失）
|
||||
|
||||
**业务目标**：
|
||||
- 后台管理端可以为未实名设备提前购买套餐（套餐待生效，等待实名激活）
|
||||
- 客户端购买套餐必须先实名（确保用户可以立即使用）
|
||||
- 设备首次实名时自动激活所有待生效套餐（无需手动操作）
|
||||
- 支持灵活配置：部分套餐支持实名激活，部分套餐立即生效
|
||||
|
||||
---
|
||||
|
||||
## 业务规则
|
||||
|
||||
### 1. 购买前置检查规则
|
||||
|
||||
购买套餐时的实名检查规则：
|
||||
|
||||
```
|
||||
后台管理端购买（/api/admin/orders）：
|
||||
1. 不检查载体是否实名
|
||||
2. 如果套餐 enable_realname_activation=true：
|
||||
- 创建 PackageUsage status=0（待生效）
|
||||
- 设置 pending_realname_activation=true
|
||||
3. 如果套餐 enable_realname_activation=false：
|
||||
- 创建 PackageUsage status=1（生效中）
|
||||
- 立即激活，计算有效期
|
||||
|
||||
客户端购买（/api/h5/orders, /api/customer/orders）：
|
||||
1. 必须检查载体是否实名
|
||||
2. 如果未实名 → 返回错误 403："设备/卡必须先完成实名认证才能购买套餐"
|
||||
3. 如果已实名 → 创建 PackageUsage status=1（生效中），立即激活
|
||||
```
|
||||
|
||||
### 2. 首次实名判定规则
|
||||
|
||||
判断是否为"首次实名"的逻辑：
|
||||
|
||||
```
|
||||
设备类型（Device）：
|
||||
- 查询该设备下所有 IoT 卡的实名状态
|
||||
- 如果至少有1张卡已实名 → 不是首次实名
|
||||
- 如果所有卡都未实名，当前卡是第1张实名 → 是首次实名
|
||||
|
||||
单卡类型（IotCard）：
|
||||
- 查询该卡的实名状态
|
||||
- 如果卡从未实名，本次实名成功 → 是首次实名
|
||||
- 如果卡已实名（重新实名） → 不是首次实名
|
||||
```
|
||||
|
||||
**实现方式**：
|
||||
- 在 `Device` 模型中维护 `realname_status` 字段（0-未实名, 1-已实名）
|
||||
- 在 `IotCard` 模型中维护 `realname_status` 字段
|
||||
- 首次实名时更新对应模型的 `realname_status=1`
|
||||
|
||||
### 3. 激活触发规则
|
||||
|
||||
首次实名时触发套餐激活：
|
||||
|
||||
```
|
||||
触发条件：
|
||||
1. 载体首次实名成功（realname_status 从 0 变为 1）
|
||||
2. 载体有待生效套餐（status=0 AND pending_realname_activation=true）
|
||||
|
||||
激活流程：
|
||||
1. 实名成功后，入队 Asynq 任务 "realname_activation"
|
||||
2. 任务 payload：
|
||||
{
|
||||
"carrier_type": "device" | "iot_card",
|
||||
"carrier_id": 123,
|
||||
"realname_at": "2026-02-15T10:30:00Z"
|
||||
}
|
||||
3. Asynq Worker 处理任务：
|
||||
- 查询该载体所有 pending_realname_activation=true 且 status=0 的套餐
|
||||
- 批量更新 status=1, activated_at=realname_at
|
||||
- 根据套餐 calendar_type 计算 expires_at
|
||||
- 记录激活日志
|
||||
```
|
||||
|
||||
### 4. 有效期计算规则
|
||||
|
||||
激活时根据 `calendar_type` 计算 `expires_at`：
|
||||
|
||||
| calendar_type | 计算规则 | 示例 |
|
||||
|---------------|---------|------|
|
||||
| `natural_month` | `expires_at = 激活月份的最后一天 23:59:59` | 2026-02-15 激活 → 2026-02-28 23:59:59 |
|
||||
| `by_day` | `expires_at = activated_at + duration_days 天 - 1秒` | 2026-02-15 10:30:00 激活，30天 → 2026-03-16 23:59:59 |
|
||||
|
||||
**详细逻辑**见 `package-calendar-type/spec.md`。
|
||||
|
||||
### 5. enable_realname_activation 配置规则
|
||||
|
||||
套餐是否支持实名激活：
|
||||
|
||||
| enable_realname_activation | 说明 | 后台购买行为 | 客户端购买行为 |
|
||||
|---------------------------|------|-------------|---------------|
|
||||
| `true` | 支持实名激活 | 未实名设备：status=0，等待激活<br>已实名设备：status=1，立即生效 | 必须实名，status=1，立即生效 |
|
||||
| `false` | 立即生效 | 无论是否实名，status=1，立即生效 | 必须实名，status=1，立即生效 |
|
||||
|
||||
---
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 支持未实名状态购买套餐
|
||||
|
||||
系统 SHALL 允许后台管理端为未实名的载体（设备/卡）购买套餐，套餐状态为"待生效"(status=0)。
|
||||
|
||||
#### Scenario: 后台为未实名设备购买套餐成功
|
||||
- **GIVEN** 设备 ID=123，realname_status=0（未实名）
|
||||
- **AND** 套餐 enable_realname_activation=true
|
||||
- **WHEN** 管理员通过 POST /api/admin/orders 为该设备购买套餐
|
||||
- **THEN** 系统创建订单成功，PackageUsage：
|
||||
- status=0（待生效）
|
||||
- pending_realname_activation=true
|
||||
- activated_at=NULL
|
||||
- expires_at=NULL
|
||||
|
||||
#### Scenario: 后台为未实名设备购买不支持实名激活的套餐
|
||||
- **GIVEN** 设备 ID=123，realname_status=0（未实名）
|
||||
- **AND** 套餐 enable_realname_activation=false
|
||||
- **WHEN** 管理员通过 POST /api/admin/orders 为该设备购买套餐
|
||||
- **THEN** 系统创建订单成功，PackageUsage：
|
||||
- status=1（生效中）
|
||||
- pending_realname_activation=false
|
||||
- activated_at=订单支付时间
|
||||
- expires_at=根据 calendar_type 计算
|
||||
|
||||
#### Scenario: 客户端未实名时购买套餐失败
|
||||
- **GIVEN** 设备 ID=123，realname_status=0（未实名）
|
||||
- **WHEN** 客户通过 POST /api/h5/orders 为该设备购买套餐
|
||||
- **THEN** 系统返回错误 403，错误码 `REALNAME_REQUIRED`，错误消息："设备/卡必须先完成实名认证才能购买套餐"
|
||||
|
||||
#### Scenario: 已实名设备购买套餐立即生效
|
||||
- **GIVEN** 设备 ID=123，realname_status=1（已实名）
|
||||
- **AND** 套餐 enable_realname_activation=true
|
||||
- **WHEN** 管理员或客户为该设备购买套餐
|
||||
- **THEN** 系统创建订单成功，PackageUsage：
|
||||
- status=1（生效中）
|
||||
- pending_realname_activation=false
|
||||
- activated_at=订单支付时间
|
||||
- expires_at=根据 calendar_type 计算
|
||||
|
||||
#### Scenario: 后台批量购买套餐（部分未实名）
|
||||
- **GIVEN** 设备A（realname_status=0），设备B（realname_status=1）
|
||||
- **WHEN** 管理员批量为设备A和设备B购买套餐（enable_realname_activation=true）
|
||||
- **THEN** 系统创建订单成功：
|
||||
- 设备A套餐：status=0，pending_realname_activation=true
|
||||
- 设备B套餐：status=1，pending_realname_activation=false
|
||||
|
||||
### Requirement: 首次实名时自动激活待生效套餐
|
||||
|
||||
系统 SHALL 在载体首次实名成功时，自动激活所有 pending_realname_activation=true 的待生效套餐。
|
||||
|
||||
#### Scenario: 设备首张卡实名触发套餐激活
|
||||
- **GIVEN** 设备 ID=123，realname_status=0，有2个待生效套餐（pending_realname_activation=true）
|
||||
- **AND** 该设备下所有 IoT 卡都未实名
|
||||
- **WHEN** 设备的第1张卡在 2026-02-15 10:30:00 完成实名认证
|
||||
- **THEN** 系统：
|
||||
1. 更新设备 realname_status=1
|
||||
2. 入队 Asynq 任务 "realname_activation"
|
||||
3. 任务执行：批量更新2个套餐 status=1，activated_at=2026-02-15 10:30:00
|
||||
4. 根据各套餐 calendar_type 计算 expires_at
|
||||
|
||||
#### Scenario: 设备后续卡实名不触发激活
|
||||
- **GIVEN** 设备 ID=123，realname_status=1（已有1张卡实名）
|
||||
- **WHEN** 设备的第2张卡在 2026-02-20 10:00:00 完成实名认证
|
||||
- **THEN** 系统不触发套餐激活，设备的套餐状态保持不变
|
||||
|
||||
#### Scenario: 单卡设备实名触发激活
|
||||
- **GIVEN** IoT 卡 ICCID=123456，realname_status=0，有1个待生效套餐
|
||||
- **WHEN** 该卡在 2026-02-15 10:30:00 完成实名认证
|
||||
- **THEN** 系统：
|
||||
1. 更新卡 realname_status=1
|
||||
2. 入队 Asynq 任务 "realname_activation"
|
||||
3. 任务执行：更新套餐 status=1，activated_at=2026-02-15 10:30:00
|
||||
|
||||
#### Scenario: 激活时排除已生效的套餐
|
||||
- **GIVEN** 设备 ID=123，realname_status=0，有2个套餐：
|
||||
- 套餐A：status=0，pending_realname_activation=true
|
||||
- 套餐B：status=1（已生效）
|
||||
- **WHEN** 设备在 2026-02-15 10:30:00 首次实名
|
||||
- **THEN** 系统只激活套餐A，套餐B 保持不变
|
||||
|
||||
#### Scenario: 无待激活套餐时不执行激活逻辑
|
||||
- **GIVEN** 设备 ID=123，realname_status=0，无任何套餐
|
||||
- **WHEN** 设备在 2026-02-15 10:30:00 首次实名
|
||||
- **THEN** 系统入队 Asynq 任务，任务执行后发现无待激活套餐，直接返回
|
||||
|
||||
### Requirement: 激活时根据套餐类型计算有效期
|
||||
|
||||
系统 SHALL 在首次实名激活套餐时，根据套餐的 calendar_type 计算 expires_at。
|
||||
|
||||
#### Scenario: 实名激活自然月套餐
|
||||
- **GIVEN** 套餐 calendar_type=natural_month，duration_months=1
|
||||
- **WHEN** 2026-02-15 10:30:00 首次实名激活
|
||||
- **THEN** 系统计算：
|
||||
- activated_at=2026-02-15 10:30:00
|
||||
- expires_at=2026-02-28 23:59:59（当月最后一天）
|
||||
|
||||
#### Scenario: 实名激活按天套餐
|
||||
- **GIVEN** 套餐 calendar_type=by_day，duration_days=30
|
||||
- **WHEN** 2026-02-15 10:30:00 首次实名激活
|
||||
- **THEN** 系统计算：
|
||||
- activated_at=2026-02-15 10:30:00
|
||||
- expires_at=2026-03-16 23:59:59（+30天-1秒）
|
||||
|
||||
#### Scenario: 实名激活跨年自然月套餐
|
||||
- **GIVEN** 套餐 calendar_type=natural_month，duration_months=2
|
||||
- **WHEN** 2026-12-15 10:30:00 首次实名激活
|
||||
- **THEN** 系统计算：
|
||||
- activated_at=2026-12-15 10:30:00
|
||||
- expires_at=2027-01-31 23:59:59（跨年到次年1月最后一天）
|
||||
|
||||
#### Scenario: 激活时有效期计算失败
|
||||
- **GIVEN** 套餐 calendar_type=natural_month，duration_months=NULL（数据异常）
|
||||
- **WHEN** 首次实名激活
|
||||
- **THEN** 系统：
|
||||
1. 激活失败，套餐 status 保持 0
|
||||
2. 记录 Error 日志（包含套餐ID、载体信息、错误原因）
|
||||
3. Asynq 重试（最多3次）
|
||||
|
||||
### Requirement: 支持配置是否启用实名激活
|
||||
|
||||
系统 SHALL 在套餐模型中提供 enable_realname_activation 字段，允许管理员配置是否需要实名激活。
|
||||
|
||||
#### Scenario: 创建需要实名激活的套餐
|
||||
- **WHEN** 管理员创建套餐时指定 enable_realname_activation=true
|
||||
- **THEN** 系统创建成功，该套餐：
|
||||
- 后台购买未实名设备：status=0，等待激活
|
||||
- 后台购买已实名设备：status=1，立即生效
|
||||
- 客户端购买：必须实名，status=1，立即生效
|
||||
|
||||
#### Scenario: 创建立即生效的套餐
|
||||
- **WHEN** 管理员创建套餐时指定 enable_realname_activation=false
|
||||
- **THEN** 系统创建成功，该套餐：
|
||||
- 无论后台还是客户端购买，status=1，立即生效
|
||||
- 不需要等待实名激活
|
||||
|
||||
#### Scenario: 更新套餐的实名激活配置
|
||||
- **GIVEN** 套餐 ID=123，enable_realname_activation=false
|
||||
- **WHEN** 管理员更新套餐配置为 enable_realname_activation=true
|
||||
- **THEN** 系统更新成功，该套餐后续购买行为遵循新配置
|
||||
- **AND** 已有的 PackageUsage 不受影响
|
||||
|
||||
### Requirement: 实名激活异步处理
|
||||
|
||||
系统 SHALL 通过 Asynq 异步任务处理首次实名激活逻辑，避免阻塞实名认证流程。
|
||||
|
||||
#### Scenario: 实名成功后入队激活任务
|
||||
- **GIVEN** 设备 ID=123 首次实名成功
|
||||
- **WHEN** 系统更新设备 realname_status=1
|
||||
- **THEN** 系统入队 Asynq 任务：
|
||||
- task_type="realname_activation"
|
||||
- payload={"carrier_type": "device", "carrier_id": 123, "realname_at": "2026-02-15T10:30:00Z"}
|
||||
- queue="default"
|
||||
- max_retry=3
|
||||
|
||||
#### Scenario: 激活任务在1分钟内完成
|
||||
- **GIVEN** Asynq 任务 "realname_activation" 从队列取出
|
||||
- **WHEN** Worker 执行任务
|
||||
- **THEN** 系统在1分钟内完成套餐激活，更新 PackageUsage 状态
|
||||
- **AND** 任务标记为成功，从队列移除
|
||||
|
||||
#### Scenario: 激活任务失败后重试
|
||||
- **GIVEN** Asynq 任务 "realname_activation" 执行时数据库连接失败
|
||||
- **WHEN** 任务执行失败
|
||||
- **THEN** 系统：
|
||||
1. 记录 Error 日志（包含载体ID、错误信息）
|
||||
2. Asynq 自动重试（间隔 10s/30s/60s）
|
||||
3. 3次失败后写入死信队列，发送告警
|
||||
|
||||
#### Scenario: 激活任务幂等性
|
||||
- **GIVEN** Asynq 任务 "realname_activation" 因网络波动重复执行
|
||||
- **WHEN** Worker 第2次执行同一任务
|
||||
- **THEN** 系统检查套餐 status：
|
||||
- 如果已是 status=1 → 跳过激活，直接返回成功
|
||||
- 如果仍是 status=0 → 执行激活逻辑
|
||||
|
||||
---
|
||||
|
||||
## 边界条件
|
||||
|
||||
### 1. 并发首次实名
|
||||
|
||||
- **场景**：设备的2张卡同时完成实名认证（并发请求）
|
||||
- **处理**：
|
||||
- 使用数据库行锁：`SELECT * FROM device WHERE id=? FOR UPDATE`
|
||||
- 第1个请求更新 realname_status=1，触发激活
|
||||
- 第2个请求发现 realname_status=1，不触发激活
|
||||
|
||||
### 2. 激活任务部分失败
|
||||
|
||||
- **场景**：设备有3个待激活套餐，激活第2个时失败
|
||||
- **处理**：
|
||||
- 使用事务：全部激活成功才提交
|
||||
- 失败时回滚，3个套餐保持 status=0
|
||||
- Asynq 重试，重新激活全部3个套餐
|
||||
|
||||
### 3. 实名时无待激活套餐
|
||||
|
||||
- **场景**：设备首次实名时，无任何套餐
|
||||
- **处理**：
|
||||
- 仍然入队 Asynq 任务
|
||||
- 任务执行时查询套餐数量=0，直接返回成功
|
||||
- 不记录错误日志
|
||||
|
||||
### 4. 套餐购买和实名并发
|
||||
|
||||
- **场景**：设备购买套餐的同时，完成首次实名
|
||||
- **处理**：
|
||||
- 购买订单时检查 realname_status：
|
||||
- 如果未实名 → status=0，pending_realname_activation=true
|
||||
- 如果已实名 → status=1，立即生效
|
||||
- 实名激活任务执行时，再次检查套餐状态，只激活 status=0 的套餐
|
||||
|
||||
### 5. 有效期计算异常
|
||||
|
||||
- **场景**：套餐 calendar_type 或 duration_days/duration_months 为 NULL
|
||||
- **处理**：
|
||||
- 激活失败，返回错误 500
|
||||
- 记录 Error 日志（包含套餐ID、载体ID、错误原因）
|
||||
- Asynq 重试（最多3次）
|
||||
- 3次失败后写入死信队列，发送告警
|
||||
|
||||
---
|
||||
|
||||
## 并发场景
|
||||
|
||||
### Scenario: 并发首次实名
|
||||
- **GIVEN** 设备 ID=123，realname_status=0，有2张卡
|
||||
- **WHEN** 两张卡同时在 2026-02-15 10:30:00 完成实名认证
|
||||
- **THEN** 系统使用行锁：
|
||||
```sql
|
||||
SELECT * FROM device WHERE id=123 FOR UPDATE
|
||||
```
|
||||
- **AND** 第1个请求：
|
||||
- 更新 realname_status=1
|
||||
- 入队 Asynq 任务
|
||||
- **AND** 第2个请求：
|
||||
- 发现 realname_status=1
|
||||
- 不入队任务
|
||||
|
||||
### Scenario: 并发购买套餐和首次实名
|
||||
- **GIVEN** 设备 ID=123，realname_status=0
|
||||
- **WHEN** 同时发生：
|
||||
- 请求1：管理员购买套餐（enable_realname_activation=true）
|
||||
- 请求2：设备完成首次实名
|
||||
- **THEN** 使用事务隔离：
|
||||
- 如果请求1先完成 → 套餐 status=0，然后被请求2激活
|
||||
- 如果请求2先完成 → 设备 realname_status=1，请求1创建套餐时 status=1（立即生效）
|
||||
|
||||
### Scenario: 并发激活任务（重复入队）
|
||||
- **GIVEN** Asynq 任务 "realname_activation" 因网络抖动重复入队
|
||||
- **WHEN** Worker 同时处理2个相同任务
|
||||
- **THEN** 系统使用行锁：
|
||||
```sql
|
||||
SELECT * FROM package_usage WHERE carrier_id=? AND status=0 FOR UPDATE
|
||||
```
|
||||
- **AND** 第1个任务：激活成功，套餐 status=1
|
||||
- **AND** 第2个任务：发现 status=1，跳过激活
|
||||
|
||||
---
|
||||
|
||||
## 异常处理
|
||||
|
||||
### 1. 激活任务失败
|
||||
|
||||
- **错误场景**：Asynq 任务执行时数据库连接失败
|
||||
- **处理流程**：
|
||||
1. 捕获错误，记录 Error 日志（包含载体ID、错误信息）
|
||||
2. Asynq 自动重试（最多3次，间隔 10s/30s/60s）
|
||||
3. 重试前检查套餐 status（避免重复激活）
|
||||
4. 3次失败后写入死信队列，发送告警通知
|
||||
- **返回错误**：不返回给用户（异步任务），仅记录日志
|
||||
|
||||
### 2. 有效期计算失败
|
||||
|
||||
- **错误场景**：套餐 calendar_type 或 duration_days 数据异常
|
||||
- **处理流程**：
|
||||
1. 激活失败，套餐 status 保持 0
|
||||
2. 记录 Error 日志（包含套餐ID、载体ID、calendar_type、duration_days）
|
||||
3. Asynq 重试（最多3次）
|
||||
4. 3次失败后写入死信队列，发送告警
|
||||
- **返回错误**：不返回给用户（异步任务），仅记录日志
|
||||
|
||||
### 3. 批量激活部分失败
|
||||
|
||||
- **错误场景**：设备有3个待激活套餐，激活第2个时失败
|
||||
- **处理流程**：
|
||||
1. 使用事务包裹批量更新
|
||||
2. 任何一个套餐激活失败 → 事务回滚，全部套餐保持 status=0
|
||||
3. 记录 Error 日志（包含设备ID、失败套餐ID、错误原因）
|
||||
4. Asynq 重试，重新激活全部套餐
|
||||
- **返回错误**：不返回给用户（异步任务），仅记录日志
|
||||
|
||||
### 4. 首次实名判定失败
|
||||
|
||||
- **错误场景**：查询设备的 IoT 卡列表时超时
|
||||
- **处理流程**：
|
||||
1. 实名认证流程继续（不阻塞）
|
||||
2. Asynq 任务入队
|
||||
3. 任务执行时再次尝试查询，失败则重试
|
||||
4. 3次失败后写入死信队列
|
||||
- **返回错误**：实名认证返回成功，激活任务在后台处理
|
||||
|
||||
---
|
||||
|
||||
## 数据一致性保证
|
||||
|
||||
### 1. 事务边界
|
||||
|
||||
- **首次实名 + 入队任务**：更新 realname_status 后再入队（确保任务执行时状态已更新）
|
||||
- **批量激活套餐**：使用单个事务，全部成功或全部失败
|
||||
- **并发首次实名检查**：使用 `SELECT FOR UPDATE` 行锁
|
||||
|
||||
### 2. 行锁机制
|
||||
|
||||
- **首次实名检查**：`SELECT * FROM device WHERE id=? FOR UPDATE`
|
||||
- **批量激活套餐**：`SELECT * FROM package_usage WHERE carrier_id=? AND status=0 FOR UPDATE`
|
||||
|
||||
### 3. 幂等性保证
|
||||
|
||||
#### 使用 first_realname_at 字段确保首次实名幂等
|
||||
|
||||
系统使用 `tb_iot_card.first_realname_at` 字段（时间戳）确保首次实名激活只执行一次：
|
||||
|
||||
**数据库字段**：
|
||||
```sql
|
||||
-- tb_iot_card 新增字段
|
||||
ALTER TABLE tb_iot_card
|
||||
ADD COLUMN first_realname_at TIMESTAMP NULL COMMENT '首次实名时间，NULL=未实名，非NULL=已实名（幂等标记）';
|
||||
```
|
||||
|
||||
**幂等更新**：
|
||||
```sql
|
||||
-- 首次实名触发时（原子操作）
|
||||
UPDATE tb_iot_card
|
||||
SET first_realname_at = NOW()
|
||||
WHERE id = ? AND first_realname_at IS NULL;
|
||||
|
||||
-- 通过影响行数判断是否首次实名
|
||||
-- rows_affected = 1 → 首次实名，执行激活逻辑
|
||||
-- rows_affected = 0 → 已处理，跳过
|
||||
```
|
||||
|
||||
**优势**：
|
||||
- **比 realname_status 更可靠**：状态字段可能被重置，时间戳不可逆
|
||||
- **可追溯首次实名时间**：便于审计和问题排查
|
||||
- **数据库层面保证唯一更新**：WHERE 条件确保只有首次实名时更新成功
|
||||
- **无需 Redis 锁**：数据库行级锁已足够，减少依赖
|
||||
|
||||
**实现示例**：
|
||||
```go
|
||||
// Service 层：检查并标记首次实名
|
||||
func (s *Service) MarkFirstRealname(ctx context.Context, cardID uint) (bool, error) {
|
||||
result := s.db.WithContext(ctx).
|
||||
Model(&model.IotCard{}).
|
||||
Where("id = ? AND first_realname_at IS NULL", cardID).
|
||||
Update("first_realname_at", time.Now())
|
||||
|
||||
if result.Error != nil {
|
||||
return false, errors.Wrap(errors.CodeInternal, result.Error, "更新首次实名时间失败")
|
||||
}
|
||||
|
||||
// 影响行数 = 1 表示首次实名
|
||||
isFirstRealname := result.RowsAffected == 1
|
||||
|
||||
return isFirstRealname, nil
|
||||
}
|
||||
|
||||
// 轮询系统：检测实名状态变更时
|
||||
func (h *Handler) HandleRealnameCheck(ctx context.Context, task *asynq.Task) error {
|
||||
// 1. 检测到卡实名状态变更（realname_status: 0 → 2）
|
||||
// ...
|
||||
|
||||
// 2. 尝试标记首次实名
|
||||
isFirstRealname, err := h.iotCardService.MarkFirstRealname(ctx, cardID)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// 3. 只有首次实名时才触发套餐激活
|
||||
if isFirstRealname {
|
||||
err := h.queueClient.Enqueue(TaskTypePackageFirstActivation, payload)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
- **激活任务幂等**：执行前检查套餐 status，如果已激活则跳过
|
||||
- **实名状态幂等**：重复实名不触发激活（通过 first_realname_at 字段保证）
|
||||
|
||||
### 4. 数据校验
|
||||
|
||||
- **购买套餐前**：校验 enable_realname_activation 与 realname_status 的一致性
|
||||
- **激活套餐前**：校验 calendar_type 和 duration_days/duration_months 是否有效
|
||||
- **首次实名判定**：校验设备的 IoT 卡列表是否完整
|
||||
|
||||
---
|
||||
|
||||
## 性能指标
|
||||
|
||||
| 操作 | 目标响应时间 | 并发要求 | 数据量 |
|
||||
|------|-------------|---------|--------|
|
||||
| 后台购买套餐（实名检查） | < 50ms | 100 QPS | 单载体查询 |
|
||||
| 客户端购买套餐（实名检查） | < 100ms | 200 QPS | 单载体查询 |
|
||||
| 首次实名入队任务 | < 50ms | 100 QPS | 入队操作 |
|
||||
| 激活任务执行（批量激活） | < 1000ms | 50 QPS | 批量更新（平均5个套餐） |
|
||||
|
||||
---
|
||||
|
||||
## 错误码定义
|
||||
|
||||
| 错误码 | HTTP 状态码 | 错误消息 | 场景 |
|
||||
|--------|------------|---------|------|
|
||||
| `REALNAME_REQUIRED` | 403 | 设备/卡必须先完成实名认证才能购买套餐 | 客户端购买套餐时未实名 |
|
||||
| `ACTIVATION_FAILED` | 500 | 套餐激活失败，请稍后重试 | 激活任务执行失败 |
|
||||
| `EXPIRY_CALCULATION_FAILED` | 500 | 有效期计算失败，请联系管理员 | calendar_type 或 duration 数据异常 |
|
||||
| `REALNAME_STATUS_UPDATE_FAILED` | 500 | 实名状态更新失败，请稍后重试 | 更新 realname_status 失败 |
|
||||
|
||||
---
|
||||
|
||||
## 数据迁移策略
|
||||
|
||||
**激进策略**（开发阶段，保证干净性）：
|
||||
|
||||
### 1. ❌ 要删除的字段
|
||||
|
||||
目前 `package_usage` 表中可能存在的冗余字段（需确认后删除）：
|
||||
- 如果有 `realname_activated` 字段（旧的实名激活标志） → **删除**
|
||||
- 如果有 `wait_realname` 字段（旧的等待实名标志） → **删除**
|
||||
|
||||
目前 `package` 表中可能存在的冗余字段（需确认后删除）：
|
||||
- 如果有 `require_realname` 字段（旧的实名要求标志） → **删除**
|
||||
|
||||
目前 `device` 和 `iot_card` 表中可能存在的冗余字段（需确认后删除）：
|
||||
- 如果有 `is_realname` 字段（旧的实名标志） → **删除**，统一使用 `realname_status`
|
||||
|
||||
### 2. ✅ 新增的字段
|
||||
|
||||
在 `package_usage` 表中新增：
|
||||
```sql
|
||||
ALTER TABLE package_usage
|
||||
ADD COLUMN pending_realname_activation BOOLEAN DEFAULT false COMMENT '是否等待实名激活';
|
||||
|
||||
CREATE INDEX idx_pending_realname_activation ON package_usage(carrier_id, pending_realname_activation, status);
|
||||
```
|
||||
|
||||
在 `package` 表中新增：
|
||||
```sql
|
||||
ALTER TABLE package
|
||||
ADD COLUMN enable_realname_activation BOOLEAN DEFAULT false COMMENT '是否启用实名激活机制（true=支持未实名购买并等待激活，false=立即生效）';
|
||||
```
|
||||
|
||||
在 `device` 表中新增（如果不存在）：
|
||||
```sql
|
||||
ALTER TABLE device
|
||||
ADD COLUMN realname_status TINYINT DEFAULT 0 COMMENT '实名状态（0-未实名，1-已实名）';
|
||||
|
||||
CREATE INDEX idx_realname_status ON device(realname_status);
|
||||
```
|
||||
|
||||
在 `iot_card` 表中新增（如果不存在）：
|
||||
```sql
|
||||
ALTER TABLE iot_card
|
||||
ADD COLUMN realname_status TINYINT DEFAULT 0 COMMENT '实名状态（0-未实名，1-已实名）';
|
||||
|
||||
CREATE INDEX idx_realname_status ON iot_card(realname_status);
|
||||
```
|
||||
|
||||
### 3. ❌ 要废弃的逻辑
|
||||
|
||||
- **废弃旧的实名检查逻辑**：如果代码中存在通过 `is_realname` 或 `require_realname` 字段检查实名的逻辑，全部删除
|
||||
- **废弃旧的激活逻辑**：如果代码中存在手动激活套餐的逻辑（非首次实名触发），全部删除
|
||||
- **废弃旧的实名状态字段**：统一使用 `realname_status`（0/1），删除其他相关字段
|
||||
|
||||
### 4. ✅ 历史数据强制转换
|
||||
|
||||
```sql
|
||||
-- Step 1: 历史设备/卡的实名状态初始化
|
||||
-- 根据实际业务规则确定历史数据的实名状态（假设有 realname_info 字段）
|
||||
UPDATE device
|
||||
SET realname_status = CASE
|
||||
WHEN realname_info IS NOT NULL AND realname_info != '' THEN 1
|
||||
ELSE 0
|
||||
END
|
||||
WHERE realname_status IS NULL;
|
||||
|
||||
UPDATE iot_card
|
||||
SET realname_status = CASE
|
||||
WHEN realname_info IS NOT NULL AND realname_info != '' THEN 1
|
||||
ELSE 0
|
||||
END
|
||||
WHERE realname_status IS NULL;
|
||||
|
||||
-- Step 2: 历史套餐的实名激活配置初始化
|
||||
-- 假设历史套餐默认不启用实名激活（立即生效）
|
||||
UPDATE package
|
||||
SET enable_realname_activation = false
|
||||
WHERE enable_realname_activation IS NULL;
|
||||
|
||||
-- Step 3: 历史 PackageUsage 的 pending_realname_activation 初始化
|
||||
-- 已生效的套餐：pending_realname_activation=false
|
||||
UPDATE package_usage
|
||||
SET pending_realname_activation = false
|
||||
WHERE status IN (1, 2, 3, 4) -- 生效中、已用完、已过期、已失效
|
||||
AND pending_realname_activation IS NULL;
|
||||
|
||||
-- 待生效的套餐：根据载体实名状态判断
|
||||
-- 如果载体未实名 → pending_realname_activation=true
|
||||
-- 如果载体已实名 → 强制激活套餐（status=1）
|
||||
-- 注意：需要根据 carrier_type 判断是 device 还是 iot_card
|
||||
UPDATE package_usage pu
|
||||
SET pending_realname_activation = true
|
||||
WHERE pu.status = 0
|
||||
AND pu.pending_realname_activation IS NULL
|
||||
AND EXISTS (
|
||||
SELECT 1 FROM device d
|
||||
WHERE d.id = pu.carrier_id
|
||||
AND pu.carrier_type = 'device'
|
||||
AND d.realname_status = 0
|
||||
);
|
||||
|
||||
UPDATE package_usage pu
|
||||
SET pending_realname_activation = true
|
||||
WHERE pu.status = 0
|
||||
AND pu.pending_realname_activation IS NULL
|
||||
AND EXISTS (
|
||||
SELECT 1 FROM iot_card ic
|
||||
WHERE ic.id = pu.carrier_id
|
||||
AND pu.carrier_type = 'iot_card'
|
||||
AND ic.realname_status = 0
|
||||
);
|
||||
|
||||
-- Step 4: 已实名但待生效的套餐强制激活
|
||||
-- （这些套餐应该在购买时就激活，现在补上）
|
||||
UPDATE package_usage pu
|
||||
SET status = 1,
|
||||
activated_at = pu.created_at, -- 假设使用创建时间作为激活时间
|
||||
pending_realname_activation = false
|
||||
WHERE pu.status = 0
|
||||
AND EXISTS (
|
||||
SELECT 1 FROM device d
|
||||
WHERE d.id = pu.carrier_id
|
||||
AND pu.carrier_type = 'device'
|
||||
AND d.realname_status = 1
|
||||
);
|
||||
|
||||
UPDATE package_usage pu
|
||||
SET status = 1,
|
||||
activated_at = pu.created_at,
|
||||
pending_realname_activation = false
|
||||
WHERE pu.status = 0
|
||||
AND EXISTS (
|
||||
SELECT 1 FROM iot_card ic
|
||||
WHERE ic.id = pu.carrier_id
|
||||
AND pu.carrier_type = 'iot_card'
|
||||
AND ic.realname_status = 1
|
||||
);
|
||||
|
||||
-- 注意：Step 4 强制激活的套餐需要重新计算 expires_at
|
||||
-- 建议编写数据修复脚本，调用有效期计算逻辑
|
||||
```
|
||||
|
||||
### 5. ❌ 删除遗留表/字段（确认后执行）
|
||||
|
||||
```sql
|
||||
-- 如果存在旧的实名相关字段，删除
|
||||
-- ALTER TABLE package_usage DROP COLUMN IF EXISTS realname_activated;
|
||||
-- ALTER TABLE package_usage DROP COLUMN IF EXISTS wait_realname;
|
||||
-- ALTER TABLE package DROP COLUMN IF EXISTS require_realname;
|
||||
-- ALTER TABLE device DROP COLUMN IF EXISTS is_realname;
|
||||
-- ALTER TABLE iot_card DROP COLUMN IF EXISTS is_realname;
|
||||
```
|
||||
|
||||
### 6. 验证步骤
|
||||
|
||||
```sql
|
||||
-- 验证1：所有设备和卡都有 realname_status
|
||||
SELECT COUNT(*)
|
||||
FROM device
|
||||
WHERE realname_status IS NULL;
|
||||
-- 预期结果：0
|
||||
|
||||
SELECT COUNT(*)
|
||||
FROM iot_card
|
||||
WHERE realname_status IS NULL;
|
||||
-- 预期结果：0
|
||||
|
||||
-- 验证2：所有套餐都有 enable_realname_activation
|
||||
SELECT COUNT(*)
|
||||
FROM package
|
||||
WHERE enable_realname_activation IS NULL;
|
||||
-- 预期结果：0
|
||||
|
||||
-- 验证3：所有 PackageUsage 都有 pending_realname_activation
|
||||
SELECT COUNT(*)
|
||||
FROM package_usage
|
||||
WHERE pending_realname_activation IS NULL;
|
||||
-- 预期结果：0
|
||||
|
||||
-- 验证4：待生效套餐的载体必须未实名（或有 pending_realname_activation=true）
|
||||
SELECT COUNT(*)
|
||||
FROM package_usage pu
|
||||
JOIN device d ON pu.carrier_id = d.id AND pu.carrier_type = 'device'
|
||||
WHERE pu.status = 0
|
||||
AND pu.pending_realname_activation = false
|
||||
AND d.realname_status = 0;
|
||||
-- 预期结果：0（不应该有未实名但又不等待激活的待生效套餐）
|
||||
|
||||
-- 验证5：已实名载体的套餐不应该待生效（除非后续购买）
|
||||
-- （这个验证需要根据实际业务规则调整）
|
||||
SELECT COUNT(*)
|
||||
FROM package_usage pu
|
||||
JOIN device d ON pu.carrier_id = d.id AND pu.carrier_type = 'device'
|
||||
WHERE pu.status = 0
|
||||
AND pu.pending_realname_activation = true
|
||||
AND d.realname_status = 1;
|
||||
-- 预期结果：0（已实名设备不应该有等待激活的套餐）
|
||||
|
||||
-- 验证6：检查是否还有遗留字段（需根据实际情况调整）
|
||||
-- SELECT column_name FROM information_schema.columns
|
||||
-- WHERE table_name = 'package_usage'
|
||||
-- AND column_name IN ('realname_activated', 'wait_realname');
|
||||
-- 预期结果：0 rows
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试场景矩阵
|
||||
|
||||
| 场景分类 | 测试用例 | 预期结果 |
|
||||
|---------|---------|---------|
|
||||
| **购买套餐** | 后台购买套餐（未实名设备，enable_realname_activation=true） | status=0，pending_realname_activation=true |
|
||||
| | 后台购买套餐（未实名设备，enable_realname_activation=false） | status=1，立即生效 |
|
||||
| | 后台购买套餐（已实名设备） | status=1，立即生效 |
|
||||
| | 客户端购买套餐（未实名设备） | 返回错误 403：REALNAME_REQUIRED |
|
||||
| | 客户端购买套餐（已实名设备） | status=1，立即生效 |
|
||||
| **首次实名** | 设备首张卡实名 | 触发激活，套餐 status=1 |
|
||||
| | 设备后续卡实名 | 不触发激活，套餐状态不变 |
|
||||
| | 单卡设备实名 | 触发激活，套餐 status=1 |
|
||||
| | 并发首次实名 | 使用行锁，只触发1次激活 |
|
||||
| **激活逻辑** | 激活自然月套餐 | expires_at=当月最后一天 23:59:59 |
|
||||
| | 激活按天套餐 | expires_at=activated_at+duration_days-1秒 |
|
||||
| | 激活时无待激活套餐 | 任务直接返回成功，不报错 |
|
||||
| | 激活时排除已生效套餐 | 只激活 status=0 的套餐 |
|
||||
| **异步任务** | 实名成功后入队任务 | 任务入队成功，payload 包含载体信息 |
|
||||
| | 激活任务在1分钟内完成 | 批量更新成功，任务标记为完成 |
|
||||
| | 激活任务失败后重试 | Asynq 重试3次，失败后进入死信队列 |
|
||||
| | 激活任务幂等性 | 重复执行时检查状态，跳过已激活套餐 |
|
||||
| **并发** | 并发购买套餐和首次实名 | 事务隔离，先完成的操作生效 |
|
||||
| | 并发激活任务 | 使用行锁，避免重复激活 |
|
||||
| **异常** | 有效期计算失败 | 激活失败，记录日志，Asynq 重试 |
|
||||
| | 批量激活部分失败 | 事务回滚，全部套餐保持 status=0 |
|
||||
| | 首次实名判定失败 | 不阻塞实名流程，任务重试 |
|
||||
|
||||
---
|
||||
|
||||
## 实现参考
|
||||
|
||||
### 购买套餐时的实名检查
|
||||
|
||||
```go
|
||||
// Service 层：CreateOrder
|
||||
func (s *Service) CreateOrder(ctx context.Context, req *CreateOrderRequest) error {
|
||||
// 1. 检查载体实名状态
|
||||
realnameStatus, err := s.getCarrierRealnameStatus(ctx, req.CarrierType, req.CarrierID)
|
||||
if err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "查询实名状态失败")
|
||||
}
|
||||
|
||||
// 2. 客户端购买必须实名
|
||||
requestSource := middleware.GetRequestSourceFromContext(ctx) // "admin" or "customer"
|
||||
if requestSource == "customer" && realnameStatus == 0 {
|
||||
return errors.New(errors.CodeForbidden, "设备/卡必须先完成实名认证才能购买套餐")
|
||||
}
|
||||
|
||||
// 3. 查询套餐配置
|
||||
pkg, err := s.packageStore.GetByID(ctx, req.PackageID)
|
||||
if err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "查询套餐失败")
|
||||
}
|
||||
|
||||
// 4. 确定套餐状态
|
||||
var status int
|
||||
var pendingRealnameActivation bool
|
||||
|
||||
if pkg.EnableRealnameActivation && realnameStatus == 0 && requestSource == "admin" {
|
||||
// 后台购买未实名设备的实名激活套餐 → 待生效
|
||||
status = constants.PackageStatusPending
|
||||
pendingRealnameActivation = true
|
||||
} else {
|
||||
// 其他情况 → 立即生效
|
||||
status = constants.PackageStatusActive
|
||||
pendingRealnameActivation = false
|
||||
}
|
||||
|
||||
// 5. 创建 PackageUsage
|
||||
usage := &model.PackageUsage{
|
||||
CarrierType: req.CarrierType,
|
||||
CarrierID: req.CarrierID,
|
||||
PackageID: req.PackageID,
|
||||
Status: status,
|
||||
PendingRealnameActivation: pendingRealnameActivation,
|
||||
}
|
||||
|
||||
if status == constants.PackageStatusActive {
|
||||
// 立即生效：计算 activated_at 和 expires_at
|
||||
usage.ActivatedAt = time.Now()
|
||||
usage.ExpiresAt = s.calculateExpiresAt(usage.ActivatedAt, pkg.CalendarType, pkg.DurationDays, pkg.DurationMonths)
|
||||
}
|
||||
|
||||
if err := s.packageUsageStore.Create(ctx, usage); err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "创建套餐使用记录失败")
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### 首次实名时入队激活任务
|
||||
|
||||
```go
|
||||
// Service 层：HandleRealnameSuccess
|
||||
func (s *Service) HandleRealnameSuccess(ctx context.Context, carrierType string, carrierID uint) error {
|
||||
// 1. 检查是否为首次实名
|
||||
isFirstRealname, err := s.checkFirstRealname(ctx, carrierType, carrierID)
|
||||
if err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "检查首次实名失败")
|
||||
}
|
||||
|
||||
if !isFirstRealname {
|
||||
s.logger.Info("非首次实名，跳过激活",
|
||||
zap.String("carrier_type", carrierType),
|
||||
zap.Uint("carrier_id", carrierID))
|
||||
return nil
|
||||
}
|
||||
|
||||
// 2. 更新实名状态
|
||||
if err := s.updateRealnameStatus(ctx, carrierType, carrierID, 1); err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "更新实名状态失败")
|
||||
}
|
||||
|
||||
// 3. 入队激活任务
|
||||
payload := map[string]interface{}{
|
||||
"carrier_type": carrierType,
|
||||
"carrier_id": carrierID,
|
||||
"realname_at": time.Now().Format(time.RFC3339),
|
||||
}
|
||||
|
||||
if err := s.asynqClient.Enqueue("realname_activation", payload); err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "入队激活任务失败")
|
||||
}
|
||||
|
||||
s.logger.Info("首次实名成功，已入队激活任务",
|
||||
zap.String("carrier_type", carrierType),
|
||||
zap.Uint("carrier_id", carrierID))
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// Service 层：checkFirstRealname
|
||||
func (s *Service) checkFirstRealname(ctx context.Context, carrierType string, carrierID uint) (bool, error) {
|
||||
if carrierType == "device" {
|
||||
// 查询设备当前实名状态
|
||||
device, err := s.deviceStore.GetByID(ctx, carrierID)
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
return device.RealnameStatus == 0, nil // 0=未实名，首次实名
|
||||
} else if carrierType == "iot_card" {
|
||||
// 查询卡当前实名状态
|
||||
card, err := s.iotCardStore.GetByICCID(ctx, carrierID)
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
return card.RealnameStatus == 0, nil
|
||||
}
|
||||
return false, fmt.Errorf("unsupported carrier_type: %s", carrierType)
|
||||
}
|
||||
```
|
||||
|
||||
### Asynq Worker 处理激活任务
|
||||
|
||||
```go
|
||||
// Handler: HandleRealnameActivation
|
||||
func (h *RealnameActivationHandler) HandleRealnameActivation(ctx context.Context, task *asynq.Task) error {
|
||||
var payload struct {
|
||||
CarrierType string `json:"carrier_type"`
|
||||
CarrierID uint `json:"carrier_id"`
|
||||
RealnameAt string `json:"realname_at"`
|
||||
}
|
||||
|
||||
if err := json.Unmarshal(task.Payload(), &payload); err != nil {
|
||||
return fmt.Errorf("unmarshal payload failed: %w", err)
|
||||
}
|
||||
|
||||
realnameAt, _ := time.Parse(time.RFC3339, payload.RealnameAt)
|
||||
|
||||
// 1. 查询待激活套餐
|
||||
usages, err := h.packageUsageStore.ListPendingRealnameActivation(ctx, payload.CarrierType, payload.CarrierID)
|
||||
if err != nil {
|
||||
return fmt.Errorf("list pending activation failed: %w", err)
|
||||
}
|
||||
|
||||
if len(usages) == 0 {
|
||||
h.logger.Info("无待激活套餐，任务完成",
|
||||
zap.String("carrier_type", payload.CarrierType),
|
||||
zap.Uint("carrier_id", payload.CarrierID))
|
||||
return nil
|
||||
}
|
||||
|
||||
// 2. 批量激活（使用事务）
|
||||
tx := h.db.Begin()
|
||||
defer tx.Rollback()
|
||||
|
||||
for _, usage := range usages {
|
||||
// 获取套餐配置
|
||||
pkg, err := h.packageStore.GetByID(ctx, usage.PackageID)
|
||||
if err != nil {
|
||||
return fmt.Errorf("get package failed: %w", err)
|
||||
}
|
||||
|
||||
// 计算有效期
|
||||
expiresAt := h.calculateExpiresAt(realnameAt, pkg.CalendarType, pkg.DurationDays, pkg.DurationMonths)
|
||||
|
||||
// 更新套餐状态
|
||||
if err := tx.Model(&usage).Updates(map[string]interface{}{
|
||||
"status": constants.PackageStatusActive,
|
||||
"activated_at": realnameAt,
|
||||
"expires_at": expiresAt,
|
||||
"pending_realname_activation": false,
|
||||
}).Error; err != nil {
|
||||
return fmt.Errorf("activate package failed: %w", err)
|
||||
}
|
||||
}
|
||||
|
||||
if err := tx.Commit().Error; err != nil {
|
||||
return fmt.Errorf("commit transaction failed: %w", err)
|
||||
}
|
||||
|
||||
h.logger.Info("套餐激活成功",
|
||||
zap.String("carrier_type", payload.CarrierType),
|
||||
zap.Uint("carrier_id", payload.CarrierID),
|
||||
zap.Int("count", len(usages)))
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**本 Spec 完成**，包含：
|
||||
- ✅ 业务背景和业务规则
|
||||
- ✅ 详细场景（购买套餐、首次实名、激活逻辑、异步任务）
|
||||
- ✅ 边界条件和并发场景
|
||||
- ✅ 异常处理和数据一致性保证
|
||||
- ✅ 性能指标和错误码定义
|
||||
- ✅ **激进的数据迁移策略**（明确删除字段、废弃逻辑、强制转换）
|
||||
- ✅ 测试场景矩阵和实现参考
|
||||
367
openspec/specs/package-usage-customer-view/spec.md
Normal file
367
openspec/specs/package-usage-customer-view/spec.md
Normal file
@@ -0,0 +1,367 @@
|
||||
# Spec: 客户视图流量查询
|
||||
|
||||
## 业务背景
|
||||
|
||||
### 为什么需要客户视图流量查询
|
||||
|
||||
**现状问题**：
|
||||
- 客户无法清晰看到主套餐和加油包的分别使用情况
|
||||
- 流量汇总不准确（包含已失效加油包）
|
||||
- 客户端需要多次调用 API 才能获取完整流量信息
|
||||
|
||||
**业务目标**：
|
||||
- 提供统一的流量查询 API
|
||||
- 区分主套餐和加油包流量
|
||||
- 自动汇总总计流量
|
||||
- 仅显示当前有效套餐
|
||||
|
||||
---
|
||||
|
||||
## 业务规则
|
||||
|
||||
### 1. 流量汇总规则
|
||||
|
||||
```
|
||||
总计流量 = 主套餐流量 + 所有生效中/已用完加油包流量
|
||||
|
||||
包含的套餐：
|
||||
- status=1（生效中）
|
||||
- status=2（已用完但未过期）
|
||||
|
||||
不包含的套餐：
|
||||
- status=0（待生效）
|
||||
- status=3（已过期）
|
||||
- status=4（已失效）
|
||||
```
|
||||
|
||||
### 2. 主套餐优先显示
|
||||
|
||||
- **规则**：如果有多个主套餐（理论上只有1个生效中），优先显示 status=1 的主套餐
|
||||
- **待生效主套餐**：不在客户视图中显示
|
||||
|
||||
### 3. 加油包按优先级排序
|
||||
|
||||
- **排序规则**：按 priority ASC 排序（优先扣减的加油包排在前面）
|
||||
- **失效加油包**：不在客户视图中显示
|
||||
|
||||
---
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 提供客户视图流量查询 API
|
||||
|
||||
系统 SHALL 提供 GET /api/h5/packages/my-usage API，返回客户的套餐流量使用情况。
|
||||
|
||||
#### Scenario: 查询单个主套餐流量
|
||||
- **GIVEN** 客户有1个主套餐（已用 8GB，总量 10GB），无加油包
|
||||
- **WHEN** 客户调用 GET /api/h5/packages/my-usage
|
||||
- **THEN** 系统返回：
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"main_package": {
|
||||
"package_id": 123,
|
||||
"package_name": "月度套餐10GB",
|
||||
"used_mb": 8192,
|
||||
"total_mb": 10240,
|
||||
"status": 1,
|
||||
"status_text": "生效中",
|
||||
"expires_at": "2026-02-28T23:59:59Z"
|
||||
},
|
||||
"addon_packages": [],
|
||||
"total": {
|
||||
"used_mb": 8192,
|
||||
"total_mb": 10240
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Scenario: 查询主套餐和加油包流量
|
||||
- **GIVEN** 客户有：
|
||||
- 主套餐：已用 9GB，总量 10GB
|
||||
- 加油包1（priority=1）：已用 3GB，总量 5GB
|
||||
- 加油包2（priority=2）：已用 1GB，总量 3GB
|
||||
- **WHEN** 客户调用 GET /api/h5/packages/my-usage
|
||||
- **THEN** 系统返回 main_package, addon_packages（2个加油包，按 priority 排序）, total: {used: 13GB, total: 18GB}
|
||||
|
||||
#### Scenario: 主套餐用完但加油包有剩余
|
||||
- **GIVEN** 客户主套餐已用 10GB/总量 10GB（status=2），加油包已用 2GB/总量 5GB（status=1）
|
||||
- **WHEN** 客户调用 API
|
||||
- **THEN** 系统返回：
|
||||
- main_package: status=2, status_text="已用完"
|
||||
- addon_packages: status=1, status_text="生效中"
|
||||
- total: {used: 12GB, total: 15GB}
|
||||
|
||||
### Requirement: 客户视图区分主套餐和加油包
|
||||
|
||||
系统 SHALL 在响应中明确区分主套餐（main_package）和加油包（addon_packages）的流量信息。
|
||||
|
||||
#### Scenario: 响应包含主套餐信息
|
||||
- **WHEN** 客户查询流量使用情况
|
||||
- **THEN** 响应的 main_package 字段包含：
|
||||
- package_id, package_name
|
||||
- used_mb, total_mb
|
||||
- status, status_text
|
||||
- expires_at, activated_at
|
||||
|
||||
#### Scenario: 响应包含加油包列表
|
||||
- **GIVEN** 客户有3个加油包
|
||||
- **WHEN** 客户查询
|
||||
- **THEN** 响应的 addon_packages 字段为数组，按 priority 排序，每个元素包含：
|
||||
- package_id, package_name
|
||||
- used_mb, total_mb
|
||||
- status, status_text
|
||||
- expires_at, activated_at
|
||||
- priority
|
||||
|
||||
### Requirement: 客户视图显示总计流量
|
||||
|
||||
系统 SHALL 在响应中提供 total 字段，汇总主套餐和所有加油包的流量。
|
||||
|
||||
#### Scenario: 总计流量计算正确
|
||||
- **GIVEN** 主套餐 used=8GB/total=10GB，加油包1 used=2GB/total=5GB，加油包2 used=1GB/total=3GB
|
||||
- **WHEN** 计算总计
|
||||
- **THEN** total: {used_mb: 11GB, total_mb: 18GB}
|
||||
|
||||
#### Scenario: 已失效加油包不计入总计
|
||||
- **GIVEN** 主套餐 used=8GB/total=10GB，加油包 status=4（已失效）used=2GB/total=5GB
|
||||
- **WHEN** 计算总计
|
||||
- **THEN** total: {used_mb: 8GB, total_mb: 10GB}（不包含已失效加油包）
|
||||
|
||||
#### Scenario: 已用完套餐计入总计
|
||||
- **GIVEN** 主套餐 status=2（已用完）used=10GB/total=10GB，加油包 status=1 used=2GB/total=5GB
|
||||
- **WHEN** 计算总计
|
||||
- **THEN** total: {used_mb: 12GB, total_mb: 15GB}（已用完套餐仍计入）
|
||||
|
||||
### Requirement: 客户视图仅返回当前生效套餐
|
||||
|
||||
系统 SHALL 仅返回 status=1（生效中）或 status=2（已用完但未过期）的套餐信息。
|
||||
|
||||
#### Scenario: 不返回待生效套餐
|
||||
- **GIVEN** 客户有1个生效中主套餐（status=1）和1个待生效主套餐（status=0）
|
||||
- **WHEN** 客户查询
|
||||
- **THEN** 响应仅包含生效中的主套餐，不包含待生效套餐
|
||||
|
||||
#### Scenario: 不返回已过期套餐
|
||||
- **GIVEN** 客户的主套餐已过期（status=3）
|
||||
- **WHEN** 客户查询
|
||||
- **THEN** 响应 main_package=null，提示"无有效套餐"
|
||||
|
||||
#### Scenario: 不返回已失效加油包
|
||||
- **GIVEN** 客户有生效中主套餐和1个已失效加油包（status=4）
|
||||
- **WHEN** 客户查询
|
||||
- **THEN** 响应 addon_packages 不包含已失效加油包
|
||||
|
||||
### Requirement: 客户视图性能要求
|
||||
|
||||
系统 SHALL 确保客户视图 API 响应时间 P95 < 200ms。
|
||||
|
||||
#### Scenario: 查询性能达标
|
||||
- **GIVEN** 客户有1个主套餐和5个加油包
|
||||
- **WHEN** 客户调用 API
|
||||
- **THEN** API 响应时间 < 200ms（P95）
|
||||
|
||||
#### Scenario: 使用索引优化查询
|
||||
- **GIVEN** 系统有索引 idx_carrier_status（carrier_id + status）
|
||||
- **WHEN** 查询套餐时
|
||||
- **THEN** 数据库使用索引，查询时间 < 50ms
|
||||
|
||||
---
|
||||
|
||||
## 边界条件
|
||||
|
||||
### 1. 无任何套餐
|
||||
|
||||
- **场景**：客户没有购买任何套餐
|
||||
- **处理**：返回 main_package=null, addon_packages=[], total={used_mb:0, total_mb:0}
|
||||
|
||||
### 2. 主套餐过期但加油包未过期
|
||||
|
||||
- **场景**：主套餐过期，加油包有独立有效期且未过期
|
||||
- **处理**：主套餐过期时，加油包被级联失效（status=4），不显示在客户视图
|
||||
|
||||
### 3. 并发查询
|
||||
|
||||
- **场景**：客户短时间内多次调用查询 API
|
||||
- **处理**：使用只读事务，确保数据一致性
|
||||
|
||||
---
|
||||
|
||||
## 数据一致性保证
|
||||
|
||||
### 1. 只读事务
|
||||
|
||||
- **查询套餐**：使用只读事务，确保数据一致性
|
||||
|
||||
### 2. 索引优化
|
||||
|
||||
- **必需索引**：
|
||||
- `idx_carrier_status`（carrier_id + status）
|
||||
- `idx_package_type_priority`（package_type + priority）
|
||||
|
||||
---
|
||||
|
||||
## 性能指标
|
||||
|
||||
| 操作 | 目标响应时间 | 并发要求 | 数据量 |
|
||||
|------|-------------|---------|--------|
|
||||
| 客户视图查询 | < 200ms (P95) | 500 QPS | 单载体查询（1主套餐+5加油包） |
|
||||
| 数据库查询 | < 50ms | 1000 QPS | 索引查询 |
|
||||
|
||||
---
|
||||
|
||||
## 错误码定义
|
||||
|
||||
| 错误码 | HTTP 状态码 | 错误消息 | 场景 |
|
||||
|--------|------------|---------|------|
|
||||
| `NO_VALID_PACKAGE` | 404 | 无有效套餐 | 客户无任何生效中套餐 |
|
||||
| `CARRIER_NOT_FOUND` | 404 | 载体不存在 | 载体ID不存在 |
|
||||
|
||||
---
|
||||
|
||||
## 数据迁移策略
|
||||
|
||||
**激进策略**（开发阶段，保证干净性）：
|
||||
|
||||
### 1. ❌ 要删除的字段
|
||||
|
||||
无（新增 API，不涉及数据迁移）
|
||||
|
||||
### 2. ✅ 新增的字段
|
||||
|
||||
无（使用现有字段）
|
||||
|
||||
### 3. ❌ 要废弃的逻辑
|
||||
|
||||
- **废弃旧的客户端流量查询 API**：如果存在旧的流量查询接口，统一替换为新接口
|
||||
|
||||
### 4. ✅ 索引优化
|
||||
|
||||
```sql
|
||||
-- 确保必需索引存在
|
||||
CREATE INDEX IF NOT EXISTS idx_carrier_status
|
||||
ON package_usage(carrier_id, status);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_package_type_priority
|
||||
ON package_usage(package_type, priority);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试场景矩阵
|
||||
|
||||
| 场景分类 | 测试用例 | 预期结果 |
|
||||
|---------|---------|---------|
|
||||
| **单个主套餐** | 查询单个主套餐流量 | 返回 main_package, addon_packages=[], total |
|
||||
| **主套餐+加油包** | 查询主套餐和加油包 | 返回 main_package, addon_packages（按 priority 排序）, total |
|
||||
| **总计流量** | 总计流量计算正确 | total = 主套餐 + 所有加油包 |
|
||||
| | 已失效加油包不计入总计 | 不包含 status=4 的加油包 |
|
||||
| | 已用完套餐计入总计 | 包含 status=2 的套餐 |
|
||||
| **筛选套餐** | 不返回待生效套餐 | 仅返回 status IN (1,2) |
|
||||
| | 不返回已过期套餐 | main_package=null |
|
||||
| | 不返回已失效加油包 | addon_packages 不含 status=4 |
|
||||
| **性能** | 查询性能达标 | 响应时间 < 200ms (P95) |
|
||||
| | 使用索引优化 | 数据库查询 < 50ms |
|
||||
| **边界** | 无任何套餐 | main_package=null, addon_packages=[], total={0,0} |
|
||||
| | 主套餐过期加油包未过期 | 加油包被级联失效，不显示 |
|
||||
|
||||
---
|
||||
|
||||
## 实现参考
|
||||
|
||||
### Handler: GetMyUsage
|
||||
|
||||
```go
|
||||
// Handler: GetMyUsage
|
||||
func (h *Handler) GetMyUsage(c *fiber.Ctx) error {
|
||||
// 从上下文获取载体信息
|
||||
carrierType := middleware.GetCarrierTypeFromContext(c.UserContext())
|
||||
carrierID := middleware.GetCarrierIDFromContext(c.UserContext())
|
||||
|
||||
// 查询流量使用情况
|
||||
usage, err := h.service.GetMyUsage(c.UserContext(), carrierType, carrierID)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
return response.Success(c, usage)
|
||||
}
|
||||
|
||||
// Service 层：GetMyUsage
|
||||
func (s *Service) GetMyUsage(ctx context.Context, carrierType string, carrierID uint) (*dto.MyUsageResponse, error) {
|
||||
// 查询生效中或已用完的套餐
|
||||
usages, err := s.store.ListActiveUsages(ctx, carrierType, carrierID)
|
||||
if err != nil {
|
||||
return nil, errors.Wrap(errors.CodeInternalError, err, "查询套餐失败")
|
||||
}
|
||||
|
||||
// 分类套餐
|
||||
var mainPackage *model.PackageUsage
|
||||
var addonPackages []*model.PackageUsage
|
||||
|
||||
for _, usage := range usages {
|
||||
if usage.PackageType == constants.PackageTypeFormal {
|
||||
if mainPackage == nil || usage.Status == constants.PackageStatusActive {
|
||||
mainPackage = usage // 优先选择生效中的主套餐
|
||||
}
|
||||
} else if usage.PackageType == constants.PackageTypeAddon {
|
||||
addonPackages = append(addonPackages, usage)
|
||||
}
|
||||
}
|
||||
|
||||
// 按优先级排序加油包
|
||||
sort.Slice(addonPackages, func(i, j int) bool {
|
||||
return addonPackages[i].Priority < addonPackages[j].Priority
|
||||
})
|
||||
|
||||
// 构造响应
|
||||
resp := &dto.MyUsageResponse{
|
||||
Total: &dto.TotalUsage{
|
||||
UsedMB: 0,
|
||||
TotalMB: 0,
|
||||
},
|
||||
}
|
||||
|
||||
// 主套餐
|
||||
if mainPackage != nil {
|
||||
resp.MainPackage = s.toPackageUsageVO(mainPackage)
|
||||
resp.Total.UsedMB += mainPackage.DataUsageMB
|
||||
resp.Total.TotalMB += mainPackage.TotalDataMB
|
||||
}
|
||||
|
||||
// 加油包
|
||||
for _, addon := range addonPackages {
|
||||
resp.AddonPackages = append(resp.AddonPackages, s.toPackageUsageVO(addon))
|
||||
resp.Total.UsedMB += addon.DataUsageMB
|
||||
resp.Total.TotalMB += addon.TotalDataMB
|
||||
}
|
||||
|
||||
return resp, nil
|
||||
}
|
||||
|
||||
// Store 层：ListActiveUsages
|
||||
func (s *Store) ListActiveUsages(ctx context.Context, carrierType string, carrierID uint) ([]*model.PackageUsage, error) {
|
||||
var usages []*model.PackageUsage
|
||||
err := s.db.WithContext(ctx).
|
||||
Where("carrier_type = ? AND carrier_id = ? AND status IN (?, ?)",
|
||||
carrierType, carrierID,
|
||||
constants.PackageStatusActive,
|
||||
constants.PackageStatusUsedUp).
|
||||
Order("package_type ASC, priority ASC").
|
||||
Find(&usages).Error
|
||||
return usages, err
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**本 Spec 完成**（简化版），包含：
|
||||
- ✅ 业务背景和业务规则
|
||||
- ✅ 详细场景（主套餐、加油包、总计流量）
|
||||
- ✅ 边界条件
|
||||
- ✅ 数据一致性保证和性能指标
|
||||
- ✅ 错误码定义
|
||||
- ✅ **激进的数据迁移策略**（索引优化）
|
||||
- ✅ 测试场景矩阵和实现参考
|
||||
465
openspec/specs/package-usage-daily-record/spec.md
Normal file
465
openspec/specs/package-usage-daily-record/spec.md
Normal file
@@ -0,0 +1,465 @@
|
||||
# Spec: 套餐流量日记录
|
||||
|
||||
## 业务背景
|
||||
|
||||
### 为什么需要流量日记录
|
||||
|
||||
**现状问题**：
|
||||
- 用户需要查看每日流量使用明细（哪天用了多少流量）
|
||||
- 套餐流量重置后，历史使用数据丢失
|
||||
- 无法统计和分析用户流量使用趋势
|
||||
- 计费对账需要每日流量记录
|
||||
|
||||
**业务目标**：
|
||||
- 按套餐维度记录每日流量增量
|
||||
- 支持按日期范围查询流量详单
|
||||
- 流量重置后历史记录仍可查询
|
||||
- 为计费对账和数据分析提供基础数据
|
||||
|
||||
---
|
||||
|
||||
## 业务规则
|
||||
|
||||
### 1. 日记录写入规则
|
||||
|
||||
每次流量扣减后，写入或更新当日记录：
|
||||
|
||||
```
|
||||
写入流量日记录：
|
||||
1. 获取当前日期（date=today）
|
||||
2. 查询是否已有今日记录：
|
||||
SELECT * FROM package_usage_daily_record
|
||||
WHERE package_usage_id=? AND date=today
|
||||
3. 如果存在 → UPDATE daily_usage_mb += increment
|
||||
4. 如果不存在 → INSERT (package_usage_id, date, daily_usage_mb, cumulative_usage_mb)
|
||||
5. 使用 UPSERT（ON CONFLICT UPDATE）确保幂等性
|
||||
```
|
||||
|
||||
### 2. 流量增量计算
|
||||
|
||||
```
|
||||
每日流量增量 = 今日上游返回的累计流量 - 昨日记录的累计流量
|
||||
|
||||
特殊情况：
|
||||
- 如果昨日无记录 → 增量 = 今日上游累计流量
|
||||
- 如果上游重置（今日累计 < 昨日累计）→ 增量 = 今日上游累计流量
|
||||
```
|
||||
|
||||
### 3. cumulative_usage_mb 字段
|
||||
|
||||
- **定义**：截止到当日的累计流量
|
||||
- **计算规则**：cumulative_usage_mb = 昨日 cumulative_usage_mb + 今日 daily_usage_mb
|
||||
- **首日规则**：首日 cumulative_usage_mb = daily_usage_mb
|
||||
|
||||
### 4. 数据保留策略
|
||||
|
||||
- **保留期限**：永久保留（或根据业务需求保留1年/2年）
|
||||
- **流量重置不删除**：套餐流量重置后，日记录仍保留
|
||||
- **套餐过期不删除**：套餐过期后，日记录仍保留
|
||||
|
||||
---
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 按套餐维度记录每日流量
|
||||
|
||||
系统 SHALL 为每个 PackageUsage 创建每日流量记录（PackageUsageDailyRecord），记录每天的流量增量。
|
||||
|
||||
#### Scenario: 首次记录当日流量
|
||||
- **GIVEN** 套餐 ID=123 在 2026-02-10 首次产生流量 1.5GB
|
||||
- **WHEN** 流量扣减完成
|
||||
- **THEN** 系统创建 PackageUsageDailyRecord：
|
||||
- package_usage_id=123
|
||||
- date=2026-02-10
|
||||
- daily_usage_mb=1536 (1.5GB)
|
||||
- cumulative_usage_mb=1536
|
||||
|
||||
#### Scenario: 同一天多次流量更新
|
||||
- **GIVEN** 套餐在 2026-02-10 已记录 1GB 流量
|
||||
- **WHEN** 再产生 0.5GB 流量
|
||||
- **THEN** 系统更新 PackageUsageDailyRecord：
|
||||
- daily_usage_mb=1536（1GB+0.5GB）
|
||||
- cumulative_usage_mb=1536
|
||||
|
||||
#### Scenario: 跨天流量记录
|
||||
- **GIVEN** 套餐在 2026-02-10 使用 2GB
|
||||
- **AND** 2026-02-11 使用 3GB
|
||||
- **WHEN** 流量扣减完成
|
||||
- **THEN** 系统创建两条记录：
|
||||
- 2月10日：daily_usage_mb=2GB, cumulative_usage_mb=2GB
|
||||
- 2月11日：daily_usage_mb=3GB, cumulative_usage_mb=5GB
|
||||
|
||||
#### Scenario: 流量重置后日记录仍保留
|
||||
- **GIVEN** 套餐在 2月1日至2月28日有28条日记录
|
||||
- **WHEN** 3月1日 00:00:00 触发流量重置
|
||||
- **THEN** 套餐 data_usage_mb 重置为 0
|
||||
- **AND** 2月的28条日记录仍存在且可查询
|
||||
|
||||
### Requirement: 流量增量基于上游查询计算
|
||||
|
||||
系统 SHALL 根据上游返回的累计流量，减去昨日记录的累计流量，计算每日增量。
|
||||
|
||||
#### Scenario: 计算每日流量增量
|
||||
- **GIVEN** 昨日（2月9日）记录 cumulative_usage_mb=10GB
|
||||
- **WHEN** 今日（2月10日）上游返回 cumulative=13GB
|
||||
- **THEN** 今日 daily_usage_mb=3GB（13GB - 10GB）
|
||||
- **AND** 今日 cumulative_usage_mb=13GB
|
||||
|
||||
#### Scenario: 上游周期重置后流量计算
|
||||
- **GIVEN** 联通卡在 2月27日 00:00:00 上游重置
|
||||
- **AND** 昨日（2月26日）记录 cumulative_usage_mb=15GB
|
||||
- **WHEN** 今日（2月27日）上游返回 cumulative=2GB
|
||||
- **THEN** 今日 daily_usage_mb=2GB（上游重置，取新增量）
|
||||
- **AND** 今日 cumulative_usage_mb=2GB
|
||||
|
||||
#### Scenario: 首日无昨日记录
|
||||
- **GIVEN** 套餐首次激活，无任何日记录
|
||||
- **WHEN** 上游返回 cumulative=5GB
|
||||
- **THEN** 今日 daily_usage_mb=5GB
|
||||
- **AND** 今日 cumulative_usage_mb=5GB
|
||||
|
||||
### Requirement: 支持按日期查询套餐流量详单
|
||||
|
||||
系统 SHALL 提供 API 查询指定套餐的每日流量记录。
|
||||
|
||||
#### Scenario: 查询套餐流量详单
|
||||
- **WHEN** 用户通过 GET /api/admin/package-usage/:id/daily-records 查询套餐流量详单
|
||||
- **THEN** 系统返回按日期排序的流量记录列表：
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": [
|
||||
{
|
||||
"date": "2026-02-01",
|
||||
"daily_usage_mb": 1024,
|
||||
"cumulative_usage_mb": 1024
|
||||
},
|
||||
{
|
||||
"date": "2026-02-02",
|
||||
"daily_usage_mb": 2048,
|
||||
"cumulative_usage_mb": 3072
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Scenario: 查询指定日期范围
|
||||
- **GIVEN** 套餐有 2月1日 至 2月28日 的流量记录
|
||||
- **WHEN** 用户查询流量详单，参数 start_date=2026-02-01, end_date=2026-02-10
|
||||
- **THEN** 系统返回 2月1日 至 2月10日 的流量记录（10条）
|
||||
|
||||
#### Scenario: 客户端查询自己的流量详单
|
||||
- **WHEN** 客户通过 GET /api/customer/package-usage/:id/daily-records 查询
|
||||
- **THEN** 系统校验套餐归属后，返回流量记录列表
|
||||
|
||||
### Requirement: 日记录索引优化
|
||||
|
||||
系统 SHALL 在 PackageUsageDailyRecord 表创建 (package_usage_id, date) 联合唯一索引。
|
||||
|
||||
#### Scenario: 同一套餐同一天只有一条记录
|
||||
- **WHEN** 系统尝试为同一 package_usage_id=123 和 date=2026-02-10 创建第二条记录
|
||||
- **THEN** 数据库返回唯一约束冲突错误
|
||||
- **AND** 使用 UPSERT 自动转为 UPDATE 操作
|
||||
|
||||
#### Scenario: 查询性能达标
|
||||
- **GIVEN** 套餐 ID=123 有 365 条日记录（一年数据）
|
||||
- **WHEN** 查询全部流量详单
|
||||
- **THEN** 查询响应时间 < 50ms
|
||||
|
||||
---
|
||||
|
||||
## 边界条件
|
||||
|
||||
### 1. 套餐过期后的日记录
|
||||
|
||||
- **场景**：套餐在 2月28日过期，3月1日仍可查询历史日记录
|
||||
- **处理**：日记录永久保留，不随套餐过期删除
|
||||
|
||||
### 2. 并发写入同一天记录
|
||||
|
||||
- **场景**：同一套餐在同一天有多个并发流量扣减请求
|
||||
- **处理**：使用 UPSERT（ON CONFLICT UPDATE）确保幂等性
|
||||
|
||||
### 3. 跨月查询日记录
|
||||
|
||||
- **场景**：查询 1月15日 至 2月15日 的日记录（跨月）
|
||||
- **处理**：按日期范围查询，返回跨月数据
|
||||
|
||||
---
|
||||
|
||||
## 并发场景
|
||||
|
||||
### Scenario: 并发写入同一天记录
|
||||
- **GIVEN** 套餐 ID=123 在 2026-02-10 10:00:00 和 10:00:01 同时扣减流量
|
||||
- **WHEN** 两个请求同时写入日记录
|
||||
- **THEN** 使用 UPSERT（ON CONFLICT UPDATE）：
|
||||
```sql
|
||||
INSERT INTO package_usage_daily_record (package_usage_id, date, daily_usage_mb, cumulative_usage_mb)
|
||||
VALUES (123, '2026-02-10', 1024, 1024)
|
||||
ON CONFLICT (package_usage_id, date)
|
||||
DO UPDATE SET
|
||||
daily_usage_mb = package_usage_daily_record.daily_usage_mb + EXCLUDED.daily_usage_mb,
|
||||
cumulative_usage_mb = package_usage_daily_record.cumulative_usage_mb + EXCLUDED.daily_usage_mb;
|
||||
```
|
||||
- **AND** 两个请求的流量累加到同一条记录
|
||||
|
||||
---
|
||||
|
||||
## 异常处理
|
||||
|
||||
### 1. 日记录写入失败
|
||||
|
||||
- **错误场景**：流量扣减成功，但日记录写入失败（数据库连接断开）
|
||||
- **处理流程**：
|
||||
1. 不回滚流量扣减（已提交）
|
||||
2. 记录 Error 日志（包含套餐ID、日期、流量增量）
|
||||
3. 通过定时任务补录日记录
|
||||
- **返回错误**：不影响用户，日记录补录在后台进行
|
||||
|
||||
### 2. 查询日记录超时
|
||||
|
||||
- **错误场景**：查询大量日记录时超时（如查询3年数据）
|
||||
- **处理流程**：
|
||||
1. 限制单次查询最多返回 365 条记录
|
||||
2. 如果超过限制，返回错误 400："查询日期范围过大，最多查询1年"
|
||||
- **返回错误**：`{"code": "DATE_RANGE_TOO_LARGE", "msg": "查询日期范围过大，最多查询1年"}`
|
||||
|
||||
---
|
||||
|
||||
## 数据一致性保证
|
||||
|
||||
### 1. 事务边界
|
||||
|
||||
- **流量扣减 + 写入日记录**：使用单个事务（可选，根据业务需求）
|
||||
- **查询日记录**：使用只读事务
|
||||
|
||||
### 2. 唯一索引
|
||||
|
||||
- **联合唯一索引**：`UNIQUE INDEX idx_package_usage_daily_record (package_usage_id, date)`
|
||||
- **确保同一套餐同一天只有一条记录**
|
||||
|
||||
### 3. UPSERT 幂等性
|
||||
|
||||
- **使用 ON CONFLICT UPDATE**：确保并发写入时累加流量而非覆盖
|
||||
|
||||
---
|
||||
|
||||
## 性能指标
|
||||
|
||||
| 操作 | 目标响应时间 | 并发要求 | 数据量 |
|
||||
|------|-------------|---------|--------|
|
||||
| 写入日记录（UPSERT） | < 10ms | 1000 QPS | 单条插入/更新 |
|
||||
| 查询日记录（单套餐） | < 50ms | 100 QPS | 查询365条记录 |
|
||||
| 查询日记录（日期范围） | < 100ms | 100 QPS | 查询指定范围 |
|
||||
|
||||
---
|
||||
|
||||
## 错误码定义
|
||||
|
||||
| 错误码 | HTTP 状态码 | 错误消息 | 场景 |
|
||||
|--------|------------|---------|------|
|
||||
| `DATE_RANGE_TOO_LARGE` | 400 | 查询日期范围过大，最多查询1年 | 查询日记录日期范围超过365天 |
|
||||
| `DAILY_RECORD_NOT_FOUND` | 404 | 未找到流量记录 | 查询不存在的日记录 |
|
||||
|
||||
---
|
||||
|
||||
## 数据迁移策略
|
||||
|
||||
**激进策略**（开发阶段，保证干净性）：
|
||||
|
||||
### 1. ❌ 要删除的字段
|
||||
|
||||
目前 `package_usage_daily_record` 表中可能存在的冗余字段（需确认后删除）：
|
||||
- 如果有 `daily_increment` 字段（旧的增量字段） → **删除**，统一使用 `daily_usage_mb`
|
||||
- 如果有 `total_usage` 字段（旧的累计字段） → **删除**，统一使用 `cumulative_usage_mb`
|
||||
|
||||
### 2. ✅ 新增的字段
|
||||
|
||||
在 `package_usage_daily_record` 表中确保有以下字段：
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS package_usage_daily_record (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
package_usage_id BIGINT NOT NULL COMMENT '套餐使用记录ID',
|
||||
date DATE NOT NULL COMMENT '日期',
|
||||
daily_usage_mb INT DEFAULT 0 COMMENT '当日流量使用量（MB）',
|
||||
cumulative_usage_mb BIGINT DEFAULT 0 COMMENT '截止当日的累计流量（MB）',
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
UNIQUE KEY idx_package_usage_daily_record (package_usage_id, date)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='套餐流量日记录';
|
||||
|
||||
CREATE INDEX idx_date ON package_usage_daily_record(date);
|
||||
```
|
||||
|
||||
### 3. ❌ 要废弃的逻辑
|
||||
|
||||
- **废弃旧的日记录写入逻辑**：如果代码中存在不使用 UPSERT 的写入逻辑，全部删除
|
||||
- **废弃旧的日记录查询逻辑**：统一使用新的查询接口
|
||||
|
||||
### 4. ✅ 历史数据强制转换
|
||||
|
||||
```sql
|
||||
-- Step 1: 如果有旧的字段名，重命名
|
||||
-- ALTER TABLE package_usage_daily_record CHANGE daily_increment daily_usage_mb INT;
|
||||
-- ALTER TABLE package_usage_daily_record CHANGE total_usage cumulative_usage_mb BIGINT;
|
||||
|
||||
-- Step 2: 修复 cumulative_usage_mb（如果历史数据不准确）
|
||||
-- 重新计算每个套餐的 cumulative_usage_mb
|
||||
-- （需要按套餐ID分组，按日期排序，累加 daily_usage_mb）
|
||||
|
||||
-- Step 3: 确保唯一索引存在
|
||||
CREATE UNIQUE INDEX IF NOT EXISTS idx_package_usage_daily_record
|
||||
ON package_usage_daily_record(package_usage_id, date);
|
||||
```
|
||||
|
||||
### 5. ❌ 删除遗留表/字段（确认后执行）
|
||||
|
||||
```sql
|
||||
-- 如果存在旧的日记录表，删除
|
||||
-- DROP TABLE IF EXISTS iot_card_usage_daily;
|
||||
|
||||
-- 如果存在旧的字段，删除
|
||||
-- ALTER TABLE package_usage_daily_record DROP COLUMN IF EXISTS daily_increment;
|
||||
-- ALTER TABLE package_usage_daily_record DROP COLUMN IF EXISTS total_usage;
|
||||
```
|
||||
|
||||
### 6. 验证步骤
|
||||
|
||||
```sql
|
||||
-- 验证1：所有日记录都有 daily_usage_mb 和 cumulative_usage_mb
|
||||
SELECT COUNT(*)
|
||||
FROM package_usage_daily_record
|
||||
WHERE daily_usage_mb IS NULL OR cumulative_usage_mb IS NULL;
|
||||
-- 预期结果：0
|
||||
|
||||
-- 验证2：同一套餐同一天只有一条记录
|
||||
SELECT package_usage_id, date, COUNT(*)
|
||||
FROM package_usage_daily_record
|
||||
GROUP BY package_usage_id, date
|
||||
HAVING COUNT(*) > 1;
|
||||
-- 预期结果：0 rows
|
||||
|
||||
-- 验证3：累计流量单调递增（同一套餐）
|
||||
-- （需要编写复杂查询验证，略）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试场景矩阵
|
||||
|
||||
| 场景分类 | 测试用例 | 预期结果 |
|
||||
|---------|---------|---------|
|
||||
| **写入日记录** | 首次记录当日流量 | 创建新记录 |
|
||||
| | 同一天多次流量更新 | 更新已有记录（UPSERT） |
|
||||
| | 跨天流量记录 | 创建多条记录 |
|
||||
| **流量增量计算** | 计算每日流量增量 | daily_usage_mb = 今日累计 - 昨日累计 |
|
||||
| | 上游周期重置后计算 | daily_usage_mb = 今日累计（重置后） |
|
||||
| | 首日无昨日记录 | daily_usage_mb = 今日累计 |
|
||||
| **查询日记录** | 查询套餐流量详单 | 返回按日期排序的记录列表 |
|
||||
| | 查询指定日期范围 | 返回指定范围内的记录 |
|
||||
| | 客户端查询自己的详单 | 校验归属后返回 |
|
||||
| **索引和性能** | 同一套餐同一天只有一条记录 | 唯一约束保证 |
|
||||
| | 查询365条记录 | 响应时间 < 50ms |
|
||||
| **并发** | 并发写入同一天记录 | UPSERT 确保累加 |
|
||||
| **异常** | 日记录写入失败 | 不回滚流量扣减，后台补录 |
|
||||
| | 查询日记录超时 | 限制日期范围，返回错误 |
|
||||
|
||||
---
|
||||
|
||||
## 实现参考
|
||||
|
||||
### 写入日记录（UPSERT）
|
||||
|
||||
```go
|
||||
// Service 层：RecordDailyUsage
|
||||
func (s *Service) RecordDailyUsage(ctx context.Context, usageID uint, date time.Time, dailyUsageMB int, cumulativeUsageMB int64) error {
|
||||
record := &model.PackageUsageDailyRecord{
|
||||
PackageUsageID: usageID,
|
||||
Date: date,
|
||||
DailyUsageMB: dailyUsageMB,
|
||||
CumulativeUsageMB: cumulativeUsageMB,
|
||||
}
|
||||
|
||||
if err := s.store.UpsertDailyRecord(ctx, record); err != nil {
|
||||
return errors.Wrap(errors.CodeInternalError, err, "写入流量日记录失败")
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// Store 层：UpsertDailyRecord
|
||||
func (s *Store) UpsertDailyRecord(ctx context.Context, record *model.PackageUsageDailyRecord) error {
|
||||
// PostgreSQL UPSERT
|
||||
return s.db.WithContext(ctx).Exec(`
|
||||
INSERT INTO package_usage_daily_record (package_usage_id, date, daily_usage_mb, cumulative_usage_mb, created_at, updated_at)
|
||||
VALUES (?, ?, ?, ?, NOW(), NOW())
|
||||
ON CONFLICT (package_usage_id, date)
|
||||
DO UPDATE SET
|
||||
daily_usage_mb = package_usage_daily_record.daily_usage_mb + EXCLUDED.daily_usage_mb,
|
||||
cumulative_usage_mb = package_usage_daily_record.cumulative_usage_mb + (EXCLUDED.daily_usage_mb),
|
||||
updated_at = NOW()
|
||||
`, record.PackageUsageID, record.Date, record.DailyUsageMB, record.CumulativeUsageMB).Error
|
||||
}
|
||||
```
|
||||
|
||||
### 查询日记录
|
||||
|
||||
```go
|
||||
// Handler: GetDailyRecords
|
||||
func (h *Handler) GetDailyRecords(c *fiber.Ctx) error {
|
||||
usageID, _ := c.ParamsInt("id")
|
||||
startDate := c.Query("start_date", "")
|
||||
endDate := c.Query("end_date", "")
|
||||
|
||||
// 查询日记录
|
||||
records, err := h.service.GetDailyRecords(c.UserContext(), uint(usageID), startDate, endDate)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
return response.Success(c, records)
|
||||
}
|
||||
|
||||
// Service 层：GetDailyRecords
|
||||
func (s *Service) GetDailyRecords(ctx context.Context, usageID uint, startDate, endDate string) ([]*model.PackageUsageDailyRecord, error) {
|
||||
// 参数校验
|
||||
start, err := time.Parse("2006-01-02", startDate)
|
||||
if err != nil {
|
||||
return nil, errors.New(errors.CodeInvalidParam, "起始日期格式错误")
|
||||
}
|
||||
|
||||
end, err := time.Parse("2006-01-02", endDate)
|
||||
if err != nil {
|
||||
return nil, errors.New(errors.CodeInvalidParam, "结束日期格式错误")
|
||||
}
|
||||
|
||||
// 限制查询范围
|
||||
if end.Sub(start).Hours() > 365*24 {
|
||||
return nil, errors.New(errors.CodeInvalidParam, "查询日期范围过大，最多查询1年")
|
||||
}
|
||||
|
||||
// 查询日记录
|
||||
return s.store.ListDailyRecords(ctx, usageID, start, end)
|
||||
}
|
||||
|
||||
// Store 层：ListDailyRecords
|
||||
func (s *Store) ListDailyRecords(ctx context.Context, usageID uint, startDate, endDate time.Time) ([]*model.PackageUsageDailyRecord, error) {
|
||||
var records []*model.PackageUsageDailyRecord
|
||||
err := s.db.WithContext(ctx).
|
||||
Where("package_usage_id = ? AND date >= ? AND date <= ?", usageID, startDate, endDate).
|
||||
Order("date ASC").
|
||||
Find(&records).Error
|
||||
return records, err
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**本 Spec 完成**，包含：
|
||||
- ✅ 业务背景和业务规则
|
||||
- ✅ 详细场景（写入、查询、增量计算）
|
||||
- ✅ 边界条件和并发场景
|
||||
- ✅ 异常处理和数据一致性保证
|
||||
- ✅ 性能指标和错误码定义
|
||||
- ✅ **激进的数据迁移策略**（明确删除字段、废弃逻辑、强制转换）
|
||||
- ✅ 测试场景矩阵和实现参考
|
||||
420
openspec/specs/package-usage-priority/spec.md
Normal file
420
openspec/specs/package-usage-priority/spec.md
Normal file
@@ -0,0 +1,420 @@
|
||||
# Spec: 流量扣减优先级机制
|
||||
|
||||
## 业务背景
|
||||
|
||||
现有套餐系统在流量扣减时不区分主套餐和加油包,导致:
|
||||
1. **用户体验差**:用户购买加油包后,主套餐仍在扣减,加油包未生效
|
||||
2. **停机逻辑错误**:主套餐流量用完即停机,加油包剩余流量浪费
|
||||
3. **流量统计混乱**:多套餐同时扣减,无法追溯流量消耗路径
|
||||
|
||||
本规范引入流量扣减优先级机制,确保:
|
||||
- **加油包优先扣减**:购买加油包后,优先消耗加油包流量
|
||||
- **主套餐兜底**:加油包用完后,再扣减主套餐流量
|
||||
- **全部用完停机**:主套餐 + 所有加油包流量都用完才停机
|
||||
|
||||
## 业务规则
|
||||
|
||||
### 扣减优先级规则(多维度排序)
|
||||
```
|
||||
优先级(从高到低):
|
||||
1. 加油包(按 priority ASC, expires_at ASC, activated_at ASC)
|
||||
2. 主套餐
|
||||
```
|
||||
|
||||
**多维度排序规则**(按优先级递减):
|
||||
1. **主键:priority ASC** - 数字越小优先级越高(1 > 2 > 3)
|
||||
2. **次键:expires_at ASC** - 先到期的优先扣减(避免流量浪费)
|
||||
3. **兜底:activated_at ASC** - 先激活的优先扣减(相同到期时间时)
|
||||
|
||||
**SQL 示例**:
|
||||
```sql
|
||||
SELECT * FROM tb_package_usage
|
||||
WHERE card_id = ?
|
||||
AND status = 'active'
|
||||
AND remaining_data_amount > 0
|
||||
ORDER BY
|
||||
priority ASC, -- 加油包(priority=1)在正式套餐(priority=10)前
|
||||
expires_at ASC, -- 同优先级:3天后到期的在7天后到期的前
|
||||
activated_at ASC -- 同到期时间:早激活的在晚激活的前
|
||||
LIMIT 10;
|
||||
```
|
||||
|
||||
**业务意义**:
|
||||
- **先用即将到期的**:避免流量过期浪费
|
||||
- **确定性排序**:相同条件下结果稳定,便于问题排查
|
||||
|
||||
**示例**:
|
||||
```
|
||||
载体有:主套餐(剩余10GB) + 加油包A(priority=1, 剩余5GB) + 加油包B(priority=2, 剩余3GB)
|
||||
产生 12GB 流量:
|
||||
1. 扣减加油包A:5GB → 0GB(用完)
|
||||
2. 扣减加油包B:3GB → 0GB(用完)
|
||||
3. 扣减主套餐:4GB → 6GB(剩余6GB)
|
||||
```
|
||||
|
||||
### 停机条件规则
|
||||
- **旧逻辑**:主套餐流量用完即停机
|
||||
- **新逻辑**:主套餐 + 所有加油包流量都用完才停机
|
||||
|
||||
**判断逻辑**:
|
||||
```sql
|
||||
SELECT COUNT(*) FROM tb_package_usage
|
||||
WHERE (iot_card_id/device_id)=? AND status=1
|
||||
AND data_usage_mb < data_limit_mb;
|
||||
|
||||
-- 如果 COUNT = 0,则触发停机
|
||||
```
|
||||
|
||||
### 流量扣减算法
|
||||
```
|
||||
输入:上游返回的累计流量(upstream_cumulative_mb)
|
||||
输出:更新各套餐的 data_usage_mb
|
||||
|
||||
1. 查询载体当前生效套餐(status=1),按优先级排序:
|
||||
加油包(priority ASC)→ 主套餐
|
||||
2. 计算本次流量增量:
|
||||
increment = upstream_cumulative_mb - 上次记录的累计流量
|
||||
3. 依次扣减:
|
||||
FOR EACH 套餐 IN 优先级列表:
|
||||
可扣减量 = MIN(increment, 套餐剩余额度)
|
||||
UPDATE data_usage_mb += 可扣减量
|
||||
记录到 PackageUsageDailyRecord
|
||||
increment -= 可扣减量
|
||||
IF data_usage_mb >= data_limit_mb:
|
||||
UPDATE status=2(已用完)
|
||||
IF increment == 0:
|
||||
BREAK
|
||||
4. 检查停机条件:
|
||||
IF 所有套餐 status=2:
|
||||
触发停机操作
|
||||
```
|
||||
|
||||
### 并发控制
|
||||
- **场景**:轮询系统同时检测到多张卡的流量增加
|
||||
- **机制**:数据库事务 + 行锁(SELECT FOR UPDATE)
|
||||
- **保证**:同一套餐不会被并发扣减导致负数流量
|
||||
|
||||
### 性能要求
|
||||
- 单次流量扣减 < 100ms(包含数据库更新 + 日记录写入)
|
||||
- 批量扣减(1000张卡) < 10秒
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 流量优先扣减加油包
|
||||
系统 SHALL 在扣减流量时,优先扣减加油包流量,再扣减主套餐流量。
|
||||
|
||||
**业务价值**:用户购买加油包后,立即生效,优先消耗加油包流量,避免浪费。
|
||||
|
||||
**技术实现**:
|
||||
- 查询时按 `master_usage_id IS NOT NULL, priority ASC` 排序
|
||||
- 主套餐(master_usage_id=NULL)排在最后
|
||||
|
||||
#### Scenario: 存在加油包时优先扣减
|
||||
- **GIVEN** 载体有主套餐(data_usage_mb=0, data_limit_mb=10240)和加油包(data_usage_mb=0, data_limit_mb=5120, priority=1)
|
||||
- **WHEN** 上游返回累计流量 3072MB(本次增量 3GB)
|
||||
- **THEN** 系统执行:
|
||||
1. 扣减加油包:data_usage_mb=3072
|
||||
2. 主套餐不扣减:data_usage_mb=0
|
||||
- **AND** PackageUsageDailyRecord 记录加油包增量 3072MB
|
||||
|
||||
#### Scenario: 加油包用完后扣减主套餐
|
||||
- **GIVEN** 载体有主套餐(data_usage_mb=0, data_limit_mb=10240)和加油包(data_usage_mb=3072, data_limit_mb=5120)
|
||||
- **WHEN** 上游返回累计流量 8192MB(本次增量 5GB)
|
||||
- **THEN** 系统执行:
|
||||
1. 扣减加油包:5120 - 3072 = 2048MB 可用,扣减 2048MB → data_usage_mb=5120(用完)
|
||||
2. 更新加油包 status=2(已用完)
|
||||
3. 剩余流量 5GB - 2GB = 3GB
|
||||
4. 扣减主套餐:data_usage_mb=3072
|
||||
- **AND** PackageUsageDailyRecord 记录加油包增量 2048MB、主套餐增量 3072MB
|
||||
|
||||
#### Scenario: 只有主套餐时直接扣减
|
||||
- **GIVEN** 载体只有主套餐(data_usage_mb=0, data_limit_mb=10240),无加油包
|
||||
- **WHEN** 上游返回累计流量 3072MB
|
||||
- **THEN** 系统直接扣减主套餐:data_usage_mb=3072
|
||||
- **AND** PackageUsageDailyRecord 记录主套餐增量 3072MB
|
||||
|
||||
#### Scenario: 加油包已用完自动跳过(边界条件)
|
||||
- **GIVEN** 载体有主套餐(data_usage_mb=0, data_limit_mb=10240)和加油包(data_usage_mb=5120, data_limit_mb=5120, status=2)
|
||||
- **WHEN** 上游返回累计流量 3072MB
|
||||
- **THEN** 系统跳过已用完的加油包,直接扣减主套餐:data_usage_mb=3072
|
||||
- **AND** 加油包 data_usage_mb 保持 5120(不再扣减)
|
||||
|
||||
#### Scenario: 流量增量为 0 不扣减(边界条件)
|
||||
- **GIVEN** 载体有主套餐和加油包
|
||||
- **WHEN** 上游返回累计流量与上次记录相同(增量=0)
|
||||
- **THEN** 系统不更新任何套餐的 data_usage_mb
|
||||
- **AND** 不创建 PackageUsageDailyRecord
|
||||
|
||||
#### Scenario: 流量增量为负数拒绝扣减(异常处理)
|
||||
- **GIVEN** 载体上次记录累计流量 10GB
|
||||
- **WHEN** 上游返回累计流量 8GB(负增量,异常情况)
|
||||
- **THEN** 系统记录 Warning 日志:"上游流量异常,累计流量减少"
|
||||
- **AND** 不更新套餐 data_usage_mb
|
||||
- **AND** 告警通知运维团队
|
||||
|
||||
### Requirement: 多个加油包按多维度排序扣减
|
||||
|
||||
系统 SHALL 当存在多个加油包时,按 **priority ASC, expires_at ASC, activated_at ASC** 多维度排序扣减流量。
|
||||
|
||||
**业务价值**:
|
||||
- 按购买顺序消耗加油包(priority)
|
||||
- 优先消耗即将到期的流量(expires_at)
|
||||
- 确定性排序便于问题排查(activated_at)
|
||||
|
||||
**技术实现**:
|
||||
- 查询时:`ORDER BY (master_usage_id IS NOT NULL) DESC, priority ASC, expires_at ASC, activated_at ASC`
|
||||
- 确保加油包按多维度排序排在主套餐前
|
||||
|
||||
#### Scenario: 按到期时间优先扣减(多维度排序验证)
|
||||
- **GIVEN** 载体有2个加油包,相同 priority:
|
||||
- 加油包A:priority=1, data_limit_mb=5120, expires_at=2026-02-15 23:59:59
|
||||
- 加油包B:priority=1, data_limit_mb=3072, expires_at=2026-02-12 23:59:59(先到期)
|
||||
- **WHEN** 上游返回累计流量 4096MB(本次增量 4GB)
|
||||
- **THEN** 系统执行:
|
||||
1. 扣减加油包B(先到期):3072MB → data_usage_mb=3072(用完),status=2
|
||||
2. 剩余流量 4GB - 3GB = 1GB
|
||||
3. 扣减加油包A:1024MB → data_usage_mb=1024
|
||||
- **AND** PackageUsageDailyRecord 记录加油包B增量 3072MB、加油包A增量 1024MB
|
||||
|
||||
#### Scenario: 完整多维度排序示例
|
||||
- **GIVEN** 载体有:
|
||||
- 主套餐:priority=10, data_limit_mb=10240, expires_at=2026-03-31
|
||||
- 加油包A:priority=1, data_limit_mb=2048, expires_at=2026-02-15, activated_at=2026-02-01
|
||||
- 加油包B:priority=2, data_limit_mb=3072, expires_at=2026-02-20, activated_at=2026-02-03
|
||||
- 加油包C:priority=1, data_limit_mb=4096, expires_at=2026-02-15, activated_at=2026-02-05(与A同priority和expires_at,但晚激活)
|
||||
- **WHEN** 上游返回累计流量 12288MB(本次增量 12GB)
|
||||
- **THEN** 系统按以下顺序扣减:
|
||||
1. 加油包A(priority=1, expires_at=2026-02-15, activated_at=2026-02-01 最早)
|
||||
2. 加油包C(priority=1, expires_at=2026-02-15, activated_at=2026-02-05)
|
||||
3. 加油包B(priority=2)
|
||||
4. 主套餐(priority=10)
|
||||
- **AND** 扣减结果:
|
||||
- 加油包A:2048MB → status=2(用完)
|
||||
- 加油包C:4096MB → status=2(用完)
|
||||
- 加油包B:3072MB → status=2(用完)
|
||||
- 主套餐:3072MB(剩余 12GB - 2GB - 4GB - 3GB)
|
||||
|
||||
#### Scenario: 按购买顺序扣减多个加油包
|
||||
- **GIVEN** 载体有加油包A(priority=1, data_usage_mb=0, data_limit_mb=3072)和加油包B(priority=2, data_usage_mb=0, data_limit_mb=5120)
|
||||
- **WHEN** 上游返回累计流量 4096MB(本次增量 4GB)
|
||||
- **THEN** 系统执行:
|
||||
1. 扣减加油包A:3072MB → data_usage_mb=3072(用完),status=2
|
||||
2. 剩余流量 4GB - 3GB = 1GB
|
||||
3. 扣减加油包B:1024MB → data_usage_mb=1024
|
||||
- **AND** PackageUsageDailyRecord 记录加油包A增量 3072MB、加油包B增量 1024MB
|
||||
|
||||
#### Scenario: Priority 最小的加油包用完后扣减下一个
|
||||
- **GIVEN** 载体有3个加油包(priority=1/2/3),priority=1 已用完(status=2)
|
||||
- **WHEN** 上游返回累计流量增量 2GB
|
||||
- **THEN** 系统跳过 priority=1,扣减 priority=2 的加油包 2GB
|
||||
|
||||
#### Scenario: 所有加油包用完后扣减主套餐
|
||||
- **GIVEN** 载体有主套餐和2个加油包(priority=1/2),两个加油包都已用完(status=2)
|
||||
- **WHEN** 上游返回累计流量增量 5GB
|
||||
- **THEN** 系统跳过所有加油包,扣减主套餐 5GB
|
||||
|
||||
#### Scenario: 3个加油包和主套餐的完整扣减流程
|
||||
- **GIVEN** 载体有:
|
||||
- 主套餐(data_limit_mb=10240, data_usage_mb=0)
|
||||
- 加油包A(priority=1, data_limit_mb=2048, data_usage_mb=0)
|
||||
- 加油包B(priority=2, data_limit_mb=3072, data_usage_mb=0)
|
||||
- 加油包C(priority=3, data_limit_mb=4096, data_usage_mb=0)
|
||||
- **WHEN** 上游返回累计流量 12288MB(本次增量 12GB)
|
||||
- **THEN** 系统执行:
|
||||
1. 扣减加油包A:2048MB → status=2(用完)
|
||||
2. 扣减加油包B:3072MB → status=2(用完)
|
||||
3. 扣减加油包C:4096MB → status=2(用完)
|
||||
4. 扣减主套餐:3072MB(剩余 12GB - 2GB - 3GB - 4GB)
|
||||
- **AND** PackageUsageDailyRecord 记录 4 条记录
|
||||
|
||||
#### Scenario: 并发扣减同一套餐(并发控制)
|
||||
- **GIVEN** 两个轮询任务同时检测到同一张卡的流量增加
|
||||
- **WHEN** 两个任务同时尝试扣减加油包A
|
||||
- **THEN** 第一个任务获取行锁(SELECT FOR UPDATE),执行扣减
|
||||
- **AND** 第二个任务等待锁释放,检测到已扣减,跳过(幂等性保证)
|
||||
- **AND** 加油包A的 data_usage_mb 只增加一次
|
||||
|
||||
### Requirement: 所有流量用完时触发停机
|
||||
系统 SHALL 在主套餐和所有加油包流量都用完时,触发停机操作。
|
||||
|
||||
**业务价值**:充分利用加油包流量,避免提前停机,提升用户体验。
|
||||
|
||||
**技术实现**:
|
||||
```sql
|
||||
-- 停机条件检查
|
||||
SELECT COUNT(*) FROM tb_package_usage
|
||||
WHERE (iot_card_id/device_id)=? AND status=1 AND master_usage_id IS NULL;
|
||||
|
||||
-- 如果 COUNT=0(主套餐已过期或用完),检查加油包
|
||||
SELECT COUNT(*) FROM tb_package_usage
|
||||
WHERE (iot_card_id/device_id)=? AND status=1 AND master_usage_id IS NOT NULL
|
||||
AND data_usage_mb < data_limit_mb;
|
||||
|
||||
-- 如果两个 COUNT 都=0,触发停机
|
||||
```
|
||||
|
||||
#### Scenario: 主套餐和加油包都用完触发停机
|
||||
- **GIVEN** 主套餐 data_usage_mb=10240, data_limit_mb=10240(用完),加油包 data_usage_mb=5120, data_limit_mb=5120(用完)
|
||||
- **WHEN** 轮询系统检查停机条件
|
||||
- **THEN** 系统查询生效中套餐剩余流量,结果为 0
|
||||
- **AND** 触发停机操作:
|
||||
1. 调用运营商 API 停机
|
||||
2. 更新 IotCard.network_status=0(已停机)
|
||||
3. 记录操作日志
|
||||
- **AND** 主套餐和加油包 status 更新为 2(已用完)
|
||||
|
||||
#### Scenario: 有加油包剩余流量时不停机
|
||||
- **GIVEN** 主套餐 data_usage_mb=10240, data_limit_mb=10240(用完),加油包 data_usage_mb=4096, data_limit_mb=5120(剩余1GB)
|
||||
- **WHEN** 轮询系统检查停机条件
|
||||
- **THEN** 系统查询生效中套餐剩余流量,结果 > 0
|
||||
- **AND** 不触发停机,继续提供服务
|
||||
|
||||
#### Scenario: 主套餐未用完但加油包都用完(不停机)
|
||||
- **GIVEN** 主套餐 data_usage_mb=8192, data_limit_mb=10240(剩余2GB),所有加油包都用完(status=2)
|
||||
- **WHEN** 轮询系统检查停机条件
|
||||
- **THEN** 系统查询主套餐剩余流量 > 0
|
||||
- **AND** 不触发停机
|
||||
|
||||
#### Scenario: 主套餐过期但加油包有剩余(不停机)
|
||||
- **GIVEN** 主套餐 status=3(已过期),加油包 data_usage_mb=2048, data_limit_mb=5120(剩余3GB), status=1
|
||||
- **WHEN** 轮询系统检查停机条件
|
||||
- **THEN** 系统查询生效中加油包剩余流量 > 0
|
||||
- **AND** 不触发停机
|
||||
|
||||
#### Scenario: 停机后续费加油包自动复机(业务理解)
|
||||
- **GIVEN** 载体已停机(所有套餐流量用完)
|
||||
- **WHEN** 用户购买新加油包(立即激活,status=1)
|
||||
- **THEN** 下次轮询检查时,发现有剩余流量 > 0
|
||||
- **AND** 自动触发复机操作:
|
||||
1. 调用运营商 API 复机
|
||||
2. 更新 IotCard.network_status=1(已开机)
|
||||
3. 记录操作日志
|
||||
|
||||
#### Scenario: 停机 API 调用失败(异常处理)
|
||||
- **GIVEN** 载体所有套餐流量用完,需要停机
|
||||
- **WHEN** 调用运营商停机 API 失败(例如网络超时)
|
||||
- **THEN** 系统记录 Error 日志,包含卡号、错误信息
|
||||
- **AND** 停机任务进入重试队列(Asynq 重试 3 次,间隔 10 秒)
|
||||
- **AND** 如果 3 次重试都失败,进入死信队列(DLQ)
|
||||
- **AND** 告警通知运维团队
|
||||
|
||||
### Requirement: 流量扣减记录到日记录表
|
||||
系统 SHALL 在扣减流量时,更新 PackageUsage 的 data_usage_mb,并创建或更新 PackageUsageDailyRecord。
|
||||
|
||||
**业务价值**:
|
||||
- 精细化流量统计(按套餐、按日)
|
||||
- 支持流量详单查询
|
||||
- 数据可追溯、可审计
|
||||
|
||||
**技术实现**:
|
||||
- 扣减流量后,创建或更新当日 PackageUsageDailyRecord
|
||||
- 使用 UPSERT(ON CONFLICT UPDATE)避免重复记录
|
||||
- 记录字段:`package_usage_id`, `date`, `daily_usage_mb`, `cumulative_usage_mb`
|
||||
|
||||
#### Scenario: 扣减主套餐流量并记录
|
||||
- **GIVEN** 主套餐 data_usage_mb=0, data_limit_mb=10240
|
||||
- **WHEN** 扣减主套餐 2048MB 流量
|
||||
- **THEN** PackageUsage 更新:data_usage_mb=2048
|
||||
- **AND** PackageUsageDailyRecord 创建记录:
|
||||
- package_usage_id=主套餐ID
|
||||
- date=2026-02-10
|
||||
- daily_usage_mb=2048
|
||||
- cumulative_usage_mb=2048
|
||||
|
||||
#### Scenario: 扣减加油包流量并记录
|
||||
- **GIVEN** 加油包 data_usage_mb=0, data_limit_mb=5120
|
||||
- **WHEN** 扣减加油包 3072MB 流量
|
||||
- **THEN** PackageUsage 更新:data_usage_mb=3072
|
||||
- **AND** PackageUsageDailyRecord 创建记录:
|
||||
- package_usage_id=加油包ID
|
||||
- date=2026-02-10
|
||||
- daily_usage_mb=3072
|
||||
- cumulative_usage_mb=3072
|
||||
|
||||
#### Scenario: 同一天多次扣减更新日记录
|
||||
- **GIVEN** PackageUsageDailyRecord 已有记录(date=2026-02-10, daily_usage_mb=2048, cumulative_usage_mb=2048)
|
||||
- **WHEN** 再次扣减主套餐 1024MB 流量
|
||||
- **THEN** PackageUsage 更新:data_usage_mb=3072
|
||||
- **AND** PackageUsageDailyRecord 更新记录:
|
||||
- daily_usage_mb=3072(2048 + 1024)
|
||||
- cumulative_usage_mb=3072
|
||||
- **AND** 使用 UPSERT 更新而非插入新记录
|
||||
|
||||
#### Scenario: 跨天扣减创建新日记录
|
||||
- **GIVEN** PackageUsageDailyRecord 有 2026-02-10 的记录(daily_usage_mb=5120, cumulative_usage_mb=5120)
|
||||
- **WHEN** 2026-02-11 扣减主套餐 2048MB 流量
|
||||
- **THEN** PackageUsageDailyRecord 创建新记录:
|
||||
- date=2026-02-11
|
||||
- daily_usage_mb=2048
|
||||
- cumulative_usage_mb=7168(5120 + 2048)
|
||||
|
||||
#### Scenario: 日记录写入失败不影响扣减(容错性)
|
||||
- **GIVEN** 数据库主表正常,日记录表存在问题(例如磁盘满)
|
||||
- **WHEN** 扣减主套餐流量,PackageUsage 更新成功,但 PackageUsageDailyRecord 写入失败
|
||||
- **THEN** 系统记录 Error 日志,包含套餐ID、日期、增量
|
||||
- **AND** PackageUsage 的 data_usage_mb 仍然更新(不回滚)
|
||||
- **AND** 告警通知运维团队修复日记录表
|
||||
|
||||
#### Scenario: 批量扣减写入日记录(性能优化)
|
||||
- **GIVEN** 轮询系统同时检测到 1000 张卡的流量增加
|
||||
- **WHEN** 批量扣减流量
|
||||
- **THEN** 使用批量 INSERT ON CONFLICT UPDATE 写入日记录
|
||||
- **AND** 1000 条记录写入时间 < 5 秒
|
||||
|
||||
## 数据一致性保证
|
||||
|
||||
### 1. 扣减流量事务保证
|
||||
- **机制**:数据库事务包含:
|
||||
1. UPDATE PackageUsage SET data_usage_mb += increment
|
||||
2. INSERT/UPDATE PackageUsageDailyRecord
|
||||
- **回滚条件**:任一步骤失败,整个事务回滚
|
||||
|
||||
### 2. 并发扣减行锁
|
||||
- **机制**:`SELECT * FROM tb_package_usage WHERE id=? FOR UPDATE`
|
||||
- **保证**:同一套餐不会被并发扣减
|
||||
|
||||
### 3. 负数流量保护
|
||||
- **机制**:数据库约束 `CHECK (data_usage_mb >= 0)`
|
||||
- **保证**:扣减后不会出现负数流量
|
||||
|
||||
### 4. 日记录唯一索引
|
||||
- **机制**:`UNIQUE INDEX (package_usage_id, date) WHERE deleted_at IS NULL`
|
||||
- **保证**:同一套餐同一天只有一条记录
|
||||
|
||||
## 性能指标
|
||||
|
||||
| 操作 | 性能要求 | 监控指标 |
|
||||
|------|---------|---------|
|
||||
| 单次流量扣减 | < 100ms | 数据库事务耗时 |
|
||||
| 批量扣减(1000张卡) | < 10秒 | 轮询任务执行时间 |
|
||||
| 日记录写入 | < 50ms | INSERT/UPDATE 耗时 |
|
||||
| 停机条件检查 | < 50ms | SELECT 查询耗时 |
|
||||
|
||||
## 错误码定义
|
||||
|
||||
| 错误码 | HTTP 状态码 | 错误消息 | 场景 |
|
||||
|--------|------------|---------|------|
|
||||
| CodeInternal | 500 | 流量扣减失败,请重试 | 数据库更新失败 |
|
||||
| CodeInternal | 500 | 停机操作失败,请重试 | 运营商 API 调用失败 |
|
||||
|
||||
## 测试场景矩阵
|
||||
|
||||
| 维度 | 场景 | 预期结果 |
|
||||
|------|------|---------|
|
||||
| **基础扣减** | 只有主套餐 | 直接扣减主套餐 |
|
||||
| | 有1个加油包 | 优先扣减加油包 |
|
||||
| | 有3个加油包 | 按 priority 顺序扣减 |
|
||||
| **扣减完整流程** | 加油包用完 → 主套餐 | 先扣完所有加油包,再扣主套餐 |
|
||||
| | 所有套餐用完 | 触发停机 |
|
||||
| **边界条件** | 流量增量=0 | 不扣减 |
|
||||
| | 流量增量<0(异常) | 拒绝扣减,告警 |
|
||||
| | 加油包已用完 | 自动跳过 |
|
||||
| **并发场景** | 并发扣减同一套餐 | 行锁保证只扣减一次 |
|
||||
| **停机条件** | 主套餐用完+加油包剩余 | 不停机 |
|
||||
| | 所有套餐用完 | 停机 |
|
||||
| | 停机后购买加油包 | 自动复机 |
|
||||
| **日记录** | 首次扣减 | 创建日记录 |
|
||||
| | 同一天多次扣减 | 更新日记录 |
|
||||
| | 跨天扣减 | 创建新日记录 |
|
||||
| **异常处理** | 停机 API 失败 | 重试 3 次,失败进 DLQ |
|
||||
| | 日记录写入失败 | 告警,不影响扣减 |
|
||||
Reference in New Issue
Block a user