feat(v2): 对账主体——周期查单收敛 + 已付订单抽查 + 退款修复扫描/卡滞告警 + main 装配 reconcile Runner

Task 5(债务 #6):两条腿收敛对账——① SyncPendingTask 调度 P2 gateway.SyncPendingAttempts
逐 pending attempt 查单收敛(防掉单);② PaidSpotCheckTask 对近期已付 attempt 反查渠道
核对金额/币种,漂移(渠道侧已退款/拒付而本地仍 paid)只告警不改状态。

追加两条 P4 T3 opus review 义务(该 review 产出时本 worktree 已分叉,P4 退款主体在主
checkout;这里对本 worktree 已有的 store.RefundStore/OrderStore 接口——P4 T2,在 base
里——建自愈扫描,设计为可在合并 P4 后继续工作):
- RefundApplyTask:退款修复扫描,重算 succeeded 退款之和,自愈「退款成功但订单卡 paid」
  的崩溃窗口(MarkRefundStatus 翻 succeeded 后、ApplyRefundToOrder 调用前崩溃)。候选订单
  =有 succeeded 退款的订单 ∪ 当前处于 refunding/partially_refunded 态的订单;走既有
  ApplyRefundToOrder 条件 UPDATE,目标态与当前态一致时跳过,天然幂等。
- RefundStuckAlertTask:卡滞 processing/manual_pending 退款超阈值(默认 30min)打 WARN,
  只观测不改状态;渠道退款查询 API 面留待后续。

main 装配前 4 job(order-expire/usage-refresh/sync-pending/paid-spotcheck)+ 上述两个退款
job 挂上 reconcile.Runner;acctPicker 的 limit_aware 用量源改用 reconcile.NewUsageSource
替 NopUsage。crypto 冷启动 Warm/孤儿扫描(AddCryptoJobs)留给 Task 6 追加。

config.go 新增 ReconcileConfig(含 Task 6 预留的 orphan_* 字段)+ 默认值;crypto.go 补
SetReservationLoader 构造后注入 setter(Task 6 依赖)。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013nMthbVEmQquxBRKb9Fj8u
This commit is contained in:
wangjia
2026-07-10 17:45:01 +08:00
parent 4ac4e6ca9f
commit 04c3f4f31a
11 changed files with 678 additions and 2 deletions
+119
View File
@@ -0,0 +1,119 @@
package reconcile
import (
"context"
"log"
"time"
"github.com/wangjia/pay/internal/model"
"github.com/wangjia/pay/internal/store"
)
// RefundApplyTask 是「RefundApply 修复扫描」:P4 T3 opus review 追加的义务(P4 退款
// 代码本体在主 checkout,未落到本 worktree;此处只对本 worktree 已有的
// store.RefundStore/OrderStore 接口(P4 T2,在 base 里)建自愈扫描,设计为能在合并
// P4 后继续工作)。
//
// 动机:退款成功的崩溃窗口 —— RefundStore.MarkRefundStatus 把某笔退款翻成
// succeeded 后,调用方在再调 OrderStore.ApplyRefundToOrder 前进程崩溃/网络抖动,
// 订单状态卡在 paid(或旧的 partially_refunded),与「已实际退款成功」的事实脱节。
// 本任务周期重算每个候选订单的 succeeded 退款之和,按既有 ApplyRefundToOrder 的
// 条件 UPDATE 语义重新 apply 一次 —— 状态已一致时 UPDATE 影响 0 行,天然幂等。
//
// 候选订单 = distinct(有 succeeded 退款的订单) (当前处于 refunding/partially_refunded
// 态的订单):前者直接命中"退款成功但订单未跟上"的崩溃窗口;后者兜住"已在退款流程
// 中、但后续又有退款 succeeded 未被重算"的情形。
func RefundApplyTask(orders *store.OrderStore, refunds *store.RefundStore, limit int) func(ctx context.Context) error {
return func(ctx context.Context) error {
succeededNos, err := refunds.ListDistinctOutTradeNosByStatus(model.RefundSucceeded, limit)
if err != nil {
return err
}
refundingOrders, err := orders.ListOrdersByStatus(
[]model.OrderStatusV2{model.OrderRefundingV2, model.OrderPartRefundedV2}, limit)
if err != nil {
return err
}
seen := make(map[string]bool, len(succeededNos)+len(refundingOrders))
candidates := make([]string, 0, len(succeededNos)+len(refundingOrders))
for _, no := range succeededNos {
if !seen[no] {
seen[no] = true
candidates = append(candidates, no)
}
}
for i := range refundingOrders {
no := refundingOrders[i].OutTradeNo
if !seen[no] {
seen[no] = true
candidates = append(candidates, no)
}
}
for _, no := range candidates {
if err := reapplyRefundState(orders, refunds, no); err != nil {
log.Printf("[reconcile] 退款修复扫描 out_trade_no=%s: %v", no, err)
}
}
return nil
}
}
// reapplyRefundState 对单个订单重算 succeeded 退款之和并按需重新 apply 状态转移。
// 只有目标态与当前态不同才真正调用 ApplyRefundToOrder(避免每轮扫描都打"翻转"日志噪声);
// 没有 succeeded 退款(sum==0)的订单跳过 —— 它不属于本扫描要修的窗口。
func reapplyRefundState(orders *store.OrderStore, refunds *store.RefundStore, outTradeNo string) error {
succ, err := refunds.RefundSum(outTradeNo, model.RefundSucceeded)
if err != nil {
return err
}
if succ <= 0 {
return nil
}
o, err := orders.GetOrder(outTradeNo)
if err != nil {
return err
}
fully := succ >= o.AmountMinor
next := model.OrderPartRefundedV2
if fully {
next = model.OrderRefundedV2
}
if o.Status == next {
return nil // 已一致,无需自愈
}
flipped, err := orders.ApplyRefundToOrder(outTradeNo, fully)
if err != nil {
return err
}
if flipped {
log.Printf("[reconcile][退款自愈] out_trade_no=%s 本地曾卡于 %s,succeeded 退款 %d/%d → 重新 apply 为 %s",
outTradeNo, o.Status, succ, o.AmountMinor, next)
}
return nil
}
// RefundStuckAlertTask 是「卡滞 processing/manual_pending 退款告警」义务:同 sweep
// 家族的姊妹任务,只读观测 —— 只打 WARN,绝不改状态(状态机翻转是
// RefundApplyTask/业务方的事)。渠道退款查询 API 面(主动向渠道问退款进度)留待后续;
// 这里先用「本地卡滞时长」兜底可见性。
func RefundStuckAlertTask(refunds *store.RefundStore, threshold time.Duration, now func() time.Time) func(ctx context.Context) error {
return func(ctx context.Context) error {
cutoff := now().Add(-threshold)
stuck, err := refunds.ListStuckRefunds(
[]model.RefundStatus{model.RefundProcessing, model.RefundManualPending}, cutoff, 200)
if err != nil {
return err
}
for i := range stuck {
r := &stuck[i]
log.Printf("[reconcile][WARN][退款卡滞] refund_id=%s out_trade_no=%s status=%s 已卡滞 %s(阈值 %s)——"+
"仅观测告警不改状态;渠道退款查询 API 面留待后续",
r.RefundID, r.OutTradeNo, r.Status, now().Sub(r.UpdatedAt).Round(time.Minute), threshold)
}
return nil
}
}
+189
View File
@@ -0,0 +1,189 @@
package reconcile_test
import (
"bytes"
"context"
"log"
"strings"
"testing"
"time"
"github.com/wangjia/pay/internal/model"
"github.com/wangjia/pay/internal/reconcile"
"github.com/wangjia/pay/internal/store"
)
// TestRefundApplyTaskSelfHealsStuckPaidOrder 钉住 P4 T3 review 的崩溃窗口:
// MarkRefundStatus 把退款翻成 succeeded 后、调用方在调 ApplyRefundToOrder 前崩溃,
// 订单卡在 paid。RefundApplyTask 应重算 succeeded 之和并重新 apply,自愈成
// refunded(全额)。
func TestRefundApplyTaskSelfHealsStuckPaidOrder(t *testing.T) {
db := model.OpenTestDB(t)
orders := store.NewOrderStore(db)
refunds := store.NewRefundStore(db)
if err := orders.CreateOrder(&model.OrderV2{OutTradeNo: "STUCK-1", AmountMinor: 10000, Currency: "CNY", Status: model.OrderPaidV2}); err != nil {
t.Fatal(err)
}
if err := refunds.CreateRefund(&model.Refund{RefundID: "rf-stuck-1", OutTradeNo: "STUCK-1", AttemptProviderRef: "STUCK-1",
AmountMinor: 10000, Currency: "CNY", Status: model.RefundSucceeded, InitiatedBy: "business"}); err != nil {
t.Fatal(err)
}
task := reconcile.RefundApplyTask(orders, refunds, 200)
if err := task(context.Background()); err != nil {
t.Fatalf("task: %v", err)
}
o, err := orders.GetOrder("STUCK-1")
if err != nil || o.Status != model.OrderRefundedV2 {
t.Fatalf("应自愈为 refunded, got %+v, err=%v", o, err)
}
}
// TestRefundApplyTaskPartialStaysPartial 部分退款(succeeded 之和 < 订单金额)应自愈为
// partially_refunded,而非误判 fully。
func TestRefundApplyTaskPartialStaysPartial(t *testing.T) {
db := model.OpenTestDB(t)
orders := store.NewOrderStore(db)
refunds := store.NewRefundStore(db)
if err := orders.CreateOrder(&model.OrderV2{OutTradeNo: "STUCK-2", AmountMinor: 10000, Currency: "CNY", Status: model.OrderPaidV2}); err != nil {
t.Fatal(err)
}
if err := refunds.CreateRefund(&model.Refund{RefundID: "rf-stuck-2", OutTradeNo: "STUCK-2", AttemptProviderRef: "STUCK-2",
AmountMinor: 4000, Currency: "CNY", Status: model.RefundSucceeded, InitiatedBy: "business"}); err != nil {
t.Fatal(err)
}
task := reconcile.RefundApplyTask(orders, refunds, 200)
if err := task(context.Background()); err != nil {
t.Fatalf("task: %v", err)
}
o, err := orders.GetOrder("STUCK-2")
if err != nil || o.Status != model.OrderPartRefundedV2 {
t.Fatalf("应自愈为 partially_refunded, got %+v, err=%v", o, err)
}
}
// TestRefundApplyTaskIdempotentNoOpOnRerun 幂等:自愈一次后重跑不应报错、不应再次
// "翻转"(状态已一致,ApplyRefundToOrder 不应被重复触发出错误的副作用)。
func TestRefundApplyTaskIdempotentNoOpOnRerun(t *testing.T) {
db := model.OpenTestDB(t)
orders := store.NewOrderStore(db)
refunds := store.NewRefundStore(db)
if err := orders.CreateOrder(&model.OrderV2{OutTradeNo: "STUCK-3", AmountMinor: 5000, Currency: "CNY", Status: model.OrderPaidV2}); err != nil {
t.Fatal(err)
}
if err := refunds.CreateRefund(&model.Refund{RefundID: "rf-stuck-3", OutTradeNo: "STUCK-3", AttemptProviderRef: "STUCK-3",
AmountMinor: 5000, Currency: "CNY", Status: model.RefundSucceeded, InitiatedBy: "business"}); err != nil {
t.Fatal(err)
}
task := reconcile.RefundApplyTask(orders, refunds, 200)
for i := 0; i < 3; i++ {
if err := task(context.Background()); err != nil {
t.Fatalf("run %d: %v", i, err)
}
}
o, err := orders.GetOrder("STUCK-3")
if err != nil || o.Status != model.OrderRefundedV2 {
t.Fatalf("重跑后仍应 refunded, got %+v, err=%v", o, err)
}
}
// TestRefundApplyTaskConsistentOrderUntouched 已一致(无 succeeded 退款,或订单已是
// 该退款对应的终态)的订单不应被误触发。
func TestRefundApplyTaskConsistentOrderUntouched(t *testing.T) {
db := model.OpenTestDB(t)
orders := store.NewOrderStore(db)
refunds := store.NewRefundStore(db)
if err := orders.CreateOrder(&model.OrderV2{OutTradeNo: "OK-1", AmountMinor: 1000, Currency: "CNY", Status: model.OrderPaidV2}); err != nil {
t.Fatal(err)
}
// 有一笔 processing(未 succeeded)退款,不该触发自愈。
if err := refunds.CreateRefund(&model.Refund{RefundID: "rf-ok-1", OutTradeNo: "OK-1", AttemptProviderRef: "OK-1",
AmountMinor: 500, Currency: "CNY", Status: model.RefundProcessing, InitiatedBy: "business"}); err != nil {
t.Fatal(err)
}
task := reconcile.RefundApplyTask(orders, refunds, 200)
if err := task(context.Background()); err != nil {
t.Fatalf("task: %v", err)
}
o, err := orders.GetOrder("OK-1")
if err != nil || o.Status != model.OrderPaidV2 {
t.Fatalf("无 succeeded 退款不应被翻转, got %+v, err=%v", o, err)
}
}
// TestRefundStuckAlertTaskLogsWarnWithoutChangingState 卡滞 processing/manual_pending
// 超阈值只应打 WARN 日志,不改任何状态(观测型)。
func TestRefundStuckAlertTaskLogsWarnWithoutChangingState(t *testing.T) {
db := model.OpenTestDB(t)
refunds := store.NewRefundStore(db)
now := time.Date(2026, 7, 10, 12, 0, 0, 0, time.UTC)
if err := refunds.CreateRefund(&model.Refund{RefundID: "rf-stall-1", OutTradeNo: "STALL-1",
AmountMinor: 100, Currency: "CNY", Status: model.RefundProcessing}); err != nil {
t.Fatal(err)
}
if err := db.Model(&model.Refund{}).Where("refund_id = ?", "rf-stall-1").
Update("updated_at", now.Add(-45*time.Minute)).Error; err != nil {
t.Fatal(err)
}
var buf bytes.Buffer
orig := log.Writer()
log.SetOutput(&buf)
defer log.SetOutput(orig)
task := reconcile.RefundStuckAlertTask(refunds, 30*time.Minute, func() time.Time { return now })
if err := task(context.Background()); err != nil {
t.Fatalf("task: %v", err)
}
if !strings.Contains(buf.String(), "rf-stall-1") || !strings.Contains(buf.String(), "WARN") {
t.Fatalf("应打 WARN 日志含 refund_id, got: %s", buf.String())
}
r, err := refunds.GetRefund("rf-stall-1")
if err != nil || r.Status != model.RefundProcessing {
t.Fatalf("告警不应改状态, got %+v, err=%v", r, err)
}
}
// TestRefundStuckAlertTaskSkipsFreshAndTerminal 未超阈值 / 已终态的退款不应被告警。
func TestRefundStuckAlertTaskSkipsFreshAndTerminal(t *testing.T) {
db := model.OpenTestDB(t)
refunds := store.NewRefundStore(db)
now := time.Date(2026, 7, 10, 12, 0, 0, 0, time.UTC)
if err := refunds.CreateRefund(&model.Refund{RefundID: "rf-fresh", OutTradeNo: "FRESH-1",
AmountMinor: 100, Currency: "CNY", Status: model.RefundProcessing}); err != nil {
t.Fatal(err)
}
if err := refunds.CreateRefund(&model.Refund{RefundID: "rf-done", OutTradeNo: "DONE-1",
AmountMinor: 100, Currency: "CNY", Status: model.RefundSucceeded}); err != nil {
t.Fatal(err)
}
if err := db.Model(&model.Refund{}).Where("refund_id = ?", "rf-done").
Update("updated_at", now.Add(-2*time.Hour)).Error; err != nil {
t.Fatal(err)
}
var buf bytes.Buffer
orig := log.Writer()
log.SetOutput(&buf)
defer log.SetOutput(orig)
task := reconcile.RefundStuckAlertTask(refunds, 30*time.Minute, func() time.Time { return now })
if err := task(context.Background()); err != nil {
t.Fatalf("task: %v", err)
}
if strings.Contains(buf.String(), "rf-fresh") || strings.Contains(buf.String(), "rf-done") {
t.Fatalf("未超阈值/已终态不应告警, got: %s", buf.String())
}
}
+59
View File
@@ -0,0 +1,59 @@
package reconcile
import (
"context"
"log"
"time"
"github.com/wangjia/pay/internal/gateway"
"github.com/wangjia/pay/internal/provider"
"github.com/wangjia/pay/internal/store"
)
// SyncPendingTask 调度 P2 gateway.SyncPendingAttempts:逐 pending attempt 查单收敛(防掉单)。
// 其内部已对 not_found/amount_mismatch/failed 打日志(settle-sync,764ed55),此处不重复。
func SyncPendingTask(gw *gateway.Gateway, limit int) func(ctx context.Context) error {
return func(ctx context.Context) error {
n, err := gw.SyncPendingAttempts(ctx, limit)
if err != nil {
return err
}
if n > 0 {
log.Printf("[reconcile] 查单对账收敛 %d 笔待支付 → paid", n)
}
return nil
}
}
// PaidSpotCheckTask 已付订单抽查:对近 window 内已付 attempt 反查渠道,金额/币种漂移即告警
// (如渠道侧已退款/拒付而本地仍 paid)。只发现不改状态——状态机翻转属 P4。
// crypto 之类 query-only 渠道:paid 后再查若命中同额即一致;查不到(链上历史滚出窗口)不报错跳过。
func PaidSpotCheckTask(orders *store.OrderStore, providers *provider.Registry, window time.Duration, now func() time.Time) func(ctx context.Context) error {
return func(ctx context.Context) error {
atts, err := orders.ListRecentlyPaidAttempts(now().Add(-window), 100)
if err != nil {
return err
}
for i := range atts {
a := &atts[i]
prov, err := providers.Get(a.Channel)
if err != nil {
continue
}
created := a.CreatedAt
ev, err := prov.Query(ctx, provider.QueryRequest{
ProviderRef: a.ProviderRef, OutTradeNo: a.OutTradeNo, AccountID: a.AccountID,
AmountMinor: a.AmountMinor, Currency: a.Currency, CreatedAt: created, ExpiresAt: a.ExpiresAt,
})
if err != nil || ev == nil {
continue // 查不到/瞬时错:抽查尽力而为,不阻断
}
// 本地 paid,渠道却报非成功,或金额/币种对不上 → 对账差异,必须可见。
if ev.Status != provider.PaidSucceeded || ev.PaidCurrency != a.Currency || ev.PaidAmountMinor < a.AmountMinor {
log.Printf("[reconcile][对账差异] attempt=%s channel=%s 本地 paid 但渠道 status=%s amount=%d/%s(本地 %d/%s)",
a.ProviderRef, a.Channel, ev.Status, ev.PaidAmountMinor, ev.PaidCurrency, a.AmountMinor, a.Currency)
}
}
return nil
}
}
+72
View File
@@ -0,0 +1,72 @@
package reconcile_test
import (
"context"
"testing"
"time"
"github.com/wangjia/pay/config"
"github.com/wangjia/pay/internal/accounts"
"github.com/wangjia/pay/internal/gateway"
"github.com/wangjia/pay/internal/model"
"github.com/wangjia/pay/internal/provider"
"github.com/wangjia/pay/internal/provider/fake"
"github.com/wangjia/pay/internal/reconcile"
"github.com/wangjia/pay/internal/store"
)
type stubResolver struct{}
func (stubResolver) Resolve(sku, currency string) (int64, string, string, error) {
return 29990000, "Pro", "pro_year", nil
}
type nopEnq struct{}
// Enqueue 签名依当前仓库 gateway.WebhookEnqueuer(4 个 string + map;brief 草稿只写 3 个 —
// P4 T2 之后加了 refundID 参数,此处适配现状,见 task-5-report.md 记录的漂移)。
func (nopEnq) Enqueue(_, _, _, _ string, _ map[string]any) error { return nil }
func TestSyncPendingTaskSettlesViaQuery(t *testing.T) {
db := model.OpenTestDB(t)
orders := store.NewOrderStore(db)
preg := provider.NewRegistry()
fp := fake.New()
preg.Register(fp)
areg := accounts.New([]config.AccountConfig{{AccountID: "fake-a1", Channel: "fake", Region: "global", Enabled: true}})
gw := gateway.New(orders, preg, accounts.NewRouter(areg, nil, nil), stubResolver{}, nopEnq{}, "global")
res, _ := gw.CreateOrder(context.Background(), gateway.CreateOrderInput{SKU: "pro_year", Method: "fake", BizSystem: "pangolin", BizRef: "u-1"})
atts, _ := orders.ListAttemptsByStatus(model.AttemptPending, 10)
fp.SetQueryResult(atts[0].ProviderRef, provider.PaidEvent{
ProviderRef: atts[0].ProviderRef, Status: provider.PaidSucceeded, PaidAmountMinor: 29990000, PaidCurrency: "USDT"})
task := reconcile.SyncPendingTask(gw, 50)
if err := task(context.Background()); err != nil {
t.Fatalf("task: %v", err)
}
o, _ := orders.GetOrder(res.OrderNo)
if o.Status != model.OrderPaidV2 {
t.Fatalf("查单对账后应 paid, got %v", o.Status)
}
_ = time.Second
}
func TestPaidSpotCheckTaskRunsCleanOnConsistent(t *testing.T) {
db := model.OpenTestDB(t)
orders := store.NewOrderStore(db)
preg := provider.NewRegistry()
fp := fake.New()
preg.Register(fp)
now := time.Date(2026, 7, 10, 12, 0, 0, 0, time.UTC)
paid := now.Add(-10 * time.Minute)
_ = orders.CreateAttempt(&model.Attempt{OutTradeNo: "O1", Channel: "fake", ProviderRef: "R-O1",
AmountMinor: 100, Currency: "USDT", Status: model.AttemptPaid, PaidAt: &paid})
// 渠道侧查单仍报 succeeded 同额 → 一致,无告警。
fp.SetQueryResult("R-O1", provider.PaidEvent{ProviderRef: "R-O1", Status: provider.PaidSucceeded, PaidAmountMinor: 100, PaidCurrency: "USDT"})
task := reconcile.PaidSpotCheckTask(orders, preg, time.Hour, func() time.Time { return now })
if err := task(context.Background()); err != nil {
t.Fatalf("spotcheck: %v", err) // 只求不报错、不 panic;漂移检测走日志
}
}