《MMO 服务器开发》16.2 竞价并发与异常回滚

// file: internal/trade/auction.go
// tier: L1
// verify: go test -race ./internal/trade/
package trade

import (
	"errors"
	"sync"
)

var (
	ErrAuctionGone   = errors.New("trade: 拍卖不存在")
	ErrAuctionClosed = errors.New("trade: 拍卖已结束")
	ErrSellerSelfBid = errors.New("trade: 卖家不能给自己出价")
	ErrBidTooLow     = errors.New("trade: 出价低于当前价 + 最小加价")
)

// taxBps 是成交税，单位万分之一（500 = 5%）。它是《晨曦大陆》最稳定的一条金币回收。
const taxBps int64 = 500

type auctionState uint8

const (
	auctionOpen auctionState = iota
	auctionSold
	auctionExpired
)

// Auction 是一条拍卖。Price==0 表示尚无人出价；Buyout==0 表示没有一口价。
type Auction struct {
	ID           AuctionID
	Seller       PlayerID
	ItemInst     ItemInstID
	ItemID       ItemID
	StartPrice   int64
	MinIncrement int64
	Buyout       int64
	Price        int64
	Winner       PlayerID
	EndAt        int64
	State        auctionState
}

// BidResult 描述一次成功出价：被顶掉的上一位及其退款额，便于广播与审计。
type BidResult struct {
	Auction  AuctionID
	Bidder   PlayerID
	Price    int64
	Refunded PlayerID
	Refund   int64
	Sold     bool
}

// Auctioneer 串行化所有出价。锁序固定为 Auctioneer.mu → Escrow.mu，
// 没有任何反向路径，因此嵌套加锁不会死锁。
type Auctioneer struct {
	mu       sync.Mutex
	escrow   *Escrow
	auctions map[AuctionID]*Auction
}

func NewAuctioneer(e *Escrow) *Auctioneer {
	return &Auctioneer{escrow: e, auctions: make(map[AuctionID]*Auction)}
}

// List 上架：先把物品冻进托管，再登记拍卖。
func (a *Auctioneer) List(au Auction) (AuctionID, error) {
	a.mu.Lock()
	defer a.mu.Unlock()
	if au.ID == 0 {
		au.ID = a.escrow.NextAuctionID()
	}
	if _, err := a.escrow.FreezeItem(au.Seller, au.ItemInst, au.ID); err != nil {
		return 0, err
	}
	au.State = auctionOpen
	a.auctions[au.ID] = &au
	return au.ID, nil
}

// PlaceBid 是本章的核心：一次出价要么完全生效，要么完全无副作用。
// 顺序被刻意固定为「先冻新、再退旧」——若先退旧，一旦新出价冻金失败，
// 就会留下「上一位已解冻、本此也没冻上」的空窗，等于白嫖一次最高价。
func (a *Auctioneer) PlaceBid(auc AuctionID, bidder PlayerID, amount, now int64) (BidResult, error) {
	a.mu.Lock()
	defer a.mu.Unlock()
	au, ok := a.auctions[auc]
	if !ok {
		return BidResult{}, ErrAuctionGone
	}
	if au.State != auctionOpen || now >= au.EndAt {
		return BidResult{}, ErrAuctionClosed
	}
	if bidder == au.Seller {
		return BidResult{}, ErrSellerSelfBid
	}
	need := au.StartPrice
	if au.Price > 0 {
		need = au.Price + au.MinIncrement
	}
	if amount < need {
		return BidResult{}, ErrBidTooLow
	}
	// 第一步：冻结新出价。失败即返回，拍卖状态一个字节都没动。
	if err := a.escrow.FreezeGold(bidder, amount); err != nil {
		return BidResult{}, err
	}
	res := BidResult{Auction: auc, Bidder: bidder, Price: amount}
	// 第二步：退回上一位。到这一步新出价已确定被冻住，退款不可能失败。
	if au.Winner != 0 {
		if err := a.escrow.ReleaseGold(au.Winner, au.Price); err != nil {
			// 旧冻结额与当前价不符 = 状态已损坏，回滚本次冻结后报错。
			_ = a.escrow.ReleaseGold(bidder, amount)
			return BidResult{}, err
		}
		res.Refunded, res.Refund = au.Winner, au.Price
	}
	au.Winner, au.Price = bidder, amount
	if au.Buyout > 0 && amount >= au.Buyout {
		a.settleLocked(au)
		res.Sold = true
	}
	return res, nil
}

// settleLocked 结算：扣掉赢家冻结金币、抽税、把物交给赢家。调用方须持有 a.mu。
func (a *Auctioneer) settleLocked(au *Auction) {
	if au.Winner == 0 {
		au.State = auctionExpired
		_ = a.escrow.ReleaseItem(au.ID)
		return
	}
	_ = a.escrow.SpendFrozen(au.Winner, au.Price)
	tax := au.Price * taxBps / 10000
	a.escrow.Credit(au.Seller, au.Price-tax)
	_, _ = a.escrow.DeliverItem(au.ID, au.Winner)
	au.State = auctionSold
}

// SettleDue 由定时器驱动：到点结算，有人出价则成交，无人出价则流拍退物。
func (a *Auctioneer) SettleDue(now int64) int {
	a.mu.Lock()
	defer a.mu.Unlock()
	n := 0
	for _, au := range a.auctions {
		if au.State == auctionOpen && now >= au.EndAt {
			a.settleLocked(au)
			n++
		}
	}
	return n
}

func (a *Auctioneer) Snapshot(auc AuctionID) (Auction, bool) {
	a.mu.Lock()
	defer a.mu.Unlock()
	au, ok := a.auctions[auc]
	if !ok {
		return Auction{}, false
	}
	return *au, true
}

// SpendFrozen 把冻结金币真正花掉（结算用），金币从系统中消失。
func (e *Escrow) SpendFrozen(p PlayerID, amount int64) error {
	e.mu.Lock()
	defer e.mu.Unlock()
	a := e.accounts[p]
	if a == nil || a.Frozen < amount {
		return ErrNoFrozen
	}
	a.Frozen -= amount
	return nil
}

// Credit 给账户加可用金币（卖家收款用）。
func (e *Escrow) Credit(p PlayerID, amount int64) {
	e.mu.Lock()
	defer e.mu.Unlock()
	if a := e.accounts[p]; a != nil {
		a.Free += amount
	}
}

// snippet: internal/trade/auction_test.go（摘录）
func TestConcurrentBidsSingleWinnerAndConserved(t *testing.T) {
	const n = 60
	bidders := make([]PlayerID, n)
	for i := range bidders {
		bidders[i] = PlayerID(100 + i)
	}
	e, a, id := setup(t, bidders, 10_000_000)
	before := systemGold(t, e, append(bidders, 9001))

	var wg sync.WaitGroup
	for i := 0; i < n; i++ {
		wg.Add(1)
		go func(k int) {
			defer wg.Done()
			// 出价随 k 递增且步长 == MinIncrement，保证「最大 k」永远能顶掉前面的。
			amount := int64(1000 + k*100)
			_, _ = a.PlaceBid(id, PlayerID(100+k), amount, 0)
		}(i)
	}
	wg.Wait()

	au, _ := a.Snapshot(id)
	wantWinner := PlayerID(100 + n - 1)
	wantPrice := int64(1000 + (n-1)*100)
	if au.Winner != wantWinner || au.Price != wantPrice {
		t.Fatalf("赢家/成交价 = %d/%d，期望 %d/%d", au.Winner, au.Price, wantWinner, wantPrice)
	}
	if _, frozen, _ := e.Account(wantWinner); frozen != wantPrice {
		t.Fatalf("赢家冻结 = %d，期望 %d", frozen, wantPrice)
	}
	for i := 0; i < n-1; i++ {
		if _, frozen, _ := e.Account(PlayerID(100 + i)); frozen != 0 {
			t.Fatalf("被顶掉的出价人 %d 仍有 %d 冻结金币", 100+i, frozen)
		}
	}
	if after := systemGold(t, e, append(bidders, 9001)); after != before {
		t.Fatalf("出价过程金币总量 %d -> %d，未守恒", before, after)
	}
}

$ go test ./internal/trade/
ok  aegis/internal/trade  0.587s   （15 个 test 全绿）

$ go test -race ./internal/trade/
ok  aegis/internal/trade           （无 data race）