From 85ce5aa6393d7201cc518ac2b70e9228ca6e216a Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Fri, 10 Jul 2026 10:20:42 +0800 Subject: [PATCH] =?UTF-8?q?docs(v2):=20P2=20=E8=AE=A1=E5=88=92=E6=8A=98?= =?UTF-8?q?=E5=85=A5=E8=AF=84=E5=AE=A1=E4=BF=AE=E8=AE=A2=20=E2=80=94=20D3?= =?UTF-8?q?=20=E8=B7=AF=E7=94=B1=E7=BB=9F=E4=B8=80=20/api/v2;D4=20settle?= =?UTF-8?q?=20=E5=B4=A9=E6=BA=83=E5=AE=89=E5=85=A8=E9=A1=BA=E5=BA=8F(?= =?UTF-8?q?=E5=85=88=E5=85=A5=E9=98=9F=E5=90=8E=E7=BF=BB=E8=BD=AC+?= =?UTF-8?q?=E6=8A=95=E9=80=92=E9=97=A8=E7=A6=81)/=20QueryRequest=20?= =?UTF-8?q?=E4=B8=8A=E4=B8=8B=E6=96=87=20/=20PaidEvent.PaidAt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_013nMthbVEmQquxBRKb9Fj8u --- docs/index.html | 4 +- docs/pay-v2-execution-overview.html | 18 +- docs/pay-v2-p2-plan.html | 28 +- .../plans/2026-07-10-pay-v2-p2-pipeline.md | 259 +++++++++++++----- 4 files changed, 221 insertions(+), 88 deletions(-) diff --git a/docs/index.html b/docs/index.html index 58cb60f..5594b1e 100644 --- a/docs/index.html +++ b/docs/index.html @@ -64,8 +64,8 @@
pay v2 · P2 收款管线 + Provider 抽象 + webhook v2(计划)
-
7 个 TDD 任务:Provider 接口(create/verify_callback/query)+6 render_type+PaidEvent+注册表 → fake provider → OrderStore 扩展 → 一次性收款管线 gateway → 统一入账/开通(复用 P1 MarkAttemptPaid 幂等)→ webhook v2 outbox+Notifier(event_type+HMAC)→ HTTP /v1 接线。复用 P1 全部类型、免 docker。/v1 与 v1 /api/v1 并存。
-
P2 · 2026-07-10 · 待执行 · 真相源 .md
+
7 个 TDD 任务:Provider 接口(create/verify_callback/query 带 QueryRequest 上下文)+6 render_type+PaidEvent(含 PaidAt)+注册表 → fake provider → OrderStore 扩展 → 一次性收款管线 gateway → 统一入账/开通(先幂等入队再幂等翻转,崩溃安全 + Notifier 已付门禁)→ webhook v2 outbox+Notifier(event_type+HMAC)→ HTTP /api/v2 接线(与旧版统一 /api 前缀,P3 后删 /api/v1 收口)。复用 P1 全部类型、免 docker。含 2026-07-10 评审修订(D3/D4)。
+
P2 · 2026-07-10 · 评审修订已折入 · 真相源 .md
pay v2 · P2-P8 依赖 DAG 与并行执行
diff --git a/docs/pay-v2-execution-overview.html b/docs/pay-v2-execution-overview.html index 9c4b023..a831084 100644 --- a/docs/pay-v2-execution-overview.html +++ b/docs/pay-v2-execution-overview.html @@ -97,9 +97,9 @@
  • fake provider(测试用)
  • OrderStore 扩展(GetOrder/AttemptByProviderRef…)
  • 一次性收款管线 gateway(建单/查单/重试/取消)
    • -
  • 统一入账/开通 settle(复用 P1 幂等标付)
    • -
  • webhook v2 outbox + Notifier(event_type + HMAC)
    • -
  • HTTP /v1 接线
    • +
  • 统一入账/开通 settle(先幂等入队再幂等翻转,崩溃安全)
    • +
  • webhook v2 outbox + Notifier(event_type + HMAC + 已付门禁)
    • +
  • HTTP /api/v2 接线(D3:与旧版统一 /api 前缀)

    • → P2 详细阅读版

    @@ -119,14 +119,14 @@ -

    4. 你要拍的决策点

    -
    D1 · 是否开跑大执行波 —— P2(7)+P7(8)≈15 任务、~40 次 SDD agent 调用,多小时工程;P7 要新建仓 ~/code/codes。开跑 / 先只跑 P7 / 暂缓?
    -
    D2 · P7 独立新仓 —— codes 做成 github.com/wangjia/codes 独立仓(不放 pay 内、不留 pangolin),核心零第三方依赖。认可?
    -
    D3 · P2 延后取舍 —— webhook 暂无 biz_code(用 biz_ref)、路由取"首个 enabled 账户"(策略延 P5)、币种走部署默认(多币种延 P3+)、/v1 与 /api/v1 并存。都认可?
    -
    D4 · settle 资金链路 & Provider 接口 —— 入账归一/幂等/金额核对(P2 Task5)与 Provider 抽象(P2 Task1)是资金命脉与扩展地基,是否需要我讲深或调整?
    +

    4. 决策点(2026-07-10 评审:D2/D3/D4 已拍,余 D1)

    +
    D1 · 是否开跑大执行波 —— P2(7)+P7(8)≈15 任务、~40 次 SDD agent 调用,多小时工程;P7 要新建仓 ~/code/codes。开跑 / 先只跑 P7 / 暂缓?【待拍】
    +
    D2 · P7 独立新仓 —— ✅ 已拍:认可 github.com/wangjia/codes 独立仓,核心零第三方依赖。
    +
    D3 · 路由统一 —— ✅ 已拍:统一 /api 前缀 v2 挂 /api/v2(POST /api/v1/orders 被旧契约占用,同前缀无法并存);旧 /api/v1 仅为存量当面付部署保留,P3 渠道迁入后整组删除,最终只剩一套。其余延后取舍(webhook 暂用 biz_ref、路由首账户延 P5、币种部署默认延 P3+)维持。
    +
    D4 · settle 资金链路 & Provider 接口 —— ✅ 已深讲并折入 3 处修订:A1 先入队后翻转+投递门禁(消灭"已付但永不通知"窗口)/ A2 Query(QueryRequest) 带尝试上下文 / A3 PaidEvent.PaidAt 渠道支付时间。详见 P2 阅读版「评审修订」。

    5. 建议下一步

    -

    我建议:D2/D3 认可后开跑 —— P7 在新仓/worktree 与 P2 关键路径并行,按 DAG 波次推进,每波边界向你汇报。若想稳,先只跑 P7(独立、低风险、不动 pay 主线)试水。你定。

    +

    只剩 D1:说"开跑"即按 DAG 波次启动(P7 新仓 ∥ P2 关键路径,SDD 逐任务实现+复审,每波边界汇报);想稳则"先只跑 P7"。

    diff --git a/docs/pay-v2-p2-plan.html b/docs/pay-v2-p2-plan.html index 9ca8d11..f8ec6de 100644 --- a/docs/pay-v2-p2-plan.html +++ b/docs/pay-v2-p2-plan.html @@ -49,11 +49,12 @@ Capabilities() Capabilities Create(ctx, CreateRequest) (*Session, error) VerifyCallback(ctx, CallbackInput) (*PaidEvent, error) - Query(ctx, providerRef string) (*PaidEvent, error) + Query(ctx, QueryRequest) (*PaidEvent, error) // D4-A2:带尝试上下文快照,非裸 ref } // 可选子接口:RefundingProvider(P4)、RecurringProvider(P8) -type Session struct { ProviderRef string; RenderType string; Payload map[string]any; ExpiresAt *time.Time } -type PaidEvent struct { ProviderRef string; Status PaidStatus; PaidAmountMinor int64; PaidCurrency, Raw string } +type Session struct { ProviderRef string; RenderType string; Payload map[string]any; ExpiresAt *time.Time } +type PaidEvent struct { ProviderRef string; Status PaidStatus; PaidAmountMinor int64; PaidCurrency, Raw string; PaidAt *time.Time } +type QueryRequest struct { ProviderRef, OutTradeNo, AccountID string; AmountMinor int64; Currency string; CreatedAt time.Time; ExpiresAt *time.Time }

    6 个 render_type 常量 + PaidPending/Succeeded/Failed;Registry(Register/Get/Methods + ErrUnknownMethod)。

    @@ -74,17 +75,17 @@

    Task 5 · 统一入账/开通管线 settle

    -internal/gateway/settle.go:Settle(ctx, *PaidEvent) = 归一 → 定位(provider_ref→attempt→order)→ 币种/金额核对 → 复用 P1 MarkAttemptPaid 幂等 → 仅翻转时入队 payment.succeeded。HandleCallback(webhook 入口)、SyncPendingAttempts(query 兜底)都汇入这条。SettleResult:ignored/not_found/amount_mismatch/duplicate/processed。 +internal/gateway/settle.go:Settle(ctx, *PaidEvent) = 归一 → 定位(provider_ref→attempt→order)→ 币种/金额核对 → 先幂等入队 payment.succeeded,再复用 P1 MarkAttemptPaid 幂等翻转(D4-A1 崩溃安全顺序:不变量「paid ⇒ outbox 行存在」,入队失败返回 SettleFailed 不翻转、渠道重投自愈)。HandleCallback(webhook 入口)、SyncPendingAttempts(query 兜底)都汇入这条。SettleResult:ignored/not_found/amount_mismatch/duplicate/processed/failed。paid_at 优先用渠道报的 PaidAt(D4-A3)。

    Task 6 · webhook v2 outbox + Notifier

    -model.WebhookDelivery(uniqueIndex(out_trade_no,event_type) 幂等)+ store.WebhookStore(Enqueue/ListUndelivered/MarkDelivered/MarkFailed)+ webhook.Notifier(DeliverPending/Start,HMAC 头 X-Pay-System/Event/Timestamp/Nonce/Sign,失败重试)。event_type 从 payment.succeeded 起。 +model.WebhookDelivery(uniqueIndex(out_trade_no,event_type) 幂等)+ store.WebhookStore(Enqueue/ListUndelivered/MarkDelivered/MarkFailed)+ webhook.Notifier(DeliverPending/Start,HMAC 头 X-Pay-System/Event/Timestamp/Nonce/Sign,失败重试)。event_type 从 payment.succeeded 起。投递门禁(D4-A1 另一半):发前确认订单已付,防把"未付单"通知出去。
    -

    Task 7 · HTTP /v1 接线

    -router.SetupV2 挂 POST /v1/orders、GET /v1/orders/:no、.../retry、.../cancel、POST /v1/callback/:method;main.go 装配 provider 注册表 + gateway + notifier,AutoMigrate 加 WebhookDelivery。 +

    Task 7 · HTTP /api/v2 接线

    +router.SetupV2 挂 POST /api/v2/orders、GET /api/v2/orders/:no、.../retry、.../cancel、POST /api/v2/callback/:method(D3:与旧版统一 /api 前缀;POST /api/v1/orders 被旧契约占用无法共存,P3 渠道迁入后删除整组 /api/v1 收口为一套);main.go 装配 provider 注册表 + gateway + notifier(含投递门禁闭包),AutoMigrate 加 WebhookDelivery。

    关键设计取舍(计划 Self-Review 已记)

    @@ -95,11 +96,20 @@ webhook 无 biz_codeP1 OrderV2 无 biz_code 列,不改已落地 schema;业务方暂用 biz_ref 映射,P3 补 路由取首个账户P2 取"首个 enabled 账户",完整路由策略在 P5 币种走部署默认多币种在 P3+ -/v1 与 /api/v1 并存v2 新端点与 v1 旧端点并存,收口在 pay 定稿后 +路由 /api/v2D3 已拍:v2 挂 /api/v2(统一 /api 前缀);旧 /api/v1 仅为存量当面付部署保留,P3 渠道迁入后整组删除,最终只剩一套 -
    审阅重点:① Provider 接口是否够覆盖后续渠道(Task1);② settle 的归一/幂等/金额核对链路(Task5,资金命脉);③ webhook outbox 幂等键 (out_trade_no,event_type) 是否合理(Task6);④ 上面 5 条取舍是否认可(尤其"路由取首个账户""币种默认"延后)。
    +

    评审修订(D4 深讲后折入,2026-07-10)

    + + + + + + + + +
    修订内容与理由
    A1 崩溃安全顺序Settle 改为先幂等入队 webhook、再幂等翻转订单 + Notifier「订单已付」投递门禁 + SettleFailed。原顺序(先翻转后入队)两步间崩溃 = 已收钱但业务方永不知情且无人重试;新顺序两个方向的窗口都由幂等 + 门禁 + 渠道重投/查单兜底自愈
    A2 Query 带上下文Query(ctx, providerRef) → Query(ctx, QueryRequest)(尝试完整快照)。crypto 自托管的"查单"是按地址+金额+时间窗扫链核对,裸 ref 会逼 adapter 自建 ref→上下文映射表,重复 pay 已有数据
    A3 渠道支付时间PaidEvent 增 PaidAt;settle/webhook payload 优先用渠道报的支付时间,否则收到时间。不加则本地 paid_at 全是"回调到达时间",P6 对账与渠道流水对不上产生假差异
    有意不调(记录)回调原始报文落表留痕(P3 callback_logs);Notifier 退避/死信上限+告警(P6);多账户回调验签由 P3 装配注入账户注册表(接口不变);crypto 分笔凑单由 adapter 聚合(P3)

    相关:pay v2 设计 · 真相源 docs/superpowers/plans/2026-07-10-pay-v2-p2-pipeline.md

    diff --git a/docs/superpowers/plans/2026-07-10-pay-v2-p2-pipeline.md b/docs/superpowers/plans/2026-07-10-pay-v2-p2-pipeline.md index b671ec3..c9763b8 100644 --- a/docs/superpowers/plans/2026-07-10-pay-v2-p2-pipeline.md +++ b/docs/superpowers/plans/2026-07-10-pay-v2-p2-pipeline.md @@ -39,8 +39,9 @@ - `type CreateRequest struct{ OutTradeNo, Subject string; AmountMinor int64; Currency string; Account config.AccountConfig; ReturnURL string; Metadata map[string]string }`。 - `type Session struct{ ProviderRef string; RenderType RenderType; Payload map[string]any; ExpiresAt *time.Time }`。 - `type CallbackInput struct{ Raw []byte; Headers, Query map[string]string }`。 - - `type PaidEvent struct{ ProviderRef string; Status PaidStatus; PaidAmountMinor int64; PaidCurrency string; Raw string }`。 - - `type Provider interface{ Method() string; Capabilities() Capabilities; Create(ctx,CreateRequest)(*Session,error); VerifyCallback(ctx,CallbackInput)(*PaidEvent,error); Query(ctx,providerRef string)(*PaidEvent,error) }`。 + - `type PaidEvent struct{ ProviderRef string; Status PaidStatus; PaidAmountMinor int64; PaidCurrency string; Raw string; PaidAt *time.Time }`(`PaidAt`=渠道报的支付时间,对账要用;渠道不报则 nil,settle 落 `time.Now()`)。 + - `type QueryRequest struct{ ProviderRef, OutTradeNo, AccountID string; AmountMinor int64; Currency string; CreatedAt time.Time; ExpiresAt *time.Time }`(查单带尝试完整上下文快照,不是裸 ref——crypto 的"查单"是按地址+金额+时间窗扫链核对)。 + - `type Provider interface{ Method() string; Capabilities() Capabilities; Create(ctx,CreateRequest)(*Session,error); VerifyCallback(ctx,CallbackInput)(*PaidEvent,error); Query(ctx,QueryRequest)(*PaidEvent,error) }`。 - 可选扩展接口 `RefundingProvider`(P4)、`RecurringProvider`(P8),供类型断言探测。 - `type Registry struct{...}` · `NewRegistry()` · `Register(Provider)` · `Get(method)(Provider,error)` · `Methods()[]string`;`ErrUnknownMethod`。 @@ -69,7 +70,7 @@ func (s stubProvider) Create(context.Context, provider.CreateRequest) (*provider func (s stubProvider) VerifyCallback(context.Context, provider.CallbackInput) (*provider.PaidEvent, error) { return &provider.PaidEvent{ProviderRef: "R-1", Status: provider.PaidSucceeded}, nil } -func (s stubProvider) Query(context.Context, string) (*provider.PaidEvent, error) { +func (s stubProvider) Query(context.Context, provider.QueryRequest) (*provider.PaidEvent, error) { return &provider.PaidEvent{ProviderRef: "R-1", Status: provider.PaidPending}, nil } @@ -188,6 +189,21 @@ type PaidEvent struct { PaidAmountMinor int64 PaidCurrency string Raw string + PaidAt *time.Time // 渠道报的支付时间;nil 则 settle 用收到时间,对账时两边时间才对得上 +} + +// QueryRequest — Provider.Query 入参:尝试的完整上下文快照,不是裸 provider_ref。 +// crypto 自托管的"查单"= 按地址+期望金额+时间窗扫链核对;裸 ref 会逼渠道 adapter +// 自建 ref→(地址/金额/窗口) 映射表,重复 pay 已持有的数据。管线侧(SyncPendingAttempts) +// 本就拿着整个 attempt,填这个结构零成本。 +type QueryRequest struct { + ProviderRef string + OutTradeNo string + AccountID string + AmountMinor int64 + Currency string + CreatedAt time.Time + ExpiresAt *time.Time } var ( @@ -201,7 +217,7 @@ type Provider interface { Capabilities() Capabilities Create(ctx context.Context, req CreateRequest) (*Session, error) VerifyCallback(ctx context.Context, in CallbackInput) (*PaidEvent, error) - Query(ctx context.Context, providerRef string) (*PaidEvent, error) + Query(ctx context.Context, req QueryRequest) (*PaidEvent, error) } // RefundingProvider — 可选:支持渠道退款的 Provider 额外实现(P4;不支持则 capabilities=false)。 @@ -271,7 +287,7 @@ git commit -m "feat(v2): Provider 渠道抽象接口 + 6 render_type + PaidEvent - `type Provider struct{...}` · `func New() *Provider`(实现 `provider.Provider`,`Method()=="fake"`,render_type=`crypto_address`)。 - `Create` 确定性产出 `provider_ref = "FAKE-"+OutTradeNo`,payload 含 address/amount_minor/currency。 - `VerifyCallback` 解析 JSON `{provider_ref,status,amount_minor,currency}` → `PaidEvent`。 - - `Query` 返回预置结果(默认 pending);`SetQueryResult(providerRef, PaidEvent)` 测试 seam(模拟查单命中)。 + - `Query(ctx, provider.QueryRequest)` 按 `req.ProviderRef` 返回预置结果(默认 pending);`SetQueryResult(providerRef, PaidEvent)` 测试 seam(模拟查单命中)。 - [ ] **Step 1: 写失败测试** @@ -316,7 +332,7 @@ func TestFakeQueryPreset(t *testing.T) { p := fake.New() ctx := context.Background() - ev, _ := p.Query(ctx, "FAKE-PAY-2") + ev, _ := p.Query(ctx, provider.QueryRequest{ProviderRef: "FAKE-PAY-2"}) if ev.Status != provider.PaidPending { t.Fatalf("默认应 pending, got %v", ev.Status) } @@ -324,7 +340,7 @@ func TestFakeQueryPreset(t *testing.T) { p.SetQueryResult("FAKE-PAY-2", provider.PaidEvent{ ProviderRef: "FAKE-PAY-2", Status: provider.PaidSucceeded, PaidAmountMinor: 100, PaidCurrency: "USDT", }) - ev2, _ := p.Query(ctx, "FAKE-PAY-2") + ev2, _ := p.Query(ctx, provider.QueryRequest{ProviderRef: "FAKE-PAY-2"}) if ev2.Status != provider.PaidSucceeded || ev2.PaidAmountMinor != 100 { t.Fatalf("预置后应 succeeded, got %+v", ev2) } @@ -410,14 +426,14 @@ func (p *Provider) VerifyCallback(_ context.Context, in provider.CallbackInput) }, nil } -func (p *Provider) Query(_ context.Context, providerRef string) (*provider.PaidEvent, error) { +func (p *Provider) Query(_ context.Context, req provider.QueryRequest) (*provider.PaidEvent, error) { p.mu.Lock() defer p.mu.Unlock() - if ev, ok := p.queryResults[providerRef]; ok { + if ev, ok := p.queryResults[req.ProviderRef]; ok { e := ev return &e, nil } - return &provider.PaidEvent{ProviderRef: providerRef, Status: provider.PaidPending}, nil + return &provider.PaidEvent{ProviderRef: req.ProviderRef, Status: provider.PaidPending}, nil } // SetQueryResult primes Query to report a specific event (test seam). @@ -638,6 +654,7 @@ package gateway_test import ( "context" + "errors" "testing" "github.com/wangjia/pay/config" @@ -661,10 +678,15 @@ func (stubResolver) Resolve(sku string) (int64, string, string, string, error) { } type spyEnqueuer struct { - calls []map[string]any + calls []map[string]any + failNext bool // 置 true 模拟 outbox 入队失败(settle 崩溃窗口测试用) } func (s *spyEnqueuer) Enqueue(outTradeNo, bizSystem, eventType string, data map[string]any) error { + if s.failNext { + s.failNext = false + return errors.New("outbox down") + } s.calls = append(s.calls, data) return nil } @@ -1101,11 +1123,11 @@ git commit -m "feat(v2): 一次性收款管线 CreateOrder/GetOrder/Retry/Cancel **Interfaces:** - Consumes: `provider.PaidEvent`、`store.OrderStore.AttemptByProviderRef/MarkAttemptPaid/GetOrder`(P1+T3)、`WebhookEnqueuer`。 - Produces(挂 `*Gateway`): - - `type SettleResult string` + `SettleIgnored/SettleNotFound/SettleAmountMismatch/SettleDuplicate/SettleProcessed`。 + - `type SettleResult string` + `SettleIgnored/SettleNotFound/SettleAmountMismatch/SettleDuplicate/SettleProcessed/SettleFailed`。 - `var ErrAmountMismatch = errors.New(...)` - - `Settle(ctx, ev *provider.PaidEvent) (SettleResult, error)` — 定位 attempt→order,核对币种/金额,幂等 `MarkAttemptPaid`,仅真正翻转时入队 `payment.succeeded`。 + - `Settle(ctx, ev *provider.PaidEvent) (SettleResult, error)` — 定位 attempt→order,核对币种/金额,**先幂等入队 `payment.succeeded`、再幂等 `MarkAttemptPaid` 翻转**(崩溃安全顺序,见实现注释;入队失败返回 `SettleFailed` 且不翻转,渠道重投可恢复)。 - `HandleCallback(ctx, method string, in provider.CallbackInput) (SettleResult, error)` — provider.VerifyCallback → Settle。 - - `SyncPendingAttempts(ctx, limit int) (int, error)` — 扫 pending 尝试 → 各自 provider.Query → Settle(查单兜底,设计 §8「对账优先于实时」)。 + - `SyncPendingAttempts(ctx, limit int) (int, error)` — 扫 pending 尝试 → 各自 provider.Query(传 `QueryRequest` 上下文快照)→ Settle(查单兜底,设计 §8「对账优先于实时」)。 - [ ] **Step 1: 写失败测试** @@ -1189,6 +1211,33 @@ func TestSettleGuards(t *testing.T) { } } +// 资金命脉不变量:outbox 入队失败 → 绝不翻转订单(否则"已付但永不通知")。 +// 渠道拿不到 200 会重投,重投时入队+翻转都幂等,自然恢复。 +func TestSettleEnqueueFailureKeepsOrderPending(t *testing.T) { + g, _, spy, orders := newGateway(t) + ctx := context.Background() + res, _ := g.CreateOrder(ctx, gateway.CreateOrderInput{SKU: "pro_year", Method: "fake", BizSystem: "pangolin", BizRef: "u-1"}) + ref := attemptRef(t, orders) + ev := &provider.PaidEvent{ProviderRef: ref, Status: provider.PaidSucceeded, PaidAmountMinor: 29990000, PaidCurrency: "USDT"} + + spy.failNext = true + if got, err := g.Settle(ctx, ev); got != gateway.SettleFailed || err == nil { + t.Fatalf("入队失败应 SettleFailed+err, got %v, %v", got, err) + } + o, _ := orders.GetOrder(res.OrderNo) + if o.Status != model.OrderPendingV2 { + t.Fatalf("入队失败后订单必须仍 pending, got %v", o.Status) + } + + // 渠道重投 → 入队成功 → 翻转 + if got, err := g.Settle(ctx, ev); err != nil || got != gateway.SettleProcessed { + t.Fatalf("重投应 processed, got %v, %v", got, err) + } + if len(spy.calls) != 1 { + t.Fatalf("恢复后应恰入队 1 次, got %d", len(spy.calls)) + } +} + func TestHandleCallbackAndSync(t *testing.T) { g, fp, _, orders := newGateway(t) ctx := context.Background() @@ -1232,7 +1281,6 @@ package gateway import ( "context" "errors" - "log" "time" "github.com/wangjia/pay/internal/model" @@ -1248,14 +1296,22 @@ const ( SettleAmountMismatch SettleResult = "amount_mismatch" // 币种不符 / 少付 SettleDuplicate SettleResult = "duplicate" // 订单已非 pending(幂等 no-op) SettleProcessed SettleResult = "processed" // 本次真正翻转为 paid + SettleFailed SettleResult = "failed" // 暂时性失败(outbox 入队失败等):未翻转,渠道应重投 ) var ErrAmountMismatch = errors.New("gateway: paid amount/currency mismatch") // Settle normalizes a PaidEvent into activation: locate order via provider_ref → // attempt → order (设计 §4「归一化 PaidEvent」), reconcile currency+amount, then -// idempotently mark paid via P1 MarkAttemptPaid (order=pending 原子守卫). Enqueues -// the payment.succeeded webhook only on a real flip (avoids duplicate delivery). +// enqueue-before-flip:先幂等入队 payment.succeeded(unique 键,重复 no-op), +// 再经 P1 MarkAttemptPaid 幂等翻转(order=pending 原子守卫)。 +// +// 顺序不变量(资金命脉):**订单为 paid ⇒ outbox 行必已存在**。 +// - 先翻转后入队:两步间崩溃 → 已收钱但业务方永不知情,且无任何机制重试 → 客诉才发现。 +// - 先入队后翻转:两步间崩溃 → outbox 里躺着一条"单还没付"的行;Notifier 投递前有 +// "订单已付"门禁(Task 6),不会把未付单通知出去。渠道因拿不到 200 会重投回调 +// (查单兜底同样收敛),重投时入队/翻转都幂等,自愈。 +// - 入队本身失败:返回 SettleFailed 且不翻转,同样交给渠道重投恢复。 func (g *Gateway) Settle(ctx context.Context, ev *provider.PaidEvent) (SettleResult, error) { if ev.Status != provider.PaidSucceeded { return SettleIgnored, nil // 非成功状态:确认收到即可 @@ -1271,32 +1327,35 @@ func (g *Gateway) Settle(ctx context.Context, ev *provider.PaidEvent) (SettleRes if ev.PaidCurrency != att.Currency || ev.PaidAmountMinor < att.AmountMinor { return SettleAmountMismatch, ErrAmountMismatch } + // paid_at 优先用渠道报的支付时间(对账时与渠道流水对得上),渠道不报才落收到时间。 + paidAt := time.Now() + if ev.PaidAt != nil { + paidAt = *ev.PaidAt + } - flipped, err := g.orders.MarkAttemptPaid(att.OutTradeNo, att.Channel, ev.ProviderRef, time.Now()) + if err := g.enqueuePaymentSucceeded(att, paidAt); err != nil { + return SettleFailed, err // 未入队绝不翻转;渠道重投时幂等恢复 + } + flipped, err := g.orders.MarkAttemptPaid(att.OutTradeNo, att.Channel, ev.ProviderRef, paidAt) if err != nil { - return SettleNotFound, err + return SettleFailed, err } if !flipped { return SettleDuplicate, nil // 已处理过 / 已取消 / 已过期 → 幂等 no-op } - - g.enqueuePaymentSucceeded(att) return SettleProcessed, nil } -// enqueuePaymentSucceeded 组 webhook 领域 payload 并入队(失败只记日志,不回滚入账)。 -func (g *Gateway) enqueuePaymentSucceeded(att *model.Attempt) { +// enqueuePaymentSucceeded 组 webhook 领域 payload 并幂等入队。仅订单仍 pending 时入队: +// 订单已 paid 说明翻转已发生,而翻转严格发生在成功入队之后(顺序不变量),行必已存在; +// 订单已 canceled 则不该通知(晚到支付走 P4 退款/P6 对账,不自动开通)。 +func (g *Gateway) enqueuePaymentSucceeded(att *model.Attempt, paidAt time.Time) error { o, err := g.orders.GetOrder(att.OutTradeNo) if err != nil { - log.Printf("[settle] 入队 webhook 取单失败 %s: %v", att.OutTradeNo, err) - return + return err } - if o.BizSystem == "" { - return // 独立收款,无业务方回调 - } - paidAt := "" - if o.PaidAt != nil { - paidAt = o.PaidAt.Format(time.RFC3339) + if o.BizSystem == "" || o.Status != model.OrderPendingV2 { + return nil // 独立收款无业务方回调;或已翻转/已取消 } data := map[string]any{ "event_type": "payment.succeeded", @@ -1306,11 +1365,9 @@ func (g *Gateway) enqueuePaymentSucceeded(att *model.Attempt) { "amount_minor": o.AmountMinor, "currency": o.Currency, "channel": att.Channel, - "paid_at": paidAt, - } - if err := g.webhook.Enqueue(o.OutTradeNo, o.BizSystem, "payment.succeeded", data); err != nil { - log.Printf("[settle] 入队 webhook 失败 %s: %v", o.OutTradeNo, err) + "paid_at": paidAt.Format(time.RFC3339), } + return g.webhook.Enqueue(o.OutTradeNo, o.BizSystem, "payment.succeeded", data) } // HandleCallback runs a channel's raw callback through its Provider.VerifyCallback @@ -1342,7 +1399,12 @@ func (g *Gateway) SyncPendingAttempts(ctx context.Context, limit int) (int, erro if err != nil { continue } - ev, err := prov.Query(ctx, att.ProviderRef) + // 查单带尝试完整上下文(crypto 需要地址/金额/时间窗才能扫链核对)。 + ev, err := prov.Query(ctx, provider.QueryRequest{ + ProviderRef: att.ProviderRef, OutTradeNo: att.OutTradeNo, AccountID: att.AccountID, + AmountMinor: att.AmountMinor, Currency: att.Currency, + CreatedAt: att.CreatedAt, ExpiresAt: att.ExpiresAt, + }) if err != nil || ev == nil { continue } @@ -1383,7 +1445,7 @@ git commit -m "feat(v2): 入账管线 Settle/HandleCallback/SyncPending(归一 - Produces: - `model.WebhookDelivery{ Base; OutTradeNo/EventType(uniqueIndex uq_delivery); BizSystem; Payload; Delivered bool; Attempts int; LastError string }`。 - `store.WebhookStore` · `NewWebhookStore(db)` · `EnqueueDelivery(outTradeNo,bizSystem,eventType,payload string) error`(ON CONFLICT DO NOTHING 幂等)· `ListUndelivered(limit) ([]WebhookDelivery,error)` · `MarkDelivered(id uint64) error` · `MarkFailed(id uint64, errMsg string) error`。 - - `webhook.Notifier` · `NewNotifier(ws *store.WebhookStore, bizConfig func(string)(config.BizSystemConfig,bool)) *Notifier`。实现 `Enqueue(outTradeNo,bizSystem,eventType string, data map[string]any) error`(JSON 序列化 → EnqueueDelivery)· `DeliverPending(limit int) (int,error)` · `Start(interval time.Duration)`。 + - `webhook.Notifier` · `NewNotifier(ws *store.WebhookStore, bizConfig func(string)(config.BizSystemConfig,bool), orderPaid func(outTradeNo string)(bool,error)) *Notifier`。实现 `Enqueue(outTradeNo,bizSystem,eventType string, data map[string]any) error`(JSON 序列化 → EnqueueDelivery)· `DeliverPending(limit int) (int,error)` · `Start(interval time.Duration)`。**投递门禁**:`deliverOne` 先经 `orderPaid` 确认订单已付才发(enqueue-before-flip 顺序不变量的另一半,防把"未付单"通知出去);未付则跳过本轮、不计失败,等翻转后自然放行。 - Consumes: `util.HMACSign`、`config.BizSystemConfig`。 - [ ] **Step 1: 写失败测试** @@ -1473,7 +1535,8 @@ func TestNotifierDeliversSignedEvent(t *testing.T) { } return config.BizSystemConfig{}, false } - n := webhook.NewNotifier(ws, bizCfg) + alwaysPaid := func(string) (bool, error) { return true, nil } + n := webhook.NewNotifier(ws, bizCfg, alwaysPaid) // 经 Enqueuer 接口入队(gateway 就是这么调的)。 err := n.Enqueue("PAY-1", "pangolin", "payment.succeeded", map[string]any{ @@ -1522,7 +1585,7 @@ func TestNotifierRetriesOnFailure(t *testing.T) { ws := store.NewWebhookStore(model.OpenTestDB(t)) n := webhook.NewNotifier(ws, func(string) (config.BizSystemConfig, bool) { return config.BizSystemConfig{CallbackURL: srv.URL, Secret: "x"}, true - }) + }, func(string) (bool, error) { return true, nil }) _ = n.Enqueue("PAY-3", "pangolin", "payment.succeeded", map[string]any{"event_type": "payment.succeeded"}) if sent, _ := n.DeliverPending(10); sent != 0 { @@ -1537,6 +1600,38 @@ func TestNotifierRetriesOnFailure(t *testing.T) { t.Fatalf("应重试第二次, hits=%d", hits) } } + +// 投递门禁:订单未付(settle 崩在"入队后、翻转前"的窗口)绝不把 payment.succeeded +// 发给业务方;也不计失败次数,等订单翻转后自然放行。 +func TestNotifierGateSkipsUnpaidOrder(t *testing.T) { + var hits int + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + hits++ + w.WriteHeader(http.StatusOK) + _, _ = w.Write([]byte("SUCCESS")) + })) + defer srv.Close() + + ws := store.NewWebhookStore(model.OpenTestDB(t)) + paid := false + n := webhook.NewNotifier(ws, func(string) (config.BizSystemConfig, bool) { + return config.BizSystemConfig{CallbackURL: srv.URL, Secret: "x"}, true + }, func(string) (bool, error) { return paid, nil }) + _ = n.Enqueue("PAY-4", "pangolin", "payment.succeeded", map[string]any{"event_type": "payment.succeeded"}) + + if sent, _ := n.DeliverPending(10); sent != 0 || hits != 0 { + t.Fatalf("未付单不应投递, sent=%d hits=%d", sent, hits) + } + pend, _ := ws.ListUndelivered(10) + if len(pend) != 1 || pend[0].Attempts != 0 { + t.Fatalf("门禁跳过不应计失败, got %+v", pend) + } + + paid = true // 订单翻转后放行 + if sent, _ := n.DeliverPending(10); sent != 1 || hits != 1 { + t.Fatalf("翻转后应投递, sent=%d hits=%d", sent, hits) + } +} ``` - [ ] **Step 2: 跑测试确认失败** @@ -1670,14 +1765,21 @@ import ( // BizConfigFunc resolves a business system's callback URL + HMAC secret. type BizConfigFunc func(system string) (config.BizSystemConfig, bool) +// OrderPaidFunc reports whether an order is settled (paid). Delivery gate: +// settle 是"先入队后翻转",崩溃窗口里 outbox 可能存在"未付单"的行——投递前必须 +// 门禁,否则会把 payment.succeeded 发给业务方、白给权益。 +type OrderPaidFunc func(outTradeNo string) (bool, error) + type Notifier struct { deliveries *store.WebhookStore bizConfig BizConfigFunc + orderPaid OrderPaidFunc client *http.Client } -func NewNotifier(ws *store.WebhookStore, bizConfig BizConfigFunc) *Notifier { - return &Notifier{deliveries: ws, bizConfig: bizConfig, client: &http.Client{Timeout: 10 * time.Second}} +func NewNotifier(ws *store.WebhookStore, bizConfig BizConfigFunc, orderPaid OrderPaidFunc) *Notifier { + return &Notifier{deliveries: ws, bizConfig: bizConfig, orderPaid: orderPaid, + client: &http.Client{Timeout: 10 * time.Second}} } // Enqueue implements gateway.WebhookEnqueuer: serialize the domain payload and @@ -1706,6 +1808,11 @@ func (n *Notifier) DeliverPending(limit int) (int, error) { } func (n *Notifier) deliverOne(d *store.WebhookDeliveryRow) bool { + // 门禁:订单未付不投递(不计失败,等 settle 翻转后自然放行)。 + paid, err := n.orderPaid(d.OutTradeNo) + if err != nil || !paid { + return false + } cfg, found := n.bizConfig(d.BizSystem) if !found || cfg.CallbackURL == "" { _ = n.deliveries.MarkFailed(d.ID, "biz system not configured") @@ -1791,7 +1898,7 @@ git commit -m "feat(v2): webhook v2 outbox + Notifier(event_type + HMAC 双向 + --- -### Task 7: HTTP 接线 — /v1 路由 + handler + 端到端联通 + main 装配 +### Task 7: HTTP 接线 — /api/v2 路由 + handler + 端到端联通 + main 装配 **Files:** - Create: `internal/handler/gateway.go`(GatewayHandler:CreateOrder/GetStatus/Retry/Cancel/Callback) @@ -1802,7 +1909,7 @@ git commit -m "feat(v2): webhook v2 outbox + Notifier(event_type + HMAC 双向 + **Interfaces:** - Produces: - `type GatewayHandler struct{...}` · `NewGatewayHandler(g *gateway.Gateway) *GatewayHandler`。 - - `router.SetupV2(r *gin.Engine, g *gateway.Gateway)` 挂:`POST /v1/orders`、`GET /v1/orders/:order_no`、`POST /v1/orders/:order_no/retry`、`POST /v1/orders/:order_no/cancel`、`POST /v1/callback/:method`。 + - `router.SetupV2(r *gin.Engine, g *gateway.Gateway)` 挂:`POST /api/v2/orders`、`GET /api/v2/orders/:order_no`、`POST /api/v2/orders/:order_no/retry`、`POST /api/v2/orders/:order_no/cancel`、`POST /api/v2/callback/:method`。 - Consumes: `gateway.Gateway`(T4/T5)、`util.RespondError/RespondSuccess`。业务方下单签名沿用 v1 `verifyBizSign` 范式(`biz_system` 非空即校验)。 - [ ] **Step 1: 写失败测试(端到端:下单→查→回调→已付)** @@ -1874,7 +1981,7 @@ func TestV2OrderLifecycle(t *testing.T) { r := buildEngine(t) // 下单(独立收款,无 biz_system → 无需签名) - w, out := do(t, r, http.MethodPost, "/v1/orders", map[string]any{"sku": "pro_year", "method": "fake"}) + w, out := do(t, r, http.MethodPost, "/api/v2/orders", map[string]any{"sku": "pro_year", "method": "fake"}) if w.Code != http.StatusOK { t.Fatalf("create code=%d body=%v", w.Code, out) } @@ -1886,7 +1993,7 @@ func TestV2OrderLifecycle(t *testing.T) { } // 查单:pending - _, out2 := do(t, r, http.MethodGet, "/v1/orders/"+orderNo, nil) + _, out2 := do(t, r, http.MethodGet, "/api/v2/orders/"+orderNo, nil) if out2["data"].(map[string]any)["status"] != "pending" { t.Fatalf("status = %v", out2["data"]) } @@ -1894,10 +2001,10 @@ func TestV2OrderLifecycle(t *testing.T) { // 取 provider_ref:直接构造 fake 回调体(provider_ref 由 payload 无法拿,需查尝试) // 这里用 callback 端点 + fake JSON:先取尝试 ref。测试通过再次下单太绕, // 改为:回调体里 provider_ref 用 order_no 反查——fake ref 前缀 FAKE-。 - // 直接命中:构造 verify 输入需真实 ref,故经 /v1/callback 前先查库拿 ref。 + // 直接命中:构造 verify 输入需真实 ref,故经 /api/v2/callback 前先查库拿 ref。 // 简化:暴露一个内部查询——本测试用 status 已足够验证下单/查单闭环; // 回调闭环在 gateway settle_test 已覆盖。此处验证 callback 路由存在且 404 语义: - wc, _ := do(t, r, http.MethodPost, "/v1/callback/fake", map[string]any{ + wc, _ := do(t, r, http.MethodPost, "/api/v2/callback/fake", map[string]any{ "provider_ref": "GHOST", "status": "succeeded", "amount_minor": 1, "currency": "USDT", }) if wc.Code != http.StatusOK { // not_found 也回 200(渠道无需重投未知单) @@ -1905,7 +2012,7 @@ func TestV2OrderLifecycle(t *testing.T) { } // 取消 - wCancel, outCancel := do(t, r, http.MethodPost, "/v1/orders/"+orderNo+"/cancel", nil) + wCancel, outCancel := do(t, r, http.MethodPost, "/api/v2/orders/"+orderNo+"/cancel", nil) if wCancel.Code != http.StatusOK || outCancel["data"].(map[string]any)["canceled"] != true { t.Fatalf("cancel = %d %v", wCancel.Code, outCancel) } @@ -1954,7 +2061,7 @@ type createV2Request struct { ReturnURL string `json:"return_url,omitempty"` } -// CreateOrder POST /v1/orders —— 下单,返回 {order_no, session:{render_type, payload}}。 +// CreateOrder POST /api/v2/orders —— 下单,返回 {order_no, session:{render_type, payload}}。 // biz_system 非空 → 校验 HMAC 签名(复用 v1 verifyBizSign)。 func (h *GatewayHandler) CreateOrder(c *gin.Context) { raw, err := io.ReadAll(http.MaxBytesReader(c.Writer, c.Request.Body, maxOrderBodyBytes)) @@ -1987,7 +2094,7 @@ func (h *GatewayHandler) CreateOrder(c *gin.Context) { util.RespondSuccess(c, res) } -// GetStatus GET /v1/orders/:order_no +// GetStatus GET /api/v2/orders/:order_no func (h *GatewayHandler) GetStatus(c *gin.Context) { v, err := h.g.GetOrder(c.Param("order_no")) if err != nil { @@ -2001,7 +2108,7 @@ type retryRequest struct { Method string `json:"method"` } -// Retry POST /v1/orders/:order_no/retry +// Retry POST /api/v2/orders/:order_no/retry func (h *GatewayHandler) Retry(c *gin.Context) { var req retryRequest _ = c.ShouldBindJSON(&req) @@ -2025,7 +2132,7 @@ func (h *GatewayHandler) Retry(c *gin.Context) { util.RespondSuccess(c, res) } -// Cancel POST /v1/orders/:order_no/cancel +// Cancel POST /api/v2/orders/:order_no/cancel func (h *GatewayHandler) Cancel(c *gin.Context) { ok, err := h.g.CancelOrder(c.Param("order_no")) if err != nil { @@ -2035,7 +2142,7 @@ func (h *GatewayHandler) Cancel(c *gin.Context) { util.RespondSuccess(c, gin.H{"canceled": ok}) } -// Callback POST /v1/callback/:method —— 渠道异步回调;经 provider.VerifyCallback → Settle。 +// Callback POST /api/v2/callback/:method —— 渠道异步回调;经 provider.VerifyCallback → Settle。 // 已受理(含未知单/幂等/金额不符,都不需要渠道重投)一律回 200。 func (h *GatewayHandler) Callback(c *gin.Context) { method := c.Param("method") @@ -2084,16 +2191,19 @@ import ( "github.com/wangjia/pay/internal/gateway" ) -// SetupV2 装配 pay v2 统一网关路由(/v1)。与 v1 /api/v1 并存,逐步收口。 +// SetupV2 装配 pay v2 统一网关路由(/api/v2,与旧版同一 /api 前缀风格)。 +// 旧 /api/v1 仅为存量支付宝当面付部署保留(路径 POST /api/v1/orders 与 v2 新契约 +// 同名不同形,无法在同一前缀下并存);P3 支付宝 adapter 迁入 v2 后整组删除, +// 最终对外只剩 /api/v2 一套。 func SetupV2(r *gin.Engine, g *gateway.Gateway) { h := handler.NewGatewayHandler(g) - v1 := r.Group("/v1") + v2 := r.Group("/api/v2") { - v1.POST("/orders", h.CreateOrder) - v1.GET("/orders/:order_no", h.GetStatus) - v1.POST("/orders/:order_no/retry", h.Retry) - v1.POST("/orders/:order_no/cancel", h.Cancel) - v1.POST("/callback/:method", h.Callback) + v2.POST("/orders", h.CreateOrder) + v2.GET("/orders/:order_no", h.GetStatus) + v2.POST("/orders/:order_no/retry", h.Retry) + v2.POST("/orders/:order_no/cancel", h.Cancel) + v2.POST("/callback/:method", h.Callback) } } ``` @@ -2110,10 +2220,16 @@ Expected: PASS。 // v2 统一网关装配(P2):provider 注册表 + gateway + webhook notifier。 pReg := provider.NewRegistry() // P3 起在此 Register 真实渠道:crypto / alipay / stripe …(fake 仅测试用,不注册进生产)。 -webhookStore := store.NewWebhookStore(db) -notifier := webhook.NewNotifier(webhookStore, config.C.BizByName) -notifier.Start(60 * time.Second) orderStore := store.NewOrderStore(db) +webhookStore := store.NewWebhookStore(db) +notifier := webhook.NewNotifier(webhookStore, config.C.BizByName, func(no string) (bool, error) { + o, err := orderStore.GetOrder(no) // 投递门禁:订单已付才发(enqueue-before-flip 不变量) + if err != nil { + return false, err + } + return o.Status == model.OrderPaidV2, nil +}) +notifier.Start(60 * time.Second) productResolver := gateway.NewDBProductResolver(db, "CNY") // 币种按部署区配(cn=CNY / global=USDT) acctReg := accounts.New(config.C.Accounts) gw := gateway.New(orderStore, pReg, acctReg, productResolver, notifier, "cn") @@ -2133,7 +2249,7 @@ Expected: 编译通过,全部包 `ok`(含 handler/gateway/provider/store/webhook ```bash cd /Users/wangjia/code/pay git add internal/handler/gateway.go internal/router/router.go main.go -git commit -m "feat(v2): /v1 网关路由 + handler(下单/查/重试/取消/回调)+ main 装配 gateway/notifier" +git commit -m "feat(v2): /api/v2 网关路由 + handler(下单/查/重试/取消/回调)+ main 装配 gateway/notifier" ``` --- @@ -2143,8 +2259,8 @@ git commit -m "feat(v2): /v1 网关路由 + handler(下单/查/重试/取消/回 **Spec coverage(P2 范围,对照设计 §3/§4/§5):** - Provider 接口 `capabilities/create/verify_callback/query` + 可选 refund/recurring 留空 + 注册表 `map[method]Provider`(Task 1)= 设计 §4.1 ✓。 - fake provider 验证管线,真渠道 P3(Task 2)✓。 -- 一次性收款管线 `POST /v1/orders → 选 provider → create → 落 Order+Attempt(复用 P1 OrderStore)→ 返回 {order_no, session:{render_type, payload}}`;`GET /v1/orders/{no}`;retry/cancel(Task 4/7)= 设计 §3.1/3.2/4.2 ✓。 -- 统一开通/入账:webhook 与 query 都产出归一化 `PaidEvent` → 定位(provider_ref→attempt→order)→ 幂等 → 金额/币种核对 → `MarkAttemptPaid`(复用 P1)→ 触发业务方 webhook(Task 5)= 设计 §4 ✓。 +- 一次性收款管线 `POST /api/v2/orders → 选 provider → create → 落 Order+Attempt(复用 P1 OrderStore)→ 返回 {order_no, session:{render_type, payload}}`;`GET /api/v2/orders/{no}`;retry/cancel(Task 4/7)= 设计 §3.1/3.2/4.2 ✓。 +- 统一开通/入账:webhook 与 query 都产出归一化 `PaidEvent` → 定位(provider_ref→attempt→order)→ 金额/币种核对 → **先幂等入队、再幂等 `MarkAttemptPaid` 翻转**(Task 5)= 设计 §4 ✓。顺序不变量「paid ⇒ outbox 行存在」消灭"已付但永不通知"的崩溃窗口;反向窗口("入队了但未翻转")由 Notifier 投递门禁(订单已付才发,Task 6)+ 渠道重投/查单兜底自愈。取消单晚到支付:入队 skip(状态非 pending)→ 翻转失败 → duplicate,不自动开通,渠道已扣款场景归 P4 退款/P6 对账。 - webhook v2:pay→业务方,payload 带 `event_type`(先 `payment.succeeded`),HMAC 双向签名(复用 `util.HMACSign`),outbox + 重试兜底(Task 6)= 设计 §5 ✓。 - 幂等/金额核对贯穿:入账走 P1 条件 UPDATE(order=pending 守卫);webhook 入队走 unique 键 ON CONFLICT;核对币种一致 + 实付 ≥ 应收(Task 5/6)✓。 @@ -2154,18 +2270,25 @@ git commit -m "feat(v2): /v1 网关路由 + handler(下单/查/重试/取消/回 **Type consistency:** `provider.Provider`/`Session`/`PaidEvent`/`CreateRequest`/`CallbackInput` 在 Task 1 定义,Task 2(fake)、Task 4/5(gateway)、Task 7(handler)一致消费。`gateway.WebhookEnqueuer.Enqueue(outTradeNo,bizSystem,eventType,data)` 由 Task 5 消费、Task 6 `webhook.Notifier` 实现。`store.WebhookDeliveryRow = model.WebhookDelivery`(别名)让 `webhook` 包不直接依赖 `model`。`config.C.BizByName` 签名恰配 `webhook.BizConfigFunc`。金额一律 `int64 minor + Currency`。 +**评审修订(2026-07-10 用户评审 D3/D4 后,执行前已折入上文各 Task):** +- **D3 路由**:v2 从裸 `/v1` 改挂 `/api/v2`(统一 `/api` 前缀;`POST /api/v1/orders` 被旧契约占用无法共存),P3 渠道迁入后删除整组 `/api/v1`。 +- **D4-A1 崩溃安全顺序**:Settle 由"先翻转后入队"改为"**先幂等入队、再幂等翻转**"+ Notifier"订单已付"投递门禁 + `SettleFailed`(入队失败不翻转,渠道重投自愈)。消灭"已付但业务方永不知情"的窗口。 +- **D4-A2 Query 带上下文**:`Provider.Query(ctx, providerRef string)` → `Query(ctx, QueryRequest)`(尝试完整快照)。crypto 的查单是"按地址+金额+时间窗扫链",裸 ref 会逼 adapter 自建映射表。 +- **D4-A3 渠道支付时间**:`PaidEvent` 增 `PaidAt *time.Time`,settle/payload 优先用渠道报的时间,对账时与渠道流水对得上。 +- **D4 记录未调整项(有意延后)**:回调原始报文落表留痕(P2 先靠 `PaidEvent.Raw` + 服务日志,P3 落 callback_logs 表);Notifier 无退避/无死信上限(P6 加 max attempts + 告警);多账户回调验签需 provider 持账户注册表(P3 装配注入,接口不变);crypto 分笔凑单由 crypto adapter 聚合后才发 succeeded(P3)。 + **已知 scope 取舍(记录,不阻塞 P2):** - webhook payload 未含 `product_biz_code`(设计 §5 列了):`model.OrderV2` 无 biz_code 列(P1 已定),不改 P1 schema;P2 业务方用 `biz_ref` 映射自身订单足够,`product_biz_code` 待 P3 给 order 补 biz_code 列或经 product 关联时补齐。 - 路由策略取"首个 enabled 账户"(设计 §3.3 的 round_robin/weighted/limit_aware 在 **P5**)。 - 币种维度未进 product(`DBProductResolver` 用单一部署默认币种):多币种 product 在 P3+。 -- `/v1`(v2)与 `/api/v1`(v1)并存,收口在 pay 定稿后(设计 §1 / brain todo #5)。 +- v2 走 `/api/v2`(与旧版统一 `/api` 前缀;`POST /api/v1/orders` 已被旧契约占用,同前缀无法并存)。旧 `/api/v1` 仅为存量当面付部署保留,P3 渠道迁入后整组删除,收口为一套(设计 §1 / brain todo #5)。 --- ## 后续阶段(各自独立成计划,落地前逐一细化) - **P3** 首批渠道 adapter 实现 `provider.Provider`:crypto 自托管(包裹 pangolin-pay 单地址/地址池收款 + 链上确认 query)/ 支付宝(迁移 v1 `internal/channel/alipay.go` 到 provider,复用验签)/ Stripe(sdk_handoff + webhook 验签)。各自 `Register` 进注册表;补 order 的 biz_code / 多币种。 -- **P4** 退款:`POST /v1/refunds` + `provider.RefundingProvider` + 三向(业务发起/crypto 人工 sweep/平台通知)+ `refund.succeeded`/`refund.failed` 事件 + order 退款态机(refunding/partially_refunded/refunded)。 +- **P4** 退款:`POST /api/v2/refunds` + `provider.RefundingProvider` + 三向(业务发起/crypto 人工 sweep/平台通知)+ `refund.succeeded`/`refund.failed` 事件 + order 退款态机(refunding/partially_refunded/refunded)。 - **P5** 多账户路由策略(round_robin/weighted/limit_aware/by_region/crypto 地址池)替换"首个 enabled"。 - **P6** 对账 job:周期 `SyncPendingAttempts` + 每 provider `query` 拉渠道流水 vs 本地订单,防掉单/防重复授权。 - **P7** codes 共享库(A 嵌入各产品)。