《游戏服务端架构·核心系统与契约》11.1 支付渠道与发货幂等

客户端            游戏服务端                    支付渠道
  |  下单            |                             |
  |----------------->| 1. 创建订单 created          |
  |                  |---------------------------->| 2. 预下单
  |                  |<----------------------------|    渠道单号/支付页
  |  支付            |                             |
  |----------------------------------------------->|
  |                  |<----------------------------| 3. 回调(事件ID+签名)
  |                  | 4. 验签 -> 去重 -> 置 paid   |
  |                  |    发货 -> 置 delivered      |
  |<-----------------| 5. 通知客户端                 |

// file: internal/paydelivery/callback.go
// tier: L1
// verify: go test ./internal/paydelivery/
package paydelivery

import "fmt"

// Handle verifies before deduplicating, so a forged replay of a real event ID
// is still rejected.
func (s *Service) Handle(n Notification) (Result, error) {
	s.mu.Lock()
	defer s.mu.Unlock()

	if err := validateNotification(n); err != nil {
		return Result{}, err
	}
	if s.verifier == nil {
		return Result{}, fmt.Errorf("%w: no verifier", ErrBadSignature)
	}
	if err := s.verifier.Verify(n); err != nil {
		return Result{}, fmt.Errorf("%w: %v", ErrBadSignature, err)
	}
	key := n.Channel + "\x00" + n.EventID
	if _, ok := s.seen[key]; ok {
		o, _ := s.orders[n.OrderID]
		if o == nil {
			return Result{Duplicate: true}, nil
		}
		return Result{Order: *o, Duplicate: true}, nil
	}

	o, ok := s.orders[n.OrderID]
	if !ok {
		return Result{}, fmt.Errorf("%w: %s", ErrOrderNotFound, n.OrderID)
	}
	if o.Channel != n.Channel {
		return Result{Order: *o}, fmt.Errorf("%w: %s", ErrChannelMismatch, n.Channel)
	}
	if o.ChannelOrderID == "" {
		o.ChannelOrderID = n.ChannelOrderID
	} else if o.ChannelOrderID != n.ChannelOrderID {
		return Result{Order: *o}, fmt.Errorf("%w: %s", ErrChannelMismatch, n.ChannelOrderID)
	}
	switch n.Status {
	case StatusPaid:
		return s.handlePaid(n, o, key)
	case StatusClosed:
		return s.handleClosed(o, key)
	default:
		return Result{Order: *o}, fmt.Errorf("%w: %s", ErrInvalidStatus, n.Status)
	}
}

func (s *Service) handlePaid(n Notification, o *Order, key string) (Result, error) {
	if o.AmountCents != n.AmountCents || o.Currency != n.Currency {
		return Result{Order: *o}, fmt.Errorf("%w: got %d %s, want %d %s",
			ErrAmountMismatch, n.AmountCents, n.Currency, o.AmountCents, o.Currency)
	}
	switch o.State {
	case StateDelivered:
		s.seen[key] = struct{}{}
		return Result{Order: *o, Duplicate: true}, nil
	case StateClosed:
		return Result{Order: *o}, fmt.Errorf("%w: paid after closed", ErrInvalidState)
	case StateCreated:
		o.State = StatePaid
		if n.OccurredAt.IsZero() {
			o.PaidAt = s.now()
		} else {
			o.PaidAt = n.OccurredAt
		}
	case StatePaid:
		// Payment recorded but delivery failed earlier; retry it.
	default:
		return Result{Order: *o}, fmt.Errorf("%w: %s", ErrInvalidState, o.State)
	}
	if s.deliverer == nil {
		return Result{Order: *o}, fmt.Errorf("%w: no deliverer", ErrDeliveryFailed)
	}
	if err := s.deliverer.Deliver(*o); err != nil {
		return Result{Order: *o}, fmt.Errorf("%w: %v", ErrDeliveryFailed, err)
	}
	o.State = StateDelivered
	o.DeliveredAt = s.now()
	s.seen[key] = struct{}{}
	return Result{Order: *o, Delivered: true}, nil
}

func (s *Service) handleClosed(o *Order, key string) (Result, error) {
	s.seen[key] = struct{}{}
	switch o.State {
	case StateCreated:
		o.State = StateClosed
		return Result{Order: *o}, nil
	case StateClosed:
		return Result{Order: *o, Duplicate: true}, nil
	default:
		// Money already moved; a late close must not undo a delivered order.
		return Result{Order: *o, Ignored: true}, nil
	}
}

func validateNotification(n Notification) error {
	if n.EventID == "" || n.Channel == "" || n.OrderID == "" || n.ChannelOrderID == "" {
		return fmt.Errorf("%w: missing event, channel, order or channel order id", ErrBadRequest)
	}
	if n.Status != StatusPaid && n.Status != StatusClosed {
		return fmt.Errorf("%w: %s", ErrInvalidStatus, n.Status)
	}
	return nil
}