归档提案
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-04-17
|
||||
@@ -0,0 +1,117 @@
|
||||
## Context
|
||||
|
||||
现有的套餐实名激活逻辑存在两个关联缺陷：
|
||||
|
||||
**缺陷 A（购买时）**：`order/service.go` 的 `activateMainPackage` 在判断 `expiry_base=from_activation` 时，无条件将套餐标记为 `pending_realname_activation=true`（status=0），未检查载体当前是否已实名。这个缺陷造成**双重故障**：
|
||||
|
||||
```
|
||||
套餐 status=0（pending）
|
||||
↓
|
||||
tryResumeAfterPayment 检查 activatedCount = 0
|
||||
↓
|
||||
ResumeCardIfStopped 不触发
|
||||
↓
|
||||
① 套餐永久无法激活
|
||||
② 购买后卡/设备不会自动开机（即使之前因无套餐而停机）
|
||||
```
|
||||
|
||||
"先实名后购买"是代理商的典型囤货场景（如：设备出厂时已实名，用户激活时购买套餐），在此场景下套餐和开机均失效。
|
||||
|
||||
**缺陷 B（轮询时）**：`polling_realname_handler.go` 的 `triggerFirstRealnameActivation` 提交的 Asynq 任务硬编码 `carrier_type="iot_card"`，即使卡属于某个设备、该设备有 `pending_realname_activation=true` 的设备级套餐，也不会触发设备级激活，同样导致设备下的卡无法通过实名事件触发复机。
|
||||
|
||||
两个缺陷叠加导致：设备级套餐在"先实名后购买"和"购买后某张卡实名"两个场景均无法激活，且均无法触发自动复机。
|
||||
|
||||
**现有关键基础设施**：
|
||||
- `DeviceSimBindingStore.GetActiveBindingByCardID(ctx, cardID)` — 通过卡 ID 查关联设备
|
||||
- `DeviceSimBindingStore.ListByDeviceID(ctx, deviceID)` — 查设备绑定的所有卡
|
||||
- `h.workerResult.Stores.DeviceSimBinding` — Worker 中已可用
|
||||
- `ActivationService.ActivateByRealname(ctx, carrierType, carrierID)` — 已支持 `carrier_type="device"`，且**激活成功后内部会异步调用 `ResumeCardIfStopped(ct, cid)`**
|
||||
- `StopResumeService.ResumeCardIfStopped("device", deviceID)` → `resumeDeviceCards`：遍历设备下因轮询原因停机的卡，逐卡检查实名状态后决定是否复机
|
||||
- `tryResumeAfterPayment`（order service）：支付回调成功后，若 `activatedCount > 0` 则异步调用 `ResumeCardIfStopped`，支持 `iot_card` 和 `device` 两种载体类型
|
||||
|
||||
**复机的 stop_reason 约束**（现有设计，本次不变）：自动复机仅处理轮询系统引起的停机原因（`no_package`、`traffic_exhausted`、`not_realname`），`manual` 手动停机不会被自动复机——这是系统的有意设计，防止覆盖人工操作。
|
||||
|
||||
---
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- 购买 `from_activation` 套餐时，若载体当前已实名，直接激活（不进入 pending 状态），同时保障 `tryResumeAfterPayment` 的复机链路正常触发
|
||||
- 卡首次实名时，同时触发其所属设备的设备级套餐激活，进而触发设备下符合条件卡的复机
|
||||
- 修复后的逻辑统一、无歧义：`from_purchase` → 立即激活；`from_activation` → 检查实名再决策（已实名直接激活，未实名等待实名事件）
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- 不引入新的数据库字段或迁移
|
||||
- 不改变卡级套餐的现有激活流程
|
||||
- 不处理历史存量被卡住的套餐（需手动 SQL 修复）
|
||||
- 不改变孤儿套餐恢复机制（仅处理 `from_purchase` 场景）
|
||||
|
||||
---
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1：在 `activateMainPackage` 中内联实名状态检查
|
||||
|
||||
**方案 A（选择）**：在现有 `activateMainPackage` 的实名决策块（REALNAME-02 段）内扩展逻辑，直接用 `tx` 查询实名状态。
|
||||
|
||||
**方案 B**：抽取独立 `checkCarrierRealnamed(tx, carrierType, carrierID)` helper。
|
||||
|
||||
选 A 原因：修改点集中在一个函数的一个分支内，变更范围小，逻辑内聚，无需跨文件重构。
|
||||
|
||||
**实现细节**：
|
||||
- `iot_card`：扩展已有的卡查询，同时 `SELECT "card_category", "real_name_status"`，避免额外查询
|
||||
- `device`：新增一次子查询，利用已有的 `tb_device_sim_binding` 关系查询是否有已实名的绑定卡：
|
||||
```sql
|
||||
SELECT COUNT(*) FROM tb_iot_card
|
||||
WHERE id IN (
|
||||
SELECT iot_card_id FROM tb_device_sim_binding
|
||||
WHERE device_id = ? AND bind_status = 1 AND deleted_at IS NULL
|
||||
) AND real_name_status = 1
|
||||
```
|
||||
|
||||
### Decision 2：在 `triggerFirstRealnameActivation` 之后添加 `triggerDeviceRealnameActivation`
|
||||
|
||||
**方案 A（选择）**：`PollingRealnameHandler` 新增 `deviceSimBindingStore` 字段 + `triggerDeviceRealnameActivation` 方法，在卡 0→1 时调用。
|
||||
|
||||
**方案 B**：在 `PackageActivationHandler.HandlePackageFirstActivation` 内部，收到 `carrier_type=iot_card` 后自动查关联设备再激活设备级套餐。
|
||||
|
||||
选 A 原因：语义更清晰——"卡实名"触发"设备套餐激活"属于实名事件的副作用，应由实名 Handler 发起；方案 B 会使激活 Handler 承担实名业务上下文的感知，违反单一职责。
|
||||
|
||||
**实现细节**：`triggerDeviceRealnameActivation` 调用 `deviceSimBindingStore.GetActiveBindingByCardID` 获取设备 ID，若无绑定则静默跳过，若有则提交 `carrier_type="device"` 的 `TaskTypePackageFirstActivation` 任务。
|
||||
|
||||
### Decision 3：`NewPollingRealnameHandler` 构造函数新增参数
|
||||
|
||||
直接在参数列表末尾追加 `deviceSimBindingStore *postgres.DeviceSimBindingStore`，`pkg/queue/handler.go` 的 `registerPollingHandlers` 传入已可用的 `h.workerResult.Stores.DeviceSimBinding`。
|
||||
|
||||
---
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
| 风险 | 缓解措施 |
|
||||
|------|---------|
|
||||
| 购买时多一次 DB 查询（device 需子查询）| 查询走索引（`tb_device_sim_binding.device_id` 有索引），影响可忽略 |
|
||||
| 卡实名时提交多一个 Asynq 任务（device 任务）| 任务幂等：`ActivateByRealname` 查不到 pending 套餐直接返回 nil，无副作用 |
|
||||
| `GetActiveBindingByCardID` 返回 `ErrRecordNotFound` 时不应 log.Error | 已处理：独立卡不属于设备，应静默跳过（Debug/无日志即可） |
|
||||
| 存量已卡住的套餐（如本次触发排查的 id=1）不会被自动修复 | 在 Migration Plan 中给出手动 SQL |
|
||||
| 手动停机（`stop_reason=manual`）的卡不会被自动复机 | 这是现有系统的有意设计，Fix 1/2 不改变此行为；手动停机需人工操作复机 |
|
||||
| 历史存量套餐手动修复后，停机卡不会立即自动开机 | 需额外手动调用 Gateway 复机接口，或等待轮询系统下次 EvaluateAndAct 评估（最长等一个轮询周期） |
|
||||
|
||||
---
|
||||
|
||||
## Migration Plan
|
||||
|
||||
**存量问题修复**（代码部署后手动执行）：
|
||||
|
||||
**当前生产环境确认**：仅 `id=1`（device_id=2，`natural_month` 12 个月，`data_reset_cycle=monthly`）受影响。
|
||||
|
||||
**关键约束**：`expires_at` 必须匹配 Go 层 `CalculateExpiryTime` 的逻辑（自然月套餐 = 目标月末 23:59:59，不是简单的 `+N months`），同时需一并写入 `next_reset_at`。具体可执行 SQL 见 `tasks.md` 任务 4.2（三步操作：确认范围 → BEGIN/UPDATE/COMMIT → 验证）。
|
||||
|
||||
**回滚**：代码变更纯逻辑，无 schema 变更，直接回滚二进制即可。
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
无。
|
||||
@@ -0,0 +1,45 @@
|
||||
## Why
|
||||
|
||||
当前系统存在两个关联缺陷，且缺陷 A 的影响远不止套餐激活本身：
|
||||
|
||||
**缺陷 A**：代理商**先给设备/卡实名，再购买 `expiry_base=from_activation` 的套餐**，系统未检查当前实名状态，无条件将套餐标记为 `pending_realname_activation=true`（待生效，status=0）。这不仅导致套餐永久无法激活，还**连带阻断了购买后的自动复机链路**：`tryResumeAfterPayment` 在检查到 `activatedCount=0` 时直接跳过，即使卡此前因无套餐而停机，购买成功后也不会自动开机。
|
||||
|
||||
**缺陷 B**：卡首次实名（0→1）时，实名轮询处理器只触发卡级套餐激活，不处理该卡所属设备的设备级套餐，导致设备级套餐在"购买后某张卡实名"场景下永不激活，同样无法触发设备下绑定卡的复机。
|
||||
|
||||
修复后的规则：**`from_activation` 套餐在购买时检查实名状态，已实名则直接激活（同时保障复机链路正常触发）；卡首次实名时同时触发其所属设备的设备级套餐激活与复机**。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **购买时实名状态检查**：在 `activateMainPackage` 中，当判断 `expiry_base != "from_purchase"` 时，额外检查载体当前实名状态：
|
||||
- `iot_card`：查询该卡的 `real_name_status`
|
||||
- `device`：通过 `tb_device_sim_binding` 查询是否存在任意已实名的绑定卡
|
||||
- 已实名 → 直接激活（`status=Active`），`tryResumeAfterPayment` 检查到 `activatedCount>0` 后正常触发复机链路
|
||||
- 未实名 → 保持原有逻辑等待实名触发
|
||||
- **实名轮询触发设备级激活与复机**：在 `PollingRealnameHandler` 的卡首次实名（0→1）路径中，额外查询该卡所属设备，若设备存在则同时提交 `carrier_type=device` 的 `TaskTypePackageFirstActivation` 任务；任务执行后 `ActivateByRealname` 内部会调用 `ResumeCardIfStopped("device", deviceID)` 触发设备下符合条件卡的复机
|
||||
- `NewPollingRealnameHandler` 构造函数新增 `*postgres.DeviceSimBindingStore` 参数
|
||||
|
||||
**复机行为说明**：自动复机仅针对由轮询系统引起的停机（`stop_reason` 为 `no_package`、`traffic_exhausted`、`not_realname`），手动停机（`manual`）不受影响，设备下每张卡独立判断实名状态后再决定是否复机。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
无新能力，均为现有逻辑的修正。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `package-realname-activation`：补充"购买时载体已实名则直接激活"的决策分支，以及"设备下卡实名时触发设备级套餐激活"的联动规则
|
||||
- `polling-task-handlers`：`PollingRealnameHandler` 新增 `DeviceSimBindingStore` 依赖，新增 `triggerDeviceRealnameActivation` 函数
|
||||
|
||||
## Impact
|
||||
|
||||
**涉及文件**：
|
||||
- `internal/service/order/service.go`（`activateMainPackage` 函数，~1782-1807 行）
|
||||
- `internal/task/polling_realname_handler.go`（结构体、构造函数、新增函数）
|
||||
- `pkg/queue/handler.go`（`registerPollingHandlers` 中的构造调用）
|
||||
|
||||
**数据库**：无 schema 变更，无迁移
|
||||
|
||||
**API**：无接口变更，对外透明
|
||||
|
||||
**当前问题设备的直接影响**：设备 `862639076038233` 的套餐（`tb_package_usage.id=1`）需要手动修复（修改 `pending_realname_activation=false`、激活套餐），代码修复仅防止新订单再次陷入同样问题。手动修复套餐后，还需手动触发设备复机（或等待轮询系统下次评估），因为历史停机事件不会被追溯重放。
|
||||
@@ -0,0 +1,80 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 支持未实名状态购买套餐
|
||||
|
||||
系统 SHALL 允许后台管理端为未实名的载体（设备/卡）购买套餐，套餐状态为"待生效"(status=0)。对于 `expiry_base=from_activation` 的套餐，系统 SHALL 在创建 `PackageUsage` 时检查载体当前实名状态：若已实名则直接激活；若未实名则标记 `pending_realname_activation=true` 等待实名触发。
|
||||
|
||||
**实名状态判定规则**：
|
||||
- `iot_card` 载体：查询该卡的 `real_name_status` 字段
|
||||
- `device` 载体：通过 `tb_device_sim_binding`（`bind_status=1`）查询是否存在任意已实名（`real_name_status=1`）的绑定卡；存在任意一张即视为设备已实名
|
||||
|
||||
#### Scenario: 后台为未实名设备购买 from_activation 套餐——待生效
|
||||
- **GIVEN** 设备 ID=2，绑定的所有卡 `real_name_status=0`（均未实名）
|
||||
- **AND** 套餐 `expiry_base=from_activation`，购买者为代理商（非 C 端）
|
||||
- **WHEN** 管理员通过后台为该设备购买套餐
|
||||
- **THEN** 系统创建 PackageUsage：`status=0`，`pending_realname_activation=true`，`activated_at=NULL`，`expires_at=NULL`
|
||||
|
||||
#### Scenario: 后台为已有实名卡的设备购买 from_activation 套餐——直接激活并触发复机
|
||||
- **GIVEN** 设备 ID=2，至少一张绑定卡 `real_name_status=1`（已实名），且设备下有卡因无套餐停机（`stop_reason=no_package`）
|
||||
- **AND** 套餐 `expiry_base=from_activation`，购买者为代理商（非 C 端）
|
||||
- **WHEN** 管理员通过后台为该设备购买套餐
|
||||
- **THEN** 系统创建 PackageUsage：`status=1`，`pending_realname_activation=false`，`activated_at=购买时间`，`expires_at` 按套餐配置计算
|
||||
- **AND** `tryResumeAfterPayment` 检测到 `activatedCount=1`，异步调用 `ResumeCardIfStopped("device", 2)`
|
||||
- **AND** 设备下已实名且因 `no_package` 停机的卡自动开机
|
||||
|
||||
#### Scenario: 后台为已实名单卡购买 from_activation 套餐——直接激活
|
||||
- **GIVEN** IoT 卡 ID=10，`real_name_status=1`（已实名）
|
||||
- **AND** 套餐 `expiry_base=from_activation`，购买者为代理商（非 C 端）
|
||||
- **WHEN** 管理员通过后台为该卡购买套餐
|
||||
- **THEN** 系统创建 PackageUsage：`status=1`，`pending_realname_activation=false`，`activated_at=购买时间`，`expires_at` 按套餐配置计算
|
||||
|
||||
#### Scenario: 后台为未实名单卡购买 from_activation 套餐——待生效
|
||||
- **GIVEN** IoT 卡 ID=10，`real_name_status=0`（未实名）
|
||||
- **AND** 套餐 `expiry_base=from_activation`，购买者为代理商（非 C 端）
|
||||
- **WHEN** 管理员通过后台为该卡购买套餐
|
||||
- **THEN** 系统创建 PackageUsage：`status=0`，`pending_realname_activation=true`，`activated_at=NULL`，`expires_at=NULL`
|
||||
|
||||
#### Scenario: from_purchase 套餐不检查实名状态——始终直接激活
|
||||
- **GIVEN** 设备 ID=2，所有绑定卡均未实名（`real_name_status=0`）
|
||||
- **AND** 套餐 `expiry_base=from_purchase`
|
||||
- **WHEN** 管理员通过后台为该设备购买套餐
|
||||
- **THEN** 系统创建 PackageUsage：`status=1`，`pending_realname_activation=false`，立即生效
|
||||
|
||||
#### Scenario: 客户端购买套餐——必须先实名（不受本次变更影响）
|
||||
- **GIVEN** 设备 ID=2，购买者为个人客户（C 端）
|
||||
- **WHEN** 客户通过 H5/小程序购买套餐
|
||||
- **THEN** 系统前置检查已实名，行为不变
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 卡首次实名时同时触发所属设备的设备级套餐激活
|
||||
|
||||
当轮询系统检测到某张 IoT 卡的实名状态从 0 变为 1（首次实名），系统 SHALL 除提交该卡的 `TaskTypePackageFirstActivation` 任务外，额外查询该卡是否属于某个设备（通过 `tb_device_sim_binding`），若存在有效绑定则同时提交以该设备为载体（`carrier_type=device`）的 `TaskTypePackageFirstActivation` 任务。
|
||||
|
||||
**设计约束**：
|
||||
- 若卡未绑定任何设备（`GetActiveBindingByCardID` 返回 `ErrRecordNotFound`）则静默跳过，不报错
|
||||
- 提交任务失败记录 Warn 日志，不阻塞卡级激活流程
|
||||
- 任务幂等：`ActivateByRealname(ctx, "device", deviceID)` 若查不到 `pending_realname_activation=true` 的套餐则直接返回 nil
|
||||
|
||||
#### Scenario: 设备下某张卡首次实名——同时触发设备级套餐激活与复机
|
||||
- **GIVEN** IoT 卡 ID=4，绑定于设备 ID=2（`tb_device_sim_binding` 中存在有效绑定）
|
||||
- **AND** 设备 ID=2 存在 `status=0, pending_realname_activation=true` 的设备级 PackageUsage
|
||||
- **AND** 设备下有卡因 `not_realname` 停机（`stop_reason=not_realname`）
|
||||
- **WHEN** 轮询系统检测到卡 ID=4 实名状态 0→1
|
||||
- **THEN** 系统提交两个 Asynq 任务：
|
||||
1. `carrier_type=iot_card, carrier_id=4`（卡级激活）
|
||||
2. `carrier_type=device, carrier_id=2`（设备级激活）
|
||||
- **AND** 设备级 PackageUsage 最终 `status=1, pending_realname_activation=false, activated_at` 已设置
|
||||
- **AND** `ActivateByRealname` 激活成功后异步调用 `ResumeCardIfStopped("device", 2)`，设备下已实名的停机卡自动开机
|
||||
|
||||
#### Scenario: 独立卡（未绑定设备）首次实名——仅触发卡级激活
|
||||
- **GIVEN** IoT 卡 ID=10，未绑定任何设备（`tb_device_sim_binding` 中无有效记录）
|
||||
- **WHEN** 轮询系统检测到卡 ID=10 实名状态 0→1
|
||||
- **THEN** 系统仅提交卡级 Asynq 任务（`carrier_type=iot_card, carrier_id=10`）
|
||||
- **AND** 不报错，不记录 Error 日志
|
||||
|
||||
#### Scenario: 设备下某张卡实名但设备无待激活套餐——任务执行幂等返回
|
||||
- **GIVEN** IoT 卡 ID=4，绑定于设备 ID=2
|
||||
- **AND** 设备 ID=2 无 `pending_realname_activation=true` 的套餐
|
||||
- **WHEN** 轮询系统检测到卡 ID=4 实名状态 0→1，并提交设备级激活任务
|
||||
- **THEN** 任务 Worker 执行 `ActivateByRealname(ctx, "device", 2)`，查询结果为空，直接返回 nil（无错误）
|
||||
@@ -0,0 +1,69 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: polling_realname_handler.go——实名数据采集
|
||||
|
||||
**文件**：`internal/task/polling_realname_handler.go`（< 220行）
|
||||
|
||||
**构造函数依赖**（通过构造函数注入，禁止全局变量）：
|
||||
```go
|
||||
func NewPollingRealnameHandler(
|
||||
base *PollingBase,
|
||||
gateway *gateway.Client,
|
||||
iotCardStore *postgres.IotCardStore,
|
||||
asynqClient *asynq.Client,
|
||||
stopResumeSvc iot_card_svc.StopResumeServiceInterface,
|
||||
deviceSimBindingStore *postgres.DeviceSimBindingStore, // 新增：用于查询卡所属设备
|
||||
) *PollingRealnameHandler
|
||||
```
|
||||
|
||||
**方法列表**：
|
||||
- `Handle(ctx, task) error`：Asynq 任务入口
|
||||
- `triggerFirstRealnameActivation(ctx, cardID)`：提交卡级首次实名激活任务（已有，不变）
|
||||
- `triggerDeviceRealnameActivation(ctx, cardID)`：**新增**，查询卡所属设备并提交设备级激活任务
|
||||
|
||||
**处理流程（0→1 路径新增步骤）**：
|
||||
1. 调 `base.acquireConcurrency("realname")`，获取失败则 requeue 后返回
|
||||
2. 调 `base.getCardWithCache(ctx, cardID)` 获取卡信息
|
||||
3. 调 Gateway 查询实名状态
|
||||
4. 写 Store（更新 `real_name_status`、`last_real_name_check_at`，首次实名时写 `first_realname_at`）
|
||||
5. 若实名状态变为已实名（0→1）：
|
||||
a. 调 `triggerFirstRealnameActivation(ctx, cardID)` — 提交卡级激活任务
|
||||
b. **调 `triggerDeviceRealnameActivation(ctx, cardID)` — 提交设备级激活任务（新增）**
|
||||
c. 调 `stopResumeService.EvaluateAndAct(ctx, freshCard)` — 触发复机判断
|
||||
6. 调 `base.requeueCard(ctx, cardID, "realname")` 重新入队
|
||||
7. 调 `base.releaseConcurrency("realname")`
|
||||
|
||||
#### Scenario: 实名状态由未实名变为已实名——同时触发卡级和设备级激活
|
||||
- **GIVEN** cardID=4，`real_name_status=0`，该卡通过 `tb_device_sim_binding` 绑定于设备 ID=2
|
||||
- **WHEN** Gateway 返回实名已完成，Handler 检测到 0→1 变化
|
||||
- **THEN** Store 更新 `real_name_status=1, first_realname_at=NOW()`
|
||||
- **AND** 提交卡级 Asynq 任务（`carrier_type=iot_card, carrier_id=4`）
|
||||
- **AND** 提交设备级 Asynq 任务（`carrier_type=device, carrier_id=2`）
|
||||
- **AND** 调用 `EvaluateAndAct` 触发复机评估
|
||||
|
||||
#### Scenario: 独立卡实名——仅触发卡级激活
|
||||
- **GIVEN** cardID=10，`real_name_status=0`，未绑定任何设备
|
||||
- **WHEN** Gateway 返回实名已完成，Handler 检测到 0→1 变化
|
||||
- **THEN** 提交卡级 Asynq 任务（`carrier_type=iot_card, carrier_id=10`）
|
||||
- **AND** `triggerDeviceRealnameActivation` 调用 `GetActiveBindingByCardID` 返回 not found，静默跳过，不报错
|
||||
|
||||
#### Scenario: 实名状态未变化——不触发任何激活
|
||||
- **GIVEN** cardID=200，`real_name_status=1`（已实名），Gateway 返回仍已实名
|
||||
- **WHEN** Handler 执行
|
||||
- **THEN** Store 不执行实名更新；不提交任何激活任务；按正常间隔 requeue
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: PollingRealnameHandler 注入 DeviceSimBindingStore
|
||||
|
||||
`PollingRealnameHandler` 结构体 SHALL 包含 `deviceSimBindingStore *postgres.DeviceSimBindingStore` 字段，由 `NewPollingRealnameHandler` 构造函数注入。`pkg/queue/handler.go` 的 `registerPollingHandlers` SHALL 将已可用的 `h.workerResult.Stores.DeviceSimBinding` 作为最后一个参数传入。
|
||||
|
||||
#### Scenario: Worker 启动时 DeviceSimBindingStore 正确注入
|
||||
- **WHEN** Worker 进程启动，调用 `registerPollingHandlers()`
|
||||
- **THEN** `NewPollingRealnameHandler` 接收 6 个参数，第 6 个为 `h.workerResult.Stores.DeviceSimBinding`
|
||||
- **AND** handler 的 `deviceSimBindingStore` 字段非 nil
|
||||
|
||||
#### Scenario: DeviceSimBindingStore 为 nil 时 triggerDeviceRealnameActivation 静默跳过
|
||||
- **GIVEN** handler 的 `deviceSimBindingStore` 为 nil（测试或未注入场景）
|
||||
- **WHEN** 调用 `triggerDeviceRealnameActivation`
|
||||
- **THEN** 函数立即返回，不 panic，不报错
|
||||
@@ -0,0 +1,89 @@
|
||||
## 1. 修复购买时实名状态检查（order/service.go）
|
||||
|
||||
- [x] 1.1 在 `activateMainPackage` 的 REALNAME-02 决策块中，扩展卡信息查询：将 `tx.Select("card_category")` 改为 `tx.Select("card_category", "real_name_status")`，并从结果读取 `currentlyRealnamed` 标志
|
||||
- [x] 1.2 在 REALNAME-02 决策块中，新增 `device` 载体的实名状态检查：当 `carrierType == "device"` 时，通过 GORM 子查询统计绑定卡（`bind_status=1`）中 `real_name_status=1` 的数量，`count > 0` 则 `currentlyRealnamed=true`；注意：使用 GORM 查询时软删除过滤（`deleted_at IS NULL`）由 GORM 自动注入，**不需要**手动添加 `.Where("deleted_at IS NULL")`
|
||||
- [x] 1.3 修改 `expiry_base != "from_purchase"` 分支的决策逻辑：若 `currentlyRealnamed=true` 则保持 `status=Active`（不切换为 pending），记录 Info 日志"购买时载体已实名，直接激活套餐"；若 `currentlyRealnamed=false` 则保持原有 `pending_realname_activation=true` 逻辑；**边界情况**：若 1.1 的卡查询失败（`err != nil`）或 1.2 的设备子查询出错，`currentlyRealnamed` 应保守默认为 `false`（走 pending 路径），不应阻断整个购买流程
|
||||
- [x] 1.4 运行 `lsp_diagnostics` 确认 `internal/service/order/service.go` 无编译错误
|
||||
|
||||
## 2. 扩展 PollingRealnameHandler（polling_realname_handler.go）
|
||||
|
||||
- [x] 2.1 在 `PollingRealnameHandler` 结构体中新增字段 `deviceSimBindingStore *postgres.DeviceSimBindingStore`
|
||||
- [x] 2.2 更新 `NewPollingRealnameHandler` 构造函数签名，在参数列表末尾新增 `deviceSimBindingStore *postgres.DeviceSimBindingStore`，并在函数体中赋值到结构体字段
|
||||
- [x] 2.3 新增 `triggerDeviceRealnameActivation(ctx context.Context, cardID uint)` 函数：调用 `h.deviceSimBindingStore.GetActiveBindingByCardID` 获取设备绑定；判断无绑定使用同包内已有的 `isNotFound(err)` 工具函数（定义于 `internal/task/polling_utils.go`），命中则静默返回；若有绑定则提交 `carrier_type="device", carrier_id=binding.DeviceID` 的 `TaskTypePackageFirstActivation` Asynq 任务（与卡级任务相同的 MaxRetry/Timeout/Queue 配置，参照 `triggerFirstRealnameActivation` 实现）；任务提交失败记录 Warn 日志，日志字段需同时包含 `card_id` 和 `device_id` 以便关联排查，不中断流程
|
||||
- [x] 2.4 在 `isFirstRealname` 分支中，在调用 `triggerFirstRealnameActivation` 之后追加调用 `triggerDeviceRealnameActivation(ctx, cardID)`
|
||||
- [x] 2.5 运行 `lsp_diagnostics` 确认 `internal/task/polling_realname_handler.go` 无编译错误
|
||||
|
||||
## 3. 更新 Worker 构造调用（pkg/queue/handler.go）
|
||||
|
||||
- [x] 3.1 在 `registerPollingHandlers` 中，将 `task.NewPollingRealnameHandler(...)` 调用末尾追加参数 `h.workerResult.Stores.DeviceSimBinding`
|
||||
- [x] 3.2 运行 `lsp_diagnostics` 确认 `pkg/queue/handler.go` 无编译错误
|
||||
|
||||
## 4. 整体编译验证与存量修复
|
||||
|
||||
- [x] 4.1 执行 `go build ./...` 确认整个项目编译通过，零错误零警告
|
||||
- [x] 4.2 通过 psql 或任意数据库客户端手动执行存量修复，分三步：
|
||||
|
||||
**步骤 0 — 确认受影响范围（只读，先跑）**
|
||||
```sql
|
||||
SELECT pu.id, pu.device_id, pu.iot_card_id,
|
||||
p.calendar_type, p.duration_months, p.duration_days, p.data_reset_cycle
|
||||
FROM tb_package_usage pu
|
||||
JOIN tb_package p ON p.id = pu.package_id
|
||||
WHERE pu.status = 0 AND pu.pending_realname_activation = true;
|
||||
```
|
||||
预期：仅返回 `id=1`（device_id=2，natural_month，12 个月，monthly 重置）。若有其他记录，核实后再执行步骤 1。
|
||||
|
||||
**步骤 1 — 批量修复（写操作，建议在事务中执行）**
|
||||
```sql
|
||||
BEGIN;
|
||||
|
||||
UPDATE tb_package_usage pu
|
||||
SET
|
||||
status = 1,
|
||||
pending_realname_activation = false,
|
||||
activated_at = NOW(),
|
||||
expires_at = CASE p.calendar_type
|
||||
WHEN 'natural_month' THEN
|
||||
DATE_TRUNC('month', NOW())
|
||||
+ ((p.duration_months + 1)::text || ' months')::interval
|
||||
- INTERVAL '1 second'
|
||||
ELSE
|
||||
DATE_TRUNC('day', NOW())
|
||||
+ (p.duration_days::text || ' days')::interval
|
||||
+ INTERVAL '86399 seconds'
|
||||
END,
|
||||
next_reset_at = CASE p.data_reset_cycle
|
||||
WHEN 'monthly' THEN
|
||||
CASE p.calendar_type
|
||||
WHEN 'natural_month' THEN DATE_TRUNC('month', NOW()) + INTERVAL '1 month'
|
||||
ELSE DATE_TRUNC('day', NOW()) + INTERVAL '30 days'
|
||||
END
|
||||
WHEN 'daily' THEN DATE_TRUNC('day', NOW()) + INTERVAL '1 day'
|
||||
WHEN 'yearly' THEN DATE_TRUNC('year', NOW() + INTERVAL '1 year')
|
||||
ELSE NULL
|
||||
END,
|
||||
updated_at = NOW()
|
||||
FROM tb_package p
|
||||
WHERE pu.package_id = p.id
|
||||
AND pu.status = 0
|
||||
AND pu.pending_realname_activation = true
|
||||
AND pu.device_id > 0
|
||||
AND pu.device_id IN (
|
||||
SELECT DISTINCT dsb.device_id
|
||||
FROM tb_device_sim_binding dsb
|
||||
JOIN tb_iot_card ic ON ic.id = dsb.iot_card_id
|
||||
WHERE dsb.bind_status = 1 AND dsb.deleted_at IS NULL
|
||||
AND ic.real_name_status = 1 AND ic.deleted_at IS NULL
|
||||
);
|
||||
|
||||
-- 确认影响行数为预期值后再 COMMIT，否则 ROLLBACK
|
||||
COMMIT;
|
||||
```
|
||||
|
||||
**步骤 2 — 验证结果**
|
||||
```sql
|
||||
SELECT id, status, pending_realname_activation, activated_at, expires_at, next_reset_at
|
||||
FROM tb_package_usage
|
||||
WHERE id = 1;
|
||||
```
|
||||
预期：`status=1`，`pending_realname_activation=false`，`expires_at` 为当月 +12 个月月末 23:59:59，`next_reset_at` 为下月 1 日 00:00:00。
|
||||
Reference in New Issue
Block a user