docs(01-03): 完成充值回调自动购包链路修复 Plan 执行总结
- 创建 01-03-SUMMARY.md（CRITICAL-04 + CRITICAL-05 修复记录） - 更新 STATE.md（Plan 计数推进至 4/5，progress 100%） - 更新 ROADMAP.md（Phase 1 进度更新） - 标记 CRITICAL-04、CRITICAL-05 需求已完成
This commit is contained in:
132
.planning/phases/01-p0/01-03-SUMMARY.md
Normal file
132
.planning/phases/01-p0/01-03-SUMMARY.md
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
phase: 01-p0
|
||||
plan: 03
|
||||
subsystem: 充值回调链路 / 自动购包任务
|
||||
tags: [bug-fix, queue, asynq, recharge, commission, auto-purchase]
|
||||
dependency_graph:
|
||||
requires: [01-01]
|
||||
provides: [充值回调→自动购包入队, 自动购包→佣金任务入队, AutoPurchaseHandler注册]
|
||||
affects: [internal/service/recharge, internal/task, pkg/queue]
|
||||
tech_stack:
|
||||
added: []
|
||||
patterns: [asynq任务入队, 事务外触发异步任务, 依赖注入]
|
||||
key_files:
|
||||
created: []
|
||||
modified:
|
||||
- internal/service/recharge/service.go
|
||||
- internal/bootstrap/services.go
|
||||
- internal/task/auto_purchase.go
|
||||
- pkg/queue/handler.go
|
||||
decisions:
|
||||
- "佣金任务在事务提交成功后入队（事务外），防止任务提交后事务回滚引发数据一致性问题"
|
||||
- "自动购包入队失败不影响充值成功，仅记录 Error 日志"
|
||||
- "AutoPurchaseHandler 的 AssetRechargeStore / AssetWalletTransactionStore 传 nil，由 NewAutoPurchaseHandler 内部按需初始化"
|
||||
metrics:
|
||||
duration: "~8 分钟"
|
||||
completed_date: "2026-03-27"
|
||||
tasks: 2
|
||||
files_changed: 4
|
||||
---
|
||||
|
||||
# Phase 01 Plan 03: 充值回调触发自动购包 + 佣金链补全 Summary
|
||||
|
||||
打通完整链路：充值回调 → 自动购包任务入队 → 执行购包 → 佣金计算任务入队（CRITICAL-04 + CRITICAL-05）。
|
||||
|
||||
## Tasks Completed
|
||||
|
||||
| Task | Name | Commit | Files |
|
||||
|------|------|--------|-------|
|
||||
| 1 | recharge.Service 注入 queueClient，触发自动购包（CRITICAL-04 Part 1） | 9a4d87a | service/recharge/service.go, bootstrap/services.go |
|
||||
| 2 | AutoPurchaseHandler 注入 asynqClient + 注册 + 触发佣金（CRITICAL-04 Part 2 + CRITICAL-05） | 030425b | task/auto_purchase.go, pkg/queue/handler.go |
|
||||
|
||||
## Changes Summary
|
||||
|
||||
### Task 1 — CRITICAL-04 Part 1
|
||||
|
||||
**`internal/service/recharge/service.go`**
|
||||
- `Service` struct 新增字段：`queueClient *queue.Client`
|
||||
- `New()` 函数末尾新增参数：`queueClient *queue.Client`
|
||||
- `HandlePaymentCallback` 事务成功后，检查 `LinkedPackageIDs` 非空时，调用 `queueClient.EnqueueTask(TaskTypeAutoPurchaseAfterRecharge)`
|
||||
- 入队失败不影响充值成功，仅记录 Error 日志
|
||||
|
||||
**`internal/bootstrap/services.go`**
|
||||
- `rechargeSvc.New(...)` 末尾追加 `deps.QueueClient` 参数
|
||||
|
||||
### Task 2 — CRITICAL-04 Part 2 + CRITICAL-05
|
||||
|
||||
**`internal/task/auto_purchase.go`**
|
||||
- `AutoPurchaseHandler` struct 新增字段：`asynqClient *asynq.Client`
|
||||
- `NewAutoPurchaseHandler()` 在 `redisClient` 参数之后新增 `asynqClient *asynq.Client`
|
||||
- `ProcessTask` 事务前声明 `var createdOrderID uint`，事务内 `tx.Create(order)` 成功后赋值
|
||||
- 事务提交成功后（事务外）入队 `TaskTypeCommission`（QueueLow，MaxRetry=3）
|
||||
- 使用 `sonic.Marshal` 序列化（符合项目规范）
|
||||
- 入队失败仅 Warn 日志，不影响购包结果
|
||||
|
||||
**`pkg/queue/handler.go`**
|
||||
- `RegisterHandlers()` 末尾调用 `h.registerAutoPurchaseHandler()`
|
||||
- 新增方法 `registerAutoPurchaseHandler()`：
|
||||
- 调用 `task.NewAutoPurchaseHandler(...)` 传入 `h.asynqClient`
|
||||
- `h.mux.HandleFunc(TaskTypeAutoPurchaseAfterRecharge, ...)`
|
||||
|
||||
## 关键代码路径
|
||||
|
||||
```
|
||||
个人客户充值微信支付回调
|
||||
└─ recharge.HandlePaymentCallback()
|
||||
├─ 事务：更新状态、增加余额、触发一次性佣金
|
||||
└─ 事务成功后：
|
||||
└─ queueClient.EnqueueTask(TaskTypeAutoPurchaseAfterRecharge, {recharge_id})
|
||||
└─ Worker: AutoPurchaseHandler.ProcessTask()
|
||||
├─ 扣款、创建订单、激活套餐（事务内）
|
||||
└─ 事务成功后：
|
||||
└─ asynqClient.EnqueueContext(TaskTypeCommission, {order_id})
|
||||
└─ Worker: CommissionCalculationHandler.HandleCommissionCalculation()
|
||||
```
|
||||
|
||||
## Verification Results
|
||||
|
||||
```bash
|
||||
# 编译验证
|
||||
go build ./... → 通过，无错误
|
||||
|
||||
# 入队代码存在
|
||||
rg "TaskTypeAutoPurchaseAfterRecharge" internal/service/recharge/service.go
|
||||
→ s.queueClient.EnqueueTask(ctx, constants.TaskTypeAutoPurchaseAfterRecharge, ...)
|
||||
|
||||
rg "TaskTypeCommission" internal/task/auto_purchase.go
|
||||
→ asynq.NewTask(constants.TaskTypeCommission, ...)
|
||||
|
||||
# handler 注册
|
||||
rg "registerAutoPurchaseHandler|TaskTypeAutoPurchaseAfterRecharge" pkg/queue/handler.go
|
||||
→ h.registerAutoPurchaseHandler()
|
||||
→ h.mux.HandleFunc(constants.TaskTypeAutoPurchaseAfterRecharge, ...)
|
||||
|
||||
# bootstrap 传入 queueClient
|
||||
rg "rechargeSvc.New" internal/bootstrap/services.go
|
||||
→ rechargeSvc.New(..., deps.QueueClient)
|
||||
```
|
||||
|
||||
## CRITICAL Requirements Status
|
||||
|
||||
| 需求 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| CRITICAL-04 | ✅ 完成 | 充值回调后自动购包入队 + AutoPurchaseHandler 注册 |
|
||||
| CRITICAL-05 | ✅ 完成 | 自动购包成功后佣金链触发（事务外入队） |
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None — 按计划执行，无偏差。
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — 所有代码路径均已实现，无占位符。
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- [x] `internal/service/recharge/service.go` 存在 ✓
|
||||
- [x] `internal/bootstrap/services.go` 存在 ✓
|
||||
- [x] `internal/task/auto_purchase.go` 存在 ✓
|
||||
- [x] `pkg/queue/handler.go` 存在 ✓
|
||||
- [x] commit 9a4d87a 存在 ✓
|
||||
- [x] commit 030425b 存在 ✓
|
||||
- [x] `go build ./...` 通过 ✓
|
||||
Reference in New Issue
Block a user