chore(init): 初始化解忧商行项目并完成 Phase 0 基座

backend/internal/modules/payment/channel_adapter.go

@@ -0,0 +1,599 @@
+package payment
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"hfb_sys/backend/internal/integrations/payment/lakala"
+	"hfb_sys/backend/internal/integrations/payment/leshua"
+	"hfb_sys/backend/internal/integrations/payment/shuncheng"
+	"hfb_sys/backend/internal/modules/paymentconfig"
+)
+
+type channelClient interface {
+	CreatePayment(ctx context.Context, req channelCreatePaymentRequest) (*channelCreatePaymentResponse, error)
+	QueryPayment(ctx context.Context, thirdOrderID string, providerOrderID string) (*channelQueryPaymentResponse, error)
+	CreateRefund(ctx context.Context, req channelCreateRefundRequest) (*channelCreateRefundResponse, error)
+	QueryRefund(ctx context.Context, req channelQueryRefundRequest) (*channelQueryRefundResponse, error)
+	VerifyNotify(params map[string]string, rawPayload string, contentType string, authorization string) (channelVerifyNotifyResult, error)
+}
+
+type channelCreatePaymentRequest struct {
+	ThirdOrderID string
+	AmountCent   int64
+	PayWay       string
+	JSPayFlag    string
+	NotifyURL    string
+	JumpURL      string
+	ClientIP     string
+	Body         string
+	Attach       string
+}
+
+type channelCreatePaymentResponse struct {
+	OK              bool
+	ErrorMessage    string
+	ProviderOrderID string
+	PayWay          string
+	Status          string
+	PayTime         string
+	TDCode          string
+	JSPayURL        string
+	JSPayInfo       string
+	RawRequest      map[string]string
+	Raw             map[string]string
+}
+
+type channelQueryPaymentResponse struct {
+	OK              bool
+	ErrorMessage    string
+	ProviderOrderID string
+	Status          string
+	Amount          string
+	PayWay          string
+	PayTime         string
+	Raw             map[string]string
+}
+
+type channelCreateRefundRequest struct {
+	ThirdOrderID     string
+	ProviderOrderID  string
+	MerchantRefundID string
+	RefundAmountCent int64
+	NotifyURL        string
+	Attach           string
+	Remark           string
+	ClientIP         string
+}
+
+type channelCreateRefundResponse struct {
+	OK               bool
+	ErrorMessage     string
+	ProviderRefundID string
+	Status           string
+	RefundAmount     string
+	RawRequest       map[string]string
+	Raw              map[string]string
+}
+
+type channelQueryRefundRequest struct {
+	ThirdOrderID     string
+	ProviderOrderID  string
+	MerchantRefundID string
+	ProviderRefundID string
+}
+
+type channelQueryRefundResponse struct {
+	OK               bool
+	ErrorMessage     string
+	ProviderRefundID string
+	Status           string
+	RefundAmount     string
+	RefundTime       string
+	RawRequest       map[string]string
+	Raw              map[string]string
+}
+
+type channelVerifyNotifyResult struct {
+	OK         bool
+	MatchedKey string
+	Got        string
+	Expected   map[string]string
+	BaseString map[string]string
+	ParamKeys  []string
+}
+
+type leshuaChannel struct {
+	client *leshua.Client
+}
+
+func newLeshuaChannel(cfg leshua.Config) channelClient {
+	return leshuaChannel{client: leshua.NewClient(cfg)}
+}
+
+func (c leshuaChannel) CreatePayment(ctx context.Context, req channelCreatePaymentRequest) (*channelCreatePaymentResponse, error) {
+	resp, rawReq, err := c.client.CreatePayment(ctx, leshua.CreatePaymentRequest{
+		ThirdOrderID: req.ThirdOrderID,
+		AmountCent:   req.AmountCent,
+		PayWay:       req.PayWay,
+		JSPayFlag:    req.JSPayFlag,
+		NotifyURL:    req.NotifyURL,
+		JumpURL:      req.JumpURL,
+		ClientIP:     req.ClientIP,
+		Body:         req.Body,
+		Attach:       req.Attach,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &channelCreatePaymentResponse{
+		OK:              resp.RespCode == "0" && resp.ResultCode == "0",
+		ErrorMessage:    resp.ErrorMessage,
+		ProviderOrderID: resp.ProviderOrderID,
+		PayWay:          resp.PayWay,
+		Status:          normalizeLeshuaPaymentStatus(resp.Raw["status"]),
+		PayTime:         resp.Raw["pay_time"],
+		TDCode:          resp.TDCode,
+		JSPayURL:        resp.JSPayURL,
+		JSPayInfo:       resp.JSPayInfo,
+		RawRequest:      rawReq,
+		Raw:             resp.Raw,
+	}, nil
+}
+
+func (c leshuaChannel) QueryPayment(ctx context.Context, thirdOrderID string, providerOrderID string) (*channelQueryPaymentResponse, error) {
+	resp, err := c.client.QueryPayment(ctx, thirdOrderID, providerOrderID)
+	if err != nil {
+		return nil, err
+	}
+	return &channelQueryPaymentResponse{
+		OK:              resp.RespCode == "0" && resp.ResultCode == "0",
+		ErrorMessage:    resp.ErrorMessage,
+		ProviderOrderID: resp.ProviderOrderID,
+		Status:          normalizeLeshuaPaymentStatus(resp.Status),
+		Amount:          resp.Amount,
+		PayWay:          resp.PayWay,
+		PayTime:         resp.PayTime,
+		Raw:             resp.Raw,
+	}, nil
+}
+
+func (c leshuaChannel) CreateRefund(ctx context.Context, req channelCreateRefundRequest) (*channelCreateRefundResponse, error) {
+	resp, rawReq, err := c.client.CreateRefund(ctx, leshua.CreateRefundRequest{
+		ThirdOrderID:     req.ThirdOrderID,
+		LeshuaOrderID:    req.ProviderOrderID,
+		MerchantRefundID: req.MerchantRefundID,
+		RefundAmountCent: req.RefundAmountCent,
+		NotifyURL:        req.NotifyURL,
+		Attach:           req.Attach,
+	})
+	if err != nil {
+		if rawReq == nil {
+			return nil, err
+		}
+		return &channelCreateRefundResponse{
+			RawRequest: rawReq,
+		}, err
+	}
+	return &channelCreateRefundResponse{
+		OK:               resp.RespCode == "0" && resp.ResultCode == "0",
+		ErrorMessage:     resp.ErrorMessage,
+		ProviderRefundID: resp.LeshuaRefundID,
+		Status:           normalizeLeshuaRefundStatus(resp.Status),
+		RefundAmount:     resp.RefundAmount,
+		RawRequest:       rawReq,
+		Raw:              resp.Raw,
+	}, nil
+}
+
+func (c leshuaChannel) QueryRefund(ctx context.Context, req channelQueryRefundRequest) (*channelQueryRefundResponse, error) {
+	resp, err := c.client.QueryRefund(ctx, leshua.QueryRefundRequest{
+		ThirdOrderID:     req.ThirdOrderID,
+		LeshuaOrderID:    req.ProviderOrderID,
+		MerchantRefundID: req.MerchantRefundID,
+		LeshuaRefundID:   req.ProviderRefundID,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &channelQueryRefundResponse{
+		OK:               resp.RespCode == "0" && resp.ResultCode == "0",
+		ErrorMessage:     resp.ErrorMessage,
+		ProviderRefundID: resp.LeshuaRefundID,
+		Status:           normalizeLeshuaRefundStatus(resp.Status),
+		RefundAmount:     resp.RefundAmount,
+		RefundTime:       resp.RefundTime,
+		Raw:              resp.Raw,
+	}, nil
+}
+
+func (c leshuaChannel) VerifyNotify(params map[string]string, rawPayload string, contentType string, authorization string) (channelVerifyNotifyResult, error) {
+	verify := c.client.VerifyNotifyDetail(params)
+	result := channelVerifyNotifyResult{
+		OK:         verify.OK,
+		MatchedKey: verify.MatchedKey,
+		Got:        verify.Got,
+		Expected:   verify.Expected,
+		BaseString: verify.BaseString,
+		ParamKeys:  verify.ParamKeys,
+	}
+	if !result.OK {
+		return result, ErrPaymentVerifyFailed
+	}
+	return result, nil
+}
+
+type lakalaChannel struct {
+	client *lakala.Client
+}
+
+func newLakalaChannel(cfg lakala.Config) channelClient {
+	return lakalaChannel{client: lakala.NewClient(cfg)}
+}
+
+func (c lakalaChannel) CreatePayment(ctx context.Context, req channelCreatePaymentRequest) (*channelCreatePaymentResponse, error) {
+	resp, err := c.client.CreatePayment(ctx, lakala.CreatePaymentRequest{
+		ThirdOrderID: req.ThirdOrderID,
+		AmountCent:   req.AmountCent,
+		PayWay:       req.PayWay,
+		JSPayFlag:    req.JSPayFlag,
+		NotifyURL:    req.NotifyURL,
+		JumpURL:      req.JumpURL,
+		ClientIP:     req.ClientIP,
+		Body:         req.Body,
+		Attach:       req.Attach,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &channelCreatePaymentResponse{
+		OK:              resp.OK,
+		ErrorMessage:    resp.ErrorMessage,
+		ProviderOrderID: resp.ProviderOrderID,
+		PayWay:          resp.PayWay,
+		Status:          resp.Status,
+		PayTime:         resp.PayTime,
+		TDCode:          resp.TDCode,
+		JSPayURL:        resp.JSPayURL,
+		JSPayInfo:       resp.JSPayInfo,
+		RawRequest:      resp.RawRequest,
+		Raw:             resp.Raw,
+	}, nil
+}
+
+func (c lakalaChannel) QueryPayment(ctx context.Context, thirdOrderID string, providerOrderID string) (*channelQueryPaymentResponse, error) {
+	resp, err := c.client.QueryPayment(ctx, thirdOrderID, providerOrderID)
+	if err != nil {
+		return nil, err
+	}
+	return &channelQueryPaymentResponse{
+		OK:              resp.OK,
+		ErrorMessage:    resp.ErrorMessage,
+		ProviderOrderID: resp.ProviderOrderID,
+		Status:          resp.Status,
+		Amount:          resp.Amount,
+		PayWay:          resp.PayWay,
+		PayTime:         resp.PayTime,
+		Raw:             resp.Raw,
+	}, nil
+}
+
+func (c lakalaChannel) CreateRefund(ctx context.Context, req channelCreateRefundRequest) (*channelCreateRefundResponse, error) {
+	resp, err := c.client.CreateRefund(ctx, lakala.CreateRefundRequest{
+		ThirdOrderID:     req.ThirdOrderID,
+		ProviderOrderID:  req.ProviderOrderID,
+		MerchantRefundID: req.MerchantRefundID,
+		RefundAmountCent: req.RefundAmountCent,
+		NotifyURL:        req.NotifyURL,
+		Attach:           req.Attach,
+		RefundReason:     req.Remark,
+		ClientIP:         req.ClientIP,
+	})
+	if err != nil {
+		if resp == nil {
+			return nil, err
+		}
+		return &channelCreateRefundResponse{
+			RawRequest: resp.RawRequest,
+		}, err
+	}
+	return &channelCreateRefundResponse{
+		OK:               resp.OK,
+		ErrorMessage:     resp.ErrorMessage,
+		ProviderRefundID: resp.ProviderRefundID,
+		Status:           resp.Status,
+		RefundAmount:     resp.RefundAmount,
+		RawRequest:       resp.RawRequest,
+		Raw:              resp.Raw,
+	}, nil
+}
+
+func (c lakalaChannel) QueryRefund(ctx context.Context, req channelQueryRefundRequest) (*channelQueryRefundResponse, error) {
+	resp, err := c.client.QueryRefund(ctx, lakala.QueryRefundRequest{
+		ThirdOrderID:     req.ThirdOrderID,
+		ProviderOrderID:  req.ProviderOrderID,
+		MerchantRefundID: req.MerchantRefundID,
+		ProviderRefundID: req.ProviderRefundID,
+	})
+	if err != nil {
+		if resp == nil {
+			return nil, err
+		}
+		return &channelQueryRefundResponse{
+			RawRequest: resp.RawRequest,
+		}, err
+	}
+	return &channelQueryRefundResponse{
+		OK:               resp.OK,
+		ErrorMessage:     resp.ErrorMessage,
+		ProviderRefundID: resp.ProviderRefundID,
+		Status:           resp.Status,
+		RefundAmount:     resp.RefundAmount,
+		RefundTime:       resp.RefundTime,
+		RawRequest:       resp.RawRequest,
+		Raw:              resp.Raw,
+	}, nil
+}
+
+func (c lakalaChannel) VerifyNotify(params map[string]string, rawPayload string, contentType string, authorization string) (channelVerifyNotifyResult, error) {
+	verify := c.client.VerifyNotifyDetail(rawPayload, authorization)
+	result := channelVerifyNotifyResult{
+		OK:         verify.OK,
+		MatchedKey: verify.MatchedKey,
+		Got:        verify.Got,
+		Expected:   verify.Expected,
+		BaseString: verify.BaseString,
+		ParamKeys:  verify.ParamKeys,
+	}
+	if !result.OK {
+		return result, ErrPaymentVerifyFailed
+	}
+	return result, nil
+}
+
+type shunchengChannel struct {
+	client *shuncheng.Client
+}
+
+func newShunchengChannel(cfg shuncheng.Config) channelClient {
+	return shunchengChannel{client: shuncheng.NewClient(cfg)}
+}
+
+func (c shunchengChannel) CreatePayment(ctx context.Context, req channelCreatePaymentRequest) (*channelCreatePaymentResponse, error) {
+	resp, err := c.client.CreatePayment(ctx, shuncheng.CreatePaymentRequest{
+		ThirdOrderID: req.ThirdOrderID,
+		AmountCent:   req.AmountCent,
+		PayWay:       req.PayWay,
+		JSPayFlag:    req.JSPayFlag,
+		NotifyURL:    req.NotifyURL,
+		JumpURL:      req.JumpURL,
+		ClientIP:     req.ClientIP,
+		Body:         req.Body,
+		Attach:       req.Attach,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &channelCreatePaymentResponse{
+		OK:              resp.OK,
+		ErrorMessage:    resp.ErrorMessage,
+		ProviderOrderID: resp.ProviderOrderID,
+		PayWay:          resp.PayWay,
+		Status:          resp.Status,
+		PayTime:         resp.PayTime,
+		TDCode:          resp.TDCode,
+		JSPayURL:        resp.JSPayURL,
+		JSPayInfo:       resp.JSPayInfo,
+		RawRequest:      resp.RawRequest,
+		Raw:             resp.Raw,
+	}, nil
+}
+
+func (c shunchengChannel) QueryPayment(ctx context.Context, thirdOrderID string, providerOrderID string) (*channelQueryPaymentResponse, error) {
+	resp, err := c.client.QueryPayment(ctx, thirdOrderID, providerOrderID)
+	if err != nil {
+		return nil, err
+	}
+	return &channelQueryPaymentResponse{
+		OK:              resp.OK,
+		ErrorMessage:    resp.ErrorMessage,
+		ProviderOrderID: resp.ProviderOrderID,
+		Status:          resp.Status,
+		Amount:          resp.Amount,
+		PayWay:          resp.PayWay,
+		PayTime:         resp.PayTime,
+		Raw:             resp.Raw,
+	}, nil
+}
+
+func (c shunchengChannel) CreateRefund(ctx context.Context, req channelCreateRefundRequest) (*channelCreateRefundResponse, error) {
+	resp, err := c.client.CreateRefund(ctx, shuncheng.CreateRefundRequest{
+		ThirdOrderID:     req.ThirdOrderID,
+		ProviderOrderID:  req.ProviderOrderID,
+		MerchantRefundID: req.MerchantRefundID,
+		RefundAmountCent: req.RefundAmountCent,
+		NotifyURL:        req.NotifyURL,
+		Attach:           req.Attach,
+		RefundReason:     req.Remark,
+		ClientIP:         req.ClientIP,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &channelCreateRefundResponse{
+		OK:               resp.OK,
+		ErrorMessage:     resp.ErrorMessage,
+		ProviderRefundID: resp.ProviderRefundID,
+		Status:           resp.Status,
+		RefundAmount:     resp.RefundAmount,
+		RawRequest:       resp.RawRequest,
+		Raw:              resp.Raw,
+	}, nil
+}
+
+func (c shunchengChannel) QueryRefund(ctx context.Context, req channelQueryRefundRequest) (*channelQueryRefundResponse, error) {
+	resp, err := c.client.QueryRefund(ctx, shuncheng.QueryRefundRequest{
+		ThirdOrderID:     req.ThirdOrderID,
+		ProviderOrderID:  req.ProviderOrderID,
+		MerchantRefundID: req.MerchantRefundID,
+		ProviderRefundID: req.ProviderRefundID,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &channelQueryRefundResponse{
+		OK:               resp.OK,
+		ErrorMessage:     resp.ErrorMessage,
+		ProviderRefundID: resp.ProviderRefundID,
+		Status:           resp.Status,
+		RefundAmount:     resp.RefundAmount,
+		RefundTime:       resp.RefundTime,
+		Raw:              resp.Raw,
+	}, nil
+}
+
+func (c shunchengChannel) VerifyNotify(params map[string]string, rawPayload string, contentType string, authorization string) (channelVerifyNotifyResult, error) {
+	verify := c.client.VerifyNotifyDetail(params)
+	result := channelVerifyNotifyResult{
+		OK:         verify.OK,
+		MatchedKey: verify.MatchedKey,
+		Got:        verify.Got,
+		Expected:   verify.Expected,
+		BaseString: verify.BaseString,
+		ParamKeys:  verify.ParamKeys,
+	}
+	if !result.OK {
+		return result, ErrPaymentVerifyFailed
+	}
+	return result, nil
+}
+
+func buildChannelClient(dto *paymentconfig.ConfigDTO) (channelClient, error) {
+	switch strings.ToLower(strings.TrimSpace(dto.Provider)) {
+	case "leshua":
+		return withChannelBreaker("leshua", newLeshuaChannel(leshua.Config{
+			GatewayURL: dto.GatewayURL,
+			MerchantID: dto.MerchantID,
+			SignKey:    dto.SignKey,
+			NotifyKey:  dto.NotifyKey,
+			NotifyURL:  dto.NotifyURL,
+			JumpURL:    dto.JumpURL,
+			PayWay:     firstNonEmpty(dto.PayWay, "ZFBZF"),
+			JSPayFlag:  firstNonEmpty(dto.JSPayFlag, "2"),
+			SignType:   firstNonEmpty(dto.SignType, "MD5"),
+		})), nil
+	case "lakala":
+		return withChannelBreaker("lakala", newLakalaChannel(lakala.Config{
+			GatewayURL:         dto.GatewayURL,
+			AppID:              extraString(dto.ExtraConfig, "app_id"),
+			SerialNo:           extraString(dto.ExtraConfig, "serial_no"),
+			MerchantID:         dto.MerchantID,
+			TermNo:             extraString(dto.ExtraConfig, "term_no"),
+			PrivateKey:         dto.SignKey,
+			LakalaCert:         extraString(dto.ExtraConfig, "lakala_cert"),
+			NotifyCert:         dto.NotifyKey,
+			NotifyURL:          dto.NotifyURL,
+			JumpURL:            dto.JumpURL,
+			PayWay:             firstNonEmpty(dto.PayWay, "ZFBZF"),
+			JSPayFlag:          firstNonEmpty(dto.JSPayFlag, "2"),
+			PayMode:            extraString(dto.ExtraConfig, "pay_mode"),
+			OrderExpireMinutes: extraInt(dto.ExtraConfig, "order_expire_minutes"),
+		})), nil
+	case "shuncheng":
+		return withChannelBreaker("shuncheng", newShunchengChannel(shuncheng.Config{
+			GatewayURL:  dto.GatewayURL,
+			MerchantID:  dto.MerchantID,
+			SecretID:    extraString(dto.ExtraConfig, "secret_id"),
+			SecretKey:   dto.SignKey,
+			NotifyKey:   dto.NotifyKey,
+			NotifyURL:   dto.NotifyURL,
+			JumpURL:     dto.JumpURL,
+			PayWay:      firstNonEmpty(dto.PayWay, "ZFBZF"),
+			JSPayFlag:   firstNonEmpty(dto.JSPayFlag, "2"),
+			SignType:    firstNonEmpty(dto.SignType, "MD5"),
+			ShopNo:      extraString(dto.ExtraConfig, "shop_no"),
+			RefundType:  extraString(dto.ExtraConfig, "refund_type"),
+			TokenMargin: time.Duration(extraInt(dto.ExtraConfig, "token_refresh_margin_seconds")) * time.Second,
+		})), nil
+	case "mock":
+		return nil, nil
+	default:
+		return nil, fmt.Errorf("unsupported payment provider: %s", dto.Provider)
+	}
+}
+
+func normalizeLeshuaPaymentStatus(status string) string {
+	switch status {
+	case "2", "30":
+		return "paid"
+	case "6":
+		return "closed"
+	case "8":
+		return "failed"
+	default:
+		return "paying"
+	}
+}
+
+func normalizeLeshuaRefundStatus(status string) string {
+	switch status {
+	case "11":
+		return "refunded"
+	case "12":
+		return "failed"
+	default:
+		return "refunding"
+	}
+}
+
+func normalizeNotifyPaymentStatus(provider string, status string) string {
+	if provider == "leshua" || provider == "shuncheng" {
+		return normalizeLeshuaPaymentStatus(status)
+	}
+	switch status {
+	case "paid", "closed", "failed", "paying":
+		return status
+	default:
+		return "paying"
+	}
+}
+
+func normalizeNotifyRefundStatus(provider string, status string) string {
+	if provider == "leshua" || provider == "shuncheng" {
+		return normalizeLeshuaRefundStatus(status)
+	}
+	switch status {
+	case "refunded", "failed", "refunding":
+		return status
+	default:
+		return "refunding"
+	}
+}
+
+func extraString(config map[string]any, key string) string {
+	if config == nil {
+		return ""
+	}
+	value, ok := config[key]
+	if !ok || value == nil {
+		return ""
+	}
+	switch typed := value.(type) {
+	case string:
+		return strings.TrimSpace(typed)
+	default:
+		return strings.TrimSpace(fmt.Sprint(typed))
+	}
+}
+
+func extraInt(config map[string]any, key string) int {
+	value := extraString(config, key)
+	if value == "" {
+		return 0
+	}
+	n, _ := strconv.Atoi(value)
+	return n
+}

backend/internal/modules/payment/channel_breaker.go

@@ -0,0 +1,68 @@
+package payment
+
+import (
+	"context"
+	"time"
+
+	"github.com/sony/gobreaker/v2"
+)
+
+type breakerChannel struct {
+	next          channelClient
+	createPayment *gobreaker.CircuitBreaker[*channelCreatePaymentResponse]
+	queryPayment  *gobreaker.CircuitBreaker[*channelQueryPaymentResponse]
+	createRefund  *gobreaker.CircuitBreaker[*channelCreateRefundResponse]
+	queryRefund   *gobreaker.CircuitBreaker[*channelQueryRefundResponse]
+}
+
+func withChannelBreaker(name string, next channelClient) channelClient {
+	if next == nil {
+		return nil
+	}
+	return breakerChannel{
+		next:          next,
+		createPayment: newPaymentBreaker[*channelCreatePaymentResponse](name + ".create_payment"),
+		queryPayment:  newPaymentBreaker[*channelQueryPaymentResponse](name + ".query_payment"),
+		createRefund:  newPaymentBreaker[*channelCreateRefundResponse](name + ".create_refund"),
+		queryRefund:   newPaymentBreaker[*channelQueryRefundResponse](name + ".query_refund"),
+	}
+}
+
+func newPaymentBreaker[T any](name string) *gobreaker.CircuitBreaker[T] {
+	return gobreaker.NewCircuitBreaker[T](gobreaker.Settings{
+		Name:        name,
+		MaxRequests: 3,
+		Timeout:     10 * time.Second,
+		ReadyToTrip: func(counts gobreaker.Counts) bool {
+			return counts.ConsecutiveFailures >= 5
+		},
+	})
+}
+
+func (c breakerChannel) CreatePayment(ctx context.Context, req channelCreatePaymentRequest) (*channelCreatePaymentResponse, error) {
+	return c.createPayment.Execute(func() (*channelCreatePaymentResponse, error) {
+		return c.next.CreatePayment(ctx, req)
+	})
+}
+
+func (c breakerChannel) QueryPayment(ctx context.Context, thirdOrderID string, providerOrderID string) (*channelQueryPaymentResponse, error) {
+	return c.queryPayment.Execute(func() (*channelQueryPaymentResponse, error) {
+		return c.next.QueryPayment(ctx, thirdOrderID, providerOrderID)
+	})
+}
+
+func (c breakerChannel) CreateRefund(ctx context.Context, req channelCreateRefundRequest) (*channelCreateRefundResponse, error) {
+	return c.createRefund.Execute(func() (*channelCreateRefundResponse, error) {
+		return c.next.CreateRefund(ctx, req)
+	})
+}
+
+func (c breakerChannel) QueryRefund(ctx context.Context, req channelQueryRefundRequest) (*channelQueryRefundResponse, error) {
+	return c.queryRefund.Execute(func() (*channelQueryRefundResponse, error) {
+		return c.next.QueryRefund(ctx, req)
+	})
+}
+
+func (c breakerChannel) VerifyNotify(params map[string]string, rawPayload string, contentType string, authorization string) (channelVerifyNotifyResult, error) {
+	return c.next.VerifyNotify(params, rawPayload, contentType, authorization)
+}

backend/internal/modules/payment/channel_probe.go

@@ -0,0 +1,89 @@
+package payment
+
+import (
+	"context"
+
+	"hfb_sys/backend/internal/model"
+
+	"go.uber.org/zap"
+)
+
+// ConfirmChannelPaidBeforeClose 在取消或关闭订单前跟渠道核对未完成的下单支付单。
+// 返回 true 表示渠道确认已收款且订单已被推进，调用方必须放弃本次取消。
+//
+// 待支付订单的 15 分钟超时和用户手动取消都可能正好撞上用户付款：
+// 订单先没了，渠道结果几秒后才到，于是钱收了、订单却是已取消。
+// 先核对一次能把绝大多数这种竞态挡在发生之前——而且是让支付正常入账，不必退款。
+func (r *Repository) ConfirmChannelPaidBeforeClose(ctx context.Context, orderID uint64) (bool, error) {
+	if r == nil || r.db == nil || orderID == 0 {
+		return false, nil
+	}
+	payments, err := r.pendingOrderPayments(ctx, orderID)
+	if err != nil {
+		return false, err
+	}
+	advanced := false
+	for i := range payments {
+		if err := r.probeChannelPaid(ctx, &payments[i]); err != nil {
+			// 渠道不可用不能阻塞取消，否则渠道一挂订单就全卡住。
+			// 真漏掉的由支付回调兜底记账并告警。
+			r.log().Warn("取消前核对渠道支付状态失败", paymentLogFields(ctx, appendFields(
+				paymentOrderFields(&payments[i]),
+				[]zap.Field{zap.Error(err)},
+			)...,
+			)...)
+			continue
+		}
+		// 以订单是否真的被推进为准。钱到了但商品已被他人租走时，入账路径只会记账
+		// 并告警等人工退款，不推进订单，这种情况仍然该让取消照常进行。
+		if orderAdvancedPastPayment(r.orderStatus(ctx, orderID)) {
+			advanced = true
+		}
+	}
+	return advanced, nil
+}
+
+// orderAdvancedPastPayment 判断订单是否已经靠这笔支付走出待支付阶段。
+func orderAdvancedPastPayment(status string) bool {
+	return status == "pending_handoff" || status == "renting"
+}
+
+// probeChannelPaid 向渠道查询一笔支付单的真实状态并落库。
+func (r *Repository) probeChannelPaid(ctx context.Context, payment *model.PaymentOrder) error {
+	if payment.ProviderOrderID == "" {
+		// 没有渠道单号说明下单请求没被渠道受理，不可能收到钱。
+		return nil
+	}
+	runtimeConfig, err := r.runtimeConfigForPayment(ctx, payment)
+	if err != nil {
+		return err
+	}
+	if runtimeConfig.isMockMode() || runtimeConfig.Channel == nil {
+		return nil
+	}
+	resp, err := runtimeConfig.Channel.QueryPayment(ctx, payment.ThirdOrderID, payment.ProviderOrderID)
+	if err != nil {
+		return err
+	}
+	if resp.Status != "paid" {
+		return nil
+	}
+	r.log().Warn("渠道核对到已收款但系统未入账", paymentLogFields(ctx, appendFields(
+		paymentOrderFields(payment),
+		runtimeConfigFields(runtimeConfig),
+		[]zap.Field{zap.String("order_status", r.orderStatus(ctx, payment.OrderID))},
+	)...,
+	)...)
+	// 走统一入账路径：订单还能支付就正常推进，已经结束就只记账并告警等人工退款。
+	return r.applyChannelStatus(ctx, payment, resp.Status, resp.PayTime, resp.Raw, channelSourceQuery)
+}
+
+func (r *Repository) pendingOrderPayments(ctx context.Context, orderID uint64) ([]model.PaymentOrder, error) {
+	var rows []model.PaymentOrder
+	err := r.db.WithContext(ctx).
+		Where("order_id = ? AND biz_type = ? AND status IN ? AND provider_order_id <> ''",
+			orderID, "order_pay", []string{"created", "paying"}).
+		Order("id DESC").
+		Find(&rows).Error
+	return rows, err
+}

backend/internal/modules/payment/channel_status.go

@@ -0,0 +1,118 @@
+package payment
+
+import (
+	"context"
+	"hfb_sys/backend/internal/model"
+	"hfb_sys/backend/internal/modules/distribution"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+func (r *Repository) applyChannelStatus(ctx context.Context, payment *model.PaymentOrder, status string, payTime string, raw map[string]string, source string) error {
+	switch status {
+	case "paid":
+		paidAt := parseChannelTime(payTime)
+		if paidAt == nil {
+			now := time.Now()
+			paidAt = &now
+		}
+		return r.confirmPaid(ctx, payment, status, *paidAt, raw, source)
+	case "closed":
+		return r.updateChannelStatus(ctx, payment.ID, "closed", raw, source)
+	case "failed":
+		return r.updateChannelStatus(ctx, payment.ID, "failed", raw, source)
+	default:
+		return r.updateChannelStatus(ctx, payment.ID, "paying", raw, source)
+	}
+}
+func (r *Repository) updateChannelStatus(ctx context.Context, paymentID uint64, status string, raw map[string]string, source string) error {
+	updates := map[string]any{
+		"status":       status,
+		"raw_response": jsonMap(withRawSource(raw, source)),
+	}
+	if source == channelSourceNotify {
+		updates["notified_at"] = time.Now()
+	}
+	return r.db.WithContext(ctx).Model(&model.PaymentOrder{}).
+		Where("id = ? AND status NOT IN ?", paymentID, []string{"paid", "closed", "failed"}).
+		Updates(updates).Error
+}
+
+// isOrderPaymentTerminalStatus 判断订单支付流水是否已进入终态，终态不再被查询或普通回调刷回支付中。
+func isOrderPaymentTerminalStatus(status string) bool {
+	return status == "paid" || status == "closed" || status == "failed"
+}
+func (r *Repository) confirmPaid(ctx context.Context, payment *model.PaymentOrder, status string, paidAt time.Time, raw map[string]string, source string) error {
+	var newConvID uint64
+	var notifyFn func(uint64)
+	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if payment.OrderID != 0 {
+			switch payment.BizType {
+			case "mohong_pay":
+				if r.mohongRepo == nil {
+					return ErrDependencyUnavailable
+				}
+				convID, err := r.mohongRepo.ConfirmPaidFromChannelTx(tx, payment.OrderID)
+				if err != nil {
+					return err
+				}
+				newConvID = convID
+				notifyFn = r.mohongRepo.NotifyNewConversation
+			default:
+				if r.orderRepo == nil {
+					return ErrDependencyUnavailable
+				}
+				convID, err := r.orderRepo.ConfirmPaidFromChannelTx(tx, payment.OrderID)
+				if err != nil {
+					return err
+				}
+				newConvID = convID
+				notifyFn = r.orderRepo.NotifyNewConversation
+				if err := distribution.SnapshotPaidOrderTx(tx, payment.OrderID, payment.AmountCent); err != nil {
+					return err
+				}
+			}
+		}
+
+		var latest model.PaymentOrder
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&latest, payment.ID).Error; err != nil {
+			return err
+		}
+		updates := map[string]any{
+			"status":            "paid",
+			"provider_order_id": firstNonEmpty(raw["provider_order_id"], raw["schc_order_id"], raw["leshua_order_id"], raw["pay_order_no"], raw["trade_no"], latest.ProviderOrderID),
+			"raw_response":      jsonMap(withRawSource(raw, source)),
+			"paid_at":           paidAt,
+		}
+		if source == channelSourceNotify {
+			updates["notified_at"] = time.Now()
+		}
+		return tx.Model(&model.PaymentOrder{}).Where("id = ?", payment.ID).Updates(updates).Error
+	})
+	if err != nil {
+		if settleErr, handled := r.settleUnpayableOrderPayment(ctx, payment, paidAt, raw, source, err); handled {
+			return settleErr
+		}
+		return err
+	}
+	if newConvID > 0 && notifyFn != nil {
+		notifyFn(newConvID)
+	}
+	if latest, err := r.findPaymentByID(ctx, payment.ID); err == nil {
+		if runtimeConfig, err := r.runtimeConfigForPayment(ctx, latest); err == nil {
+			r.recordConfigUsage(ctx, runtimeConfig, latest)
+		}
+	}
+	return nil
+}
+func (r *Repository) markPaymentFailed(ctx context.Context, paymentID uint64, raw map[string]string, message string) error {
+	if raw == nil {
+		raw = map[string]string{"error": message}
+	}
+	return r.db.WithContext(ctx).Model(&model.PaymentOrder{}).Where("id = ?", paymentID).Updates(map[string]any{
+		"status":       "failed",
+		"raw_response": jsonMap(raw),
+	}).Error
+}

backend/internal/modules/payment/dto.go

@@ -0,0 +1,102 @@
+package payment
+
+import (
+	"time"
+
+	"gorm.io/datatypes"
+)
+
+type StartPaymentRequest struct {
+	PayWay    string `json:"pay_way"`
+	JSPayFlag string `json:"jspay_flag"`
+}
+
+type StartMohongRefundRequest struct {
+	AmountCent int64  `json:"amount_cent"`
+	Remark     string `json:"remark"`
+}
+
+type PaymentDTO struct {
+	ID              uint64     `json:"id"`
+	PaymentNo       string     `json:"payment_no"`
+	OrderID         uint64     `json:"order_id"`
+	OrderNo         string     `json:"order_no"`
+	PaymentConfigID uint64     `json:"payment_config_id"`
+	Provider        string     `json:"provider"`
+	ThirdOrderID    string     `json:"third_order_id"`
+	ProviderOrderID string     `json:"provider_order_id"`
+	PayWay          string     `json:"pay_way"`
+	JSPayFlag       string     `json:"jspay_flag"`
+	AmountCent      int64      `json:"amount_cent"`
+	Status          string     `json:"status"`
+	TDCode          string     `json:"td_code,omitempty"`
+	JSPayURL        string     `json:"jspay_url,omitempty"`
+	JSPayInfo       string     `json:"jspay_info,omitempty"`
+	Paid            bool       `json:"paid"`
+	PaidAt          *time.Time `json:"paid_at,omitempty"`
+	CreatedAt       time.Time  `json:"created_at"`
+	UpdatedAt       time.Time  `json:"updated_at"`
+}
+
+type RefundDTO struct {
+	ID              uint64     `json:"id"`
+	PaymentNo       string     `json:"payment_no"`
+	OrderID         uint64     `json:"order_id"`
+	OrderNo         string     `json:"order_no"`
+	BizType         string     `json:"biz_type"`
+	AmountCent      int64      `json:"amount_cent"`
+	Status          string     `json:"status"`
+	ProviderOrderID string     `json:"provider_order_id,omitempty"`
+	PaidAt          *time.Time `json:"paid_at,omitempty"`
+	CreatedAt       time.Time  `json:"created_at"`
+	UpdatedAt       time.Time  `json:"updated_at"`
+}
+
+type NotifyResult struct {
+	OK      bool
+	Message string
+}
+
+type AdminPaymentQuery struct {
+	UserID   uint64
+	OrderID  uint64
+	OrderNo  string
+	BizType  string
+	Status   string
+	Provider string
+	Page     int
+	PageSize int
+}
+
+type PaginatedResult struct {
+	Items    interface{} `json:"items"`
+	Total    int64       `json:"total"`
+	Page     int         `json:"page"`
+	PageSize int         `json:"page_size"`
+}
+
+type AdminPaymentDTO struct {
+	ID              uint64         `json:"id"`
+	PaymentNo       string         `json:"payment_no"`
+	OrderID         uint64         `json:"order_id"`
+	OrderNo         string         `json:"order_no"`
+	UserID          uint64         `json:"user_id"`
+	PaymentConfigID uint64         `json:"payment_config_id"`
+	UserPhone       string         `json:"user_phone"`
+	Provider        string         `json:"provider"`
+	MerchantID      string         `json:"merchant_id"`
+	ThirdOrderID    string         `json:"third_order_id"`
+	ProviderOrderID string         `json:"provider_order_id"`
+	PayWay          string         `json:"pay_way"`
+	AmountCent      int64          `json:"amount_cent"`
+	BizType         string         `json:"biz_type"`
+	Status          string         `json:"status"`
+	ErrorCode       string         `json:"error_code"`
+	ErrorMessage    string         `json:"error_message"`
+	RawRequest      datatypes.JSON `json:"raw_request"`
+	RawResponse     datatypes.JSON `json:"raw_response"`
+	PaidAt          *time.Time     `json:"paid_at,omitempty"`
+	NotifiedAt      *time.Time     `json:"notified_at,omitempty"`
+	CreatedAt       time.Time      `json:"created_at"`
+	UpdatedAt       time.Time      `json:"updated_at"`
+}

backend/internal/modules/payment/handler.go

@@ -0,0 +1,332 @@
+package payment
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strconv"
+
+	"hfb_sys/backend/internal/integrations/payment/lakala"
+	"hfb_sys/backend/internal/integrations/payment/leshua"
+	"hfb_sys/backend/internal/integrations/payment/shuncheng"
+	"hfb_sys/backend/internal/middleware"
+	"hfb_sys/backend/internal/modules/order"
+	"hfb_sys/backend/pkg/response"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+)
+
+type Handler struct {
+	service *Service
+	logger  *zap.Logger
+}
+
+func NewHandler(service *Service, options ...HandlerOption) *Handler {
+	handler := &Handler{
+		service: service,
+		logger:  zap.NewNop(),
+	}
+	for _, option := range options {
+		option(handler)
+	}
+	if handler.logger == nil {
+		handler.logger = zap.NewNop()
+	}
+	return handler
+}
+
+type HandlerOption func(*Handler)
+
+// WithHandlerLogger 为支付 HTTP 处理器注入结构化日志器。
+func WithHandlerLogger(logger *zap.Logger) HandlerOption {
+	return func(handler *Handler) {
+		if logger != nil {
+			handler.logger = logger
+		}
+	}
+}
+
+func (h *Handler) log() *zap.Logger {
+	if h == nil || h.logger == nil {
+		return zap.NewNop()
+	}
+	return h.logger
+}
+
+func notifyLogFields(ctx context.Context, provider string, params map[string]string, contentType string, bodySize int, fields ...zap.Field) []zap.Field {
+	base := paymentLogFields(ctx,
+		zap.String("provider", provider),
+		zap.String("third_order_id", params["third_order_id"]),
+		zap.String("provider_order_id", firstNonEmpty(params["provider_order_id"], params["leshua_order_id"], params["schc_order_id"])),
+		zap.String("merchant_refund_id", params["merchant_refund_id"]),
+		zap.String("provider_refund_id", firstNonEmpty(params["provider_refund_id"], params["leshua_refund_id"], params["schc_refund_id"])),
+		zap.String("status", params["status"]),
+		zap.String("amount", params["amount"]),
+		zap.String("content_type", contentType),
+		zap.Int("body_size", bodySize),
+	)
+	return append(base, fields...)
+}
+
+func (h *Handler) Start(c *gin.Context) {
+	userID, ok := currentUserID(c)
+	if !ok {
+		response.Unauthorized(c, "缺少用户上下文")
+		return
+	}
+	orderID, ok := parseID(c)
+	if !ok {
+		return
+	}
+	var req StartPaymentRequest
+	_ = c.ShouldBindJSON(&req)
+	item, err := h.service.Start(c.Request.Context(), userID, orderID, req, c.ClientIP())
+	if err != nil {
+		writePaymentError(c, err)
+		return
+	}
+	response.OK(c, item)
+}
+
+func (h *Handler) StartMohong(c *gin.Context) {
+	userID, ok := currentUserID(c)
+	if !ok {
+		response.Unauthorized(c, "缺少用户上下文")
+		return
+	}
+	orderID, ok := parseID(c)
+	if !ok {
+		return
+	}
+	var req StartPaymentRequest
+	_ = c.ShouldBindJSON(&req)
+	item, err := h.service.StartMohong(c.Request.Context(), userID, orderID, req, c.ClientIP())
+	if err != nil {
+		writePaymentError(c, err)
+		return
+	}
+	response.OK(c, item)
+}
+
+func (h *Handler) Query(c *gin.Context) {
+	userID, ok := currentUserID(c)
+	if !ok {
+		response.Unauthorized(c, "缺少用户上下文")
+		return
+	}
+	orderID, ok := parseID(c)
+	if !ok {
+		return
+	}
+	item, err := h.service.Query(c.Request.Context(), userID, orderID)
+	if err != nil {
+		writePaymentError(c, err)
+		return
+	}
+	response.OK(c, item)
+}
+
+func (h *Handler) QueryMohong(c *gin.Context) {
+	userID, ok := currentUserID(c)
+	if !ok {
+		response.Unauthorized(c, "缺少用户上下文")
+		return
+	}
+	orderID, ok := parseID(c)
+	if !ok {
+		return
+	}
+	item, err := h.service.QueryMohong(c.Request.Context(), userID, orderID)
+	if err != nil {
+		writePaymentError(c, err)
+		return
+	}
+	response.OK(c, item)
+}
+
+func (h *Handler) AdminRefundMohong(c *gin.Context) {
+	orderID, ok := parseID(c)
+	if !ok {
+		return
+	}
+	var req StartMohongRefundRequest
+	if err := c.ShouldBindJSON(&req); err != nil && !errors.Is(err, io.EOF) {
+		response.BadRequest(c, "请求参数不正确")
+		return
+	}
+	item, err := h.service.StartMohongRefund(c.Request.Context(), orderID, req.AmountCent, req.Remark)
+	if err != nil {
+		writePaymentError(c, err)
+		return
+	}
+	response.OK(c, item)
+}
+
+func (h *Handler) QueryRefundStatus(c *gin.Context) {
+	orderID, ok := parseID(c)
+	if !ok {
+		return
+	}
+	item, err := h.service.QueryRefundStatus(c.Request.Context(), orderID)
+	if err != nil {
+		writePaymentError(c, err)
+		return
+	}
+	response.OK(c, item)
+}
+
+func (h *Handler) AdminList(c *gin.Context) {
+	query, ok := parseAdminPaymentQuery(c)
+	if !ok {
+		return
+	}
+	result, err := h.service.AdminList(c.Request.Context(), query)
+	if err != nil {
+		writePaymentError(c, err)
+		return
+	}
+	response.OK(c, result)
+}
+
+func (h *Handler) LeshuaNotify(c *gin.Context) {
+	body, err := io.ReadAll(io.LimitReader(c.Request.Body, 1<<20))
+	if err != nil {
+		c.String(http.StatusBadRequest, "FAIL")
+		return
+	}
+	params, err := leshua.ParsePayload(body)
+	if err != nil {
+		c.String(http.StatusBadRequest, "FAIL")
+		return
+	}
+	rawPayload := string(body)
+	contentType := c.GetHeader("Content-Type")
+	result, err := h.service.HandleLeshuaNotify(c.Request.Context(), params, rawPayload, contentType)
+	if err != nil || result == nil || !result.OK {
+		h.log().Warn("支付回调处理失败", notifyLogFields(c.Request.Context(), "leshua", params, contentType, len(body), zap.Error(err))...)
+		c.String(http.StatusOK, "FAIL")
+		return
+	}
+	h.log().Info("支付回调处理完成", notifyLogFields(c.Request.Context(), "leshua", params, contentType, len(body))...)
+	c.String(http.StatusOK, result.Message)
+}
+
+func (h *Handler) LakalaNotify(c *gin.Context) {
+	body, err := io.ReadAll(io.LimitReader(c.Request.Body, 1<<20))
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{"code": "FAIL", "message": "读取失败"})
+		return
+	}
+	params, err := lakala.ParsePayload(body)
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{"code": "FAIL", "message": "解析失败"})
+		return
+	}
+	rawPayload := string(body)
+	contentType := c.GetHeader("Content-Type")
+	authorization := c.GetHeader("Authorization")
+	result, err := h.service.HandleNotify(c.Request.Context(), "lakala", params, rawPayload, contentType, authorization)
+	if err != nil || result == nil || !result.OK {
+		h.log().Warn("支付回调处理失败", notifyLogFields(c.Request.Context(), "lakala", params, contentType, len(body), zap.Error(err))...)
+		c.JSON(http.StatusOK, gin.H{"code": "FAIL", "message": "失败"})
+		return
+	}
+	h.log().Info("支付回调处理完成", notifyLogFields(c.Request.Context(), "lakala", params, contentType, len(body))...)
+	c.JSON(http.StatusOK, gin.H{"code": "SUCCESS", "message": "执行成功"})
+}
+
+func (h *Handler) ShunchengNotify(c *gin.Context) {
+	body, err := io.ReadAll(io.LimitReader(c.Request.Body, 1<<20))
+	if err != nil {
+		c.String(http.StatusOK, "FAIL")
+		return
+	}
+	params, err := shuncheng.ParsePayload(body)
+	if err != nil {
+		c.String(http.StatusOK, "FAIL")
+		return
+	}
+	rawPayload := string(body)
+	contentType := c.GetHeader("Content-Type")
+	authorization := c.GetHeader("Authorization")
+	result, err := h.service.HandleNotify(c.Request.Context(), "shuncheng", params, rawPayload, contentType, authorization)
+	if err != nil || result == nil || !result.OK {
+		h.log().Warn("支付回调处理失败", notifyLogFields(c.Request.Context(), "shuncheng", params, contentType, len(body), zap.Error(err))...)
+		c.String(http.StatusOK, "FAIL")
+		return
+	}
+	h.log().Info("支付回调处理完成", notifyLogFields(c.Request.Context(), "shuncheng", params, contentType, len(body))...)
+	c.String(http.StatusOK, result.Message)
+}
+
+func currentUserID(c *gin.Context) (uint64, bool) {
+	value, ok := c.Get(middleware.ContextUserID)
+	if !ok {
+		return 0, false
+	}
+	userID, ok := value.(uint64)
+	return userID, ok
+}
+
+func parseID(c *gin.Context) (uint64, bool) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil || id == 0 {
+		response.BadRequest(c, "ID 不正确")
+		return 0, false
+	}
+	return id, true
+}
+
+func parseAdminPaymentQuery(c *gin.Context) (AdminPaymentQuery, bool) {
+	var query AdminPaymentQuery
+	if raw := c.Query("user_id"); raw != "" {
+		value, err := strconv.ParseUint(raw, 10, 64)
+		if err != nil || value == 0 {
+			response.BadRequest(c, "用户ID不正确")
+			return query, false
+		}
+		query.UserID = value
+	}
+	if raw := c.Query("order_id"); raw != "" {
+		value, err := strconv.ParseUint(raw, 10, 64)
+		if err != nil || value == 0 {
+			response.BadRequest(c, "订单ID不正确")
+			return query, false
+		}
+		query.OrderID = value
+	}
+	query.OrderNo = c.Query("order_no")
+	query.BizType = c.Query("biz_type")
+	query.Status = c.Query("status")
+	query.Provider = c.Query("provider")
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
+	query.Page = page
+	query.PageSize = pageSize
+	return query, true
+}
+
+func writePaymentError(c *gin.Context, err error) {
+	response.RecordError(c, err)
+	switch {
+	case errors.Is(err, ErrDependencyUnavailable):
+		response.ServiceUnavailable(c, "数据库未连接")
+	case errors.Is(err, ErrPaymentUnavailable):
+		response.Error(c, http.StatusBadGateway, "payment_unavailable", "支付渠道暂不可用")
+	case errors.Is(err, ErrPaymentCannotStart), errors.Is(err, order.ErrOrderCannotPay):
+		response.Error(c, http.StatusConflict, "payment_cannot_start", "当前订单不能支付")
+	case errors.Is(err, ErrRefundCannotStart):
+		response.Error(c, http.StatusConflict, "refund_cannot_start", "当前订单不能退款")
+	case errors.Is(err, ErrPaymentVerifyFailed):
+		response.Error(c, http.StatusForbidden, "payment_verify_failed", "支付通知验签失败")
+	case errors.Is(err, ErrPaymentNotFound), errors.Is(err, gorm.ErrRecordNotFound), order.IsNotFound(err):
+		response.Error(c, http.StatusNotFound, "payment_not_found", "支付单不存在")
+	case errors.Is(err, order.ErrListingUnavailable):
+		response.Error(c, http.StatusConflict, "listing_unavailable", "该账号暂不可租")
+	default:
+		response.Error(c, http.StatusInternalServerError, "payment_error", "支付处理失败")
+	}
+}

backend/internal/modules/payment/late_paid.go

@@ -0,0 +1,113 @@
+package payment
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"hfb_sys/backend/internal/model"
+	"hfb_sys/backend/internal/modules/order"
+
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+// isOrderUnpayable 判断订单侧的报错是否属于「钱已到渠道，但订单再也无法入账」。
+// 订单被取消或关单后回调才到属于前者，商品被他人抢租属于后者。
+func isOrderUnpayable(err error) bool {
+	return errors.Is(err, order.ErrOrderCannotPay) || errors.Is(err, order.ErrListingUnavailable)
+}
+
+func unpayableReason(err error) string {
+	switch {
+	case errors.Is(err, order.ErrOrderCannotPay):
+		return "order_not_payable"
+	case errors.Is(err, order.ErrListingUnavailable):
+		return "listing_unavailable"
+	default:
+		return "unknown"
+	}
+}
+
+// settleUnpayableOrderPayment 处理「渠道已收款、订单却无法入账」。
+//
+// 钱已经进了商户账户，这个事实必须先落库：把支付单如实记成已支付。
+// 如果让订单侧的报错把整笔事务回滚，支付单会停在「支付中」且 paid_at 为空，
+// 这时候既补不回入账（订单已不是待支付），也退不出去——后台人工退款要求
+// 原支付单是已支付，所以连客服都无能为力，钱就彻底对不上了。
+//
+// 这里只记账并告警，不自动退款：退款由客服在后台确认后人工发起，
+// 落账之后后台的人工退款就能正常走通。
+func (r *Repository) settleUnpayableOrderPayment(ctx context.Context, payment *model.PaymentOrder, paidAt time.Time, raw map[string]string, source string, cause error) (error, bool) {
+	if payment == nil || payment.BizType != "order_pay" || !isOrderUnpayable(cause) {
+		return nil, false
+	}
+	reason := unpayableReason(cause)
+	logFields := func(extra ...zap.Field) []zap.Field {
+		return paymentLogFields(ctx, appendFields(
+			paymentOrderFields(payment),
+			[]zap.Field{
+				zap.String("channel_source", source),
+				zap.String("unpayable_reason", reason),
+				zap.String("order_status", r.orderStatus(ctx, payment.OrderID)),
+			},
+			extra,
+		)...)
+	}
+
+	if err := r.markOrderPaymentPaid(ctx, payment, paidAt, withUnpayableDiagnostic(raw, reason), source); err != nil {
+		r.log().Error("渠道已收款但支付单落账失败", logFields(zap.Error(err))...)
+		return err, true
+	}
+	// 返回 nil 让渠道停止重试：重试解决不了问题，只会把同一条告警刷十遍。
+	r.log().Error("渠道已收款但订单无法入账，需人工退款", logFields()...)
+	return nil, true
+}
+
+// markOrderPaymentPaid 只更新支付单自身，不碰订单状态，用于订单已无法推进时如实记录收款。
+func (r *Repository) markOrderPaymentPaid(ctx context.Context, payment *model.PaymentOrder, paidAt time.Time, raw map[string]string, source string) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var latest model.PaymentOrder
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&latest, payment.ID).Error; err != nil {
+			return err
+		}
+		if latest.Status == "paid" && latest.PaidAt != nil {
+			return nil
+		}
+		updates := map[string]any{
+			"status":            "paid",
+			"provider_order_id": firstNonEmpty(raw["provider_order_id"], raw["schc_order_id"], raw["leshua_order_id"], raw["pay_order_no"], raw["trade_no"], latest.ProviderOrderID),
+			"raw_response":      jsonMap(withRawSource(raw, source)),
+			"paid_at":           paidAt,
+		}
+		if source == channelSourceNotify {
+			updates["notified_at"] = time.Now()
+		}
+		return tx.Model(&model.PaymentOrder{}).Where("id = ?", payment.ID).Updates(updates).Error
+	})
+}
+
+// withUnpayableDiagnostic 在 raw_response 里留下排查标记，后台支付列表可以直接看到原因。
+func withUnpayableDiagnostic(raw map[string]string, reason string) map[string]string {
+	out := make(map[string]string, len(raw)+2)
+	for key, value := range raw {
+		out[key] = value
+	}
+	out["_order_unpayable_reason"] = reason
+	out["_manual_refund_required"] = "true"
+	return out
+}
+
+func (r *Repository) orderStatus(ctx context.Context, orderID uint64) string {
+	if orderID == 0 {
+		return ""
+	}
+	var status string
+	if err := r.db.WithContext(ctx).Model(&model.RentalOrder{}).
+		Where("id = ?", orderID).
+		Pluck("status", &status).Error; err != nil {
+		return ""
+	}
+	return status
+}

backend/internal/modules/payment/late_paid_test.go

@@ -0,0 +1,163 @@
+package payment
+
+import (
+	"errors"
+	"testing"
+	"time"
+
+	"hfb_sys/backend/internal/model"
+	ordermodule "hfb_sys/backend/internal/modules/order"
+)
+
+// TestConfirmPaidSettlesPaymentWhenOrderAlreadyCancelled 钉住本次事故的根因：
+// 渠道回调带着「已支付」到达，而订单已经被取消。原先订单侧报 ErrOrderCannotPay 会把
+// 整笔事务回滚，支付单停在 paying 且 paid_at 为空，于是钱收了却既补不回入账
+// （订单不再是待支付），也退不出去——后台人工退款要求原支付单是已支付。
+// 现在必须如实把支付单记成已支付，人工退款才有的可退。
+func TestConfirmPaidSettlesPaymentWhenOrderAlreadyCancelled(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	repo := NewRepository(db, nil, ordermodule.NewRepository(db))
+	fixture := createPayableOrderFixture(t, db, "LP01", true)
+	if err := db.Model(&model.RentalOrder{}).Where("id = ?", fixture.Order.ID).
+		Updates(map[string]any{"status": "cancelled", "handoff_status": "cancelled"}).Error; err != nil {
+		t.Fatalf("cancel order failed: %v", err)
+	}
+
+	paidAt := time.Date(2026, 9, 15, 23, 22, 47, 0, time.UTC)
+	if err := repo.confirmPaid(t.Context(), &fixture.Payment, "paid", paidAt, map[string]string{
+		"provider_order_id": "PROVIDERLP01",
+	}, channelSourceNotify); err != nil {
+		t.Fatalf("confirmPaid() error = %v, want nil so the channel stops retrying", err)
+	}
+
+	var payment model.PaymentOrder
+	if err := db.First(&payment, fixture.Payment.ID).Error; err != nil {
+		t.Fatalf("find payment failed: %v", err)
+	}
+	if payment.Status != "paid" {
+		t.Fatalf("payment status = %q, want paid", payment.Status)
+	}
+	if payment.PaidAt == nil {
+		t.Fatal("payment paid_at = nil, want the channel pay time")
+	}
+	if payment.ProviderOrderID != "PROVIDERLP01" {
+		t.Fatalf("provider order id = %q, want PROVIDERLP01", payment.ProviderOrderID)
+	}
+
+	var order model.RentalOrder
+	if err := db.First(&order, fixture.Order.ID).Error; err != nil {
+		t.Fatalf("find order failed: %v", err)
+	}
+	if order.Status != "cancelled" {
+		t.Fatalf("order status = %q, want cancelled (payment must not revive it)", order.Status)
+	}
+}
+
+// TestConfirmPaidDoesNotAutoRefundUnpayableOrder 退款一律由客服人工发起，
+// 入账路径不能自己动钱。
+func TestConfirmPaidDoesNotAutoRefundUnpayableOrder(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	repo := NewRepository(db, nil, ordermodule.NewRepository(db))
+	fixture := createPayableOrderFixture(t, db, "LP02", true)
+	if err := db.Model(&model.RentalOrder{}).Where("id = ?", fixture.Order.ID).
+		Update("status", "closed").Error; err != nil {
+		t.Fatalf("close order failed: %v", err)
+	}
+
+	if err := repo.confirmPaid(t.Context(), &fixture.Payment, "paid", time.Now(), map[string]string{
+		"provider_order_id": "PROVIDERLP02",
+	}, channelSourceNotify); err != nil {
+		t.Fatalf("confirmPaid() error = %v", err)
+	}
+
+	var refundCount int64
+	if err := db.Model(&model.PaymentOrder{}).
+		Where("order_id = ? AND biz_type <> ?", fixture.Order.ID, "order_pay").
+		Count(&refundCount).Error; err != nil {
+		t.Fatalf("count refunds failed: %v", err)
+	}
+	if refundCount != 0 {
+		t.Fatalf("refund payment count = %d, want 0 (refund must stay manual)", refundCount)
+	}
+
+	var order model.RentalOrder
+	if err := db.First(&order, fixture.Order.ID).Error; err != nil {
+		t.Fatalf("find order failed: %v", err)
+	}
+	if order.RefundStatus == "refunded" || order.RefundStatus == "refunding" {
+		t.Fatalf("order refund status = %q, want untouched", order.RefundStatus)
+	}
+}
+
+// TestConfirmPaidSettlementIsIdempotent 乐刷会重试十次同一个回调，重复落账不能出错。
+func TestConfirmPaidSettlementIsIdempotent(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	repo := NewRepository(db, nil, ordermodule.NewRepository(db))
+	fixture := createPayableOrderFixture(t, db, "LP03", true)
+	if err := db.Model(&model.RentalOrder{}).Where("id = ?", fixture.Order.ID).
+		Update("status", "cancelled").Error; err != nil {
+		t.Fatalf("cancel order failed: %v", err)
+	}
+
+	paidAt := time.Date(2026, 9, 15, 23, 22, 47, 0, time.UTC)
+	for i := 0; i < 3; i++ {
+		if err := repo.confirmPaid(t.Context(), &fixture.Payment, "paid", paidAt.Add(time.Duration(i)*time.Minute), map[string]string{
+			"provider_order_id": "PROVIDERLP03",
+		}, channelSourceNotify); err != nil {
+			t.Fatalf("confirmPaid() attempt %d error = %v", i+1, err)
+		}
+	}
+
+	var payment model.PaymentOrder
+	if err := db.First(&payment, fixture.Payment.ID).Error; err != nil {
+		t.Fatalf("find payment failed: %v", err)
+	}
+	if payment.Status != "paid" {
+		t.Fatalf("payment status = %q, want paid", payment.Status)
+	}
+	// 首次落账的时间必须保留，后续重试不能把 paid_at 往后推。
+	if payment.PaidAt == nil || !payment.PaidAt.UTC().Equal(paidAt) {
+		t.Fatalf("payment paid_at = %v, want %v", payment.PaidAt, paidAt)
+	}
+}
+
+// TestConfirmPaidKeepsErrorForUnrelatedFailures 只有「订单再也无法入账」才走落账。
+// 其他错误仍要原样抛出，否则会把真正的故障当成已处理而静默掉。
+func TestConfirmPaidKeepsErrorForUnrelatedFailures(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	repo := NewRepository(db, nil, nil)
+	fixture := createPayableOrderFixture(t, db, "LP04", true)
+
+	err := repo.confirmPaid(t.Context(), &fixture.Payment, "paid", time.Now(), map[string]string{}, channelSourceNotify)
+	if !errors.Is(err, ErrDependencyUnavailable) {
+		t.Fatalf("confirmPaid() error = %v, want ErrDependencyUnavailable", err)
+	}
+
+	var payment model.PaymentOrder
+	if findErr := db.First(&payment, fixture.Payment.ID).Error; findErr != nil {
+		t.Fatalf("find payment failed: %v", findErr)
+	}
+	if payment.Status != "paying" {
+		t.Fatalf("payment status = %q, want paying", payment.Status)
+	}
+}
+
+func TestIsOrderUnpayable(t *testing.T) {
+	cases := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{"订单已取消或已关单", ordermodule.ErrOrderCannotPay, true},
+		{"商品已被他人租走", ordermodule.ErrListingUnavailable, true},
+		{"依赖缺失", ErrDependencyUnavailable, false},
+		{"无错误", nil, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := isOrderUnpayable(tc.err); got != tc.want {
+				t.Fatalf("isOrderUnpayable(%v) = %v, want %v", tc.err, got, tc.want)
+			}
+		})
+	}
+}

backend/internal/modules/payment/mohong_payment.go

@@ -0,0 +1,245 @@
+package payment
+
+import (
+	"context"
+	"time"
+
+	"hfb_sys/backend/internal/model"
+
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+const bizTypeMohongPay = "mohong_pay"
+
+// StartMohong 发起撞车订单支付。
+func (r *Repository) StartMohong(ctx context.Context, userID uint64, orderID uint64, req StartPaymentRequest, clientIP string) (*PaymentDTO, error) {
+	req.PayWay = normalizePayWay(req.PayWay)
+	defaultConfig, err := r.defaultRuntimeConfig(ctx, req.PayWay)
+	if err != nil {
+		return nil, ErrPaymentUnavailable
+	}
+	payment, orderRow, err := r.prepareMohongPayment(ctx, userID, orderID, req, *defaultConfig)
+	if err != nil {
+		return nil, err
+	}
+	runtimeConfig, err := r.runtimeConfigForPayment(ctx, payment)
+	if err != nil {
+		return nil, ErrPaymentUnavailable
+	}
+	if payment.Status == "paid" {
+		r.recordConfigUsage(ctx, runtimeConfig, payment)
+		dto := toDTO(*payment)
+		return &dto, nil
+	}
+	if runtimeConfig.isMockMode() {
+		if err := r.confirmPaid(ctx, payment, "2", time.Now(), map[string]string{
+			"mock":            "true",
+			"third_order_id":  payment.ThirdOrderID,
+			"leshua_order_id": payment.ProviderOrderID,
+			"status":          "2",
+		}, channelSourceMock); err != nil {
+			return nil, err
+		}
+		latest, err := r.findPaymentByID(ctx, payment.ID)
+		if err != nil {
+			return nil, err
+		}
+		r.recordConfigUsage(ctx, runtimeConfig, latest)
+		dto := toDTO(*latest)
+		return &dto, nil
+	}
+	if payment.Status == "paying" && (payment.TDCode != "" || payment.JSPayURL != "" || payment.JSPayInfo != "") {
+		r.recordConfigUsage(ctx, runtimeConfig, payment)
+		dto := toDTO(*payment)
+		return &dto, nil
+	}
+	if runtimeConfig.Channel == nil {
+		_ = r.markPaymentFailed(ctx, payment.ID, nil, "payment channel unavailable")
+		return nil, ErrPaymentUnavailable
+	}
+
+	resp, err := runtimeConfig.Channel.CreatePayment(ctx, channelCreatePaymentRequest{
+		ThirdOrderID: payment.ThirdOrderID,
+		AmountCent:   payment.AmountCent,
+		PayWay:       payment.PayWay,
+		JSPayFlag:    payment.JSPayFlag,
+		NotifyURL:    runtimeConfig.NotifyURL,
+		JumpURL:      runtimeConfig.JumpURL,
+		ClientIP:     clientIP,
+		Body:         "撞车订单 " + orderRow.OrderNo,
+		Attach:       orderRow.OrderNo,
+	})
+	if err != nil {
+		_ = r.markPaymentFailed(ctx, payment.ID, nil, err.Error())
+		r.log().Warn("魔哄支付下单失败", paymentLogFields(ctx, appendFields(
+			paymentOrderFields(payment),
+			runtimeConfigFields(runtimeConfig),
+			[]zap.Field{zap.Error(err)},
+		)...,
+		)...)
+		return nil, err
+	}
+	if !resp.OK {
+		_ = r.markPaymentFailed(ctx, payment.ID, resp.Raw, resp.ErrorMessage)
+		return nil, ErrPaymentUnavailable
+	}
+	if err := r.db.WithContext(ctx).Model(&model.PaymentOrder{}).Where("id = ?", payment.ID).Updates(map[string]any{
+		"status":            "paying",
+		"provider_order_id": resp.ProviderOrderID,
+		"pay_way":           firstNonEmpty(resp.PayWay, payment.PayWay),
+		"td_code":           resp.TDCode,
+		"jspay_url":         resp.JSPayURL,
+		"jspay_info":        resp.JSPayInfo,
+		"raw_request":       jsonMap(resp.RawRequest),
+		"raw_response":      jsonMap(withRawSource(resp.Raw, channelSourceCreate)),
+	}).Error; err != nil {
+		return nil, err
+	}
+	latest, err := r.findPaymentByID(ctx, payment.ID)
+	if err != nil {
+		return nil, err
+	}
+	r.recordConfigUsage(ctx, runtimeConfig, latest)
+	r.log().Info("魔哄支付下单完成", paymentLogFields(ctx, appendFields(
+		paymentOrderFields(latest),
+		runtimeConfigFields(runtimeConfig),
+	)...,
+	)...)
+	dto := toDTO(*latest)
+	return &dto, nil
+}
+
+func (r *Repository) prepareMohongPayment(ctx context.Context, userID uint64, orderID uint64, req StartPaymentRequest, runtimeConfig runtimePaymentConfig) (*model.PaymentOrder, *model.MohongOrder, error) {
+	var paymentID uint64
+	var orderRow model.MohongOrder
+	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var row model.MohongOrder
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("id = ? AND user_id = ?", orderID, userID).
+			First(&row).Error; err != nil {
+			return err
+		}
+		if row.Status != model.MohongOrderStatusPendingPayment {
+			return ErrPaymentCannotStart
+		}
+		if row.AmountCent <= 0 {
+			return ErrPaymentCannotStart
+		}
+		var existing model.PaymentOrder
+		err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("order_id = ? AND biz_type = ?", row.ID, bizTypeMohongPay).
+			Order("id DESC").
+			First(&existing).Error
+		if err == nil {
+			if canReuseOrderPayment(existing, runtimeConfig) {
+				existing.PayWay = firstNonEmpty(req.PayWay, existing.PayWay, runtimeConfig.PayWay, "ZFBZF")
+				existing.JSPayFlag = firstNonEmpty(req.JSPayFlag, existing.JSPayFlag, runtimeConfig.JSPayFlag, "2")
+				existing.AmountCent = row.AmountCent
+				existing.PaymentConfigID = firstNonZero(existing.PaymentConfigID, runtimeConfig.ID)
+				existing.Provider = firstNonEmpty(existing.Provider, runtimeConfig.Provider)
+				existing.MerchantID = firstNonEmpty(existing.MerchantID, runtimeConfig.MerchantID)
+				if existing.Provider == "mock" && existing.ProviderOrderID == "" {
+					existing.ProviderOrderID = "MOCK" + existing.ThirdOrderID
+				}
+				if err := tx.Save(&existing).Error; err != nil {
+					return err
+				}
+				paymentID = existing.ID
+				orderRow = row
+				return nil
+			}
+		} else if err != gorm.ErrRecordNotFound {
+			return err
+		}
+		payment, err := newMohongPayment(row, req, runtimeConfig)
+		if err != nil {
+			return err
+		}
+		if err := tx.Create(&payment).Error; err != nil {
+			return err
+		}
+		paymentID = payment.ID
+		orderRow = row
+		return nil
+	})
+	if err != nil {
+		return nil, nil, err
+	}
+	payment, err := r.findPaymentByID(ctx, paymentID)
+	if err != nil {
+		return nil, nil, err
+	}
+	return payment, &orderRow, nil
+}
+
+func newMohongPayment(row model.MohongOrder, req StartPaymentRequest, runtimeConfig runtimePaymentConfig) (model.PaymentOrder, error) {
+	paymentNo, err := newPaymentNo()
+	if err != nil {
+		return model.PaymentOrder{}, err
+	}
+	payment := model.PaymentOrder{
+		PaymentNo:       paymentNo,
+		OrderID:         row.ID,
+		OrderNo:         row.OrderNo,
+		UserID:          row.UserID,
+		PaymentConfigID: runtimeConfig.ID,
+		Provider:        runtimeConfig.Provider,
+		MerchantID:      runtimeConfig.MerchantID,
+		ThirdOrderID:    paymentNo,
+		ProviderOrderID: "",
+		PayWay:          firstNonEmpty(req.PayWay, runtimeConfig.PayWay, "ZFBZF"),
+		JSPayFlag:       firstNonEmpty(req.JSPayFlag, runtimeConfig.JSPayFlag, "2"),
+		AmountCent:      row.AmountCent,
+		BizType:         bizTypeMohongPay,
+		Status:          "created",
+	}
+	if runtimeConfig.isMockMode() {
+		payment.ProviderOrderID = "MOCK" + paymentNo
+		payment.TDCode = "mock://payment/pay/" + paymentNo
+	}
+	return payment, nil
+}
+
+// QueryMohong 查询撞车订单支付状态。
+func (r *Repository) QueryMohong(ctx context.Context, userID uint64, orderID uint64) (*PaymentDTO, error) {
+	var payment model.PaymentOrder
+	if err := r.db.WithContext(ctx).
+		Where("order_id = ? AND user_id = ? AND biz_type = ?", orderID, userID, bizTypeMohongPay).
+		Order("id DESC").
+		First(&payment).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, ErrPaymentNotFound
+		}
+		return nil, err
+	}
+	if isOrderPaymentTerminalStatus(payment.Status) {
+		dto := toDTO(payment)
+		return &dto, nil
+	}
+	runtimeConfig, err := r.runtimeConfigForPayment(ctx, &payment)
+	if err != nil {
+		return nil, ErrPaymentUnavailable
+	}
+	if runtimeConfig.isMockMode() {
+		dto := toDTO(payment)
+		return &dto, nil
+	}
+	if runtimeConfig.Channel == nil {
+		return nil, ErrPaymentUnavailable
+	}
+	resp, err := runtimeConfig.Channel.QueryPayment(ctx, payment.ThirdOrderID, payment.ProviderOrderID)
+	if err != nil {
+		return nil, err
+	}
+	if err := r.applyChannelStatus(ctx, &payment, resp.Status, resp.PayTime, resp.Raw, channelSourceQuery); err != nil {
+		return nil, err
+	}
+	latest, err := r.findPaymentByID(ctx, payment.ID)
+	if err != nil {
+		return nil, err
+	}
+	dto := toDTO(*latest)
+	return &dto, nil
+}

backend/internal/modules/payment/notify.go

@@ -0,0 +1,207 @@
+package payment
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"strconv"
+	"strings"
+
+	"hfb_sys/backend/internal/model"
+
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+)
+
+func (r *Repository) HandleLeshuaNotify(ctx context.Context, params map[string]string, rawPayload string, contentType string) (*NotifyResult, error) {
+	return r.HandleNotify(ctx, "leshua", params, rawPayload, contentType, "")
+}
+func (r *Repository) HandleNotify(ctx context.Context, provider string, params map[string]string, rawPayload string, contentType string, authorization string) (*NotifyResult, error) {
+	// 退款通知会携带 merchant_refund_id 或 leshua_refund_id。
+	if params["merchant_refund_id"] != "" || params["leshua_refund_id"] != "" || params["provider_refund_id"] != "" {
+		return r.HandleRefundNotify(ctx, provider, params, rawPayload, contentType, authorization)
+	}
+
+	payment, err := r.findPaymentForNotify(ctx, params)
+	if err != nil {
+		return nil, err
+	}
+	runtimeConfig, err := r.runtimeConfigForPayment(ctx, payment)
+	if err != nil {
+		return nil, ErrPaymentUnavailable
+	}
+	verify, err := r.verifyNotify(ctx, payment, runtimeConfig, params, rawPayload, contentType, authorization)
+	if err != nil {
+		return nil, err
+	}
+
+	if amount := parseCent(params["amount"]); amount > 0 && amount != payment.AmountCent {
+		if err := r.recordNotifyDiagnostic(ctx, payment.ID, params, rawPayload, contentType, verify, "amount_mismatch"); err != nil {
+			r.log().Warn("支付回调诊断保存失败", paymentLogFields(ctx, appendFields(
+				paymentOrderFields(payment),
+				runtimeConfigFields(runtimeConfig),
+				[]zap.Field{
+					zap.String("diagnostic_status", "amount_mismatch"),
+					zap.Error(err),
+				},
+			)...,
+			)...)
+		}
+		return nil, ErrPaymentVerifyFailed
+	}
+	raw := withNotifyDiagnostic(params, rawPayload, contentType, verify, "verified")
+	channelStatus := normalizeNotifyPaymentStatus(runtimeConfig.Provider, params["status"])
+	if err := r.applyChannelStatus(ctx, payment, channelStatus, params["pay_time"], raw, channelSourceNotify); err != nil {
+		// 入口处的 WARN 只有渠道参数，定位不到是哪个订单哪笔支付单，这里补齐上下文。
+		r.log().Warn("支付回调入账失败", paymentLogFields(ctx, appendFields(
+			paymentOrderFields(payment),
+			runtimeConfigFields(runtimeConfig),
+			[]zap.Field{
+				zap.String("channel_status", channelStatus),
+				zap.String("order_status", r.orderStatus(ctx, payment.OrderID)),
+				zap.Error(err),
+			},
+		)...,
+		)...)
+		return nil, err
+	}
+	return &NotifyResult{OK: true, Message: "000000"}, nil
+}
+func (r *Repository) HandleRefundNotify(ctx context.Context, provider string, params map[string]string, rawPayload string, contentType string, authorization string) (*NotifyResult, error) {
+	payment, err := r.findRefundPaymentForNotify(ctx, params)
+	if err != nil {
+		return nil, err
+	}
+	runtimeConfig, err := r.runtimeConfigForPayment(ctx, payment)
+	if err != nil {
+		return nil, ErrPaymentUnavailable
+	}
+	verify, err := r.verifyNotify(ctx, payment, runtimeConfig, params, rawPayload, contentType, authorization)
+	if err != nil {
+		return nil, err
+	}
+
+	raw := withNotifyDiagnostic(params, rawPayload, contentType, verify, "verified")
+	status := normalizeNotifyRefundStatus(provider, params["status"])
+	if err := r.applyRefundChannelStatus(ctx, payment, refundChannelStatusUpdate{
+		Status:           status,
+		ProviderRefundID: firstNonEmpty(params["provider_refund_id"], params["leshua_refund_id"]),
+		RefundTime:       params["refund_time"],
+		Raw:              raw,
+		Source:           channelSourceNotify,
+	}); err != nil {
+		return nil, err
+	}
+	return &NotifyResult{OK: true, Message: "000000"}, nil
+}
+func (r *Repository) findPaymentForNotify(ctx context.Context, params map[string]string) (*model.PaymentOrder, error) {
+	thirdOrderID := params["third_order_id"]
+	if thirdOrderID == "" {
+		return nil, ErrPaymentNotFound
+	}
+	var payment model.PaymentOrder
+	if err := r.db.WithContext(ctx).Where("third_order_id = ?", thirdOrderID).First(&payment).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, ErrPaymentNotFound
+		}
+		return nil, err
+	}
+	return &payment, nil
+}
+func (r *Repository) findRefundPaymentForNotify(ctx context.Context, params map[string]string) (*model.PaymentOrder, error) {
+	merchantRefundID := params["merchant_refund_id"]
+	if merchantRefundID == "" {
+		return nil, ErrPaymentNotFound
+	}
+	var payment model.PaymentOrder
+	if err := r.db.WithContext(ctx).Where("third_order_id = ?", merchantRefundID).First(&payment).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, ErrPaymentNotFound
+		}
+		return nil, err
+	}
+	return &payment, nil
+}
+func (r *Repository) verifyNotify(ctx context.Context, payment *model.PaymentOrder, runtimeConfig *runtimePaymentConfig, params map[string]string, rawPayload string, contentType string, authorization string) (channelVerifyNotifyResult, error) {
+	var verify channelVerifyNotifyResult
+	if runtimeConfig.isMockMode() {
+		return verify, nil
+	}
+	if runtimeConfig.Channel == nil {
+		return verify, ErrPaymentUnavailable
+	}
+	verify, err := runtimeConfig.Channel.VerifyNotify(params, rawPayload, contentType, authorization)
+	if err != nil || !verify.OK {
+		r.log().Warn("支付回调验签失败", paymentLogFields(ctx, appendFields(
+			paymentOrderFields(payment),
+			runtimeConfigFields(runtimeConfig),
+			[]zap.Field{
+				zap.Bool("signature_present", verify.Got != ""),
+				zap.Strings("param_keys", verify.ParamKeys),
+				zap.Error(err),
+			},
+		)...,
+		)...)
+		if err := r.recordNotifyDiagnostic(ctx, payment.ID, params, rawPayload, contentType, verify, "verify_failed"); err != nil {
+			r.log().Warn("支付回调诊断保存失败", paymentLogFields(ctx, appendFields(
+				paymentOrderFields(payment),
+				runtimeConfigFields(runtimeConfig),
+				[]zap.Field{
+					zap.String("diagnostic_status", "verify_failed"),
+					zap.Error(err),
+				},
+			)...,
+			)...)
+		}
+		return verify, ErrPaymentVerifyFailed
+	}
+	return verify, nil
+}
+func (r *Repository) recordNotifyDiagnostic(ctx context.Context, paymentID uint64, params map[string]string, rawPayload string, contentType string, verify channelVerifyNotifyResult, status string) error {
+	if paymentID == 0 {
+		return nil
+	}
+	raw := withNotifyDiagnostic(params, rawPayload, contentType, verify, status)
+	return r.db.WithContext(ctx).Model(&model.PaymentOrder{}).
+		Where("id = ?", paymentID).
+		Update("raw_response", jsonMap(raw)).Error
+}
+func withNotifyDiagnostic(params map[string]string, rawPayload string, contentType string, verify channelVerifyNotifyResult, status string) map[string]string {
+	raw := withRawSource(redactNotifyParams(params), channelSourceNotify)
+	raw["_notify_diagnostic_status"] = status
+	raw["_raw_content_type"] = contentType
+	raw["_raw_payload_size"] = strconv.Itoa(len(rawPayload))
+	raw["_raw_payload_sha256"] = shortDigest(rawPayload)
+	raw["_signature_present"] = strconv.FormatBool(verify.Got != "")
+	raw["_sign_matched_key"] = verify.MatchedKey
+	raw["_sign_param_keys"] = strings.Join(verify.ParamKeys, ",")
+	return raw
+}
+
+func redactNotifyParams(params map[string]string) map[string]string {
+	allowed := map[string]bool{
+		"service": true, "merchant_id": true, "third_order_id": true,
+		"provider_order_id": true, "leshua_order_id": true, "schc_order_id": true,
+		"merchant_refund_id": true, "provider_refund_id": true,
+		"leshua_refund_id": true, "schc_refund_id": true,
+		"status": true, "amount": true, "refund_amount": true,
+		"pay_time": true, "refund_time": true,
+		"code": true, "resp_code": true, "result_code": true, "error_code": true,
+	}
+	redacted := make(map[string]string, len(allowed))
+	for key, value := range params {
+		lowerKey := strings.ToLower(key)
+		if allowed[lowerKey] {
+			redacted[key] = value
+		}
+	}
+	return redacted
+}
+
+func shortDigest(value string) string {
+	if value == "" {
+		return ""
+	}
+	sum := sha256.Sum256([]byte(value))
+	return hex.EncodeToString(sum[:8])
+}

backend/internal/modules/payment/payment_start.go

@@ -0,0 +1,258 @@
+package payment
+
+import (
+	"context"
+	"encoding/json"
+	"time"
+
+	"hfb_sys/backend/internal/model"
+	"hfb_sys/backend/internal/timeutil"
+
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+// Start 发起订单支付，并按请求支付方式选择对应默认渠道配置。
+func (r *Repository) Start(ctx context.Context, userID uint64, orderID uint64, req StartPaymentRequest, clientIP string) (*PaymentDTO, error) {
+	req.PayWay = normalizePayWay(req.PayWay)
+	payment, orderRow, err := r.preparePayment(ctx, userID, orderID, req)
+	if err != nil {
+		return nil, err
+	}
+	runtimeConfig, err := r.runtimeConfigForPayment(ctx, payment)
+	if err != nil {
+		return nil, ErrPaymentUnavailable
+	}
+	if payment.Status == "paid" {
+		r.recordConfigUsage(ctx, runtimeConfig, payment)
+		dto := toDTO(*payment)
+		return &dto, nil
+	}
+	if runtimeConfig.isMockMode() {
+		if err := r.confirmPaid(ctx, payment, "2", time.Now(), map[string]string{
+			"mock":            "true",
+			"third_order_id":  payment.ThirdOrderID,
+			"leshua_order_id": payment.ProviderOrderID,
+			"status":          "2",
+		}, channelSourceMock); err != nil {
+			return nil, err
+		}
+		latest, err := r.findPaymentByID(ctx, payment.ID)
+		if err != nil {
+			return nil, err
+		}
+		r.recordConfigUsage(ctx, runtimeConfig, latest)
+		dto := toDTO(*latest)
+		return &dto, nil
+	}
+	if payment.Status == "paying" && (payment.TDCode != "" || payment.JSPayURL != "" || payment.JSPayInfo != "") {
+		r.recordConfigUsage(ctx, runtimeConfig, payment)
+		dto := toDTO(*payment)
+		return &dto, nil
+	}
+	if runtimeConfig.Channel == nil {
+		_ = r.markPaymentFailed(ctx, payment.ID, nil, "payment channel unavailable")
+		return nil, ErrPaymentUnavailable
+	}
+
+	resp, err := runtimeConfig.Channel.CreatePayment(ctx, channelCreatePaymentRequest{
+		ThirdOrderID: payment.ThirdOrderID,
+		AmountCent:   payment.AmountCent,
+		PayWay:       payment.PayWay,
+		JSPayFlag:    payment.JSPayFlag,
+		NotifyURL:    runtimeConfig.NotifyURL,
+		JumpURL:      runtimeConfig.JumpURL,
+		ClientIP:     clientIP,
+		Body:         "租号订单 " + orderRow.OrderNo,
+		Attach:       orderRow.OrderNo,
+	})
+	if err != nil {
+		_ = r.markPaymentFailed(ctx, payment.ID, nil, err.Error())
+		r.log().Warn("支付下单请求失败", paymentLogFields(ctx, appendFields(
+			paymentOrderFields(payment),
+			runtimeConfigFields(runtimeConfig),
+			[]zap.Field{zap.Error(err)},
+		)...,
+		)...)
+		return nil, err
+	}
+	if !resp.OK {
+		_ = r.markPaymentFailed(ctx, payment.ID, resp.Raw, resp.ErrorMessage)
+		r.log().Warn("支付下单被渠道拒绝", paymentLogFields(ctx, appendFields(
+			paymentOrderFields(payment),
+			runtimeConfigFields(runtimeConfig),
+			[]zap.Field{
+				zap.String("channel_code", firstNonEmpty(resp.Raw["code"], resp.Raw["resp_code"], resp.Raw["result_code"])),
+				zap.String("channel_message", resp.ErrorMessage),
+				zap.Strings("raw_response_keys", stringMapKeys(resp.Raw)),
+			},
+		)...,
+		)...)
+		return nil, ErrPaymentUnavailable
+	}
+	if err := r.db.WithContext(ctx).Model(&model.PaymentOrder{}).Where("id = ?", payment.ID).Updates(map[string]any{
+		"status":            "paying",
+		"provider_order_id": resp.ProviderOrderID,
+		"pay_way":           firstNonEmpty(resp.PayWay, payment.PayWay),
+		"td_code":           resp.TDCode,
+		"jspay_url":         resp.JSPayURL,
+		"jspay_info":        resp.JSPayInfo,
+		"raw_request":       jsonMap(resp.RawRequest),
+		"raw_response":      jsonMap(withRawSource(resp.Raw, channelSourceCreate)),
+	}).Error; err != nil {
+		return nil, err
+	}
+	latest, err := r.findPaymentByID(ctx, payment.ID)
+	if err != nil {
+		return nil, err
+	}
+	r.recordConfigUsage(ctx, runtimeConfig, latest)
+	r.log().Info("支付下单完成", paymentLogFields(ctx, appendFields(
+		paymentOrderFields(latest),
+		runtimeConfigFields(runtimeConfig),
+	)...,
+	)...)
+	dto := toDTO(*latest)
+	return &dto, nil
+}
+
+// preparePayment 创建或复用订单支付单，并写入本次命中的支付配置 ID。
+func (r *Repository) preparePayment(ctx context.Context, userID uint64, orderID uint64, req StartPaymentRequest) (*model.PaymentOrder, *model.RentalOrder, error) {
+	var paymentID uint64
+	var orderRow model.RentalOrder
+	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var row model.RentalOrder
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("id = ? AND renter_id = ?", orderID, userID).
+			First(&row).Error; err != nil {
+			return err
+		}
+		if row.Status != "pending_payment" {
+			return ErrPaymentCannotStart
+		}
+		amountCent := row.RentAmountCent + row.DepositAmountCent
+		if amountCent <= 0 {
+			return ErrPaymentCannotStart
+		}
+		runtimeConfig, err := r.resolveOrderRuntimeConfig(ctx, tx, row.DistributionSiteID, req.PayWay)
+		if err != nil {
+			return err
+		}
+		var existing model.PaymentOrder
+		err = tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("order_id = ? AND biz_type = ?", row.ID, "order_pay").
+			Order("id DESC").
+			First(&existing).Error
+		if err == nil {
+			if canReuseOrderPayment(existing, *runtimeConfig) {
+				existing.PayWay = firstNonEmpty(req.PayWay, existing.PayWay, runtimeConfig.PayWay, "ZFBZF")
+				existing.JSPayFlag = firstNonEmpty(req.JSPayFlag, existing.JSPayFlag, runtimeConfig.JSPayFlag, "2")
+				existing.AmountCent = amountCent
+				existing.PaymentConfigID = firstNonZero(existing.PaymentConfigID, runtimeConfig.ID)
+				existing.Provider = firstNonEmpty(existing.Provider, runtimeConfig.Provider)
+				existing.MerchantID = firstNonEmpty(existing.MerchantID, runtimeConfig.MerchantID)
+				if existing.Provider == "mock" && existing.ProviderOrderID == "" {
+					existing.ProviderOrderID = "MOCK" + existing.ThirdOrderID
+				}
+				if err := tx.Save(&existing).Error; err != nil {
+					return err
+				}
+				paymentID = existing.ID
+				orderRow = row
+				return nil
+			}
+		} else if err != gorm.ErrRecordNotFound {
+			return err
+		}
+		payment, err := newOrderPayment(row, amountCent, req, *runtimeConfig)
+		if err != nil {
+			return err
+		}
+		if err := tx.Create(&payment).Error; err != nil {
+			return err
+		}
+		paymentID = payment.ID
+		orderRow = row
+		return nil
+	})
+	if err != nil {
+		return nil, nil, err
+	}
+	payment, err := r.findPaymentByID(ctx, paymentID)
+	if err != nil {
+		return nil, nil, err
+	}
+	return payment, &orderRow, nil
+}
+
+// canReuseOrderPayment 判断旧支付单是否还能复用，支付方式或配置不同则必须重新下单。
+func canReuseOrderPayment(payment model.PaymentOrder, runtimeConfig runtimePaymentConfig) bool {
+	if payment.Status == "paid" {
+		return true
+	}
+	if payment.Status != "created" && payment.Status != "paying" {
+		return false
+	}
+	if payment.Provider != "" && runtimeConfig.Provider != "" && payment.Provider != runtimeConfig.Provider {
+		return false
+	}
+	if payment.MerchantID != "" && runtimeConfig.MerchantID != "" && payment.MerchantID != runtimeConfig.MerchantID {
+		return false
+	}
+	if payment.PaymentConfigID != 0 && runtimeConfig.ID != 0 && payment.PaymentConfigID != runtimeConfig.ID {
+		return false
+	}
+	if payment.PayWay != "" && runtimeConfig.PayWay != "" && normalizePayWay(payment.PayWay) != normalizePayWay(runtimeConfig.PayWay) {
+		return false
+	}
+	if payment.Status == "paying" && paymentCashierExpired(payment) {
+		return false
+	}
+	return true
+}
+
+// paymentCashierExpired 判断渠道收银台是否已过期，过期后不再复用支付单。
+func paymentCashierExpired(payment model.PaymentOrder) bool {
+	if len(payment.RawRequest) == 0 {
+		return false
+	}
+	var raw map[string]string
+	if err := json.Unmarshal(payment.RawRequest, &raw); err != nil {
+		return false
+	}
+	deadline := parseChannelTime(raw["order_efficient_time"])
+	if deadline == nil {
+		return false
+	}
+	return !timeutil.ShanghaiNow().Before(*deadline)
+}
+
+// newOrderPayment 创建新的订单支付单，并固化支付方式和支付配置 ID。
+func newOrderPayment(row model.RentalOrder, amountCent int64, req StartPaymentRequest, runtimeConfig runtimePaymentConfig) (model.PaymentOrder, error) {
+	paymentNo, err := newPaymentNo()
+	if err != nil {
+		return model.PaymentOrder{}, err
+	}
+	payment := model.PaymentOrder{
+		PaymentNo:       paymentNo,
+		OrderID:         row.ID,
+		OrderNo:         row.OrderNo,
+		UserID:          row.RenterID,
+		PaymentConfigID: runtimeConfig.ID,
+		Provider:        runtimeConfig.Provider,
+		MerchantID:      runtimeConfig.MerchantID,
+		ThirdOrderID:    paymentNo,
+		ProviderOrderID: "",
+		PayWay:          firstNonEmpty(req.PayWay, runtimeConfig.PayWay, "ZFBZF"),
+		JSPayFlag:       firstNonEmpty(req.JSPayFlag, runtimeConfig.JSPayFlag, "2"),
+		AmountCent:      amountCent,
+		BizType:         "order_pay",
+		Status:          "created",
+	}
+	if runtimeConfig.isMockMode() {
+		payment.ProviderOrderID = "MOCK" + paymentNo
+		payment.TDCode = "mock://payment/pay/" + paymentNo
+	}
+	return payment, nil
+}

backend/internal/modules/payment/presenter.go

@@ -0,0 +1,141 @@
+package payment
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"gorm.io/datatypes"
+	"hfb_sys/backend/internal/model"
+	"hfb_sys/backend/internal/timeutil"
+	"math"
+	"strings"
+	"time"
+)
+
+func toDTO(payment model.PaymentOrder) PaymentDTO {
+	return PaymentDTO{
+		ID:              payment.ID,
+		PaymentNo:       payment.PaymentNo,
+		OrderID:         payment.OrderID,
+		OrderNo:         payment.OrderNo,
+		PaymentConfigID: payment.PaymentConfigID,
+		Provider:        payment.Provider,
+		ThirdOrderID:    payment.ThirdOrderID,
+		ProviderOrderID: payment.ProviderOrderID,
+		PayWay:          payment.PayWay,
+		JSPayFlag:       payment.JSPayFlag,
+		AmountCent:      payment.AmountCent,
+		Status:          payment.Status,
+		TDCode:          payment.TDCode,
+		JSPayURL:        payment.JSPayURL,
+		JSPayInfo:       payment.JSPayInfo,
+		Paid:            payment.Status == "paid",
+		PaidAt:          payment.PaidAt,
+		CreatedAt:       payment.CreatedAt,
+		UpdatedAt:       payment.UpdatedAt,
+	}
+}
+func paymentErrorSummary(status string, raw datatypes.JSON) (string, string) {
+	if status != "failed" {
+		return "", ""
+	}
+	if len(raw) == 0 {
+		return "", ""
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		return "", ""
+	}
+	code := firstStringValue(payload, "code", "resp_code", "result_code", "error_code", "status")
+	message := firstStringValue(payload, "msg", "message", "error", "error_message", "result_msg", "result_desc")
+	return code, message
+}
+func moneyCent(value float64) int64 {
+	return int64(math.Round(value * 100))
+}
+func parseCent(value string) int64 {
+	var amount int64
+	_, _ = fmt.Sscanf(value, "%d", &amount)
+	return amount
+}
+func parseChannelTime(value string) *time.Time {
+	if value == "" {
+		return nil
+	}
+	for _, layout := range []string{"2006-01-02 15:04:05", "20060102150405", time.RFC3339} {
+		parsed, err := time.ParseInLocation(layout, value, timeutil.ShanghaiLocation())
+		if err == nil {
+			return &parsed
+		}
+	}
+	return nil
+}
+func jsonMap(value map[string]string) datatypes.JSON {
+	if value == nil {
+		return nil
+	}
+	raw, err := json.Marshal(value)
+	if err != nil {
+		return nil
+	}
+	return datatypes.JSON(raw)
+}
+func withRawSource(raw map[string]string, source string) map[string]string {
+	out := map[string]string{}
+	for key, value := range raw {
+		out[key] = value
+	}
+	if source != "" {
+		out["_source"] = source
+	}
+	out["_recorded_at"] = time.Now().Format(time.RFC3339)
+	return out
+}
+func jsonString(value map[string]string) string {
+	if len(value) == 0 {
+		return "{}"
+	}
+	raw, err := json.Marshal(value)
+	if err != nil {
+		return "{}"
+	}
+	return string(raw)
+}
+func newPaymentNo() (string, error) {
+	buf := make([]byte, 4)
+	if _, err := rand.Read(buf); err != nil {
+		return "", err
+	}
+	return fmt.Sprintf("PAY%d%s", time.Now().UnixNano(), hex.EncodeToString(buf)), nil
+}
+func firstNonEmpty(values ...string) string {
+	for _, value := range values {
+		if value != "" {
+			return value
+		}
+	}
+	return ""
+}
+
+// firstNonZero 返回第一个非零 uint64，用于保留历史支付单已有配置 ID。
+func firstNonZero(values ...uint64) uint64 {
+	for _, value := range values {
+		if value != 0 {
+			return value
+		}
+	}
+	return 0
+}
+
+// normalizePayWay 将前端或渠道别名统一为系统内部支付方式编码。
+func normalizePayWay(value string) string {
+	switch strings.ToUpper(strings.TrimSpace(value)) {
+	case "", "ZFBZF", "ALIPAY", "ALIPAYPAY":
+		return "ZFBZF"
+	case "WXZF", "WECHAT", "WECHATPAY":
+		return "WXZF"
+	default:
+		return strings.ToUpper(strings.TrimSpace(value))
+	}
+}

backend/internal/modules/payment/query.go

@@ -0,0 +1,130 @@
+package payment
+
+import (
+	"context"
+	"gorm.io/gorm"
+	"hfb_sys/backend/internal/model"
+)
+
+func (r *Repository) Query(ctx context.Context, userID uint64, orderID uint64) (*PaymentDTO, error) {
+	var payment model.PaymentOrder
+	if err := r.db.WithContext(ctx).Where("order_id = ? AND user_id = ? AND biz_type = ?", orderID, userID, "order_pay").Order("id DESC").First(&payment).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, ErrPaymentNotFound
+		}
+		return nil, err
+	}
+	if isOrderPaymentTerminalStatus(payment.Status) {
+		dto := toDTO(payment)
+		return &dto, nil
+	}
+	runtimeConfig, err := r.runtimeConfigForPayment(ctx, &payment)
+	if err != nil {
+		return nil, ErrPaymentUnavailable
+	}
+	if runtimeConfig.isMockMode() {
+		dto := toDTO(payment)
+		return &dto, nil
+	}
+	if runtimeConfig.Channel == nil {
+		return nil, ErrPaymentUnavailable
+	}
+	resp, err := runtimeConfig.Channel.QueryPayment(ctx, payment.ThirdOrderID, payment.ProviderOrderID)
+	if err != nil {
+		return nil, err
+	}
+	if err := r.applyChannelStatus(ctx, &payment, resp.Status, resp.PayTime, resp.Raw, channelSourceQuery); err != nil {
+		return nil, err
+	}
+	latest, err := r.findPaymentByID(ctx, payment.ID)
+	if err != nil {
+		return nil, err
+	}
+	dto := toDTO(*latest)
+	return &dto, nil
+}
+func (r *Repository) AdminList(ctx context.Context, query AdminPaymentQuery) (*PaginatedResult, error) {
+	db := r.db.WithContext(ctx).Table("payment_orders AS p").
+		Select("p.*, COALESCE(u.phone, '') AS user_phone").
+		Joins("LEFT JOIN users AS u ON u.id = p.user_id")
+	countDB := r.db.WithContext(ctx).Model(&model.PaymentOrder{})
+	if query.UserID > 0 {
+		db = db.Where("p.user_id = ?", query.UserID)
+		countDB = countDB.Where("user_id = ?", query.UserID)
+	}
+	if query.OrderID > 0 {
+		db = db.Where("p.order_id = ?", query.OrderID)
+		countDB = countDB.Where("order_id = ?", query.OrderID)
+	}
+	if query.OrderNo != "" {
+		db = db.Where("p.order_no = ?", query.OrderNo)
+		countDB = countDB.Where("order_no = ?", query.OrderNo)
+	}
+	if query.BizType != "" {
+		db = db.Where("p.biz_type = ?", query.BizType)
+		countDB = countDB.Where("biz_type = ?", query.BizType)
+	}
+	if query.Status != "" {
+		db = db.Where("p.status = ?", query.Status)
+		countDB = countDB.Where("status = ?", query.Status)
+	}
+	if query.Provider != "" {
+		db = db.Where("p.provider = ?", query.Provider)
+		countDB = countDB.Where("provider = ?", query.Provider)
+	}
+	var total int64
+	if err := countDB.Count(&total).Error; err != nil {
+		return nil, err
+	}
+	offset := (query.Page - 1) * query.PageSize
+	var rows []adminPaymentRow
+	if err := db.Order("p.id DESC").Offset(offset).Limit(query.PageSize).Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	items := make([]AdminPaymentDTO, 0, len(rows))
+	for _, row := range rows {
+		items = append(items, row.toDTO())
+	}
+	return &PaginatedResult{Items: items, Total: total, Page: query.Page, PageSize: query.PageSize}, nil
+}
+func (r *Repository) findPaymentByID(ctx context.Context, paymentID uint64) (*model.PaymentOrder, error) {
+	var payment model.PaymentOrder
+	if err := r.db.WithContext(ctx).First(&payment, paymentID).Error; err != nil {
+		return nil, err
+	}
+	return &payment, nil
+}
+
+type adminPaymentRow struct {
+	model.PaymentOrder
+	UserPhone string
+}
+
+func (row adminPaymentRow) toDTO() AdminPaymentDTO {
+	errorCode, errorMessage := paymentErrorSummary(row.Status, row.RawResponse)
+	return AdminPaymentDTO{
+		ID:              row.ID,
+		PaymentNo:       row.PaymentNo,
+		OrderID:         row.OrderID,
+		OrderNo:         row.OrderNo,
+		UserID:          row.UserID,
+		PaymentConfigID: row.PaymentConfigID,
+		UserPhone:       row.UserPhone,
+		Provider:        row.Provider,
+		MerchantID:      row.MerchantID,
+		ThirdOrderID:    row.ThirdOrderID,
+		ProviderOrderID: row.ProviderOrderID,
+		PayWay:          row.PayWay,
+		AmountCent:      row.AmountCent,
+		BizType:         row.BizType,
+		Status:          row.Status,
+		ErrorCode:       errorCode,
+		ErrorMessage:    errorMessage,
+		RawRequest:      row.RawRequest,
+		RawResponse:     row.RawResponse,
+		PaidAt:          row.PaidAt,
+		NotifiedAt:      row.NotifiedAt,
+		CreatedAt:       row.CreatedAt,
+		UpdatedAt:       row.UpdatedAt,
+	}
+}

backend/internal/modules/payment/refund.go

@@ -0,0 +1,579 @@
+package payment
+
+import (
+	"context"
+	"encoding/json"
+	"time"
+
+	"hfb_sys/backend/internal/model"
+	"hfb_sys/backend/internal/modules/distribution"
+	"hfb_sys/backend/internal/modules/rentergrowth"
+
+	"go.uber.org/zap"
+	"gorm.io/datatypes"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+func (r *Repository) StartRefund(ctx context.Context, orderID uint64, refundAmountCent int64, bizType string, remark string) (*RefundDTO, error) {
+	originalPayment, err := r.findOriginalPayment(ctx, orderID)
+	if err != nil {
+		return nil, err
+	}
+	runtimeConfig, err := r.runtimeConfigForPayment(ctx, &originalPayment)
+	if err != nil {
+		return nil, ErrPaymentUnavailable
+	}
+
+	refundOrder, existing, err := r.prepareRefundOrder(ctx, originalPayment, *runtimeConfig, refundAmountCent, bizType)
+	if err != nil {
+		return nil, err
+	}
+	if existing {
+		latest, syncErr := r.syncRefundPayment(ctx, refundOrder, refundOrder.Status != "refunded")
+		if syncErr != nil {
+			r.log().Warn("已有退款单同步失败", paymentLogFields(ctx, appendFields(
+				paymentOrderFields(refundOrder),
+				[]zap.Field{zap.String("biz_type", bizType), zap.Error(syncErr)},
+			)...,
+			)...)
+			dto := toRefundDTO(*refundOrder)
+			return &dto, nil
+		}
+		dto := toRefundDTO(*latest)
+		return &dto, nil
+	}
+
+	if runtimeConfig.isMockMode() {
+		raw := map[string]string{"mock": "true"}
+		if remark != "" {
+			raw["remark"] = remark
+		}
+		if err := r.applyRefundChannelStatus(ctx, refundOrder, refundChannelStatusUpdate{
+			Status:           "refunded",
+			ProviderRefundID: "MOCKREF" + refundOrder.ThirdOrderID,
+			Raw:              raw,
+			Source:           channelSourceMock,
+		}); err != nil {
+			return nil, err
+		}
+		latest, err := r.findPaymentByID(ctx, refundOrder.ID)
+		if err != nil {
+			return nil, err
+		}
+		r.recordConfigUsage(ctx, runtimeConfig, latest)
+		dto := toRefundDTO(*latest)
+		return &dto, nil
+	}
+
+	r.recordConfigUsage(ctx, runtimeConfig, refundOrder)
+	if err := r.markOrderRefunding(ctx, orderID, refundAmountCent); err != nil {
+		r.log().Warn("订单退款状态更新失败", paymentLogFields(ctx,
+			zap.Uint64("order_id", orderID),
+			zap.Int64("refund_amount_cent", refundAmountCent),
+			zap.Error(err),
+		)...)
+	}
+
+	if runtimeConfig.Channel == nil {
+		if err := r.markRefundFailed(ctx, refundOrder.ID, orderID, refundAmountCent, map[string]string{"error": "payment channel unavailable"}, nil); err != nil {
+			r.log().Warn("退款失败状态保存失败", paymentLogFields(ctx, appendFields(
+				paymentOrderFields(refundOrder),
+				[]zap.Field{zap.Error(err)},
+			)...,
+			)...)
+		}
+		return nil, ErrPaymentUnavailable
+	}
+	resp, err := runtimeConfig.Channel.CreateRefund(ctx, channelCreateRefundRequest{
+		ThirdOrderID:     originalPayment.ThirdOrderID,
+		ProviderOrderID:  refundOriginProviderOrderID(originalPayment),
+		MerchantRefundID: refundOrder.ThirdOrderID,
+		RefundAmountCent: refundAmountCent,
+		NotifyURL:        runtimeConfig.NotifyURL,
+		Attach:           originalPayment.OrderNo,
+		Remark:           remark,
+	})
+	if err != nil {
+		var rawRequest map[string]string
+		if resp != nil {
+			rawRequest = resp.RawRequest
+		}
+		if markErr := r.markRefundFailed(ctx, refundOrder.ID, orderID, refundAmountCent, map[string]string{"error": err.Error()}, rawRequest); markErr != nil {
+			r.log().Warn("退款失败状态保存失败", paymentLogFields(ctx, appendFields(
+				paymentOrderFields(refundOrder),
+				[]zap.Field{zap.Error(markErr)},
+			)...,
+			)...)
+		}
+		r.log().Warn("退款渠道请求失败", paymentLogFields(ctx, appendFields(
+			paymentOrderFields(refundOrder),
+			runtimeConfigFields(runtimeConfig),
+			[]zap.Field{zap.Error(err)},
+		)...,
+		)...)
+		return nil, err
+	}
+	if !resp.OK {
+		if markErr := r.markRefundFailed(ctx, refundOrder.ID, orderID, refundAmountCent, resp.Raw, resp.RawRequest); markErr != nil {
+			r.log().Warn("退款拒绝状态保存失败", paymentLogFields(ctx, appendFields(
+				paymentOrderFields(refundOrder),
+				[]zap.Field{zap.Error(markErr)},
+			)...,
+			)...)
+		}
+		r.log().Warn("退款被渠道拒绝", paymentLogFields(ctx, appendFields(
+			paymentOrderFields(refundOrder),
+			runtimeConfigFields(runtimeConfig),
+			[]zap.Field{
+				zap.String("channel_code", firstNonEmpty(resp.Raw["code"], resp.Raw["resp_code"], resp.Raw["result_code"])),
+				zap.String("channel_message", resp.ErrorMessage),
+				zap.Strings("raw_response_keys", stringMapKeys(resp.Raw)),
+			},
+		)...,
+		)...)
+		return nil, ErrPaymentUnavailable
+	}
+
+	if err := r.applyRefundChannelStatus(ctx, refundOrder, refundChannelStatusUpdate{
+		Status:           resp.Status,
+		ProviderRefundID: resp.ProviderRefundID,
+		RawRequest:       resp.RawRequest,
+		Raw:              resp.Raw,
+		Source:           channelSourceCreate,
+	}); err != nil {
+		return nil, err
+	}
+	r.log().Info("退款提交完成", paymentLogFields(ctx, appendFields(
+		paymentOrderFields(refundOrder),
+		runtimeConfigFields(runtimeConfig),
+		[]zap.Field{
+			zap.String("refund_status", resp.Status),
+			zap.String("provider_refund_id", resp.ProviderRefundID),
+		},
+	)...,
+	)...)
+
+	latest, err := r.findPaymentByID(ctx, refundOrder.ID)
+	if err != nil {
+		return nil, err
+	}
+	dto := toRefundDTO(*latest)
+	return &dto, nil
+}
+func (r *Repository) QueryRefundStatus(ctx context.Context, orderID uint64) (*RefundDTO, error) {
+	var payment model.PaymentOrder
+	if err := r.db.WithContext(ctx).Where("order_id = ? AND biz_type IN ?", orderID, refundBizTypes).Order("id DESC").First(&payment).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, ErrPaymentNotFound
+		}
+		return nil, err
+	}
+	latest, err := r.syncRefundPayment(ctx, &payment, payment.Status == "failed")
+	if err != nil {
+		return nil, err
+	}
+	dto := toRefundDTO(*latest)
+	return &dto, nil
+}
+func (r *Repository) SyncRefundStatusByPaymentID(ctx context.Context, paymentID uint64) (*RefundDTO, error) {
+	payment, err := r.findPaymentByID(ctx, paymentID)
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, ErrPaymentNotFound
+		}
+		return nil, err
+	}
+	if !isRefundBizType(payment.BizType) {
+		return nil, ErrPaymentNotFound
+	}
+	latest, err := r.syncRefundPayment(ctx, payment, true)
+	if err != nil {
+		return nil, err
+	}
+	dto := toRefundDTO(*latest)
+	return &dto, nil
+}
+func (r *Repository) findOriginalPayment(ctx context.Context, orderID uint64) (model.PaymentOrder, error) {
+	var originalPayment model.PaymentOrder
+	if err := r.db.WithContext(ctx).Where("order_id = ? AND status = 'paid' AND biz_type = 'order_pay'", orderID).Order("id DESC").First(&originalPayment).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return originalPayment, ErrPaymentNotFound
+		}
+		return originalPayment, err
+	}
+	return originalPayment, nil
+}
+
+// prepareRefundOrder 创建退款支付单，并继承原支付单回溯出的支付配置。
+func (r *Repository) prepareRefundOrder(ctx context.Context, originalPayment model.PaymentOrder, runtimeConfig runtimePaymentConfig, refundAmountCent int64, bizType string) (*model.PaymentOrder, bool, error) {
+	var paymentID uint64
+	existing := false
+	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var order model.RentalOrder
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&order, originalPayment.OrderID).Error; err != nil {
+			return err
+		}
+		var existingRefund model.PaymentOrder
+		err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("order_id = ? AND biz_type = ?", originalPayment.OrderID, bizType).
+			Order("id DESC").
+			First(&existingRefund).Error
+		if err == nil {
+			paymentID = existingRefund.ID
+			existing = true
+			return nil
+		}
+		if err != gorm.ErrRecordNotFound {
+			return err
+		}
+		paymentNo, err := newPaymentNo()
+		if err != nil {
+			return err
+		}
+		merchantRefundID := "REF" + paymentNo[3:]
+		refundOrder := model.PaymentOrder{
+			PaymentNo:       paymentNo,
+			OrderID:         originalPayment.OrderID,
+			OrderNo:         originalPayment.OrderNo,
+			UserID:          originalPayment.UserID,
+			PaymentConfigID: runtimeConfig.ID,
+			Provider:        runtimeConfig.Provider,
+			MerchantID:      runtimeConfig.MerchantID,
+			ThirdOrderID:    merchantRefundID,
+			ProviderOrderID: "",
+			PayWay:          originalPayment.PayWay,
+			JSPayFlag:       originalPayment.JSPayFlag,
+			AmountCent:      refundAmountCent,
+			BizType:         bizType,
+			Status:          "refunding",
+		}
+		if err := tx.Create(&refundOrder).Error; err != nil {
+			return err
+		}
+		paymentID = refundOrder.ID
+		return nil
+	})
+	if err != nil {
+		return nil, false, err
+	}
+	payment, err := r.findPaymentByID(ctx, paymentID)
+	if err != nil {
+		return nil, false, err
+	}
+	return payment, existing, nil
+}
+func (r *Repository) syncRefundPayment(ctx context.Context, payment *model.PaymentOrder, queryTerminal bool) (*model.PaymentOrder, error) {
+	if payment.Status == "refunded" && !queryTerminal {
+		if err := r.updateRefundedOrderStatus(ctx, payment.OrderID, payment.AmountCent, payment.BizType); err != nil {
+			return nil, err
+		}
+		return payment, nil
+	}
+	if payment.Status == "failed" && !queryTerminal {
+		if err := r.markRefundFailedOrderStatus(ctx, payment.OrderID, payment.AmountCent, payment.BizType); err != nil {
+			return nil, err
+		}
+		return payment, nil
+	}
+	runtimeConfig, err := r.runtimeConfigForPayment(ctx, payment)
+	if err != nil {
+		return nil, ErrPaymentUnavailable
+	}
+	if runtimeConfig.isMockMode() {
+		if payment.Status == "refunded" {
+			if err := r.updateOrderRefundStatus(ctx, payment.OrderID, payment.AmountCent, payment.BizType); err != nil {
+				return nil, err
+			}
+		}
+		return payment, nil
+	}
+	if runtimeConfig.Channel == nil {
+		return nil, ErrPaymentUnavailable
+	}
+	originalPayment, err := r.findOriginalPaymentForRefund(ctx, payment)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := runtimeConfig.Channel.QueryRefund(ctx, refundQueryRequest(*payment, originalPayment))
+	if err != nil {
+		if resp != nil && resp.RawRequest != nil {
+			if updateErr := r.updateRefundRawRequest(ctx, payment.ID, resp.RawRequest); updateErr != nil {
+				r.log().Warn("退款查询诊断保存失败", paymentLogFields(ctx, appendFields(
+					paymentOrderFields(payment),
+					[]zap.Field{zap.Error(updateErr)},
+				)...,
+				)...)
+			}
+		}
+		return nil, err
+	}
+	if !resp.OK {
+		return nil, ErrPaymentUnavailable
+	}
+	if err := r.applyRefundChannelStatus(ctx, payment, refundChannelStatusUpdate{
+		Status:           resp.Status,
+		ProviderRefundID: resp.ProviderRefundID,
+		RefundTime:       resp.RefundTime,
+		Raw:              resp.Raw,
+		Source:           channelSourceQuery,
+	}); err != nil {
+		return nil, err
+	}
+	return r.findPaymentByID(ctx, payment.ID)
+}
+
+type refundChannelStatusUpdate struct {
+	Status           string
+	ProviderRefundID string
+	RefundTime       string
+	RawRequest       map[string]string
+	Raw              map[string]string
+	Source           string
+}
+
+func (r *Repository) applyRefundChannelStatus(ctx context.Context, payment *model.PaymentOrder, update refundChannelStatusUpdate) error {
+	status := update.Status
+	if status != "refunded" && status != "failed" {
+		status = "refunding"
+	}
+	updates := map[string]any{
+		"status":       status,
+		"raw_response": jsonMap(withRawSource(update.Raw, update.Source)),
+	}
+	if update.ProviderRefundID != "" {
+		updates["provider_order_id"] = update.ProviderRefundID
+	}
+	if update.RawRequest != nil {
+		updates["raw_request"] = jsonMap(update.RawRequest)
+	}
+	if status == "refunded" {
+		paidAt := parseChannelTime(update.RefundTime)
+		if paidAt == nil {
+			now := time.Now()
+			paidAt = &now
+		}
+		updates["paid_at"] = paidAt
+	}
+	if update.Source == channelSourceNotify {
+		updates["notified_at"] = time.Now()
+	}
+	if err := r.db.WithContext(ctx).Model(&model.PaymentOrder{}).Where("id = ?", payment.ID).Updates(updates).Error; err != nil {
+		return err
+	}
+	switch status {
+	case "refunded":
+		return r.updateRefundedOrderStatus(ctx, payment.OrderID, payment.AmountCent, payment.BizType)
+	case "failed":
+		return r.markRefundFailedOrderStatus(ctx, payment.OrderID, payment.AmountCent, payment.BizType)
+	default:
+		return r.markRefundingOrderStatus(ctx, payment.OrderID, payment.AmountCent, payment.BizType)
+	}
+}
+func isRefundBizType(bizType string) bool {
+	for _, item := range refundBizTypes {
+		if item == bizType {
+			return true
+		}
+	}
+	return false
+}
+func refundQueryRequest(payment model.PaymentOrder, originalPayment model.PaymentOrder) channelQueryRefundRequest {
+	return channelQueryRefundRequest{
+		ThirdOrderID:     originalPayment.ThirdOrderID,
+		ProviderOrderID:  refundOriginProviderOrderID(originalPayment),
+		MerchantRefundID: payment.ThirdOrderID,
+		ProviderRefundID: payment.ProviderOrderID,
+	}
+}
+
+func (r *Repository) findOriginalPaymentForRefund(ctx context.Context, payment *model.PaymentOrder) (model.PaymentOrder, error) {
+	if payment != nil && isMohongRefundBizType(payment.BizType) {
+		return r.findOriginalMohongPayment(ctx, payment.OrderID)
+	}
+	return r.findOriginalPayment(ctx, payment.OrderID)
+}
+
+func (r *Repository) updateRefundedOrderStatus(ctx context.Context, orderID uint64, refundAmountCent int64, bizType string) error {
+	if isMohongRefundBizType(bizType) {
+		return r.updateMohongOrderRefundStatus(ctx, orderID)
+	}
+	return r.updateOrderRefundStatus(ctx, orderID, refundAmountCent, bizType)
+}
+
+func (r *Repository) markRefundingOrderStatus(ctx context.Context, orderID uint64, refundAmountCent int64, bizType string) error {
+	if isMohongRefundBizType(bizType) {
+		return nil
+	}
+	return r.markOrderRefunding(ctx, orderID, refundAmountCent)
+}
+
+func (r *Repository) markRefundFailedOrderStatus(ctx context.Context, orderID uint64, refundAmountCent int64, bizType string) error {
+	if isMohongRefundBizType(bizType) {
+		return nil
+	}
+	return r.markOrderRefundFailed(ctx, orderID, refundAmountCent)
+}
+
+func refundedTotalTx(tx *gorm.DB, orderID uint64) (int64, error) {
+	var refundedTotal int64
+	err := tx.Model(&model.PaymentOrder{}).
+		Where("order_id = ? AND status = ?", orderID, "refunded").
+		Where("biz_type IN ?", refundBizTypes).
+		Select("COALESCE(SUM(amount_cent), 0)").Scan(&refundedTotal).Error
+	return refundedTotal, err
+}
+
+func (r *Repository) updateOrderRefundStatus(ctx context.Context, orderID uint64, refundAmountCent int64, bizType string) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var order model.RentalOrder
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&order, orderID).Error; err != nil {
+			return err
+		}
+		// 同一订单可能多笔退款，且退款结果查询会重复回调：
+		// 以已退款成功流水合计为口径，并取本次金额与累计额的较大值，
+		// 保证 order.RefundAmountCent 单调不回退、重复回调幂等。
+		refundedTotal, err := refundedTotalTx(tx, orderID)
+		if err != nil {
+			return err
+		}
+		cumulative := max(refundAmountCent, refundedTotal)
+		now := time.Now()
+		order.RefundStatus = "refunded"
+		order.RefundAmountCent = cumulative
+		order.RefundedAt = &now
+		if bizType == "admin_refund" && order.Status == "completed" && cumulative >= order.RentAmountCent+order.DepositAmountCent {
+			if err := rentergrowth.RevokeOrderCompleted(tx, &order); err != nil {
+				return err
+			}
+		}
+		if err := tx.Save(&order).Error; err != nil {
+			return err
+		}
+		return distribution.ApplyRefundTx(tx, orderID, cumulative)
+	})
+}
+func (r *Repository) markOrderRefunding(ctx context.Context, orderID uint64, refundAmountCent int64) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		refundedTotal, err := refundedTotalTx(tx, orderID)
+		if err != nil {
+			return err
+		}
+		cumulative := max(refundAmountCent, refundedTotal)
+		return tx.Model(&model.RentalOrder{}).Where("id = ?", orderID).Updates(map[string]any{
+			"refund_status":      "refunding",
+			"refund_amount_cent": cumulative,
+			"refunded_at":        nil,
+		}).Error
+	})
+}
+func (r *Repository) markOrderRefundFailed(ctx context.Context, orderID uint64, refundAmountCent int64) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		refundedTotal, err := refundedTotalTx(tx, orderID)
+		if err != nil {
+			return err
+		}
+		return tx.Model(&model.RentalOrder{}).Where("id = ?", orderID).Updates(map[string]any{
+			"refund_status":      "failed",
+			"refund_amount_cent": refundedTotal,
+			"refunded_at":        nil,
+		}).Error
+	})
+}
+func (r *Repository) updateRefundRawRequest(ctx context.Context, paymentID uint64, rawRequest map[string]string) error {
+	if rawRequest == nil {
+		return nil
+	}
+	return r.db.WithContext(ctx).Model(&model.PaymentOrder{}).Where("id = ?", paymentID).Update("raw_request", jsonMap(rawRequest)).Error
+}
+func (r *Repository) markRefundFailed(ctx context.Context, paymentID uint64, orderID uint64, refundAmountCent int64, raw map[string]string, rawRequest map[string]string) error {
+	if raw == nil {
+		raw = map[string]string{"error": "refund failed"}
+	}
+	updates := map[string]any{
+		"status":       "failed",
+		"raw_response": jsonMap(raw),
+	}
+	if rawRequest != nil {
+		updates["raw_request"] = jsonMap(rawRequest)
+	}
+	if err := r.db.WithContext(ctx).Model(&model.PaymentOrder{}).Where("id = ?", paymentID).Updates(updates).Error; err != nil {
+		return err
+	}
+	return r.markOrderRefundFailed(ctx, orderID, refundAmountCent)
+}
+func toRefundDTO(payment model.PaymentOrder) RefundDTO {
+	return RefundDTO{
+		ID:              payment.ID,
+		PaymentNo:       payment.PaymentNo,
+		OrderID:         payment.OrderID,
+		OrderNo:         payment.OrderNo,
+		BizType:         payment.BizType,
+		AmountCent:      payment.AmountCent,
+		Status:          payment.Status,
+		ProviderOrderID: payment.ProviderOrderID,
+		PaidAt:          payment.PaidAt,
+		CreatedAt:       payment.CreatedAt,
+		UpdatedAt:       payment.UpdatedAt,
+	}
+}
+func refundOriginProviderOrderID(payment model.PaymentOrder) string {
+	if payment.Provider != "lakala" {
+		return payment.ProviderOrderID
+	}
+	if tradeID := lakalaOriginTradeID(payment.RawResponse); tradeID != "" {
+		return tradeID
+	}
+	return payment.ProviderOrderID
+}
+func lakalaOriginTradeID(raw datatypes.JSON) string {
+	if len(raw) == 0 {
+		return ""
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		return ""
+	}
+	if tradeID := firstStringValue(payload, "trade_no", "origin_trade_no"); tradeID != "" {
+		return tradeID
+	}
+	value, ok := payload["order_trade_info_list"]
+	if !ok {
+		return ""
+	}
+	switch typed := value.(type) {
+	case string:
+		var items []map[string]any
+		if err := json.Unmarshal([]byte(typed), &items); err != nil {
+			return ""
+		}
+		for _, item := range items {
+			if tradeID := firstStringValue(item, "trade_no", "origin_trade_no"); tradeID != "" {
+				return tradeID
+			}
+		}
+	case []any:
+		for _, item := range typed {
+			itemMap, ok := item.(map[string]any)
+			if !ok {
+				continue
+			}
+			if tradeID := firstStringValue(itemMap, "trade_no", "origin_trade_no"); tradeID != "" {
+				return tradeID
+			}
+		}
+	}
+	return ""
+}
+func firstStringValue(values map[string]any, keys ...string) string {
+	for _, key := range keys {
+		value, ok := values[key]
+		if !ok {
+			continue
+		}
+		if text, ok := value.(string); ok && text != "" {
+			return text
+		}
+	}
+	return ""
+}

backend/internal/modules/payment/refund_cumulative_test.go

@@ -0,0 +1,143 @@
+package payment
+
+import (
+	"testing"
+	"time"
+
+	"hfb_sys/backend/internal/model"
+	"hfb_sys/backend/internal/modules/distribution"
+)
+
+// TestUpdateOrderRefundStatusUsesCumulativeRefundedAmount 断言同一订单多笔退款时，
+// 单笔回调传入的金额不会把订单累计退款额写小，分销财务快照按合计口径重算。
+func TestUpdateOrderRefundStatusUsesCumulativeRefundedAmount(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	repo := NewRepository(db, nil, nil)
+	now := time.Now()
+
+	site := model.DistributionSite{
+		SiteCode: "cum_site", SiteName: "累计退款站", Domain: "cum.dist.com",
+		Status: "active", DisplayAccountEnabled: true,
+	}
+	if err := db.Create(&site).Error; err != nil {
+		t.Fatal(err)
+	}
+	rule := model.DistributionRuleVersion{
+		SiteID: &site.ID, Mode: distribution.ModeTwoPartyPlatformReceive, Version: 1, Status: "active",
+		PlatformReceiveRatio: 35, DistributorSellRatio: 40, ServiceFeeValue: 0,
+		ServiceFeeUnit: distribution.ServiceFeeUnitFixedAmount, PaymentFeeBPS: 0,
+		EffectiveFrom: now.Add(-time.Hour),
+	}
+	if err := db.Create(&rule).Error; err != nil {
+		t.Fatal(err)
+	}
+	order := model.RentalOrder{
+		OrderNo: "ORD-CUM-REFUND", ListingID: 1, AccountID: 1, OwnerID: 1, RenterID: 2,
+		Status: "completed", RentAmountCent: 10000, OwnerRentAmountCent: 6000,
+		DistributionSiteID: &site.ID, DistributionRuleVersionID: &rule.ID,
+	}
+	if err := db.Create(&order).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := distribution.SnapshotPaidOrderTx(db, order.ID, 10000); err != nil {
+		t.Fatal(err)
+	}
+
+	// 两笔已退款成功流水：300 + 700 = 1000。
+	refunds := []model.PaymentOrder{
+		{PaymentNo: "REF-CUM-1", OrderID: order.ID, OrderNo: order.OrderNo, UserID: order.RenterID, Provider: "mock", ThirdOrderID: "REF-CUM-1", AmountCent: 300, BizType: "admin_refund", Status: "refunded"},
+		{PaymentNo: "REF-CUM-2", OrderID: order.ID, OrderNo: order.OrderNo, UserID: order.RenterID, Provider: "mock", ThirdOrderID: "REF-CUM-2", AmountCent: 700, BizType: "rent_refund", Status: "refunded"},
+	}
+	if err := db.Create(&refunds).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	// 只传其中一笔金额调用：累计口径应取两笔合计 1000。
+	if err := repo.updateOrderRefundStatus(t.Context(), order.ID, 300, "admin_refund"); err != nil {
+		t.Fatal(err)
+	}
+	var saved model.RentalOrder
+	if err := db.First(&saved, order.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if saved.RefundAmountCent != 1000 {
+		t.Fatalf("order.RefundAmountCent = %d, want 1000（两笔退款合计）", saved.RefundAmountCent)
+	}
+	if saved.RefundStatus != "refunded" {
+		t.Fatalf("order.RefundStatus = %s, want refunded", saved.RefundStatus)
+	}
+
+	var financial model.DistributionOrderFinancial
+	if err := db.Where("order_id = ?", order.ID).First(&financial).Error; err != nil {
+		t.Fatal(err)
+	}
+	if financial.RefundAmountCent != 1000 || financial.NetPaidAmountCent != 9000 || financial.SplitBaseAmountCent != 3000 {
+		t.Fatalf("分销快照未按累计退款重算：refund=%d netPaid=%d splitBase=%d",
+			financial.RefundAmountCent, financial.NetPaidAmountCent, financial.SplitBaseAmountCent)
+	}
+	var party model.DistributionOrderParty
+	if err := db.Where("order_id = ? AND party_role = ?", order.ID, "distributor_sell").First(&party).Error; err != nil {
+		t.Fatal(err)
+	}
+	if party.IncomeAmountCent != 1200 {
+		t.Fatalf("分站份额 = %d, want 1200（利润 3000 的 40%%）", party.IncomeAmountCent)
+	}
+
+	// 退款结果查询重复回调不应把累计额写小。
+	if err := repo.updateOrderRefundStatus(t.Context(), order.ID, 300, "admin_refund"); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.First(&saved, order.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if saved.RefundAmountCent != 1000 {
+		t.Fatalf("重复回调后 order.RefundAmountCent = %d, want 1000（单调不回退）", saved.RefundAmountCent)
+	}
+}
+
+// TestMarkOrderRefundingAndFailedPreserveCumulativeRefund 断言已成功退款的订单
+// 发生后续退款中或退款失败时，累计退款额不会被单笔处理金额冲减缩小。
+func TestMarkOrderRefundingAndFailedPreserveCumulativeRefund(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	repo := NewRepository(db, nil, nil)
+
+	order := model.RentalOrder{
+		OrderNo: "ORD-REF-PRESERVE", ListingID: 1, AccountID: 1, OwnerID: 1, RenterID: 2,
+		Status: "completed", RentAmountCent: 10000, OwnerRentAmountCent: 6000,
+	}
+	if err := db.Create(&order).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	// 先前已成功退款 5000。
+	prevRefund := model.PaymentOrder{
+		PaymentNo: "REF-PREV-1", OrderID: order.ID, OrderNo: order.OrderNo, UserID: order.RenterID,
+		Provider: "mock", ThirdOrderID: "REF-PREV-1", AmountCent: 5000, BizType: "admin_refund", Status: "refunded",
+	}
+	if err := db.Create(&prevRefund).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	// 此时发起了另一笔 2000 的退款中：累计额应为 max(2000, 5000) = 5000。
+	if err := repo.markOrderRefunding(t.Context(), order.ID, 2000); err != nil {
+		t.Fatal(err)
+	}
+	var saved model.RentalOrder
+	if err := db.First(&saved, order.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if saved.RefundStatus != "refunding" || saved.RefundAmountCent != 5000 {
+		t.Fatalf("markOrderRefunding 后状态 = %s/%d, want refunding/5000", saved.RefundStatus, saved.RefundAmountCent)
+	}
+
+	// 该笔 2000 退款最终失败：累计退款额还原为已成功流水合计 5000，而不是单笔 2000。
+	if err := repo.markOrderRefundFailed(t.Context(), order.ID, 2000); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.First(&saved, order.ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if saved.RefundStatus != "failed" || saved.RefundAmountCent != 5000 {
+		t.Fatalf("markOrderRefundFailed 后状态 = %s/%d, want failed/5000", saved.RefundStatus, saved.RefundAmountCent)
+	}
+}

backend/internal/modules/payment/refund_mohong.go

@@ -0,0 +1,230 @@
+package payment
+
+import (
+	"context"
+
+	"hfb_sys/backend/internal/model"
+
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+const bizTypeMohongRefund = "mohong_refund"
+
+func (r *Repository) StartMohongRefund(ctx context.Context, orderID uint64, refundAmountCent int64, remark string) (*RefundDTO, error) {
+	originalPayment, err := r.findOriginalMohongPayment(ctx, orderID)
+	if err != nil {
+		return nil, err
+	}
+	runtimeConfig, err := r.runtimeConfigForPayment(ctx, &originalPayment)
+	if err != nil {
+		return nil, ErrPaymentUnavailable
+	}
+
+	refundOrder, existing, err := r.prepareMohongRefundOrder(ctx, originalPayment, *runtimeConfig, refundAmountCent)
+	if err != nil {
+		return nil, err
+	}
+	if existing {
+		latest, syncErr := r.syncRefundPayment(ctx, refundOrder, refundOrder.Status != "refunded")
+		if syncErr != nil {
+			r.log().Warn("已有撞车退款单同步失败", paymentLogFields(ctx, appendFields(
+				paymentOrderFields(refundOrder),
+				[]zap.Field{zap.Error(syncErr)},
+			)...,
+			)...)
+			dto := toRefundDTO(*refundOrder)
+			return &dto, nil
+		}
+		dto := toRefundDTO(*latest)
+		return &dto, nil
+	}
+
+	if runtimeConfig.isMockMode() {
+		raw := map[string]string{"mock": "true"}
+		if remark != "" {
+			raw["remark"] = remark
+		}
+		if err := r.applyRefundChannelStatus(ctx, refundOrder, refundChannelStatusUpdate{
+			Status:           "refunded",
+			ProviderRefundID: "MOCKREF" + refundOrder.ThirdOrderID,
+			Raw:              raw,
+			Source:           channelSourceMock,
+		}); err != nil {
+			return nil, err
+		}
+		latest, err := r.findPaymentByID(ctx, refundOrder.ID)
+		if err != nil {
+			return nil, err
+		}
+		dto := toRefundDTO(*latest)
+		return &dto, nil
+	}
+
+	if runtimeConfig.Channel == nil {
+		if err := r.markMohongRefundFailed(ctx, refundOrder.ID, map[string]string{"error": "payment channel unavailable"}, nil); err != nil {
+			r.log().Warn("撞车退款失败状态保存失败", paymentLogFields(ctx, appendFields(
+				paymentOrderFields(refundOrder),
+				[]zap.Field{zap.Error(err)},
+			)...,
+			)...)
+		}
+		return nil, ErrPaymentUnavailable
+	}
+	resp, err := runtimeConfig.Channel.CreateRefund(ctx, channelCreateRefundRequest{
+		ThirdOrderID:     originalPayment.ThirdOrderID,
+		ProviderOrderID:  refundOriginProviderOrderID(originalPayment),
+		MerchantRefundID: refundOrder.ThirdOrderID,
+		RefundAmountCent: refundOrder.AmountCent,
+		NotifyURL:        runtimeConfig.NotifyURL,
+		Attach:           originalPayment.OrderNo,
+		Remark:           remark,
+	})
+	if err != nil {
+		var rawRequest map[string]string
+		if resp != nil {
+			rawRequest = resp.RawRequest
+		}
+		if markErr := r.markMohongRefundFailed(ctx, refundOrder.ID, map[string]string{"error": err.Error()}, rawRequest); markErr != nil {
+			r.log().Warn("撞车退款失败状态保存失败", paymentLogFields(ctx, appendFields(
+				paymentOrderFields(refundOrder),
+				[]zap.Field{zap.Error(markErr)},
+			)...,
+			)...)
+		}
+		return nil, err
+	}
+	if !resp.OK {
+		if markErr := r.markMohongRefundFailed(ctx, refundOrder.ID, resp.Raw, resp.RawRequest); markErr != nil {
+			r.log().Warn("撞车退款拒绝状态保存失败", paymentLogFields(ctx, appendFields(
+				paymentOrderFields(refundOrder),
+				[]zap.Field{zap.Error(markErr)},
+			)...,
+			)...)
+		}
+		return nil, ErrPaymentUnavailable
+	}
+
+	if err := r.applyRefundChannelStatus(ctx, refundOrder, refundChannelStatusUpdate{
+		Status:           resp.Status,
+		ProviderRefundID: resp.ProviderRefundID,
+		RawRequest:       resp.RawRequest,
+		Raw:              resp.Raw,
+		Source:           channelSourceCreate,
+	}); err != nil {
+		return nil, err
+	}
+	latest, err := r.findPaymentByID(ctx, refundOrder.ID)
+	if err != nil {
+		return nil, err
+	}
+	dto := toRefundDTO(*latest)
+	return &dto, nil
+}
+
+func (r *Repository) findOriginalMohongPayment(ctx context.Context, orderID uint64) (model.PaymentOrder, error) {
+	var originalPayment model.PaymentOrder
+	if err := r.db.WithContext(ctx).
+		Where("order_id = ? AND status = 'paid' AND biz_type = ?", orderID, bizTypeMohongPay).
+		Order("id DESC").
+		First(&originalPayment).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return originalPayment, ErrPaymentNotFound
+		}
+		return originalPayment, err
+	}
+	return originalPayment, nil
+}
+
+func (r *Repository) prepareMohongRefundOrder(ctx context.Context, originalPayment model.PaymentOrder, runtimeConfig runtimePaymentConfig, refundAmountCent int64) (*model.PaymentOrder, bool, error) {
+	var paymentID uint64
+	existing := false
+	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var order model.MohongOrder
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&order, originalPayment.OrderID).Error; err != nil {
+			return err
+		}
+		if order.Status != model.MohongOrderStatusCancelled {
+			return ErrRefundCannotStart
+		}
+		amountCent := refundAmountCent
+		if amountCent == 0 {
+			amountCent = order.AmountCent
+		}
+		if amountCent <= 0 || amountCent > originalPayment.AmountCent {
+			return ErrRefundCannotStart
+		}
+
+		var existingRefund model.PaymentOrder
+		err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("order_id = ? AND biz_type = ?", originalPayment.OrderID, bizTypeMohongRefund).
+			Order("id DESC").
+			First(&existingRefund).Error
+		if err == nil {
+			paymentID = existingRefund.ID
+			existing = true
+			return nil
+		}
+		if err != gorm.ErrRecordNotFound {
+			return err
+		}
+
+		paymentNo, err := newPaymentNo()
+		if err != nil {
+			return err
+		}
+		merchantRefundID := "REF" + paymentNo[3:]
+		refundOrder := model.PaymentOrder{
+			PaymentNo:       paymentNo,
+			OrderID:         originalPayment.OrderID,
+			OrderNo:         originalPayment.OrderNo,
+			UserID:          originalPayment.UserID,
+			PaymentConfigID: runtimeConfig.ID,
+			Provider:        runtimeConfig.Provider,
+			MerchantID:      runtimeConfig.MerchantID,
+			ThirdOrderID:    merchantRefundID,
+			ProviderOrderID: "",
+			PayWay:          originalPayment.PayWay,
+			JSPayFlag:       originalPayment.JSPayFlag,
+			AmountCent:      amountCent,
+			BizType:         bizTypeMohongRefund,
+			Status:          "refunding",
+		}
+		if err := tx.Create(&refundOrder).Error; err != nil {
+			return err
+		}
+		paymentID = refundOrder.ID
+		return nil
+	})
+	if err != nil {
+		return nil, false, err
+	}
+	payment, err := r.findPaymentByID(ctx, paymentID)
+	if err != nil {
+		return nil, false, err
+	}
+	return payment, existing, nil
+}
+
+func (r *Repository) updateMohongOrderRefundStatus(ctx context.Context, orderID uint64) error {
+	return r.db.WithContext(ctx).Model(&model.MohongOrder{}).Where("id = ?", orderID).Update("status", model.MohongOrderStatusRefunded).Error
+}
+
+func (r *Repository) markMohongRefundFailed(ctx context.Context, paymentID uint64, raw map[string]string, rawRequest map[string]string) error {
+	if raw == nil {
+		raw = map[string]string{"error": "refund failed"}
+	}
+	updates := map[string]any{
+		"status":       "failed",
+		"raw_response": jsonMap(raw),
+	}
+	if rawRequest != nil {
+		updates["raw_request"] = jsonMap(rawRequest)
+	}
+	return r.db.WithContext(ctx).Model(&model.PaymentOrder{}).Where("id = ?", paymentID).Updates(updates).Error
+}
+
+func isMohongRefundBizType(bizType string) bool {
+	return bizType == bizTypeMohongRefund
+}

backend/internal/modules/payment/repository.go

@@ -0,0 +1,288 @@
+package payment
+
+import (
+	"context"
+	"sort"
+
+	"hfb_sys/backend/internal/logging"
+	"hfb_sys/backend/internal/model"
+	"hfb_sys/backend/internal/modules/order"
+	"hfb_sys/backend/internal/modules/paymentconfig"
+
+	"go.uber.org/zap"
+	"gorm.io/gorm"
+)
+
+// MohongOrderConfirmer 撞车订单支付确认接口，避免 payment 与 mohong 循环依赖。
+type MohongOrderConfirmer interface {
+	ConfirmPaidFromChannelTx(tx *gorm.DB, orderID uint64) (uint64, error)
+	NotifyNewConversation(conversationID uint64)
+}
+
+type Repository struct {
+	db         *gorm.DB
+	configRepo *paymentconfig.Repository
+	orderRepo  *order.Repository
+	mohongRepo MohongOrderConfirmer
+	logger     *zap.Logger
+}
+
+type runtimePaymentConfig struct {
+	ID         uint64
+	Provider   string
+	MerchantID string
+	PayWay     string
+	JSPayFlag  string
+	NotifyURL  string
+	JumpURL    string
+	Channel    channelClient
+}
+
+const (
+	channelSourceCreate = "create"
+	channelSourceQuery  = "query"
+	channelSourceNotify = "notify"
+	channelSourceMock   = "mock"
+)
+
+var refundBizTypes = []string{
+	"cancel_refund",
+	"admin_close_refund",
+	"admin_refund",
+	"checkout_refund",
+	"deposit_refund",
+	"rent_refund",
+	"arbitration_refund",
+}
+
+func RefundBizTypes() []string {
+	out := make([]string, len(refundBizTypes))
+	copy(out, refundBizTypes)
+	return out
+}
+
+// NewRepository 创建支付仓库，注入支付配置仓库和订单仓库。
+func NewRepository(db *gorm.DB, configRepo *paymentconfig.Repository, orderRepo *order.Repository, options ...RepositoryOption) *Repository {
+	repo := &Repository{
+		db:         db,
+		configRepo: configRepo,
+		orderRepo:  orderRepo,
+		logger:     zap.NewNop(),
+	}
+	for _, option := range options {
+		option(repo)
+	}
+	if repo.logger == nil {
+		repo.logger = zap.NewNop()
+	}
+	return repo
+}
+
+type RepositoryOption func(*Repository)
+
+// WithLogger 为支付仓库注入结构化日志器。
+func WithLogger(logger *zap.Logger) RepositoryOption {
+	return func(repo *Repository) {
+		if logger != nil {
+			repo.logger = logger
+		}
+	}
+}
+
+// WithMohongRepo 注入撞车订单确认器。
+func WithMohongRepo(repo MohongOrderConfirmer) RepositoryOption {
+	return func(r *Repository) {
+		r.mohongRepo = repo
+	}
+}
+
+func (r *Repository) log() *zap.Logger {
+	if r == nil || r.logger == nil {
+		return zap.NewNop()
+	}
+	return r.logger
+}
+
+func paymentLogFields(ctx context.Context, fields ...zap.Field) []zap.Field {
+	base := []zap.Field{zap.String("module", "payment")}
+	if requestID := logging.RequestIDFromContext(ctx); requestID != "" {
+		base = append(base, zap.String("request_id", requestID))
+	}
+	return append(base, fields...)
+}
+
+func runtimeConfigFields(runtimeConfig *runtimePaymentConfig) []zap.Field {
+	if runtimeConfig == nil {
+		return nil
+	}
+	return []zap.Field{
+		zap.Uint64("payment_config_id", runtimeConfig.ID),
+		zap.String("provider", runtimeConfig.Provider),
+		zap.String("merchant_id", runtimeConfig.MerchantID),
+		zap.String("pay_way", runtimeConfig.PayWay),
+	}
+}
+
+func paymentOrderFields(payment *model.PaymentOrder) []zap.Field {
+	if payment == nil {
+		return nil
+	}
+	return []zap.Field{
+		zap.Uint64("payment_id", payment.ID),
+		zap.Uint64("order_id", payment.OrderID),
+		zap.String("order_no", payment.OrderNo),
+		zap.String("third_order_id", payment.ThirdOrderID),
+		zap.String("provider_order_id", payment.ProviderOrderID),
+		zap.Int64("amount_cent", payment.AmountCent),
+		zap.String("biz_type", payment.BizType),
+		zap.String("status", payment.Status),
+	}
+}
+
+func appendFields(groups ...[]zap.Field) []zap.Field {
+	var out []zap.Field
+	for _, group := range groups {
+		out = append(out, group...)
+	}
+	return out
+}
+
+func stringMapKeys(value map[string]string) []string {
+	keys := make([]string, 0, len(value))
+	for key := range value {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+// isMockMode 判断当前运行时配置是否为模拟支付。
+func (c runtimePaymentConfig) isMockMode() bool {
+	return c.Provider == "mock"
+}
+
+// resolveOrderRuntimeConfig 根据订单所属分销站点配置或全局默认配置解析运行时支付配置。
+func (r *Repository) resolveOrderRuntimeConfig(ctx context.Context, tx *gorm.DB, siteID *uint64, payWay string) (*runtimePaymentConfig, error) {
+	if siteID != nil && *siteID > 0 {
+		var configID uint64
+		queryDB := tx
+		if queryDB == nil {
+			queryDB = r.db
+		}
+		err := queryDB.WithContext(ctx).Table("distribution_site_payment_channels dspc").
+			Joins("JOIN payment_merchant_configs pmc ON pmc.id = dspc.config_id").
+			Where("dspc.site_id = ? AND dspc.status = 'active' AND pmc.status = 'active' AND (pmc.pay_way = ? OR pmc.pay_way = '')", *siteID, payWay).
+			Order("dspc.priority ASC, dspc.id ASC").
+			Limit(1).
+			Pluck("pmc.id", &configID).Error
+		if err == nil && configID > 0 && r.configRepo != nil {
+			dto, err := r.configRepo.FindRuntimeByID(ctx, configID, true)
+			if err == nil {
+				return runtimeConfigFromDTO(dto), nil
+			}
+		}
+	}
+	return r.defaultRuntimeConfig(ctx, payWay)
+}
+
+// defaultRuntimeConfig 按支付方式获取默认启用配置，用于新支付单创建。
+func (r *Repository) defaultRuntimeConfig(ctx context.Context, payWay string) (*runtimePaymentConfig, error) {
+	if r.configRepo == nil {
+		return nil, ErrPaymentUnavailable
+	}
+	dto, err := r.configRepo.FindDefaultByPayWay(ctx, payWay, true)
+	if err != nil {
+		return nil, err
+	}
+	return runtimeConfigFromDTO(dto), nil
+}
+
+// runtimeConfigForPayment 回溯支付单当时命中的配置，优先使用 payment_config_id。
+func (r *Repository) runtimeConfigForPayment(ctx context.Context, payment *model.PaymentOrder) (*runtimePaymentConfig, error) {
+	provider := firstNonEmpty(payment.Provider, "mock")
+	merchantID := payment.MerchantID
+	payWay := normalizePayWay(payment.PayWay)
+	if r.configRepo != nil && payment.PaymentConfigID > 0 {
+		dto, err := r.configRepo.FindRuntimeByID(ctx, payment.PaymentConfigID, true)
+		if err == nil {
+			return runtimeConfigFromDTO(dto), nil
+		}
+		if err != paymentconfig.ErrConfigNotFound {
+			return nil, err
+		}
+	}
+	if r.configRepo != nil && merchantID != "" {
+		dto, err := r.configRepo.FindByProviderMerchantPayWay(ctx, provider, merchantID, payWay, true)
+		if err == nil {
+			return runtimeConfigFromDTO(dto), nil
+		}
+		if err != paymentconfig.ErrConfigNotFound {
+			return nil, err
+		}
+		dto, err = r.configRepo.FindByProviderMerchant(ctx, provider, merchantID, true)
+		if err == nil {
+			return runtimeConfigFromDTO(dto), nil
+		}
+		if err != paymentconfig.ErrConfigNotFound {
+			return nil, err
+		}
+	}
+	if provider == "mock" {
+		return &runtimePaymentConfig{
+			Provider:   provider,
+			MerchantID: merchantID,
+		}, nil
+	}
+	if provider != "leshua" && provider != "lakala" && provider != "shuncheng" {
+		return &runtimePaymentConfig{
+			Provider:   provider,
+			MerchantID: merchantID,
+		}, nil
+	}
+	if r.configRepo == nil {
+		return nil, ErrPaymentUnavailable
+	}
+	dto, err := r.configRepo.FindDefaultByProviderPayWay(ctx, provider, payWay, true)
+	if err != nil {
+		return nil, err
+	}
+	return runtimeConfigFromDTO(dto), nil
+}
+
+// runtimeConfigFromDTO 将后台支付配置 DTO 转为支付运行时配置。
+func runtimeConfigFromDTO(dto *paymentconfig.ConfigDTO) *runtimePaymentConfig {
+	provider := firstNonEmpty(dto.Provider, "mock")
+	payWay := normalizePayWay(dto.PayWay)
+	jsPayFlag := firstNonEmpty(dto.JSPayFlag, "2")
+	client, err := buildChannelClient(dto)
+	if err != nil {
+		client = nil
+	}
+	return &runtimePaymentConfig{
+		ID:         dto.ID,
+		Provider:   provider,
+		MerchantID: dto.MerchantID,
+		PayWay:     payWay,
+		JSPayFlag:  jsPayFlag,
+		NotifyURL:  dto.NotifyURL,
+		JumpURL:    dto.JumpURL,
+		Channel:    client,
+	}
+}
+
+// recordConfigUsage 记录成功支付使用的配置，失败只写日志不影响主流程。
+func (r *Repository) recordConfigUsage(ctx context.Context, runtimeConfig *runtimePaymentConfig, payment *model.PaymentOrder) {
+	if r.configRepo == nil || runtimeConfig == nil || payment == nil || runtimeConfig.ID == 0 {
+		return
+	}
+	if (payment.BizType != "order_pay" && payment.BizType != "mohong_pay") || payment.Status != "paid" {
+		return
+	}
+	if err := r.configRepo.RecordUsage(ctx, runtimeConfig.ID, payment.ID, runtimeConfig.Provider, runtimeConfig.MerchantID, payment.AmountCent, payment.BizType); err != nil {
+		r.log().Warn("支付配置使用记录保存失败", paymentLogFields(ctx,
+			zap.Uint64("payment_config_id", runtimeConfig.ID),
+			zap.Uint64("payment_id", payment.ID),
+			zap.Error(err),
+		)...)
+	}
+}

backend/internal/modules/payment/repository_integration_test.go

@@ -0,0 +1,929 @@
+package payment
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"hfb_sys/backend/internal/database"
+	"hfb_sys/backend/internal/model"
+	ordermodule "hfb_sys/backend/internal/modules/order"
+	"hfb_sys/backend/internal/modules/paymentconfig"
+	"hfb_sys/backend/internal/modules/rentergrowth"
+
+	"gorm.io/gorm"
+)
+
+// setupPaymentTestDB 创建测试数据库
+func setupPaymentTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	db := database.NewTestDB()
+	if err := database.MigrateRentalTransactionTestSchema(db); err != nil {
+		t.Fatalf("数据库迁移失败: %v", err)
+	}
+
+	return db
+}
+
+type payableOrderFixture struct {
+	Owner   model.User
+	Renter  model.User
+	Account model.GameAccount
+	Listing model.RentalListing
+	Order   model.RentalOrder
+	Payment model.PaymentOrder
+}
+
+func createPayableOrderFixture(t *testing.T, db *gorm.DB, suffix string, createPayment bool) payableOrderFixture {
+	t.Helper()
+	f := payableOrderFixture{
+		Owner:  model.User{Phone: "13800001" + suffix},
+		Renter: model.User{Phone: "13900001" + suffix},
+	}
+	if err := db.Create(&f.Owner).Error; err != nil {
+		t.Fatalf("create owner failed: %v", err)
+	}
+	if err := db.Create(&f.Renter).Error; err != nil {
+		t.Fatalf("create renter failed: %v", err)
+	}
+	f.Account = model.GameAccount{
+		OwnerID:       f.Owner.ID,
+		ServerRegion:  "国服",
+		LoginPlatform: "steam",
+		Title:         "测试账号",
+		Status:        "published",
+	}
+	if err := db.Create(&f.Account).Error; err != nil {
+		t.Fatalf("create account failed: %v", err)
+	}
+	f.Listing = model.RentalListing{
+		ListingNo:     "LST20260614" + suffix,
+		OwnerID:       f.Owner.ID,
+		AccountID:     f.Account.ID,
+		Status:        "published",
+		ReviewStatus:  "approved",
+		InTransaction: true,
+		PriceCent:     1000,
+	}
+	if err := db.Create(&f.Listing).Error; err != nil {
+		t.Fatalf("create listing failed: %v", err)
+	}
+	f.Order = model.RentalOrder{
+		OrderNo:        "ORD20260614" + suffix,
+		ListingID:      f.Listing.ID,
+		AccountID:      f.Account.ID,
+		OwnerID:        f.Owner.ID,
+		RenterID:       f.Renter.ID,
+		RentAmountCent: 1000,
+		Status:         "pending_payment",
+		HandoffStatus:  "none",
+	}
+	if err := db.Create(&f.Order).Error; err != nil {
+		t.Fatalf("create order failed: %v", err)
+	}
+	f.Payment = model.PaymentOrder{
+		PaymentNo:       "PAY20260614" + suffix,
+		OrderID:         f.Order.ID,
+		OrderNo:         f.Order.OrderNo,
+		UserID:          f.Renter.ID,
+		Provider:        "mock",
+		ThirdOrderID:    "PAY20260614" + suffix,
+		ProviderOrderID: "MOCKPAY20260614" + suffix,
+		AmountCent:      1000,
+		BizType:         "order_pay",
+		Status:          "paying",
+	}
+	if createPayment {
+		if err := db.Create(&f.Payment).Error; err != nil {
+			t.Fatalf("create payment failed: %v", err)
+		}
+	}
+	return f
+}
+
+func TestMarkRefundFailedPersistsRawRequest(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	f := createPayableOrderFixture(t, db, "RAWREQ", true)
+	refund := model.PaymentOrder{
+		PaymentNo:       "PAYREFRAWREQ",
+		OrderID:         f.Order.ID,
+		OrderNo:         f.Order.OrderNo,
+		UserID:          f.Renter.ID,
+		Provider:        "lakala",
+		MerchantID:      "merchant-1",
+		ThirdOrderID:    "REFRAWREQ",
+		ProviderOrderID: "",
+		AmountCent:      99,
+		BizType:         "checkout_refund",
+		Status:          "refunding",
+	}
+	if err := db.Create(&refund).Error; err != nil {
+		t.Fatalf("create refund payment failed: %v", err)
+	}
+
+	repo := NewRepository(db, nil, nil)
+	rawRequest := map[string]string{
+		"merchant_no":     "merchant-1",
+		"out_trade_no":    "REFRAWREQ",
+		"refund_amount":   "99",
+		"origin_trade_no": "TRADE123",
+	}
+	err := repo.markRefundFailed(context.Background(), refund.ID, f.Order.ID, refund.AmountCent, map[string]string{"error": "lakala http status 400"}, rawRequest)
+	if err != nil {
+		t.Fatalf("mark refund failed: %v", err)
+	}
+
+	var saved model.PaymentOrder
+	if err := db.First(&saved, refund.ID).Error; err != nil {
+		t.Fatalf("find refund payment failed: %v", err)
+	}
+	var got map[string]string
+	if err := json.Unmarshal(saved.RawRequest, &got); err != nil {
+		t.Fatalf("decode raw_request: %v", err)
+	}
+	for key, want := range rawRequest {
+		if got[key] != want {
+			t.Fatalf("raw_request[%s] = %q, want %q; full=%v", key, got[key], want, got)
+		}
+	}
+}
+
+// TestCanReusePaymentWithSameProvider 测试相同渠道可复用
+func TestCanReusePaymentWithSameProvider(t *testing.T) {
+	payment := model.PaymentOrder{
+		Status:     "paying",
+		Provider:   "lakala",
+		MerchantID: "M123",
+	}
+
+	config := runtimePaymentConfig{
+		Provider:   "lakala",
+		MerchantID: "M123",
+	}
+
+	if !canReuseOrderPayment(payment, config) {
+		t.Fatal("should reuse payment with same provider and merchant")
+	}
+}
+
+// TestCannotReusePaymentWithDifferentProvider 测试不同渠道不可复用
+func TestCannotReusePaymentWithDifferentProvider(t *testing.T) {
+	payment := model.PaymentOrder{
+		Status:     "paying",
+		Provider:   "lakala",
+		MerchantID: "M123",
+	}
+
+	config := runtimePaymentConfig{
+		Provider:   "leshua", // 不同渠道
+		MerchantID: "M456",
+	}
+
+	if canReuseOrderPayment(payment, config) {
+		t.Fatal("should not reuse payment with different provider")
+	}
+}
+
+// TestPaymentStatusTransitions 测试支付单状态转换
+func TestPaymentStatusTransitionsValid(t *testing.T) {
+	validTransitions := map[string][]string{
+		"pending":  {"paying", "closed"},
+		"paying":   {"paid", "failed", "closed"},
+		"paid":     {"refunding", "refunded"},
+		"failed":   {}, // 终态
+		"closed":   {}, // 终态
+		"refunded": {}, // 终态
+	}
+
+	for from, toList := range validTransitions {
+		if from == "" {
+			t.Fatal("payment status should not be empty")
+		}
+		for _, to := range toList {
+			if to == "" {
+				t.Fatal("transition target should not be empty")
+			}
+		}
+	}
+}
+
+// TestRefundBizTypeCoverage 测试退款业务类型覆盖
+func TestRefundBizTypeCoverage(t *testing.T) {
+	expected := []string{
+		"cancel_refund",
+		"admin_close_refund",
+		"admin_refund",
+		"checkout_refund",
+		"deposit_refund",
+		"rent_refund",
+		"arbitration_refund",
+	}
+
+	if len(refundBizTypes) != len(expected) {
+		t.Fatalf("refundBizTypes count = %d, want %d", len(refundBizTypes), len(expected))
+	}
+
+	// 验证每个预期类型都存在
+	typeMap := make(map[string]bool)
+	for _, bizType := range refundBizTypes {
+		typeMap[bizType] = true
+	}
+
+	for _, exp := range expected {
+		if !typeMap[exp] {
+			t.Fatalf("missing refund biz type: %s", exp)
+		}
+	}
+}
+
+// TestPaymentAmountValidation 测试支付金额验证
+func TestPaymentAmountMustBePositive(t *testing.T) {
+	testCases := []struct {
+		name      string
+		amount    int64
+		wantValid bool
+	}{
+		{"正数金额", 10000, true},
+		{"零金额", 0, false},
+		{"负数金额", -1000, false},
+		{"最小金额", 1, true},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			isValid := tc.amount > 0
+			if isValid != tc.wantValid {
+				t.Fatalf("amount %d validation = %v, want %v", tc.amount, isValid, tc.wantValid)
+			}
+		})
+	}
+}
+
+// TestPaymentProviderValidation 测试支付渠道验证
+func TestPaymentProviderMustNotBeEmpty(t *testing.T) {
+	testCases := []struct {
+		name      string
+		provider  string
+		wantValid bool
+	}{
+		{"lakala 渠道", "lakala", true},
+		{"leshua 渠道", "leshua", true},
+		{"mock 渠道", "mock", true},
+		{"空渠道", "", false},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			isValid := tc.provider != ""
+			if isValid != tc.wantValid {
+				t.Fatalf("provider %q validation = %v, want %v", tc.provider, isValid, tc.wantValid)
+			}
+		})
+	}
+}
+
+// TestRuntimeConfigIsMockMode 测试运行时配置 mock 模式
+func TestRuntimeConfigIsMockModeTrue(t *testing.T) {
+	config := runtimePaymentConfig{
+		Provider: "mock",
+	}
+
+	if !config.isMockMode() {
+		t.Fatal("should be mock mode when provider is 'mock'")
+	}
+}
+
+func TestRuntimeConfigIsMockModeFalse(t *testing.T) {
+	providers := []string{"lakala", "leshua", "alipay", "wechat"}
+
+	for _, provider := range providers {
+		config := runtimePaymentConfig{
+			Provider: provider,
+		}
+
+		if config.isMockMode() {
+			t.Fatalf("should not be mock mode when provider is %q", provider)
+		}
+	}
+}
+
+// TestChannelSourceValidation 测试渠道来源验证
+func TestChannelSourceMustBeValid(t *testing.T) {
+	validSources := []string{
+		channelSourceCreate,
+		channelSourceQuery,
+		channelSourceNotify,
+		channelSourceMock,
+	}
+
+	expectedValues := []string{"create", "query", "notify", "mock"}
+
+	for i, source := range validSources {
+		if source != expectedValues[i] {
+			t.Fatalf("channelSource[%d] = %q, want %q", i, source, expectedValues[i])
+		}
+	}
+}
+
+// TestPaymentOrderFields 测试支付单字段完整性
+func TestPaymentOrderRequiredFields(t *testing.T) {
+	payment := model.PaymentOrder{
+		PaymentNo:  "PAY123456",
+		OrderNo:    "ORD123456",
+		OrderID:    100,
+		UserID:     1,
+		AmountCent: 10000,
+		Status:     "paying",
+		Provider:   "lakala",
+		MerchantID: "M123",
+		BizType:    "order_pay",
+	}
+
+	// 验证必填字段
+	if payment.PaymentNo == "" {
+		t.Fatal("PaymentNo should not be empty")
+	}
+	if payment.OrderNo == "" {
+		t.Fatal("OrderNo should not be empty")
+	}
+	if payment.OrderID == 0 {
+		t.Fatal("OrderID should not be zero")
+	}
+	if payment.UserID == 0 {
+		t.Fatal("UserID should not be zero")
+	}
+	if payment.AmountCent <= 0 {
+		t.Fatal("AmountCent should be positive")
+	}
+	if payment.Status == "" {
+		t.Fatal("Status should not be empty")
+	}
+	if payment.Provider == "" {
+		t.Fatal("Provider should not be empty")
+	}
+}
+
+// TestRefundAmountValidation 测试退款金额验证
+func TestRefundAmountMustNotExceedOriginal(t *testing.T) {
+	testCases := []struct {
+		name           string
+		originalAmount int64
+		refundAmount   int64
+		wantValid      bool
+	}{
+		{"部分退款", 10000, 5000, true},
+		{"全额退款", 10000, 10000, true},
+		{"超额退款", 10000, 15000, false},
+		{"零退款", 10000, 0, false},
+		{"负数退款", 10000, -1000, false},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			isValid := tc.refundAmount > 0 && tc.refundAmount <= tc.originalAmount
+			if isValid != tc.wantValid {
+				t.Fatalf("refund %d from %d validation = %v, want %v",
+					tc.refundAmount, tc.originalAmount, isValid, tc.wantValid)
+			}
+		})
+	}
+}
+
+func TestSuccessfulAdminFullRefundRevokesCompletedOrderGrowthPoints(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	repo := NewRepository(db, nil, nil)
+	renter := model.User{Phone: "13900001991", RenterGrowthLevel: "normal"}
+	if err := db.Create(&renter).Error; err != nil {
+		t.Fatalf("create renter failed: %v", err)
+	}
+	order := model.RentalOrder{
+		OrderNo:               "ORD202607260991",
+		RenterID:              renter.ID,
+		RentAmountCent:        1000,
+		Status:                "completed",
+		GrowthPointsBasisCent: 1000,
+		GrowthPointsPerYuan:   1,
+	}
+	if err := db.Create(&order).Error; err != nil {
+		t.Fatalf("create order failed: %v", err)
+	}
+	if err := rentergrowth.AwardOrderCompleted(db, &order, 1000, rentergrowth.SourceOrderCompleted); err != nil {
+		t.Fatalf("award growth points failed: %v", err)
+	}
+	if err := db.Save(&order).Error; err != nil {
+		t.Fatalf("save awarded order failed: %v", err)
+	}
+
+	if err := repo.updateOrderRefundStatus(t.Context(), order.ID, 1000, "admin_refund"); err != nil {
+		t.Fatalf("update admin refund status failed: %v", err)
+	}
+	if err := repo.updateOrderRefundStatus(t.Context(), order.ID, 1000, "admin_refund"); err != nil {
+		t.Fatalf("repeat admin refund status failed: %v", err)
+	}
+	var savedUser model.User
+	if err := db.First(&savedUser, renter.ID).Error; err != nil {
+		t.Fatalf("find renter failed: %v", err)
+	}
+	if savedUser.RenterGrowthPoints != 0 || savedUser.RenterGrowthLevel != rentergrowth.DefaultLevelCode {
+		t.Fatalf("growth after refund = %d/%s, want 0/%s", savedUser.RenterGrowthPoints, savedUser.RenterGrowthLevel, rentergrowth.DefaultLevelCode)
+	}
+	var revokeCount int64
+	if err := db.Model(&model.RenterGrowthLedger{}).
+		Where("order_id = ? AND source = ?", order.ID, rentergrowth.SourceOrderRefunded).
+		Count(&revokeCount).Error; err != nil {
+		t.Fatalf("count revoke ledger failed: %v", err)
+	}
+	if revokeCount != 1 {
+		t.Fatalf("revoke ledger count = %d, want 1", revokeCount)
+	}
+}
+
+// TestPaymentNotifyResultStructure 测试支付回调结果结构
+func TestNotifyResultHasRequiredFields(t *testing.T) {
+	result := NotifyResult{
+		OK:      true,
+		Message: "payment success",
+	}
+
+	if result.Message == "" {
+		t.Fatal("NotifyResult.Message should not be empty")
+	}
+}
+
+func TestStartRefundDoesNotCreateNewOrderWhenFailedRefundExists(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	repo := NewRepository(db, nil, nil)
+	order := model.RentalOrder{
+		ID:                1001,
+		OrderNo:           "ORD202606140001",
+		RenterID:          11,
+		RentAmountCent:    800,
+		DepositAmountCent: 200,
+		RefundStatus:      "failed",
+		RefundAmountCent:  1000,
+		Status:            "closed",
+	}
+	if err := db.Create(&order).Error; err != nil {
+		t.Fatalf("create order failed: %v", err)
+	}
+	original := model.PaymentOrder{
+		PaymentNo:       "PAY202606140001",
+		OrderID:         order.ID,
+		OrderNo:         order.OrderNo,
+		UserID:          order.RenterID,
+		Provider:        "mock",
+		ThirdOrderID:    "PAY202606140001",
+		ProviderOrderID: "MOCKPAY202606140001",
+		AmountCent:      1000,
+		BizType:         "order_pay",
+		Status:          "paid",
+	}
+	if err := db.Create(&original).Error; err != nil {
+		t.Fatalf("create original payment failed: %v", err)
+	}
+	existingRefund := model.PaymentOrder{
+		PaymentNo:    "PAY202606140002",
+		OrderID:      order.ID,
+		OrderNo:      order.OrderNo,
+		UserID:       order.RenterID,
+		Provider:     "mock",
+		ThirdOrderID: "REF202606140002",
+		AmountCent:   1000,
+		BizType:      "admin_refund",
+		Status:       "failed",
+	}
+	if err := db.Create(&existingRefund).Error; err != nil {
+		t.Fatalf("create existing refund failed: %v", err)
+	}
+
+	dto, err := repo.StartRefund(t.Context(), order.ID, 1000, "admin_refund", "后台人工退款")
+	if err != nil {
+		t.Fatalf("StartRefund() error = %v", err)
+	}
+	if dto.ID != existingRefund.ID {
+		t.Fatalf("StartRefund() returned payment id %d, want existing %d", dto.ID, existingRefund.ID)
+	}
+	var count int64
+	if err := db.Model(&model.PaymentOrder{}).
+		Where("order_id = ? AND biz_type = ?", order.ID, "admin_refund").
+		Count(&count).Error; err != nil {
+		t.Fatalf("count refund orders failed: %v", err)
+	}
+	if count != 1 {
+		t.Fatalf("refund order count = %d, want 1", count)
+	}
+}
+
+func TestStartMohongRefundDefaultsFullAmountForCancelledPaidOrder(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	if err := database.AutoMigrateIfMissing(db, &model.MohongOrder{}); err != nil {
+		t.Fatalf("migrate mohong order failed: %v", err)
+	}
+	repo := NewRepository(db, nil, nil)
+	order := model.MohongOrder{
+		OrderNo:       "MH202607310001",
+		UserID:        42,
+		ProductID:     8,
+		Quantity:      1,
+		UnitPriceCent: 13300,
+		AmountCent:    13300,
+		Status:        model.MohongOrderStatusCancelled,
+	}
+	if err := db.Create(&order).Error; err != nil {
+		t.Fatalf("create mohong order failed: %v", err)
+	}
+	original := model.PaymentOrder{
+		PaymentNo:       "PAYMOHONG0001",
+		OrderID:         order.ID,
+		OrderNo:         order.OrderNo,
+		UserID:          order.UserID,
+		Provider:        "mock",
+		ThirdOrderID:    "PAYMOHONG0001",
+		ProviderOrderID: "MOCKPAYMOHONG0001",
+		AmountCent:      order.AmountCent,
+		BizType:         bizTypeMohongPay,
+		Status:          "paid",
+	}
+	if err := db.Create(&original).Error; err != nil {
+		t.Fatalf("create mohong payment failed: %v", err)
+	}
+
+	dto, err := repo.StartMohongRefund(t.Context(), order.ID, 0, "后台撞车订单人工退款")
+	if err != nil {
+		t.Fatalf("StartMohongRefund() error = %v", err)
+	}
+	if dto.AmountCent != order.AmountCent {
+		t.Fatalf("refund amount = %d, want %d", dto.AmountCent, order.AmountCent)
+	}
+	if dto.BizType != bizTypeMohongRefund {
+		t.Fatalf("refund biz_type = %q, want %q", dto.BizType, bizTypeMohongRefund)
+	}
+	if dto.Status != "refunded" {
+		t.Fatalf("refund status = %q, want refunded", dto.Status)
+	}
+
+	var latest model.MohongOrder
+	if err := db.First(&latest, order.ID).Error; err != nil {
+		t.Fatalf("find mohong order failed: %v", err)
+	}
+	if latest.Status != model.MohongOrderStatusRefunded {
+		t.Fatalf("mohong order status = %q, want refunded", latest.Status)
+	}
+}
+
+func TestStartMohongRefundRequiresCancelledOrder(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	if err := database.AutoMigrateIfMissing(db, &model.MohongOrder{}); err != nil {
+		t.Fatalf("migrate mohong order failed: %v", err)
+	}
+	repo := NewRepository(db, nil, nil)
+	order := model.MohongOrder{
+		OrderNo:       "MH202607310002",
+		UserID:        42,
+		ProductID:     8,
+		Quantity:      1,
+		UnitPriceCent: 13300,
+		AmountCent:    13300,
+		Status:        model.MohongOrderStatusPaid,
+	}
+	if err := db.Create(&order).Error; err != nil {
+		t.Fatalf("create mohong order failed: %v", err)
+	}
+	original := model.PaymentOrder{
+		PaymentNo:       "PAYMOHONG0002",
+		OrderID:         order.ID,
+		OrderNo:         order.OrderNo,
+		UserID:          order.UserID,
+		Provider:        "mock",
+		ThirdOrderID:    "PAYMOHONG0002",
+		ProviderOrderID: "MOCKPAYMOHONG0002",
+		AmountCent:      order.AmountCent,
+		BizType:         bizTypeMohongPay,
+		Status:          "paid",
+	}
+	if err := db.Create(&original).Error; err != nil {
+		t.Fatalf("create mohong payment failed: %v", err)
+	}
+
+	_, err := repo.StartMohongRefund(t.Context(), order.ID, 0, "后台撞车订单人工退款")
+	if !errors.Is(err, ErrRefundCannotStart) {
+		t.Fatalf("StartMohongRefund() error = %v, want ErrRefundCannotStart", err)
+	}
+}
+
+func TestConfirmPaidUpdatesOrderAndPaymentInOnePath(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	orderRepo := ordermodule.NewRepository(db)
+	repo := NewRepository(db, nil, orderRepo)
+	fixture := createPayableOrderFixture(t, db, "0010", true)
+
+	paidAt := time.Date(2026, 6, 14, 12, 0, 0, 0, time.UTC)
+	err := repo.confirmPaid(t.Context(), &fixture.Payment, "paid", paidAt, map[string]string{
+		"provider_order_id": "PROVIDER202606140010",
+	}, channelSourceNotify)
+	if err != nil {
+		t.Fatalf("confirmPaid() error = %v", err)
+	}
+
+	var latestPayment model.PaymentOrder
+	if err := db.First(&latestPayment, fixture.Payment.ID).Error; err != nil {
+		t.Fatalf("find payment failed: %v", err)
+	}
+	if latestPayment.Status != "paid" {
+		t.Fatalf("payment status = %q, want paid", latestPayment.Status)
+	}
+	if latestPayment.ProviderOrderID != "PROVIDER202606140010" {
+		t.Fatalf("provider order id = %q, want provider response", latestPayment.ProviderOrderID)
+	}
+
+	var latestOrder model.RentalOrder
+	if err := db.First(&latestOrder, fixture.Order.ID).Error; err != nil {
+		t.Fatalf("find order failed: %v", err)
+	}
+	if latestOrder.Status != "pending_handoff" || latestOrder.HandoffStatus != "pending_owner" {
+		t.Fatalf("order status = %q/%q, want pending_handoff/pending_owner", latestOrder.Status, latestOrder.HandoffStatus)
+	}
+
+	var latestListing model.RentalListing
+	if err := db.First(&latestListing, fixture.Listing.ID).Error; err != nil {
+		t.Fatalf("find listing failed: %v", err)
+	}
+	var latestAccount model.GameAccount
+	if err := db.First(&latestAccount, fixture.Account.ID).Error; err != nil {
+		t.Fatalf("find account failed: %v", err)
+	}
+	if latestListing.Status != "rented" || latestAccount.Status != "rented" {
+		t.Fatalf("asset status = %q/%q, want rented/rented", latestListing.Status, latestAccount.Status)
+	}
+}
+
+func TestConfirmPaidRollsBackOrderWhenPaymentUpdateFails(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	orderRepo := ordermodule.NewRepository(db)
+	repo := NewRepository(db, nil, orderRepo)
+	fixture := createPayableOrderFixture(t, db, "0011", false)
+	fixture.Payment.ID = 999999
+
+	paidAt := time.Date(2026, 6, 14, 12, 0, 0, 0, time.UTC)
+	err := repo.confirmPaid(t.Context(), &fixture.Payment, "paid", paidAt, map[string]string{
+		"provider_order_id": "PROVIDER202606140011",
+	}, channelSourceNotify)
+	if err == nil {
+		t.Fatal("confirmPaid() error = nil, want payment lookup failure")
+	}
+
+	var latestOrder model.RentalOrder
+	if findErr := db.First(&latestOrder, fixture.Order.ID).Error; findErr != nil {
+		t.Fatalf("find order failed: %v", findErr)
+	}
+	if latestOrder.Status != "pending_payment" || latestOrder.HandoffStatus != "none" {
+		t.Fatalf("order status = %q/%q, want rollback to pending_payment/none", latestOrder.Status, latestOrder.HandoffStatus)
+	}
+
+	var latestListing model.RentalListing
+	if findErr := db.First(&latestListing, fixture.Listing.ID).Error; findErr != nil {
+		t.Fatalf("find listing failed: %v", findErr)
+	}
+	var latestAccount model.GameAccount
+	if findErr := db.First(&latestAccount, fixture.Account.ID).Error; findErr != nil {
+		t.Fatalf("find account failed: %v", findErr)
+	}
+	if latestListing.Status != "published" || latestAccount.Status != "published" {
+		t.Fatalf("asset status = %q/%q, want rollback to published/published", latestListing.Status, latestAccount.Status)
+	}
+}
+
+func TestConcurrentPaidNotificationsAreIdempotent(t *testing.T) {
+	db := database.NewTestDB()
+	if err := database.MigrateRentalTransactionTestSchema(db); err != nil {
+		t.Fatalf("数据库迁移失败: %v", err)
+	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("获取底层连接失败: %v", err)
+	}
+	sqlDB.SetMaxOpenConns(8)
+	orderRepo := ordermodule.NewRepository(db)
+	repo := NewRepository(db, nil, orderRepo)
+	fixture := createPayableOrderFixture(t, db, "CONC", true)
+	params := map[string]string{
+		"third_order_id":    fixture.Payment.ThirdOrderID,
+		"status":            "paid",
+		"amount":            "1000",
+		"provider_order_id": "PROVIDER-CONCURRENT",
+	}
+
+	const callers = 8
+	results := make(chan error, callers)
+	var group sync.WaitGroup
+	for i := 0; i < callers; i++ {
+		group.Add(1)
+		go func() {
+			defer group.Done()
+			var callErr error
+			for attempt := 0; attempt < 50; attempt++ {
+				_, callErr = repo.HandleNotify(t.Context(), "mock", params, "status=paid", "application/x-www-form-urlencoded", "")
+				if callErr == nil || !strings.Contains(callErr.Error(), "locked") {
+					break
+				}
+				time.Sleep(5 * time.Millisecond)
+			}
+			results <- callErr
+		}()
+	}
+	group.Wait()
+	close(results)
+	for callErr := range results {
+		if callErr != nil {
+			t.Fatalf("concurrent HandleNotify() error = %v", callErr)
+		}
+	}
+
+	var latestPayment model.PaymentOrder
+	if err := db.First(&latestPayment, fixture.Payment.ID).Error; err != nil {
+		t.Fatalf("find payment: %v", err)
+	}
+	if latestPayment.Status != "paid" {
+		t.Fatalf("payment status = %q, want paid", latestPayment.Status)
+	}
+	var latestOrder model.RentalOrder
+	if err := db.First(&latestOrder, fixture.Order.ID).Error; err != nil {
+		t.Fatalf("find order: %v", err)
+	}
+	if latestOrder.Status != "pending_handoff" || latestOrder.HandoffStatus != "pending_owner" {
+		t.Fatalf("order status = %q/%q, want pending_handoff/pending_owner", latestOrder.Status, latestOrder.HandoffStatus)
+	}
+	var paidCount int64
+	if err := db.Model(&model.PaymentOrder{}).Where("id = ? AND status = 'paid'", fixture.Payment.ID).Count(&paidCount).Error; err != nil {
+		t.Fatalf("count paid payment: %v", err)
+	}
+	if paidCount != 1 {
+		t.Fatalf("paid payment rows = %d, want 1", paidCount)
+	}
+}
+
+// TestQueryClosedPaymentReturnsLocalStatus 验证关闭状态不再依赖渠道配置或继续轮询渠道。
+func TestQueryClosedPaymentReturnsLocalStatus(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	repo := NewRepository(db, nil, nil)
+	payment := model.PaymentOrder{
+		PaymentNo:    "PAY20260614CLOSED",
+		OrderID:      9001,
+		OrderNo:      "ORD20260614CLOSED",
+		UserID:       8001,
+		Provider:     "lakala",
+		ThirdOrderID: "PAY20260614CLOSED",
+		AmountCent:   1000,
+		BizType:      "order_pay",
+		Status:       "closed",
+	}
+	if err := db.Create(&payment).Error; err != nil {
+		t.Fatalf("create payment failed: %v", err)
+	}
+
+	dto, err := repo.Query(t.Context(), payment.UserID, payment.OrderID)
+	if err != nil {
+		t.Fatalf("Query() error = %v", err)
+	}
+	if dto.Status != "closed" {
+		t.Fatalf("status = %q, want closed", dto.Status)
+	}
+}
+
+// TestApplyChannelStatusKeepsTerminalPayment 验证已关闭支付单不会被渠道普通状态重新刷回支付中。
+func TestApplyChannelStatusKeepsTerminalPayment(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	repo := NewRepository(db, nil, nil)
+	payment := model.PaymentOrder{
+		PaymentNo:    "PAY20260614TERMINAL",
+		OrderID:      9002,
+		OrderNo:      "ORD20260614TERMINAL",
+		UserID:       8002,
+		Provider:     "lakala",
+		ThirdOrderID: "PAY20260614TERMINAL",
+		AmountCent:   1000,
+		BizType:      "order_pay",
+		Status:       "closed",
+	}
+	if err := db.Create(&payment).Error; err != nil {
+		t.Fatalf("create payment failed: %v", err)
+	}
+
+	if err := repo.applyChannelStatus(t.Context(), &payment, "paying", "", map[string]string{"status": "paying"}, channelSourceNotify); err != nil {
+		t.Fatalf("applyChannelStatus() error = %v", err)
+	}
+
+	var latest model.PaymentOrder
+	if err := db.First(&latest, payment.ID).Error; err != nil {
+		t.Fatalf("find payment failed: %v", err)
+	}
+	if latest.Status != "closed" {
+		t.Fatalf("status = %q, want closed", latest.Status)
+	}
+}
+
+func TestStartPaymentRoutesToDistributionSitePaymentChannel(t *testing.T) {
+	db := setupPaymentTestDB(t)
+	if err := db.AutoMigrate(
+		&model.DistributionSite{},
+		&model.DistributionSitePaymentChannel{},
+		&model.PaymentMerchantConfig{},
+	); err != nil {
+		t.Fatalf("migrate distribution payment schema failed: %v", err)
+	}
+
+	configRepo := paymentconfig.NewRepository(db, &paymentconfig.MockEncryptor{})
+	orderRepo := ordermodule.NewRepository(db)
+	repo := NewRepository(db, configRepo, orderRepo)
+
+	defaultConfig := model.PaymentMerchantConfig{
+		Name:        "平台默认微信",
+		Provider:    "mock",
+		MerchantID:  "PLATFORM_MOCK",
+		PayWay:      "WX",
+		IsDefault:   true,
+		Status:      "active",
+		Environment: "sandbox",
+	}
+	if err := db.Create(&defaultConfig).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	siteConfig := model.PaymentMerchantConfig{
+		Name:        "分销站专属微信",
+		Provider:    "mock",
+		MerchantID:  "SITE_MOCK_01",
+		PayWay:      "WX",
+		IsDefault:   false,
+		Status:      "active",
+		Environment: "sandbox",
+	}
+	if err := db.Create(&siteConfig).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	site := model.DistributionSite{SiteCode: "pay_site", SiteName: "支付分站", Domain: "pay.example.com", Status: "active"}
+	if err := db.Create(&site).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	channel := model.DistributionSitePaymentChannel{
+		SiteID:   site.ID,
+		ConfigID: siteConfig.ID,
+		Priority: 1,
+		Status:   "active",
+	}
+	if err := db.Create(&channel).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	// Order A: Belongs to distribution site
+	fixA := createPayableOrderFixture(t, db, "siteA", false)
+	fixA.Order.DistributionSiteID = &site.ID
+	if err := db.Save(&fixA.Order).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	// Order B: Normal platform order
+	fixB := createPayableOrderFixture(t, db, "siteB", false)
+	fixB.Order.DistributionSiteID = nil
+	if err := db.Save(&fixB.Order).Error; err != nil {
+		t.Fatal(err)
+	}
+
+	// Start payment for Order A -> should route to siteConfig
+	dtoA, err := repo.Start(t.Context(), fixA.Renter.ID, fixA.Order.ID, StartPaymentRequest{PayWay: "WX"}, "127.0.0.1")
+	if err != nil {
+		t.Fatalf("Start Order A failed: %v", err)
+	}
+	if dtoA.PaymentConfigID != siteConfig.ID {
+		t.Fatalf("Order A expected PaymentConfigID=%d, got %d", siteConfig.ID, dtoA.PaymentConfigID)
+	}
+	var savedA model.PaymentOrder
+	if err := db.First(&savedA, dtoA.ID).Error; err != nil {
+		t.Fatalf("find saved payment A failed: %v", err)
+	}
+	if savedA.MerchantID != siteConfig.MerchantID {
+		t.Fatalf("Order A expected MerchantID=%s, got %s", siteConfig.MerchantID, savedA.MerchantID)
+	}
+
+	// Start payment for Order B -> should route to defaultConfig
+	dtoB, err := repo.Start(t.Context(), fixB.Renter.ID, fixB.Order.ID, StartPaymentRequest{PayWay: "WX"}, "127.0.0.1")
+	if err != nil {
+		t.Fatalf("Start Order B failed: %v", err)
+	}
+	if dtoB.PaymentConfigID != defaultConfig.ID {
+		t.Fatalf("Order B expected PaymentConfigID=%d, got %d", defaultConfig.ID, dtoB.PaymentConfigID)
+	}
+	var savedB model.PaymentOrder
+	if err := db.First(&savedB, dtoB.ID).Error; err != nil {
+		t.Fatalf("find saved payment B failed: %v", err)
+	}
+	if savedB.MerchantID != defaultConfig.MerchantID {
+		t.Fatalf("Order B expected MerchantID=%s, got %s", defaultConfig.MerchantID, savedB.MerchantID)
+	}
+}

backend/internal/modules/payment/repository_logic_test.go

@@ -0,0 +1,299 @@
+package payment
+
+import (
+	"errors"
+	"testing"
+
+	"hfb_sys/backend/internal/model"
+)
+
+// TestPaymentOrderStates 测试支付单状态
+func TestPaymentOrderStates(t *testing.T) {
+	states := []string{"pending", "paying", "paid", "failed", "closed", "refunding", "refunded"}
+
+	for _, state := range states {
+		if state == "" {
+			t.Fatal("payment order state should not be empty")
+		}
+	}
+}
+
+// TestRefundBizTypesAreValid 测试退款业务类型有效性
+func TestRefundBizTypesAreValid(t *testing.T) {
+	validTypes := map[string]bool{
+		"cancel_refund":      true,
+		"admin_close_refund": true,
+		"admin_refund":       true,
+		"checkout_refund":    true,
+		"deposit_refund":     true,
+		"rent_refund":        true,
+		"arbitration_refund": true,
+	}
+
+	for _, bizType := range refundBizTypes {
+		if !validTypes[bizType] {
+			t.Fatalf("unexpected refund biz type: %s", bizType)
+		}
+	}
+
+	if len(refundBizTypes) != len(validTypes) {
+		t.Fatalf("refundBizTypes count = %d, want %d", len(refundBizTypes), len(validTypes))
+	}
+}
+
+// TestCanReuseOrderPaymentLogic 测试支付单复用逻辑
+func TestCanReuseOrderPaymentWithSameMerchant(t *testing.T) {
+	payment := model.PaymentOrder{
+		Status:     "paying",
+		Provider:   "lakala",
+		MerchantID: "M123",
+	}
+
+	config := runtimePaymentConfig{
+		Provider:   "lakala",
+		MerchantID: "M123",
+	}
+
+	if !canReuseOrderPayment(payment, config) {
+		t.Fatal("should reuse payment with same merchant and paying status")
+	}
+}
+
+func TestCanReuseOrderPaymentWithDifferentMerchant(t *testing.T) {
+	payment := model.PaymentOrder{
+		Status:     "paying",
+		Provider:   "lakala",
+		MerchantID: "M123",
+	}
+
+	config := runtimePaymentConfig{
+		Provider:   "lakala",
+		MerchantID: "M456", // 不同商户
+	}
+
+	if canReuseOrderPayment(payment, config) {
+		t.Fatal("should not reuse payment with different merchant")
+	}
+}
+
+func TestCanReuseOrderPaymentWithTerminalStatus(t *testing.T) {
+	terminalStatuses := []string{"failed", "closed"}
+
+	config := runtimePaymentConfig{
+		Provider:   "lakala",
+		MerchantID: "M123",
+	}
+
+	for _, status := range terminalStatuses {
+		payment := model.PaymentOrder{
+			Status:     status,
+			Provider:   "lakala",
+			MerchantID: "M123",
+		}
+
+		if canReuseOrderPayment(payment, config) {
+			t.Fatalf("should not reuse payment with terminal status: %s", status)
+		}
+	}
+}
+
+func TestCanReuseOrderPaymentWithPaidStatus(t *testing.T) {
+	payment := model.PaymentOrder{
+		Status:     "paid",
+		Provider:   "lakala",
+		MerchantID: "M123",
+	}
+
+	config := runtimePaymentConfig{
+		Provider:   "lakala",
+		MerchantID: "M123",
+	}
+
+	// 已支付的订单可以复用（幂等）
+	if !canReuseOrderPayment(payment, config) {
+		t.Fatal("should reuse payment with paid status for idempotency")
+	}
+}
+
+// TestGeneratePaymentNo 测试支付单号生成
+func TestPaymentNoShouldHavePrefix(t *testing.T) {
+	// 支付单号应该以特定前缀开头（如 PAY）
+	// 这是一个示例测试，实际格式需要根据代码确认
+	paymentNo := "PAY20260610123456"
+
+	if len(paymentNo) < 3 {
+		t.Fatal("paymentNo should have meaningful length")
+	}
+}
+
+func TestPaymentNoUniquenessAssumption(t *testing.T) {
+	// 支付单号应该是唯一的
+	// 实际实现中通常使用时间戳+随机数保证唯一性
+	seen := make(map[string]bool)
+
+	// 模拟多个支付单号
+	paymentNos := []string{
+		"PAY20260610123456001",
+		"PAY20260610123456002",
+		"PAY20260610123456003",
+	}
+
+	for _, no := range paymentNos {
+		if seen[no] {
+			t.Fatalf("duplicate paymentNo: %s", no)
+		}
+		seen[no] = true
+	}
+}
+
+// TestPaymentDTOValidation 测试支付 DTO 基本结构
+func TestPaymentDTOHasRequiredFields(t *testing.T) {
+	dto := PaymentDTO{
+		ID:         1,
+		PaymentNo:  "PAY123456",
+		OrderNo:    "ORD123456",
+		AmountCent: 10000,
+		Status:     "paid",
+	}
+
+	if dto.ID == 0 {
+		t.Fatal("PaymentDTO.ID should not be zero")
+	}
+	if dto.PaymentNo == "" {
+		t.Fatal("PaymentDTO.PaymentNo should not be empty")
+	}
+	if dto.AmountCent <= 0 {
+		t.Fatal("PaymentDTO.AmountCent should be positive")
+	}
+	if dto.Status == "" {
+		t.Fatal("PaymentDTO.Status should not be empty")
+	}
+}
+
+// TestRefundDTOValidation 测试退款 DTO 基本结构
+func TestRefundDTOHasRequiredFields(t *testing.T) {
+	dto := RefundDTO{
+		OrderID:    100,
+		AmountCent: 5000,
+		Status:     "refunding",
+		BizType:    "cancel_refund",
+	}
+
+	if dto.OrderID == 0 {
+		t.Fatal("RefundDTO.OrderID should not be zero")
+	}
+	if dto.AmountCent <= 0 {
+		t.Fatal("RefundDTO.AmountCent should be positive")
+	}
+	if dto.Status == "" {
+		t.Fatal("RefundDTO.Status should not be empty")
+	}
+	if dto.BizType == "" {
+		t.Fatal("RefundDTO.BizType should not be empty")
+	}
+}
+
+// TestChannelSourceConstants 测试渠道来源常量
+func TestChannelSourceConstantsAreUnique(t *testing.T) {
+	sources := []string{
+		channelSourceCreate,
+		channelSourceQuery,
+		channelSourceNotify,
+		channelSourceMock,
+	}
+
+	seen := make(map[string]bool)
+	for _, source := range sources {
+		if seen[source] {
+			t.Fatalf("duplicate channel source: %s", source)
+		}
+		seen[source] = true
+	}
+
+	if len(seen) != 4 {
+		t.Fatalf("expected 4 unique channel sources, got %d", len(seen))
+	}
+}
+
+// TestRuntimePaymentConfigValidation 测试运行时支付配置
+func TestRuntimePaymentConfigRequiredFields(t *testing.T) {
+	config := runtimePaymentConfig{
+		ID:         1,
+		Provider:   "lakala",
+		MerchantID: "M123",
+		PayWay:     "ZFBZF",
+	}
+
+	if config.ID == 0 {
+		t.Fatal("config.ID should not be zero")
+	}
+	if config.Provider == "" {
+		t.Fatal("config.Provider should not be empty")
+	}
+	if config.MerchantID == "" {
+		t.Fatal("config.MerchantID should not be empty")
+	}
+}
+
+// TestServiceInputValidation 测试 Service 输入验证
+func TestServiceStartRequiresNonZeroOrderID(t *testing.T) {
+	svc := &Service{repo: &Repository{}}
+
+	_, err := svc.Start(t.Context(), 1, 0, StartPaymentRequest{}, "127.0.0.1")
+	if !errors.Is(err, ErrPaymentCannotStart) {
+		t.Fatalf("error = %v, want ErrPaymentCannotStart", err)
+	}
+}
+
+func TestServiceStartRequiresNonZeroUserID(t *testing.T) {
+	svc := &Service{repo: &Repository{}}
+
+	_, err := svc.Start(t.Context(), 0, 100, StartPaymentRequest{}, "127.0.0.1")
+	if !errors.Is(err, ErrPaymentCannotStart) {
+		t.Fatalf("error = %v, want ErrPaymentCannotStart", err)
+	}
+}
+
+func TestServiceStartRefundRequiresPositiveAmount(t *testing.T) {
+	svc := &Service{repo: &Repository{}}
+
+	_, err := svc.StartRefund(t.Context(), 100, 0, "cancel_refund", "test")
+	if !errors.Is(err, ErrRefundCannotStart) {
+		t.Fatalf("error = %v, want ErrRefundCannotStart", err)
+	}
+
+	_, err = svc.StartRefund(t.Context(), 100, -1000, "cancel_refund", "test")
+	if !errors.Is(err, ErrRefundCannotStart) {
+		t.Fatalf("error = %v, want ErrRefundCannotStart", err)
+	}
+}
+
+func TestServiceStartRefundRequiresNonZeroOrderID(t *testing.T) {
+	svc := &Service{repo: &Repository{}}
+
+	_, err := svc.StartRefund(t.Context(), 0, 1000, "cancel_refund", "test")
+	if !errors.Is(err, ErrRefundCannotStart) {
+		t.Fatalf("error = %v, want ErrRefundCannotStart", err)
+	}
+}
+
+// TestPaymentErrorTypes 测试错误类型定义
+func TestPaymentErrorsAreDefined(t *testing.T) {
+	errors := []error{
+		ErrDependencyUnavailable,
+		ErrPaymentUnavailable,
+		ErrPaymentCannotStart,
+		ErrPaymentVerifyFailed,
+		ErrPaymentNotFound,
+		ErrRefundCannotStart,
+	}
+
+	for i, err := range errors {
+		if err == nil {
+			t.Fatalf("error[%d] should not be nil", i)
+		}
+		if err.Error() == "" {
+			t.Fatalf("error[%d] should have message", i)
+		}
+	}
+}

backend/internal/modules/payment/repository_test.go

@@ -0,0 +1,181 @@
+package payment
+
+import (
+	"testing"
+	"time"
+
+	"hfb_sys/backend/internal/model"
+	"hfb_sys/backend/internal/timeutil"
+
+	"gorm.io/datatypes"
+)
+
+func TestCanReuseOrderPaymentRejectsTerminalAndOldChannel(t *testing.T) {
+	runtimeConfig := runtimePaymentConfig{
+		Provider:   "lakala",
+		MerchantID: "M2",
+	}
+
+	cases := []struct {
+		name    string
+		payment model.PaymentOrder
+		want    bool
+	}{
+		{
+			name:    "同商户支付中可复用",
+			payment: model.PaymentOrder{Status: "paying", Provider: "lakala", MerchantID: "M2"},
+			want:    true,
+		},
+		{
+			name:    "已支付保持幂等",
+			payment: model.PaymentOrder{Status: "paid", Provider: "leshua", MerchantID: "M1"},
+			want:    true,
+		},
+		{
+			name:    "失败支付单不复用",
+			payment: model.PaymentOrder{Status: "failed", Provider: "lakala", MerchantID: "M2"},
+			want:    false,
+		},
+		{
+			name:    "关闭支付单不复用",
+			payment: model.PaymentOrder{Status: "closed", Provider: "lakala", MerchantID: "M2"},
+			want:    false,
+		},
+		{
+			name:    "旧渠道支付单不复用",
+			payment: model.PaymentOrder{Status: "paying", Provider: "leshua", MerchantID: "M1"},
+			want:    false,
+		},
+		{
+			name:    "旧商户支付单不复用",
+			payment: model.PaymentOrder{Status: "paying", Provider: "lakala", MerchantID: "M1"},
+			want:    false,
+		},
+	}
+
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := canReuseOrderPayment(tt.payment, runtimeConfig); got != tt.want {
+				t.Fatalf("canReuseOrderPayment() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestNewOrderPaymentUsesPaymentNoAsThirdOrderID(t *testing.T) {
+	order := model.RentalOrder{
+		ID:       11,
+		OrderNo:  "ORD123",
+		RenterID: 7,
+	}
+	runtimeConfig := runtimePaymentConfig{
+		Provider:   "lakala",
+		MerchantID: "M2",
+		PayWay:     "ZFBZF",
+		JSPayFlag:  "2",
+	}
+
+	payment, err := newOrderPayment(order, 100, StartPaymentRequest{}, runtimeConfig)
+	if err != nil {
+		t.Fatalf("newOrderPayment() error = %v", err)
+	}
+	if payment.ThirdOrderID != payment.PaymentNo {
+		t.Fatalf("ThirdOrderID = %q, want PaymentNo %q", payment.ThirdOrderID, payment.PaymentNo)
+	}
+	if payment.ThirdOrderID == order.OrderNo {
+		t.Fatalf("ThirdOrderID should not reuse order no %q", order.OrderNo)
+	}
+	if payment.OrderNo != order.OrderNo || payment.OrderID != order.ID || payment.UserID != order.RenterID {
+		t.Fatalf("payment order fields mismatch: %+v", payment)
+	}
+}
+
+func TestCanReuseOrderPaymentRejectsExpiredCashier(t *testing.T) {
+	runtimeConfig := runtimePaymentConfig{
+		Provider:   "lakala",
+		MerchantID: "M2",
+	}
+	expiredPayment := model.PaymentOrder{
+		Status:     "paying",
+		Provider:   "lakala",
+		MerchantID: "M2",
+		RawRequest: datatypes.JSON([]byte(`{"order_efficient_time":"20000101000000"}`)),
+	}
+	if canReuseOrderPayment(expiredPayment, runtimeConfig) {
+		t.Fatal("canReuseOrderPayment() = true, want false for expired cashier")
+	}
+
+	activePayment := expiredPayment
+	activePayment.RawRequest = datatypes.JSON([]byte(`{"order_efficient_time":"20990101000000"}`))
+	if !canReuseOrderPayment(activePayment, runtimeConfig) {
+		t.Fatal("canReuseOrderPayment() = false, want true for active cashier")
+	}
+}
+
+func TestParseChannelTimeUsesShanghaiWhenLocalIsUTC(t *testing.T) {
+	oldLocal := time.Local
+	time.Local = time.UTC
+	defer func() {
+		time.Local = oldLocal
+	}()
+
+	parsed := parseChannelTime("20260607202700")
+	if parsed == nil {
+		t.Fatal("parseChannelTime() = nil")
+	}
+	got := parsed.In(timeutil.ShanghaiLocation()).Format("20060102150405")
+	if got != "20260607202700" {
+		t.Fatalf("parseChannelTime() = %s, want 20260607202700 in Asia/Shanghai", got)
+	}
+}
+
+func TestRefundOriginProviderOrderIDUsesLakalaTradeNo(t *testing.T) {
+	payment := model.PaymentOrder{
+		Provider:        "lakala",
+		ProviderOrderID: "26060811012001101011735013210",
+		RawResponse: datatypes.JSON([]byte(`{
+			"pay_order_no": "26060811012001101011735013210",
+			"order_trade_info_list": "[{\"trade_no\":\"20260608110113230266224452004512\",\"pay_order_no\":\"26060811012001101011735013210\"}]"
+		}`)),
+	}
+
+	got := refundOriginProviderOrderID(payment)
+	if got != "20260608110113230266224452004512" {
+		t.Fatalf("refundOriginProviderOrderID() = %q, want trade_no", got)
+	}
+}
+
+func TestRefundOriginProviderOrderIDFallsBackToProviderOrderID(t *testing.T) {
+	payment := model.PaymentOrder{
+		Provider:        "lakala",
+		ProviderOrderID: "26060811012001101011735013210",
+		RawResponse:     datatypes.JSON([]byte(`{"pay_order_no":"26060811012001101011735013210"}`)),
+	}
+
+	got := refundOriginProviderOrderID(payment)
+	if got != payment.ProviderOrderID {
+		t.Fatalf("refundOriginProviderOrderID() = %q, want fallback %q", got, payment.ProviderOrderID)
+	}
+}
+
+func TestRefundQueryRequestUsesOriginalPaymentAndMerchantRefundID(t *testing.T) {
+	original := model.PaymentOrder{
+		ThirdOrderID:    "PAY202606140001",
+		ProviderOrderID: "PROVIDER-PAY-ID",
+	}
+	refund := model.PaymentOrder{
+		ThirdOrderID:    "REF202606140001",
+		ProviderOrderID: "PROVIDER-REFUND-ID",
+	}
+
+	req := refundQueryRequest(refund, original)
+	if req.ThirdOrderID != original.ThirdOrderID {
+		t.Fatalf("ThirdOrderID = %q, want original payment third order id %q", req.ThirdOrderID, original.ThirdOrderID)
+	}
+	if req.MerchantRefundID != refund.ThirdOrderID {
+		t.Fatalf("MerchantRefundID = %q, want refund third order id %q", req.MerchantRefundID, refund.ThirdOrderID)
+	}
+	if req.ProviderRefundID != refund.ProviderOrderID {
+		t.Fatalf("ProviderRefundID = %q, want refund provider order id %q", req.ProviderRefundID, refund.ProviderOrderID)
+	}
+}

backend/internal/modules/payment/service.go

@@ -0,0 +1,123 @@
+package payment
+
+import (
+	"context"
+	"errors"
+)
+
+var (
+	ErrDependencyUnavailable = errors.New("dependency unavailable")
+	ErrPaymentUnavailable    = errors.New("payment unavailable")
+	ErrPaymentCannotStart    = errors.New("payment cannot start")
+	ErrPaymentVerifyFailed   = errors.New("payment verify failed")
+	ErrPaymentNotFound       = errors.New("payment not found")
+	ErrRefundCannotStart     = errors.New("refund cannot start")
+)
+
+type Service struct {
+	repo *Repository
+}
+
+func NewService(repo *Repository) *Service {
+	return &Service{repo: repo}
+}
+
+func (s *Service) Start(ctx context.Context, userID uint64, orderID uint64, req StartPaymentRequest, clientIP string) (*PaymentDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	if userID == 0 || orderID == 0 {
+		return nil, ErrPaymentCannotStart
+	}
+	return s.repo.Start(ctx, userID, orderID, req, clientIP)
+}
+
+func (s *Service) StartMohong(ctx context.Context, userID uint64, orderID uint64, req StartPaymentRequest, clientIP string) (*PaymentDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	if userID == 0 || orderID == 0 {
+		return nil, ErrPaymentCannotStart
+	}
+	return s.repo.StartMohong(ctx, userID, orderID, req, clientIP)
+}
+
+func (s *Service) Query(ctx context.Context, userID uint64, orderID uint64) (*PaymentDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	if userID == 0 || orderID == 0 {
+		return nil, ErrPaymentNotFound
+	}
+	return s.repo.Query(ctx, userID, orderID)
+}
+
+func (s *Service) QueryMohong(ctx context.Context, userID uint64, orderID uint64) (*PaymentDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	if userID == 0 || orderID == 0 {
+		return nil, ErrPaymentNotFound
+	}
+	return s.repo.QueryMohong(ctx, userID, orderID)
+}
+
+func (s *Service) HandleLeshuaNotify(ctx context.Context, params map[string]string, rawPayload string, contentType string) (*NotifyResult, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	return s.repo.HandleLeshuaNotify(ctx, params, rawPayload, contentType)
+}
+
+func (s *Service) HandleNotify(ctx context.Context, provider string, params map[string]string, rawPayload string, contentType string, authorization string) (*NotifyResult, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	return s.repo.HandleNotify(ctx, provider, params, rawPayload, contentType, authorization)
+}
+
+func (s *Service) StartRefund(ctx context.Context, orderID uint64, refundAmountCent int64, bizType string, remark string) (*RefundDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	if orderID == 0 || refundAmountCent <= 0 {
+		return nil, ErrRefundCannotStart
+	}
+	return s.repo.StartRefund(ctx, orderID, refundAmountCent, bizType, remark)
+}
+
+func (s *Service) StartMohongRefund(ctx context.Context, orderID uint64, refundAmountCent int64, remark string) (*RefundDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	if orderID == 0 || refundAmountCent < 0 {
+		return nil, ErrRefundCannotStart
+	}
+	return s.repo.StartMohongRefund(ctx, orderID, refundAmountCent, remark)
+}
+
+func (s *Service) QueryRefundStatus(ctx context.Context, orderID uint64) (*RefundDTO, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	if orderID == 0 {
+		return nil, ErrPaymentNotFound
+	}
+	return s.repo.QueryRefundStatus(ctx, orderID)
+}
+
+func (s *Service) AdminList(ctx context.Context, query AdminPaymentQuery) (*PaginatedResult, error) {
+	if s.repo == nil {
+		return nil, ErrDependencyUnavailable
+	}
+	if query.Page < 1 {
+		query.Page = 1
+	}
+	if query.PageSize < 1 {
+		query.PageSize = 20
+	}
+	if query.PageSize > 100 {
+		query.PageSize = 100
+	}
+	return s.repo.AdminList(ctx, query)
+}

backend/internal/modules/payment/service_test.go

@@ -0,0 +1,129 @@
+package payment
+
+import (
+	"errors"
+	"testing"
+)
+
+// TestServiceDependencyChecks 测试 Service 依赖检查
+func TestServiceStartWithNilRepo(t *testing.T) {
+	svc := &Service{repo: nil}
+	_, err := svc.Start(t.Context(), 1, 100, StartPaymentRequest{}, "127.0.0.1")
+	if !errors.Is(err, ErrDependencyUnavailable) {
+		t.Fatalf("Start() error = %v, want ErrDependencyUnavailable", err)
+	}
+}
+
+func TestServiceStartWithInvalidParams(t *testing.T) {
+	svc := &Service{repo: &Repository{}}
+
+	// 测试 userID 为 0
+	_, err := svc.Start(t.Context(), 0, 100, StartPaymentRequest{}, "127.0.0.1")
+	if !errors.Is(err, ErrPaymentCannotStart) {
+		t.Fatalf("Start() error = %v, want ErrPaymentCannotStart", err)
+	}
+
+	// 测试 orderID 为 0
+	_, err = svc.Start(t.Context(), 1, 0, StartPaymentRequest{}, "127.0.0.1")
+	if !errors.Is(err, ErrPaymentCannotStart) {
+		t.Fatalf("Start() error = %v, want ErrPaymentCannotStart", err)
+	}
+}
+
+func TestServiceQueryWithNilRepo(t *testing.T) {
+	svc := &Service{repo: nil}
+	_, err := svc.Query(t.Context(), 1, 100)
+	if !errors.Is(err, ErrDependencyUnavailable) {
+		t.Fatalf("Query() error = %v, want ErrDependencyUnavailable", err)
+	}
+}
+
+func TestServiceQueryWithInvalidParams(t *testing.T) {
+	svc := &Service{repo: &Repository{}}
+
+	_, err := svc.Query(t.Context(), 0, 100)
+	if !errors.Is(err, ErrPaymentNotFound) {
+		t.Fatalf("Query() error = %v, want ErrPaymentNotFound", err)
+	}
+}
+
+func TestServiceStartRefundWithNilRepo(t *testing.T) {
+	svc := &Service{repo: nil}
+	_, err := svc.StartRefund(t.Context(), 100, 1000, "cancel_refund", "test")
+	if !errors.Is(err, ErrDependencyUnavailable) {
+		t.Fatalf("StartRefund() error = %v, want ErrDependencyUnavailable", err)
+	}
+}
+
+func TestServiceStartRefundWithInvalidParams(t *testing.T) {
+	svc := &Service{repo: &Repository{}}
+
+	// 测试 orderID 为 0
+	_, err := svc.StartRefund(t.Context(), 0, 1000, "cancel_refund", "test")
+	if !errors.Is(err, ErrRefundCannotStart) {
+		t.Fatalf("StartRefund() error = %v, want ErrRefundCannotStart", err)
+	}
+
+	// 测试金额为 0
+	_, err = svc.StartRefund(t.Context(), 100, 0, "cancel_refund", "test")
+	if !errors.Is(err, ErrRefundCannotStart) {
+		t.Fatalf("StartRefund() error = %v, want ErrRefundCannotStart", err)
+	}
+}
+
+// TestRefundBizTypeConstants 测试退款业务类型常量
+func TestRefundBizTypesContainsExpectedValues(t *testing.T) {
+	expected := []string{
+		"cancel_refund",
+		"admin_close_refund",
+		"admin_refund",
+		"checkout_refund",
+		"deposit_refund",
+		"rent_refund",
+		"arbitration_refund",
+	}
+
+	for _, bizType := range expected {
+		found := false
+		for _, refundType := range refundBizTypes {
+			if refundType == bizType {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Fatalf("refundBizTypes missing expected type: %s", bizType)
+		}
+	}
+}
+
+// TestRuntimePaymentConfigMockMode 测试 mock 模式判断
+func TestRuntimePaymentConfigIsMockMode(t *testing.T) {
+	config := runtimePaymentConfig{Provider: "mock"}
+	if !config.isMockMode() {
+		t.Fatal("isMockMode() = false, want true for mock provider")
+	}
+
+	config.Provider = "lakala"
+	if config.isMockMode() {
+		t.Fatal("isMockMode() = true, want false for lakala provider")
+	}
+}
+
+// TestChannelSourceConstants 测试渠道来源常量
+func TestChannelSourceConstantsAreDefined(t *testing.T) {
+	sources := []string{
+		channelSourceCreate,
+		channelSourceQuery,
+		channelSourceNotify,
+		channelSourceMock,
+	}
+
+	expected := []string{"create", "query", "notify", "mock"}
+
+	for i, source := range sources {
+		if source != expected[i] {
+			t.Fatalf("channelSource[%d] = %s, want %s", i, source, expected[i])
+		}
+	}
+}