《游戏服务端架构·核心系统与契约》6.2 交易托管、冻结与回滚

总资产 = 可用余额 + 冻结余额

// file: internal/tradeescrow/tradeescrow.go
// tier: L1
// verify: go test ./internal/tradeescrow/
package tradeescrow

import (
	"errors"
	"fmt"
	"sync"
)

var (
	ErrPartyCount      = errors.New("tradeescrow: trade needs exactly two distinct parties")
	ErrEmptyOffer      = errors.New("tradeescrow: each party must offer at least one item")
	ErrBadQuantity     = errors.New("tradeescrow: quantity must be positive")
	ErrBadItem         = errors.New("tradeescrow: item id is empty")
	ErrDuplicateItem   = errors.New("tradeescrow: duplicate item in one offer")
	ErrInsufficient    = errors.New("tradeescrow: insufficient available quantity")
	ErrUnknownTrade    = errors.New("tradeescrow: unknown trade")
	ErrVersionConflict = errors.New("tradeescrow: stale version")
	ErrIllegalState    = errors.New("tradeescrow: illegal state transition")
	ErrRollbackDenied  = errors.New("tradeescrow: receiver already spent swapped items")
)

// State is the escrow lifecycle. Swapped is the point of no easy return: items
// have moved, so Rollback from Swapped needs a reverse transfer.
type State string

const (
	StateLocked     State = "locked"
	StateValidated  State = "validated"
	StateSwapped    State = "swapped"
	StateReleased   State = "released"
	StateRolledBack State = "rolled_back"
)

// Item is a stack of one item id. Per-instance attributes belong to the item
// service; the trade only moves quantities.
type Item struct {
	ID  string
	Qty int64
}

// Offer is one party's side of the trade.
type Offer struct {
	Party string
	Items []Item
}

// Trade is the externally visible state. Version increments on every accepted
// transition and is the compare-and-swap token callers must send back.
type Trade struct {
	ID      string
	State   State
	Version int
	Offers  map[string][]Item
}

// Engine owns available and frozen quantities. The mutex makes validation,
// freezing and state change one critical section.
type Engine struct {
	mu        sync.Mutex
	available map[string]map[string]int64
	frozen    map[string]map[string]int64
	trades    map[string]*Trade
}

// New creates an empty escrow engine.
func New() *Engine {
	return &Engine{
		available: make(map[string]map[string]int64),
		frozen:    make(map[string]map[string]int64),
		trades:    make(map[string]*Trade),
	}
}

// Open validates both offers, moves quantities from available to frozen, and
// creates the trade in StateLocked. A repeated id returns the original trade
// with replay=true and freezes nothing twice.
func (e *Engine) Open(id string, offers []Offer) (*Trade, bool, error) {
	e.mu.Lock()
	defer e.mu.Unlock()
	if existing, ok := e.trades[id]; ok {
		return snapshot(existing), true, nil
	}
	if len(offers) != 2 || offers[0].Party == "" || offers[1].Party == "" ||
		offers[0].Party == offers[1].Party {
		return nil, false, ErrPartyCount
	}
	want := make(map[string]map[string]int64, 2)
	for _, offer := range offers {
		if len(offer.Items) == 0 {
			return nil, false, ErrEmptyOffer
		}
		want[offer.Party] = make(map[string]int64, len(offer.Items))
		for _, item := range offer.Items {
			if item.ID == "" {
				return nil, false, ErrBadItem
			}
			if item.Qty <= 0 {
				return nil, false, ErrBadQuantity
			}
			if _, dup := want[offer.Party][item.ID]; dup {
				return nil, false, fmt.Errorf("%w: %s/%s", ErrDuplicateItem, offer.Party, item.ID)
			}
			want[offer.Party][item.ID] = item.Qty
		}
	}
	for party, items := range want {
		for item, qty := range items {
			if e.available[party][item] < qty {
				return nil, false, fmt.Errorf("%w: %s/%s", ErrInsufficient, party, item)
			}
		}
	}
	for party, items := range want {
		if e.frozen[party] == nil {
			e.frozen[party] = make(map[string]int64)
		}
		for item, qty := range items {
			e.available[party][item] -= qty
			e.frozen[party][item] += qty
		}
	}
	stored := make(map[string][]Item, 2)
	for _, offer := range offers {
		stored[offer.Party] = append([]Item(nil), offer.Items...)
	}
	trade := &Trade{ID: id, State: StateLocked, Version: 1, Offers: stored}
	e.trades[id] = trade
	return snapshot(trade), false, nil
}

// Validate is the anti-cheat and item-existence gate. No inventory moves yet.
func (e *Engine) Validate(id string, expect int) (*Trade, error) {
	return e.transition(id, expect, StateLocked, StateValidated)
}

// Swap moves frozen items to the other party and marks the trade Swapped.
func (e *Engine) Swap(id string, expect int) (*Trade, error) {
	e.mu.Lock()
	defer e.mu.Unlock()
	trade, err := e.lookup(id, expect)
	if err != nil {
		return nil, err
	}
	if trade.State != StateValidated {
		return nil, fmt.Errorf("%w: %s -> swapped", ErrIllegalState, trade.State)
	}
	for party, items := range trade.Offers {
		other := otherParty(trade, party)
		if e.available[other] == nil {
			e.available[other] = make(map[string]int64)
		}
		for _, item := range items {
			e.frozen[party][item.ID] -= item.Qty
			if e.frozen[party][item.ID] == 0 {
				delete(e.frozen[party], item.ID)
			}
			e.available[other][item.ID] += item.Qty
		}
	}
	trade.State = StateSwapped
	trade.Version++
	return snapshot(trade), nil
}

// Release closes a swapped trade. At this point the items are final.
func (e *Engine) Release(id string, expect int) (*Trade, error) {
	return e.transition(id, expect, StateSwapped, StateReleased)
}

// Rollback unfreezes a pre-swap trade, or reverses a swapped one. A reverse
// transfer is refused if the receiver no longer holds enough of an item.
func (e *Engine) Rollback(id string, expect int) (*Trade, error) {
	e.mu.Lock()
	defer e.mu.Unlock()
	trade, err := e.lookup(id, expect)
	if err != nil {
		return nil, err
	}
	switch trade.State {
	case StateLocked, StateValidated:
		for party, items := range trade.Offers {
			for _, item := range items {
				e.frozen[party][item.ID] -= item.Qty
				if e.frozen[party][item.ID] == 0 {
					delete(e.frozen[party], item.ID)
				}
				e.available[party][item.ID] += item.Qty
			}
		}
	case StateSwapped:
		for party, items := range trade.Offers {
			other := otherParty(trade, party)
			for _, item := range items {
				if e.available[other][item.ID] < item.Qty {
					return nil, fmt.Errorf("%w: %s/%s", ErrRollbackDenied, other, item.ID)
				}
			}
		}
		for party, items := range trade.Offers {
			other := otherParty(trade, party)
			for _, item := range items {
				e.available[other][item.ID] -= item.Qty
				e.available[party][item.ID] += item.Qty
			}
		}
	default:
		return nil, fmt.Errorf("%w: %s -> rolled_back", ErrIllegalState, trade.State)
	}
	trade.State = StateRolledBack
	trade.Version++
	return snapshot(trade), nil
}

func (e *Engine) transition(id string, expect int, from, to State) (*Trade, error) {
	e.mu.Lock()
	defer e.mu.Unlock()
	trade, err := e.lookup(id, expect)
	if err != nil {
		return nil, err
	}
	if trade.State != from {
		return nil, fmt.Errorf("%w: %s -> %s", ErrIllegalState, trade.State, to)
	}
	trade.State = to
	trade.Version++
	return snapshot(trade), nil
}

func (e *Engine) lookup(id string, expect int) (*Trade, error) {
	trade, ok := e.trades[id]
	if !ok {
		return nil, fmt.Errorf("%w: %s", ErrUnknownTrade, id)
	}
	if trade.Version != expect {
		return nil, fmt.Errorf("%w: have %d, want %d", ErrVersionConflict, trade.Version, expect)
	}
	return trade, nil
}

func otherParty(trade *Trade, party string) string {
	for candidate := range trade.Offers {
		if candidate != party {
			return candidate
		}
	}
	return ""
}

func snapshot(trade *Trade) *Trade {
	out := &Trade{
		ID:      trade.ID,
		State:   trade.State,
		Version: trade.Version,
		Offers:  make(map[string][]Item, len(trade.Offers)),
	}
	for party, items := range trade.Offers {
		out.Offers[party] = append([]Item(nil), items...)
	}
	return out
}