fix(payment): 渠道已收款时不再把支付单回滚成支付中

租客在待支付超时或取消的最后几十秒完成付款时，订单先被取消，乐刷的支付
结果几秒后才到，入账被判定订单不可支付而拒收。原先订单推进和支付单更新
在同一个事务里，订单一报错整笔回滚，支付单停在支付中且 paid_at 为空：
钱已在渠道，系统却毫不知情。乐刷重试十次后放弃，之后既补不回入账（订单
不再是待支付），后台人工退款也发不出去（退款要求原支付单是已支付）。
日志保留期内 13 天出了 5 笔，合计 4085.60 元。

- 取消前核对渠道：超时取消、租客取消、客服关单都先查一次渠道，已收款并
  已推进订单就放弃取消，让支付正常入账而不是走退款。渠道异常时按未收款
  继续，避免渠道一抖订单全卡住
- 回调兜底记账：订单确实已结束时不再回滚，把支付单如实记成已支付并写入
  paid_at 与渠道单号，后台人工退款从此可用。退款仍由客服人工发起
- 客服关单：待支付订单按实际已收款减已退款的差额退，补上本次事故中关单
  不生成退款的直接原因
- 补齐日志上下文：回调入账失败原先只有 error="order cannot pay"，现在带
  支付单号、订单号、订单状态和金额；新增 ERROR「渠道已收款但订单无法入账，
  需人工退款」作为唯一需人工介入的告警

Co-authored-by: Cursor <cursoragent@cursor.com>

backend/internal/modules/order/admin_actions.go

@@ -14,6 +14,11 @@ import (
 )
 
 func (r *Repository) AdminClose(ctx context.Context, adminID uint64, orderID uint64, req AdminActionRequest, meta AuditMeta) error {
+	// 客服常以「支付失败」关闭待支付订单，但渠道结果可能只是还没回来。
+	// 先核对一次，已收款的订单直接推进，避免关单后钱收了却查无记录。
+	if r.pendingPaymentOrderPaidAtChannelForAdmin(ctx, orderID) {
+		return ErrOrderPaidAtChannel
+	}
 	var refund *refundAction
 	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 		assets, err := r.lockOrderAssets(tx, orderID)
@@ -48,6 +53,20 @@ func (r *Repository) AdminClose(ctx context.Context, adminID uint64, orderID uin
 				return err
 			}
 			refund = action
+		} else {
+			// 待支付订单照理没有款项，但渠道钱款迟到时支付单会被记成已支付。
+			// 按「已收款减去已退款」退，漏掉就等于白收用户一笔钱。
+			outstandingCent, err := outstandingPaidOrderPaymentCentTx(tx, order.ID)
+			if err != nil {
+				return err
+			}
+			if outstandingCent > 0 {
+				action, err := r.prepareRefund(order, outstandingCent, refundBizAdminClose, "客服关闭订单原路退款")
+				if err != nil {
+					return err
+				}
+				refund = action
+			}
 		}
 		if err := notification.Append(tx,
 			notification.Entry{

backend/internal/modules/order/channel_paid_guard_test.go

@@ -0,0 +1,252 @@
+package order
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"hfb_sys/backend/internal/model"
+
+	"gorm.io/gorm"
+)
+
+// TestCancelAbortsWhenChannelAlreadyPaid 租客一边点取消、一边在渠道付成功时，
+// 取消必须让位给支付，否则订单没了而钱已经到账。
+func TestCancelAbortsWhenChannelAlreadyPaid(t *testing.T) {
+	db := setupOrderTestDB(t)
+	probed := uint64(0)
+	repo := NewRepository(db, Dependencies{
+		PaymentProbe: ChannelPaymentProbeFunc(func(_ context.Context, orderID uint64) (bool, error) {
+			probed = orderID
+			return true, nil
+		}),
+	})
+	_, renter, order := createPendingPaymentOrderFixture(t, db, "CPG1")
+
+	err := repo.Cancel(t.Context(), renter.ID, order.ID)
+	if !errors.Is(err, ErrOrderPaidAtChannel) {
+		t.Fatalf("Cancel() error = %v, want ErrOrderPaidAtChannel", err)
+	}
+	if probed != order.ID {
+		t.Fatalf("probed order id = %d, want %d", probed, order.ID)
+	}
+
+	var saved model.RentalOrder
+	if findErr := db.First(&saved, order.ID).Error; findErr != nil {
+		t.Fatalf("find order failed: %v", findErr)
+	}
+	if saved.Status != orderStatusPendingPayment {
+		t.Fatalf("order status = %q, want pending_payment", saved.Status)
+	}
+}
+
+// TestCancelProceedsWhenChannelProbeFails 渠道查不通不能让取消卡住，
+// 否则渠道一抖所有待支付订单都取消不掉；真漏掉的由回调兜底和对账任务收尾。
+func TestCancelProceedsWhenChannelProbeFails(t *testing.T) {
+	db := setupOrderTestDB(t)
+	repo := NewRepository(db, Dependencies{
+		PaymentProbe: ChannelPaymentProbeFunc(func(context.Context, uint64) (bool, error) {
+			return false, errors.New("channel timeout")
+		}),
+	})
+	_, renter, order := createPendingPaymentOrderFixture(t, db, "CPG2")
+
+	if err := repo.Cancel(t.Context(), renter.ID, order.ID); err != nil {
+		t.Fatalf("Cancel() error = %v, want nil", err)
+	}
+
+	var saved model.RentalOrder
+	if findErr := db.First(&saved, order.ID).Error; findErr != nil {
+		t.Fatalf("find order failed: %v", findErr)
+	}
+	if saved.Status != orderStatusCancelled {
+		t.Fatalf("order status = %q, want cancelled", saved.Status)
+	}
+}
+
+// TestAdminCloseAbortsWhenChannelAlreadyPaid 客服常以「支付失败」关闭待支付订单，
+// 但渠道结果可能只是还没回来。关单前核对到已收款就不能关。
+func TestAdminCloseAbortsWhenChannelAlreadyPaid(t *testing.T) {
+	db := setupOrderTestDB(t)
+	repo := NewRepository(db, Dependencies{
+		PaymentProbe: ChannelPaymentProbeFunc(func(context.Context, uint64) (bool, error) {
+			return true, nil
+		}),
+	})
+	_, _, order := createPendingPaymentOrderFixture(t, db, "CPG3")
+
+	err := repo.AdminClose(t.Context(), 9001, order.ID, AdminActionRequest{Reason: "支付失败"}, AuditMeta{})
+	if !errors.Is(err, ErrOrderPaidAtChannel) {
+		t.Fatalf("AdminClose() error = %v, want ErrOrderPaidAtChannel", err)
+	}
+}
+
+// TestAdminCloseRefundsAlreadyPaidPendingPaymentOrder 待支付订单照理没有款项，
+// 所以原先关单一律不退款。但渠道钱款迟到时支付单会被记成已支付，
+// 这正是本次 1358.70 元收了却查无退款记录的直接原因：关单必须按实际收款退。
+func TestAdminCloseRefundsAlreadyPaidPendingPaymentOrder(t *testing.T) {
+	db := setupOrderTestDB(t)
+	var startedAmount int64
+	var startedBizType string
+	repo := NewRepository(db, Dependencies{
+		RefundStarter: RefundStarterFunc(func(_ context.Context, _ uint64, refundAmountCent int64, bizType string, _ string) (string, error) {
+			startedAmount = refundAmountCent
+			startedBizType = bizType
+			return "refunding", nil
+		}),
+	})
+	_, renter, order := createPendingPaymentOrderFixture(t, db, "CPG4")
+	createOrderPayment(t, db, order, renter.ID, "CPG4", "order_pay", "paid", 135870)
+
+	if err := repo.AdminClose(t.Context(), 9001, order.ID, AdminActionRequest{Reason: "支付失败"}, AuditMeta{}); err != nil {
+		t.Fatalf("AdminClose() error = %v", err)
+	}
+	if startedAmount != 135870 {
+		t.Fatalf("refund amount = %d, want 135870", startedAmount)
+	}
+	if startedBizType != refundBizAdminClose {
+		t.Fatalf("refund biz type = %q, want %q", startedBizType, refundBizAdminClose)
+	}
+
+	var saved model.RentalOrder
+	if findErr := db.First(&saved, order.ID).Error; findErr != nil {
+		t.Fatalf("find order failed: %v", findErr)
+	}
+	if saved.RefundAmountCent != 135870 {
+		t.Fatalf("order refund amount = %d, want 135870", saved.RefundAmountCent)
+	}
+}
+
+// TestAdminCloseSkipsRefundWhenAlreadyRefunded 已经退过的订单，关单不能再退一次。
+func TestAdminCloseSkipsRefundWhenAlreadyRefunded(t *testing.T) {
+	db := setupOrderTestDB(t)
+	refundStarted := false
+	repo := NewRepository(db, Dependencies{
+		RefundStarter: RefundStarterFunc(func(context.Context, uint64, int64, string, string) (string, error) {
+			refundStarted = true
+			return "refunding", nil
+		}),
+	})
+	_, renter, order := createPendingPaymentOrderFixture(t, db, "CPG5")
+	createOrderPayment(t, db, order, renter.ID, "CPG5A", "order_pay", "paid", 135870)
+	createOrderPayment(t, db, order, renter.ID, "CPG5B", "admin_refund", "refunded", 135870)
+
+	if err := repo.AdminClose(t.Context(), 9001, order.ID, AdminActionRequest{Reason: "支付失败"}, AuditMeta{}); err != nil {
+		t.Fatalf("AdminClose() error = %v", err)
+	}
+	if refundStarted {
+		t.Fatal("refund started again, want no duplicate refund")
+	}
+}
+
+// TestAdminCloseRefundsRemainderWhenPartiallyRefunded 已退一部分时只退差额。
+func TestAdminCloseRefundsRemainderWhenPartiallyRefunded(t *testing.T) {
+	db := setupOrderTestDB(t)
+	var startedAmount int64
+	repo := NewRepository(db, Dependencies{
+		RefundStarter: RefundStarterFunc(func(_ context.Context, _ uint64, refundAmountCent int64, _ string, _ string) (string, error) {
+			startedAmount = refundAmountCent
+			return "refunding", nil
+		}),
+	})
+	_, renter, order := createPendingPaymentOrderFixture(t, db, "CPG7")
+	createOrderPayment(t, db, order, renter.ID, "CPG7A", "order_pay", "paid", 135870)
+	createOrderPayment(t, db, order, renter.ID, "CPG7B", "admin_refund", "refunded", 35870)
+
+	if err := repo.AdminClose(t.Context(), 9001, order.ID, AdminActionRequest{Reason: "支付失败"}, AuditMeta{}); err != nil {
+		t.Fatalf("AdminClose() error = %v", err)
+	}
+	if startedAmount != 100000 {
+		t.Fatalf("refund amount = %d, want 100000", startedAmount)
+	}
+}
+
+// TestAdminCloseKeepsNoRefundForUnpaidPendingPaymentOrder 没收到钱的待支付订单照旧不退款。
+func TestAdminCloseKeepsNoRefundForUnpaidPendingPaymentOrder(t *testing.T) {
+	db := setupOrderTestDB(t)
+	refundStarted := false
+	repo := NewRepository(db, Dependencies{
+		RefundStarter: RefundStarterFunc(func(context.Context, uint64, int64, string, string) (string, error) {
+			refundStarted = true
+			return "refunding", nil
+		}),
+	})
+	_, renter, order := createPendingPaymentOrderFixture(t, db, "CPG6")
+	createOrderPayment(t, db, order, renter.ID, "CPG6", "order_pay", "paying", 135870)
+
+	if err := repo.AdminClose(t.Context(), 9001, order.ID, AdminActionRequest{Reason: "支付失败"}, AuditMeta{}); err != nil {
+		t.Fatalf("AdminClose() error = %v", err)
+	}
+	if refundStarted {
+		t.Fatal("refund started for an unpaid order, want none")
+	}
+}
+
+func createPendingPaymentOrderFixture(t *testing.T, db *gorm.DB, suffix string) (model.User, model.User, model.RentalOrder) {
+	t.Helper()
+	owner := model.User{Phone: "1380" + suffix + "01"}
+	renter := model.User{Phone: "1390" + suffix + "02"}
+	if err := db.Create(&owner).Error; err != nil {
+		t.Fatalf("create owner failed: %v", err)
+	}
+	if err := db.Create(&renter).Error; err != nil {
+		t.Fatalf("create renter failed: %v", err)
+	}
+	account := model.GameAccount{
+		OwnerID:       owner.ID,
+		ServerRegion:  "国服",
+		LoginPlatform: "steam",
+		Title:         "测试账号" + suffix,
+		Status:        "published",
+	}
+	if err := db.Create(&account).Error; err != nil {
+		t.Fatalf("create account failed: %v", err)
+	}
+	listing := model.RentalListing{
+		ListingNo:     "LST" + suffix,
+		OwnerID:       owner.ID,
+		AccountID:     account.ID,
+		Status:        "published",
+		ReviewStatus:  "approved",
+		InTransaction: true,
+		PriceCent:     1000,
+	}
+	if err := db.Create(&listing).Error; err != nil {
+		t.Fatalf("create listing failed: %v", err)
+	}
+	order := model.RentalOrder{
+		OrderNo:           "ORD" + suffix,
+		ListingID:         listing.ID,
+		AccountID:         account.ID,
+		OwnerID:           owner.ID,
+		RenterID:          renter.ID,
+		RentAmountCent:    125870,
+		DepositAmountCent: 10000,
+		Status:            orderStatusPendingPayment,
+		HandoffStatus:     "none",
+	}
+	if err := db.Create(&order).Error; err != nil {
+		t.Fatalf("create order failed: %v", err)
+	}
+	return owner, renter, order
+}
+
+func createOrderPayment(t *testing.T, db *gorm.DB, order model.RentalOrder, userID uint64, suffix string, bizType string, status string, amountCent int64) model.PaymentOrder {
+	t.Helper()
+	payment := model.PaymentOrder{
+		PaymentNo:       "PAY" + suffix,
+		OrderID:         order.ID,
+		OrderNo:         order.OrderNo,
+		UserID:          userID,
+		Provider:        "leshua",
+		ThirdOrderID:    "THIRD" + suffix,
+		ProviderOrderID: "PROVIDER" + suffix,
+		AmountCent:      amountCent,
+		BizType:         bizType,
+		Status:          status,
+	}
+	if err := db.Create(&payment).Error; err != nil {
+		t.Fatalf("create payment failed: %v", err)
+	}
+	return payment
+}

backend/internal/modules/order/handler_error.go

@@ -30,6 +30,8 @@ func writeOrderError(c *gin.Context, err error) {
 		response.Error(c, http.StatusConflict, "order_cannot_pay", "当前订单不能支付")
 	case errors.Is(err, ErrOrderCannotCancel):
 		response.Error(c, http.StatusConflict, "order_cannot_cancel", "当前订单不能取消")
+	case errors.Is(err, ErrOrderPaidAtChannel):
+		response.Error(c, http.StatusConflict, "order_paid_at_channel", "该订单已支付成功，请刷新后查看最新状态")
 	case errors.Is(err, ErrOrderCannotHide):
 		response.Error(c, http.StatusConflict, "order_cannot_hide", "只有已结束且款项处理完毕的订单可以删除")
 	case errors.Is(err, ErrOrderCannotHandoff):

backend/internal/modules/order/lifecycle.go

@@ -428,6 +428,11 @@ func (r *Repository) ConfirmPaidFromChannelTx(tx *gorm.DB, orderID uint64) (uint
 }
 
 func (r *Repository) Cancel(ctx context.Context, userID uint64, orderID uint64) error {
+	// 租客可能一边点取消一边在渠道完成付款。先核对渠道，已收款就让支付正常入账，
+	// 不要把订单取消掉，否则钱收了订单却没了。
+	if r.pendingPaymentOrderPaidAtChannel(ctx, userID, orderID) {
+		return ErrOrderPaidAtChannel
+	}
 	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 		var order model.RentalOrder
 		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).

backend/internal/modules/order/refund.go

@@ -7,6 +7,7 @@ import (
 	"hfb_sys/backend/internal/model"
 
 	"go.uber.org/zap"
+	"gorm.io/gorm"
 )
 
 func (r *Repository) prepareRefund(order *model.RentalOrder, amountCent int64, bizType string, remark string) (*refundAction, error) {
@@ -27,6 +28,45 @@ func (r *Repository) prepareRefund(order *model.RentalOrder, amountCent int64, b
 	}, nil
 }
 
+// outstandingPaidOrderPaymentCentTx 算出订单实际收到、尚未退回的下单款项。
+// 口径是已支付的下单流水合计减去已退/在退的退款流水合计，重复关单不会重复退。
+func outstandingPaidOrderPaymentCentTx(tx *gorm.DB, orderID uint64) (int64, error) {
+	var paidCent int64
+	if err := tx.Model(&model.PaymentOrder{}).
+		Where("order_id = ? AND biz_type = ? AND status = ?", orderID, "order_pay", "paid").
+		Select("COALESCE(SUM(amount_cent), 0)").Scan(&paidCent).Error; err != nil {
+		return 0, err
+	}
+	if paidCent <= 0 {
+		return 0, nil
+	}
+	var refundedCent int64
+	if err := tx.Model(&model.PaymentOrder{}).
+		Where("order_id = ? AND biz_type <> ? AND status IN ?", orderID, "order_pay", []string{"refunding", "refunded"}).
+		Select("COALESCE(SUM(amount_cent), 0)").Scan(&refundedCent).Error; err != nil {
+		return 0, err
+	}
+	if refundedCent >= paidCent {
+		return 0, nil
+	}
+	return paidCent - refundedCent, nil
+}
+
+// pendingPaymentOrderPaidAtChannelForAdmin 在客服关单前核对待支付订单的渠道收款情况。
+func (r *Repository) pendingPaymentOrderPaidAtChannelForAdmin(ctx context.Context, orderID uint64) bool {
+	if r.paymentProbe == nil {
+		return false
+	}
+	var status string
+	err := r.db.WithContext(ctx).Model(&model.RentalOrder{}).
+		Where("id = ?", orderID).
+		Pluck("status", &status).Error
+	if err != nil || status != orderStatusPendingPayment {
+		return false
+	}
+	return r.channelPaidBeforeClose(ctx, orderID)
+}
+
 func (r *Repository) startRefundBestEffort(ctx context.Context, action *refundAction) {
 	if action == nil || r.refundStarter == nil {
 		return

backend/internal/modules/order/repository.go

@@ -3,6 +3,10 @@ package order
 import (
 	"context"
 
+	"hfb_sys/backend/internal/logging"
+	"hfb_sys/backend/internal/model"
+
+	"go.uber.org/zap"
 	"gorm.io/gorm"
 )
 
@@ -27,10 +31,22 @@ type OrderChatArchiver interface {
 	ArchiveListingConversation(tx *gorm.DB, listingID uint64, reason string) error
 }
 
+// ChannelPaymentProbe 由支付模块适配实现，用于在取消或关单前跟渠道核对是否已收款。
+type ChannelPaymentProbe interface {
+	ConfirmChannelPaidBeforeClose(ctx context.Context, orderID uint64) (paid bool, err error)
+}
+
+type ChannelPaymentProbeFunc func(ctx context.Context, orderID uint64) (bool, error)
+
+func (fn ChannelPaymentProbeFunc) ConfirmChannelPaidBeforeClose(ctx context.Context, orderID uint64) (bool, error) {
+	return fn(ctx, orderID)
+}
+
 type Dependencies struct {
 	ChatNotifier  OrderChatNotifier
 	ChatArchiver  OrderChatArchiver
 	RefundStarter RefundStarter
+	PaymentProbe  ChannelPaymentProbe
 }
 
 type refundAction struct {
@@ -45,6 +61,7 @@ type Repository struct {
 	chatNotifier  OrderChatNotifier
 	chatArchiver  OrderChatArchiver
 	refundStarter RefundStarter
+	paymentProbe  ChannelPaymentProbe
 }
 
 const defaultPendingPaymentTimeoutMinutes = 15
@@ -55,10 +72,51 @@ func NewRepository(db *gorm.DB, deps ...Dependencies) *Repository {
 		repo.chatNotifier = deps[0].ChatNotifier
 		repo.chatArchiver = deps[0].ChatArchiver
 		repo.refundStarter = deps[0].RefundStarter
+		repo.paymentProbe = deps[0].PaymentProbe
 	}
 	return repo
 }
 
+// channelPaidBeforeClose 在关闭待支付订单前跟渠道核对一次，已收款则放弃关闭。
+// 核对必须在事务外做（含渠道 HTTP 调用），渠道异常时按「未收款」继续，
+// 真漏掉的由支付回调兜底和对账任务收尾。
+func (r *Repository) channelPaidBeforeClose(ctx context.Context, orderID uint64) bool {
+	if r.paymentProbe == nil {
+		return false
+	}
+	paid, err := r.paymentProbe.ConfirmChannelPaidBeforeClose(ctx, orderID)
+	if err != nil {
+		logging.FromContext(ctx).Warn("关闭订单前核对渠道支付失败",
+			zap.String("module", "order"),
+			zap.Uint64("order_id", orderID),
+			zap.Error(err),
+		)
+		return false
+	}
+	if paid {
+		logging.FromContext(ctx).Warn("关闭订单前核对到渠道已收款，放弃关闭",
+			zap.String("module", "order"),
+			zap.Uint64("order_id", orderID),
+		)
+	}
+	return paid
+}
+
+// pendingPaymentOrderPaidAtChannel 仅对租客自己的待支付订单做渠道核对，其余情况直接放行。
+func (r *Repository) pendingPaymentOrderPaidAtChannel(ctx context.Context, userID uint64, orderID uint64) bool {
+	if r.paymentProbe == nil {
+		return false
+	}
+	var status string
+	err := r.db.WithContext(ctx).Model(&model.RentalOrder{}).
+		Where("id = ? AND renter_id = ?", orderID, userID).
+		Pluck("status", &status).Error
+	if err != nil || status != orderStatusPendingPayment {
+		return false
+	}
+	return r.channelPaidBeforeClose(ctx, orderID)
+}
+
 func (r *Repository) NotifyNewConversation(conversationID uint64) {
 	if conversationID > 0 && r.chatNotifier != nil {
 		r.chatNotifier.NotifyNewConversation(conversationID)

backend/internal/modules/order/service.go

@@ -14,6 +14,7 @@ var (
 	ErrOrderCannotPay              = errors.New("order cannot pay")
 	ErrChannelPaymentRequired      = errors.New("channel payment required")
 	ErrOrderCannotCancel           = errors.New("order cannot cancel")
+	ErrOrderPaidAtChannel          = errors.New("order already paid at channel")
 	ErrOrderCannotHandoff          = errors.New("order cannot handoff")
 	ErrOrderCannotForceHandoff     = errors.New("order cannot force handoff")
 	ErrOrderCannotResetHandoff     = errors.New("order cannot reset handoff")