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 需求已完成
2026-03-27 23:33:47 +08:00
parent 030425be33
commit dbeed92ed9
4 changed files with 144 additions and 11 deletions
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -13,8 +13,8 @@
 - [x] **CRITICAL-01**: 实名状态常量统一 — `parseRealnameStatus` 写入值 2 改为常量 1，Model 注释统一，全链路使用 `constants.RealNameStatusVerified`
 - [x] **CRITICAL-02**: C 端实名校验修复 — `client_order/service.go` 实名判断改用 `constants.RealNameStatusVerified`（依赖 CRITICAL-01）
 - [x] **CRITICAL-03**: 实名激活任务断链修复 — `PollingHandler` 注入 `asynq.Client`，删除 RPush 降级方案，改用 `asynq.Client.EnqueueContext()`
- [ ] **CRITICAL-04**: 充值回调后自动购包触发 — `recharge/service.go` 在 HandlePaymentCallback 成功后入队 `TaskTypeAutoPurchaseAfterRecharge`；注册 `AutoPurchaseHandler`
- [ ] **CRITICAL-05**: 自动购包佣金链补全 — `AutoPurchaseHandler.ProcessTask()` 事务提交成功后入队 `TaskTypeCommission`
+- [x] **CRITICAL-04**: 充值回调后自动购包触发 — `recharge/service.go` 在 HandlePaymentCallback 成功后入队 `TaskTypeAutoPurchaseAfterRecharge`；注册 `AutoPurchaseHandler`
+- [x] **CRITICAL-05**: 自动购包佣金链补全 — `AutoPurchaseHandler.ProcessTask()` 事务提交成功后入队 `TaskTypeCommission`
 - [x] **CRITICAL-06**: 代购订单金额修正 — 场景 5（代理代购下级）`sellerCostPrice` 全部 6 处逐一审查，确保使用 `operatorCostPrice`（非 `buyerCostPrice`）
 - [x] **CRITICAL-07**: 设备导入补充 IMEI 字段 — `DeviceRow` 新增 IMEI，`ParseDeviceExcel` 列名映射新增 IMEI，`device_import.go` 导入时填充
 - [x] **CRITICAL-08**: 提现冻结并发校验 — `my_commission/service.go` 冻结余额后检查 `RowsAffected == 0`，余额不足并发场景返回错误而非静默继续
@@ -123,8 +123,8 @@
 | CRITICAL-01 | Phase 1 | Complete |
 | CRITICAL-02 | Phase 1 | Complete |
 | CRITICAL-03 | Phase 1 | Complete |
-| CRITICAL-04 | Phase 1 | Pending |
-| CRITICAL-05 | Phase 1 | Pending |
+| CRITICAL-04 | Phase 1 | Complete |
+| CRITICAL-05 | Phase 1 | Complete |
 | CRITICAL-06 | Phase 1 | Complete |
 | CRITICAL-07 | Phase 1 | Complete |
 | CRITICAL-08 | Phase 1 | Complete |
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -10,7 +10,7 @@

 ## Phases

- [ ] **Phase 1: P0 紧急修复** — 修复所有阻塞主链路的 P0 Bug，使充值→购包→佣金→实名激活全链路可跑通
+- [x] **Phase 1: P0 紧急修复** — 修复所有阻塞主链路的 P0 Bug，使充值→购包→佣金→实名激活全链路可跑通 (completed 2026-03-27)
 - [ ] **Phase 2: 权限/财务/实名/轮询修复** — 补全企业权限、提现财务流程、实名激活架构重构、轮询系统小修
 - [ ] **Phase 3: 设备体系完善** — 扩展设备模型字段、对接 Gateway sync-info、完善绑卡标识
 - [ ] **Phase 4: 退款 + 支付 + 运营修复** — 实现退款完整流程、补全富友支付接口、修复运营逻辑
@@ -36,7 +36,7 @@
 Plans:
 - [x] 01-01-PLAN.md — CRITICAL-01/02：实名状态常量统一 + C 端实名校验修复（Wave 1）
 - [x] 01-02-PLAN.md — CRITICAL-03：实名激活任务断链（PollingHandler 注入 asynqClient）（Wave 2）
- [ ] 01-03-PLAN.md — CRITICAL-04/05：充值回调触发自动购包 + 佣金链补全（Wave 2，parallel）
+- [x] 01-03-PLAN.md — CRITICAL-04/05：充值回调触发自动购包 + 佣金链补全（Wave 2，parallel）
 - [x] 01-04-PLAN.md — CRITICAL-06：代购订单 sellerCostPrice 6 处语义审查修正（Wave 1，parallel）
 - [x] 01-05-PLAN.md — CRITICAL-07/08：设备导入 IMEI + 提现冻结并发校验（Wave 1，parallel）

@@ -118,7 +118,7 @@ Plans:

 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
-| 1. P0 紧急修复 | 4/5 | In Progress|  |
+| 1. P0 紧急修复 | 5/5 | Complete   | 2026-03-27 |
 | 2. 权限/财务/实名/轮询修复 | 0/1 | Not started | - |
 | 3. 设备体系完善 | 0/1 | Not started | - |
 | 4. 退款 + 支付 + 运营修复 | 0/1 | Not started | - |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,12 +3,12 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: unknown
-last_updated: "2026-03-27T15:30:07.725Z"
+last_updated: "2026-03-27T15:33:12.355Z"
 progress:
  total_phases: 6
-  completed_phases: 0
+  completed_phases: 1
  total_plans: 5
-  completed_plans: 4
+  completed_plans: 5
 ---

 # Project State — 君鸿卡管系统
@@ -22,7 +22,7 @@ progress:
 ## Current Position

 Phase: 01 (p0) — EXECUTING
-Plan: 3 of 5
+Plan: 4 of 5
 | Field | Value |
 |-------|-------|
 | **Current Phase** | 1 — P0 紧急修复 |
@@ -75,6 +75,7 @@ Progress: [ 1 ]──[ 2 ]──[ 3 ]──[ 4 ]──[ 5 ]──[ 6 ]
 | Phase 01-p0 P01 | 15 | 2 tasks | 7 files |
 | Phase 01-p0 P04 | 4min | 1 tasks | 1 files |
 | Phase 01-p0 P02 | 3min | 1 tasks | 2 files |
+| Phase 01-p0 P03 | 8min | 2 tasks | 4 files |

 ## Accumulated Context

--- a/.planning/phases/01-p0/01-03-SUMMARY.md
+++ b/.planning/phases/01-p0/01-03-SUMMARY.md
@@ -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 ./...` 通过 ✓