From 8b5cd50576ca380106d7c8188fb98cf7092aa9ba Mon Sep 17 00:00:00 2001 From: huang Date: Tue, 31 Mar 2026 18:12:44 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E5=BD=92=E6=A1=A3=20fix-stop-resume-l?= =?UTF-8?q?ifecycle-engine=20=E5=8F=98=E6=9B=B4=E6=8F=90=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- .../.openspec.yaml | 2 + .../design.md | 81 +++++++++++++++++++ .../proposal.md | 44 ++++++++++ .../specs/auto-resume-on-purchase/spec.md | 36 +++++++++ .../specs/auto-resume-on-reset/spec.md | 37 +++++++++ .../specs/auto-stop-resume/spec.md | 56 +++++++++++++ .../specs/package-queue-activation/spec.md | 46 +++++++++++ .../tasks.md | 80 ++++++++++++++++++ 8 files changed, 382 insertions(+) create mode 100644 openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/.openspec.yaml create mode 100644 openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/design.md create mode 100644 openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/proposal.md create mode 100644 openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/auto-resume-on-purchase/spec.md create mode 100644 openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/auto-resume-on-reset/spec.md create mode 100644 openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/auto-stop-resume/spec.md create mode 100644 openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/package-queue-activation/spec.md create mode 100644 openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/tasks.md diff --git a/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/.openspec.yaml b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/.openspec.yaml new file mode 100644 index 0000000..8fb8631 --- /dev/null +++ b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-31 diff --git a/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/design.md b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/design.md new file mode 100644 index 0000000..8fc1dbb --- /dev/null +++ b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/design.md @@ -0,0 +1,81 @@ +## Context + +现有停复机系统存在多条互相依赖的断链： + +1. **stop_reason 不一致**：`stopCards`（虚流量超额停机路径）写入 DB 时缺少 `stop_reason` 和 `stopped_at`，导致 `ResumeCardIfStopped` 的 `stop_reason == "traffic_exhausted"` 判断永远不通过 +2. **复机回调缺失**：购买套餐（`order/service.go`）和流量重置（`reset_service.go`）后均无复机触发，两者都没有注入 `StopResumeService` 的依赖 +3. **Depleted 套餐到期盲区**：`findExpiredMainPackages` 只查 `status=1`，已耗尽（`status=2`）套餐到期后无人处理，预购的下一个套餐永远卡在 Pending +4. **device 类型无覆盖**：`ResumeCardIfStopped` 及其两处调用点均有 `carrierType == "iot_card"` 硬判断，设备类型完全跳过 +5. **未实名卡无防护**：系统自动复机不检查 `real_name_status`，未实名卡可能被复机 +6. **并发不安全**：流量重置和排队激活可能同时触发同一张卡的 `gateway.StartCard` + +## Goals / Non-Goals + +**Goals:** +- 修复所有已识别的停复机断链，使停机卡在满足条件时可靠地自动复机 +- 统一 `stop_reason` 写入，所有系统自动停机路径都使用常量 +- 设备类型与单卡类型的停复机行为对等 +- 未实名卡不被自动复机 +- 防止并发 Gateway 调用 + +**Non-Goals:** +- 企业设备的 `SuspendCard/ResumeCard` Gateway 补全（独立 Issue） +- Gateway + DB 双阶段补偿机制（后期迭代） +- 对人工复机接口增加实名校验（业务上不需要） + +## Decisions + +### 决策 1：扩展 ResumeCardIfStopped 签名为 (ctx, carrierType, carrierID) + +**备选方案**：新增独立的 `ResumeDeviceIfStopped` 函数 +**选择原因**：复机的核心逻辑（检查 stop_reason、检查实名状态、加锁、调 Gateway）对两种类型是共用的，只有"查哪张卡"不同。将两者合并到一个函数，只在内部分支处理差异，避免维护两套并行逻辑。调用点签名统一，未来新增类型只改函数内部。 +**代价**：所有现有调用点需要更新传参（当前只有 2 处，成本可控）。 + +### 决策 2：SetResumeCallback 模式注入 StopResumeService + +**备选方案**：构造函数直接注入 +**选择原因**：项目中 `UsageService` 和 `ActivationService` 已采用此模式，保持一致性。`SetResumeCallback` 使依赖为可选（nil 检查），不强制要求所有场景都提供复机逻辑，例如纯退款场景的 `ActivationService` 实例可以不注入。 + +### 决策 3：findExpiredMainPackages 改为 status IN (1,2) + +**备选方案 B**：新增独立扫描任务处理 Depleted 套餐 +**备选方案 C**：套餐变 Depleted 时立即激活下一个 +**选择原因**： +- 方案 B 引入重复调度逻辑，两个任务并发时需要额外幂等保护 +- 方案 C 改变了状态机触发时机，`expires_at` 的语义是"到期才交接"，提前交接会导致套餐重叠或加油包提前失效 +- 方案 A 最小改动，语义与现有 `Active→Expired` 路径完全一致，`processExpiredPackage` 已包含加油包级联失效和下一套餐激活的完整逻辑 + +**加油包处理**：当 Depleted 主套餐到达 `expires_at` 时，加油包一并级联失效（现有 `invalidateAddons` 逻辑），符合"加油包跟随主套餐生命周期"的业务规则。 + +### 决策 4：实名检查在 ResumeCardIfStopped 内部统一执行 + +**备选方案**：各调用点分别检查 +**选择原因**：一处检查所有自动复机路径都受保护，不会因新增调用点而遗漏。静默跳过（warn 日志但不返回 error），不影响调用方的正常流程。 + +### 决策 5：Redis 分布式锁保护 ResumeCardIfStopped + +Key 格式：`card:resume:lock:{cardID}`，TTL 30s。 +**背景**：流量重置和排队激活有可能在同一时间窗口内对同一张卡触发复机。重复 `gateway.StartCard` 后果可控（运营商幂等），但增加无效 Gateway 调用和日志噪音。Redis 锁以最低成本解决此问题。 +加锁失败（锁被占用）时直接返回，不排队等待——说明正在复机，本次复机请求可丢弃。 + +## Risks / Trade-offs + +| 风险 | 缓解措施 | +|------|---------| +| `ResumeCardIfStopped` 签名变更导致编译错误 | 直接用 `lsp_diagnostics` 找所有调用点，修改完后编译验证 | +| `findExpiredMainPackages` 扩展后 Depleted 套餐被重复处理 | `processExpiredPackage` 内部先更新状态为 `Expired`，幂等性由 `expires_at <= now AND status IN (1,2)` 条件查询保证，相同套餐不会被重复捞起 | +| `order/service.go` 复机调用在事务外执行，事务失败但复机已触发 | 复机调用在事务 **commit 之后**（`HandlePaymentCallback` 的 `if err != nil { return }` 之后），事务失败不会执行复机；事务成功但复机 Gateway 失败时用户购买了套餐但卡仍停机，属于可接受的降级（有日志可人工介入） | +| device 类型遍历绑定卡时部分卡实名部分未实名 | 内部实名检查在每张卡维度独立执行，已实名卡复机，未实名卡跳过，互不影响 | +| Redis 锁超时（30s）内卡无法再次被复机触发 | 30s 是宽裕值，正常复机操作 < 5s；锁超时后自动释放，不会永久阻塞 | + +## Migration Plan + +**无需数据库迁移**。本次所有变更均为代码逻辑修复。 + +**部署顺序**：直接滚动升级。修复不改变数据库 schema，旧版停机的卡 `stop_reason` 为空或中文字符串，在 `ResumeCardIfStopped` 中会命中"非 traffic_exhausted 不复机"的逻辑，行为与现有一致（不会错误复机）。新版停机的卡会写入正确的 `stop_reason`，才能走自动复机链路。 + +**回滚**：直接回滚代码版本，无状态变化需要回滚。 + +## Open Questions + +无。所有关键决策已在盘问环节与产品确认。 diff --git a/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/proposal.md b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/proposal.md new file mode 100644 index 0000000..f643aa7 --- /dev/null +++ b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/proposal.md @@ -0,0 +1,44 @@ +## Why + +停复机与套餐生命周期引擎存在多处系统性缺陷：停机时 `stop_reason` 字段写入不一致导致自动复机链路断裂；已耗尽（Depleted）套餐在到期时无法触发下一个排队套餐激活；流量重置后停机卡不自动复机；设备类型载体完全缺失复机逻辑；`ResumeCardIfStopped` 未检查实名状态。这些问题直接影响用户续费后无法正常上网的核心业务场景。 + +## What Changes + +- **停机原因标准化**：`stopCards`（套餐超额停机）补写 `stop_reason=traffic_exhausted` + `stopped_at`，与其他停机路径对齐 +- **购买套餐后自动复机**：`order/service.go` 支付回调激活套餐后，调用复机回调 +- **Depleted 套餐到期处理**：`findExpiredMainPackages` 扩展为同时查 `status IN (1,2)`，使已耗尽套餐在到期日触发下一个 Pending 套餐激活与复机 +- **流量重置后自动复机**：`reset_service` 注入复机回调，重置后对满足条件的卡自动复机 +- **设备类型复机覆盖**：`ResumeCardIfStopped` 扩展签名支持 `carrierType`，设备类型时遍历绑定的已实名卡逐一复机 +- **未实名不自动复机**：`ResumeCardIfStopped` 内部统一检查 `real_name_status`，未实名卡静默跳过 +- **并发保护**：`ResumeCardIfStopped` 加 Redis 分布式锁，防止同一张卡并发触发多次 `gateway.StartCard` +- **告警日志**：Gateway 成功但 DB 更新失败时记录 ERROR 日志便于人工排查 +- **常量化**：`HandleProtectConsistencyCheck` 停机原因提取为 `constants.StopReasonProtectPeriod` 常量 + +## Capabilities + +### New Capabilities + +- `auto-resume-on-purchase`：购买套餐（支付回调激活）后触发停机卡自动复机的能力 +- `auto-resume-on-reset`：流量周期重置（日/月/年）后触发停机卡自动复机的能力 + +### Modified Capabilities + +- `auto-stop-resume`：扩展复机前置条件（未实名不复机）、添加设备类型支持、添加并发保护 +- `package-queue-activation`：扩展过期套餐检测逻辑，将 Depleted 套餐纳入到期检测范围 + +## Impact + +**修改文件：** +- `internal/task/polling_handler.go`：`stopCards` 补写 `stop_reason` + `stopped_at`；`HandleProtectConsistencyCheck` 使用 `StopReasonProtectPeriod` 常量 +- `internal/service/package/activation_service.go`：更新 `ResumeCallback` 接口签名（增加 `carrierType` 参数）；两处调用点更新传参 +- `internal/service/iot_card/stop_resume_service.go`：`ResumeCardIfStopped` 扩展支持 `carrierType`；内部加未实名检查；加 Redis 分布式锁；设备类型时遍历复机绑定卡 +- `internal/service/order/service.go`：注入 `ResumeCallback`；`HandlePaymentCallback` 事务后调用复机 +- `internal/service/package/reset_service.go`：注入 `ResumeCallback`；三个重置方法结束后异步调用复机 +- `internal/polling/package_activation_handler.go`：`findExpiredMainPackages` 查询改为 `status IN (1,2)` +- `pkg/constants/iot.go`：新增 `StopReasonProtectPeriod` 常量 +- `pkg/constants/redis.go`：新增 `RedisCardResumeLockKey(cardID)` Key 生成函数 +- `internal/bootstrap/worker_services.go`：为 `orderService`、`resetService` 注入 `stopResumeService` + +**不在本次范围：** +- `enterprise_device/service.go`：SuspendCard/ResumeCard 缺失 Gateway 调用（单独立 Issue 跟踪） +- Gateway + DB 双阶段补偿机制（后期迭代） diff --git a/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/auto-resume-on-purchase/spec.md b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/auto-resume-on-purchase/spec.md new file mode 100644 index 0000000..89ca462 --- /dev/null +++ b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/auto-resume-on-purchase/spec.md @@ -0,0 +1,36 @@ +## ADDED Requirements + +### Requirement: 购买套餐支付成功后自动复机 + +系统 SHALL 在支付回调成功激活套餐（`PackageUsage.status` 变为 1）后，对因流量耗尽而停机的卡自动触发复机操作。 + +#### Scenario: C 端购买套餐支付成功后停机卡自动复机 +- **GIVEN** 卡 C1 因流量耗尽停机（`network_status=0`，`stop_reason=traffic_exhausted`），已完成实名认证（`real_name_status=1`） +- **WHEN** C 端用户为 C1 购买新套餐并完成微信/支付宝支付，`HandlePaymentCallback` 事务提交成功 +- **THEN** 系统异步调用 `ResumeCardIfStopped(ctx, "iot_card", cardID)` +- **AND** 系统调用 `gateway.StartCard`，更新 `network_status=1`，清空 `stop_reason` + +#### Scenario: 后台购买套餐（钱包支付）后停机卡自动复机 +- **GIVEN** 卡 C2 因流量耗尽停机，已实名 +- **WHEN** 后台管理员通过钱包支付为 C2 购买套餐，`HandlePaymentCallback` 事务提交成功，套餐状态为 `status=1` +- **THEN** 系统调用复机逻辑，C2 自动复机 + +#### Scenario: 购买排队套餐（新套餐为 Pending 状态）时不触发复机 +- **GIVEN** 卡 C3 已有生效中套餐，用户购买第二个套餐（新套餐创建为 `status=0` Pending） +- **WHEN** 支付成功，`HandlePaymentCallback` 完成 +- **THEN** 系统 SHALL NOT 触发复机调用（仅在套餐变为 `status=1` 时才复机） + +#### Scenario: 未实名卡购买套餐不触发复机 +- **GIVEN** 卡 C4 停机（`stop_reason=traffic_exhausted`），但 `real_name_status=0`（未实名） +- **WHEN** 为 C4 购买新套餐且套餐激活为 `status=1` +- **THEN** `ResumeCardIfStopped` 内部检测到未实名，静默跳过，C4 保持停机状态 + +#### Scenario: 停机原因非流量耗尽时不触发复机 +- **GIVEN** 卡 C5 因手动停机（`stop_reason=manual`） +- **WHEN** 为 C5 购买新套餐并激活 +- **THEN** `ResumeCardIfStopped` 检测到 `stop_reason` 不为 `traffic_exhausted`，静默跳过 + +#### Scenario: 设备类型载体购买套餐后自动复机 +- **GIVEN** 设备 D1 绑定了 3 张卡，其中 2 张已实名且因流量耗尽停机，1 张未实名 +- **WHEN** 为 D1 购买设备级套餐并激活 +- **THEN** 已实名的 2 张卡自动复机，未实名的 1 张卡保持停机状态 diff --git a/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/auto-resume-on-reset/spec.md b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/auto-resume-on-reset/spec.md new file mode 100644 index 0000000..8f893dc --- /dev/null +++ b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/auto-resume-on-reset/spec.md @@ -0,0 +1,37 @@ +## ADDED Requirements + +### Requirement: 流量周期重置后自动复机 + +系统 SHALL 在成功重置套餐流量（`data_usage_mb` 归零，`status` 恢复为 `Active`）后，对因流量耗尽而停机的卡自动触发复机操作。 + +#### Scenario: 3 个月套餐第 2 个月耗尽停机，第 3 个月重置后自动复机 +- **GIVEN** 卡 C1 有一个 3 个月套餐（`data_reset_cycle=monthly`），第 2 个月流量耗尽（`status=2 Depleted`），卡已停机（`network_status=0`，`stop_reason=traffic_exhausted`），已实名 +- **WHEN** 月度重置任务运行，套餐 `data_usage_mb` 归零，`status` 恢复为 `1 Active` +- **THEN** `ResetService` 调用 `ResumeCardIfStopped(ctx, "iot_card", cardID)` +- **AND** 卡自动复机（`network_status=1`） + +#### Scenario: 日流量套餐重置后停机卡自动复机 +- **GIVEN** 卡 C2 有日流量套餐（`data_reset_cycle=daily`），当天流量耗尽停机，已实名 +- **WHEN** 次日零点日流量重置任务运行 +- **THEN** 卡自动复机 + +#### Scenario: 年流量套餐重置后停机卡自动复机 +- **GIVEN** 卡 C3 有年流量套餐（`data_reset_cycle=yearly`），年内流量耗尽停机，已实名 +- **WHEN** 年度重置任务运行 +- **THEN** 卡自动复机 + +#### Scenario: 重置后卡已处于开机状态不重复复机 +- **GIVEN** 卡 C4 套餐被重置，但 `network_status=1`（已开机，可能已被人工复机） +- **WHEN** `ResumeCardIfStopped` 被调用 +- **THEN** 检测到卡已开机，幂等跳过，不调用 Gateway + +#### Scenario: 重置后未实名卡不复机 +- **GIVEN** 卡 C5 套餐被重置，`real_name_status=0`（未实名），停机中 +- **WHEN** `ResumeCardIfStopped` 被调用 +- **THEN** 检测到未实名，静默跳过，卡保持停机 + +#### Scenario: 批量重置中部分套餐的卡已停机 +- **GIVEN** 月度重置扫描到 100 个套餐，其中 10 个对应的卡处于停机状态且已实名 +- **WHEN** 月度重置完成 +- **THEN** 10 张停机卡异步触发复机，其余 90 张正常跳过 +- **AND** 单个复机失败不影响其他卡的处理 diff --git a/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/auto-stop-resume/spec.md b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/auto-stop-resume/spec.md new file mode 100644 index 0000000..d669392 --- /dev/null +++ b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/auto-stop-resume/spec.md @@ -0,0 +1,56 @@ +## MODIFIED Requirements + +### Requirement: 流量耗尽自动复机 + +系统 SHALL 在套餐激活或流量重置后，对满足以下全部条件的卡自动调用运营商接口复机： +1. `stop_reason = "traffic_exhausted"`（仅限流量耗尽停机，手动停机不自动复机） +2. `real_name_status = 1`（已完成实名认证） +3. `network_status = 0`（当前处于停机状态） + +系统 SHALL 在执行复机前获取 Redis 分布式锁（Key：`card:resume:lock:{cardID}`，TTL 30s），防止并发重复调用 Gateway。 + +#### Scenario: 所有条件满足时自动复机 +- **GIVEN** 卡 C1 满足：`stop_reason=traffic_exhausted`，`real_name_status=1`，`network_status=0` +- **WHEN** `ResumeCardIfStopped(ctx, "iot_card", cardID)` 被调用 +- **THEN** 系统获取分布式锁，调用 `gateway.StartCard`，更新 `network_status=1`，清空 `stop_reason`，释放锁 + +#### Scenario: 未实名卡跳过自动复机 +- **GIVEN** 卡 C2 `stop_reason=traffic_exhausted`，`real_name_status=0`，`network_status=0` +- **WHEN** `ResumeCardIfStopped` 被调用 +- **THEN** 系统记录 WARN 日志，静默跳过，不调用 Gateway，函数返回 nil + +#### Scenario: 手动停机的卡不被自动复机 +- **GIVEN** 卡 C3 `stop_reason=manual`，`real_name_status=1`，`network_status=0` +- **WHEN** `ResumeCardIfStopped` 被调用 +- **THEN** 系统检测到 `stop_reason != traffic_exhausted`，静默跳过 + +#### Scenario: 并发调用时只有一次复机执行 +- **GIVEN** 卡 C4 满足复机条件，复机操作正在执行（分布式锁被持有） +- **WHEN** 第二个 `ResumeCardIfStopped` 调用同时到达 +- **THEN** 第二个调用获锁失败，直接返回，不调用 Gateway + +#### Scenario: 设备类型载体复机遍历所有绑定卡 +- **GIVEN** 设备 D1 绑定 3 张卡（C1 已实名停机、C2 已实名停机、C3 未实名停机） +- **WHEN** `ResumeCardIfStopped(ctx, "device", deviceID)` 被调用 +- **THEN** C1 和 C2 自动复机，C3 因未实名跳过 + +## ADDED Requirements + +### Requirement: 套餐超额停机必须写入 stop_reason 和 stopped_at + +系统 SHALL 在套餐虚流量超额触发停机时（`stopCards` 函数），写入 `stop_reason=traffic_exhausted` 和 `stopped_at` 到 IoT 卡记录。 + +#### Scenario: 虚流量超额停机完整写入 DB +- **GIVEN** 卡 C1 当月流量超过套餐 `virtual_data_mb` 上限，`network_status=1` +- **WHEN** `HandlePackageCheck` 的 `stopCards` 执行 +- **THEN** Gateway 调用成功后，DB 更新包含：`network_status=0`，`stop_reason=traffic_exhausted`，`stopped_at=now()`，`updated_at=now()` + +### Requirement: 保护期停机使用常量 stop_reason + +系统 SHALL 在保护期一致性检查停机时，使用 `constants.StopReasonProtectPeriod` 常量（值：`protect_period`）记录 `stop_reason`。 + +#### Scenario: 保护期停机写入正确原因 +- **GIVEN** 设备处于停机保护期，绑定的卡 C1 `network_status=1`（开机状态不一致） +- **WHEN** `HandleProtectConsistencyCheck` 触发停机 +- **THEN** DB 中 `stop_reason=protect_period`（使用常量，非中文硬编码） +- **AND** `ResumeCardIfStopped` 调用时因 `stop_reason != traffic_exhausted` 跳过，不会错误触发自动复机 diff --git a/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/package-queue-activation/spec.md b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/package-queue-activation/spec.md new file mode 100644 index 0000000..5f3a8a9 --- /dev/null +++ b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/specs/package-queue-activation/spec.md @@ -0,0 +1,46 @@ +## MODIFIED Requirements + +### Requirement: 同时只能有一个生效中的主套餐 + +系统 SHALL 确保载体（设备/卡）同一时刻只能有一个 `package_type=formal` 且 `status=1` 的套餐。 + +**到期检测扩展**：过期检测 SHALL 同时覆盖 `status=1`（生效中）和 `status=2`（已耗尽）的主套餐。当 `expires_at <= now` 时，无论套餐当前是生效中还是已耗尽，均视为到期，触发下一个排队套餐激活。 + +**数据一致性保证**： +- 购买时检查：查询 `WHERE (iot_card_id/device_id)=? AND status=1 AND master_usage_id IS NULL` +- 并发控制：使用数据库事务避免并发插入多个生效中主套餐 +- 激活时二次检查：激活前再次查询是否有生效中主套餐，避免并发激活 + +#### Scenario: 首次购买主套餐立即生效 +- **GIVEN** 载体无任何主套餐记录 +- **WHEN** 用户购买主套餐并支付成功 +- **THEN** 系统创建 PackageUsage：`status=1`，`priority=1`，`activated_at=支付完成时间`，`expires_at=根据 calendar_type 计算`，`master_usage_id=NULL` + +#### Scenario: 购买第二个主套餐自动排队 +- **GIVEN** 载体已有 1 个生效中的主套餐（`priority=1`，`status=1`） +- **WHEN** 用户购买第 2 个主套餐 +- **THEN** 系统创建 PackageUsage：`status=0`，`priority=2`，无 `activated_at` 和 `expires_at` + +#### Scenario: 生效中主套餐到期触发下一个激活 +- **GIVEN** 卡 C1 有生效中主套餐（`status=1`，`expires_at=过去时间`）和一个排队套餐（`status=0`） +- **WHEN** 过期检测任务扫描到该套餐 +- **THEN** 生效中套餐更新为 `status=3 Expired`，加油包级联失效，下一个排队套餐激活为 `status=1` +- **AND** 如卡因流量耗尽停机（`stop_reason=traffic_exhausted`）且已实名，触发自动复机 + +#### Scenario: 已耗尽（Depleted）主套餐到期后触发下一个激活 +- **GIVEN** 卡 C2 有已耗尽主套餐（`status=2 Depleted`，`expires_at=过去时间`）和一个预购排队套餐（`status=0`） +- **WHEN** 过期检测任务扫描（查询条件：`status IN (1,2) AND expires_at <= now AND master_usage_id IS NULL`） +- **THEN** 耗尽套餐更新为 `status=3 Expired`，加油包级联失效，预购排队套餐激活为 `status=1` +- **AND** 如卡因流量耗尽停机且已实名，触发自动复机 + +#### Scenario: 已耗尽套餐到期时加油包级联失效 +- **GIVEN** 卡 C3 有耗尽主套餐（`status=2`，`expires_at=过去时间`），以及绑定到该主套餐的 1 个加油包（`status=1`，尚有剩余流量） +- **WHEN** 过期检测任务处理该主套餐 +- **THEN** 主套餐更新为 `status=3`，加油包更新为 `status=4 Invalidated`（即使尚有剩余流量） +- **AND** 下一个排队主套餐激活 + +#### Scenario: 已耗尽套餐到期且无下一个排队套餐 +- **GIVEN** 卡 C4 有耗尽主套餐（`status=2`，`expires_at=过去时间`），无排队套餐 +- **WHEN** 过期检测任务处理该主套餐 +- **THEN** 耗尽套餐更新为 `status=3`，加油包级联失效，无新套餐激活 +- **AND** 卡的业务状态更新为 `IotCardStatusSuspended=4`（已停用） diff --git a/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/tasks.md b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/tasks.md new file mode 100644 index 0000000..29c5e21 --- /dev/null +++ b/openspec/changes/archive/2026-03-31-fix-stop-resume-lifecycle-engine/tasks.md @@ -0,0 +1,80 @@ +# Tasks: fix-stop-resume-lifecycle-engine + +## 阶段 1：基础层修复（常量 + 停机写入） + +> 优先级最高，其他所有阶段的复机逻辑都依赖 stop_reason 写入正确。 + +- [x] **1.1** `pkg/constants/iot.go`：新增 `StopReasonProtectPeriod = "protect_period"` 常量 +- [x] **1.2** `pkg/constants/redis.go`：新增 `RedisCardResumeLockKey(cardID uint) string` 函数，Key 格式 `card:resume:lock:{cardID}` +- [x] **1.3** `internal/task/polling_handler.go`：`stopCards` 函数 DB 更新中补充 `"stop_reason": constants.StopReasonTrafficExhausted` 和 `"stopped_at": now` +- [x] **1.4** `internal/task/polling_handler.go`：`HandleProtectConsistencyCheck` 中的 `"stop_reason": "保护期一致性检查自动停机"` 替换为 `constants.StopReasonProtectPeriod` + +--- + +## 阶段 2：ResumeCardIfStopped 核心重构 + +> 扩展签名 + 加未实名检查 + 加并发锁 + 加 device 支持。其他阶段依赖此函数签名。 + +- [x] **2.1** `internal/service/iot_card/stop_resume_service.go`：`ResumeCallback` 接口方法签名改为 `ResumeCardIfStopped(ctx context.Context, carrierType string, carrierID uint) error` +- [x] **2.2** `internal/service/iot_card/stop_resume_service.go`：`ResumeCardIfStopped` 实现： + - 参数改为 `(ctx, carrierType, carrierID)` + - `carrierType == "iot_card"` 时：读取单卡信息 → 检查实名 → 检查 stop_reason → 加 Redis 锁 → 调 Gateway → 更新 DB + - `carrierType == "device"` 时：查询设备绑定的所有已绑定卡（`bind_status=bound`） → 逐一执行 iot_card 复机逻辑（含实名检查） + - Gateway 成功但 DB 失败时记录 ERROR 日志（含卡 ID、ICCID），不返回 error 阻断流程 +- [x] **2.3** `internal/service/package/activation_service.go`：更新 `ResumeCallback` 接口定义（与 2.1 一致） +- [x] **2.4** `internal/service/package/activation_service.go`：两处 `resumeCallback.ResumeCardIfStopped` 调用点更新传参（传入 `carrierType`、`carrierID`） +- [x] **2.5** 编译检查：`lsp_diagnostics` 确认无编译错误 + +--- + +## 阶段 3：购买套餐后复机（order service） + +- [x] **3.1** `internal/service/order/service.go`：`Service` 结构体增加 `resumeCallback ResumeCallback` 字段（复用 `activation_service.go` 中定义的接口） +- [x] **3.2** `internal/service/order/service.go`：新增 `SetResumeCallback(callback ResumeCallback)` 方法 +- [x] **3.3** `internal/service/order/service.go`：`HandlePaymentCallback` 在事务成功后（`if err != nil { return err }` 之后），根据订单的 `carrierType` 和 `carrierID` 调用 `s.resumeCallback.ResumeCardIfStopped`（检查 nil，异步 goroutine 调用） + - 仅当 `activateMainPackage` 创建了 `status=1` 的套餐时才触发（即 `!hasActiveMain` 分支） + - 传递载体信息：从 order 中读取 `IotCardID` 或 `DeviceID` + +--- + +## 阶段 4：Depleted 套餐到期处理 + +- [x] **4.1** `internal/polling/package_activation_handler.go`：`findExpiredMainPackages` 查询条件改为 `WHERE status IN (1,2) AND expires_at <= now AND master_usage_id IS NULL` +- [x] **4.2** 验证：`processExpiredPackage` 的状态更新 `tx.Model(pkg).Update("status", constants.PackageUsageStatusExpired)` 对 `status=2` 的套餐同样生效（GORM 无状态前置条件，直接更新，逻辑正确无需修改） + +--- + +## 阶段 5：流量重置后复机（reset service） + +- [x] **5.1** `internal/service/package/reset_service.go`：`ResetService` 结构体增加 `resumeCallback ResumeCallback` 字段 +- [x] **5.2** `internal/service/package/reset_service.go`：新增 `SetResumeCallback(callback ResumeCallback)` 方法 +- [x] **5.3** `internal/service/package/reset_service.go`：`resetDailyUsageWithDB`、`resetMonthlyUsageWithDB`、`resetYearlyUsageWithDB` 三个方法在批量重置完成后，遍历被重置的套餐列表，对每个套餐的 `IotCardID` 异步调用 `resumeCallback.ResumeCardIfStopped(ctx, "iot_card", cardID)`（device 类型套餐传 `"device"` 和 `DeviceID`，nil 检查） + +--- + +## 阶段 6：Bootstrap 注入 + +- [x] **6.1** `internal/bootstrap/worker_services.go`：`stopResumeService` 创建后，调用： + - `orderService.SetResumeCallback(stopResumeService)` （注意：`orderService` 已在 bootstrap 中创建） + - `resetService.SetResumeCallback(stopResumeService)` + - `usageService.SetStopResumeCallback(stopResumeService)`（已有，确认保留） + - `activationService.SetResumeCallback(stopResumeService)`（已有，确认保留） + +--- + +## 阶段 7：知识库更新 + +- [x] **7.1** 更新知识库 `卡管业务整理/11-停机与复机流程.md`：在"这条链路的问题"表中标注已修复项；补充"自动停复机触发点"说明 +- [x] **7.2** 更新知识库 `卡管业务整理/08-套餐使用生命周期.md`：补充"Depleted 套餐到期处理"流程节点 +- [x] **7.3** 更新知识库 `修正业务/修正业务总览.md`：将本次修复的 Bug 从待修复移到已修复，新增企业设备停复机的独立追踪条目 + +--- + +## 验证清单 + +- [x] **V1** 编译通过：`go build ./...` 无错误 +- [ ] **V2** DB 查询验证：停机卡买套餐后 `network_status=1`，`stop_reason` 清空 +- [ ] **V3** DB 查询验证：流量耗尽的 3 个月套餐在模拟重置后复机 +- [ ] **V4** DB 查询验证：Depleted 主套餐到期后，下一个 Pending 套餐激活为 status=1 +- [ ] **V5** 日志验证：未实名卡触发复机时出现 WARN 日志而非 ERROR +- [ ] **V6** 日志验证：`stopCards` 停机后 `stop_reason=traffic_exhausted` 写入 DB