《MMO 服务器开发》16.1 资产冻结与托管

// file: internal/trade/escrow.go
// tier: L1
// verify: go test ./internal/trade/
package trade

import (
	"errors"
	"sync"
)

// 卷二共享的内部 ID 口径（见 BRIEF §3.5）：ItemID 是配置表 ID，ItemInstID 是背包内实例 ID。
type (
	PlayerID   uint64
	ItemID     uint32
	ItemInstID uint64
	AuctionID  uint64
)

var (
	ErrItemNotFound  = errors.New("trade: 背包里没有该物品实例")
	ErrItemLocked    = errors.New("trade: 物品已被托管，不能重复冻结")
	ErrEscrowMissing = errors.New("trade: 托管记录不存在或已结算")
	ErrNoGold        = errors.New("trade: 可用金币不足")
	ErrNoFrozen      = errors.New("trade: 冻结金币不足")
)

// ItemStack 是背包里的一格。Locked 与第 8 章背包的并发修改口径一致：
// 任何会改变归属的操作（交易、拍卖、分解）都必须先把 Locked 置位，
// 由同一把锁串行化，禁止出现「已上架又拿去强化」这类双重占用。
type ItemStack struct {
	InstID ItemInstID
	ItemID ItemID
	Count  int
	Locked bool
}

// Bag 是玩家背包的最小模型，只保留托管用得到的那部分。
type Bag struct {
	Items map[ItemInstID]ItemStack
}

// Account 把金币拆成「可用」与「冻结」两栏。冻结不是扣款，
// 而是把金币从可用栏搬到冻结栏，总量守恒，便于审计。
type Account struct {
	Free   int64
	Frozen int64
}

type escrowState uint8

const (
	escrowHeld escrowState = iota
	escrowSettled
	escrowReleased
)

// escrowRecord 是一条托管记录：谁把哪个物品实例、以什么名义交给了系统。
type escrowRecord struct {
	Auction AuctionID
	Owner   PlayerID
	Item    ItemStack
	State   escrowState
}

// Escrow 是资产托管服务：物品托管 + 金币冻结共用一把锁，
// 保证「扣物」与「冻金」这两步要么都成、要么都不成。
type Escrow struct {
	mu       sync.Mutex
	seq      uint64
	items    map[PlayerID]*Bag
	accounts map[PlayerID]*Account
	records  map[AuctionID]*escrowRecord
}

func NewEscrow() *Escrow {
	return &Escrow{
		items:    make(map[PlayerID]*Bag),
		accounts: make(map[PlayerID]*Account),
		records:  make(map[AuctionID]*escrowRecord),
	}
}

// PutBag / PutAccount 只是测试与初始化用的挂载点。
func (e *Escrow) PutBag(p PlayerID, b *Bag)         { e.mu.Lock(); e.items[p] = b; e.mu.Unlock() }
func (e *Escrow) PutAccount(p PlayerID, a *Account) { e.mu.Lock(); e.accounts[p] = a; e.mu.Unlock() }
func (e *Escrow) NextAuctionID() AuctionID {
	e.mu.Lock()
	defer e.mu.Unlock()
	e.seq++
	return AuctionID(e.seq)
}
func (e *Escrow) Account(p PlayerID) (int64, int64, bool) {
	e.mu.Lock()
	defer e.mu.Unlock()
	a, ok := e.accounts[p]
	if !ok {
		return 0, 0, false
	}
	return a.Free, a.Frozen, true
}

func (e *Escrow) bag(p PlayerID) *Bag {
	b, ok := e.items[p]
	if !ok {
		b = &Bag{Items: make(map[ItemInstID]ItemStack)}
		e.items[p] = b
	}
	return b
}

// FreezeItem 把物品从背包搬到托管，是「上架」的第一步。
// 关键点：先校验再改状态，任何一步失败都不留下半冻结的物品。
func (e *Escrow) FreezeItem(seller PlayerID, inst ItemInstID, auc AuctionID) (ItemStack, error) {
	e.mu.Lock()
	defer e.mu.Unlock()
	b := e.bag(seller)
	it, ok := b.Items[inst]
	if !ok {
		return ItemStack{}, ErrItemNotFound
	}
	if it.Locked {
		return ItemStack{}, ErrItemLocked
	}
	// 冻结 = 置位 Locked 并移出背包格；物还在系统手里，记录在 escrowRecord。
	it.Locked = true
	delete(b.Items, inst)
	e.records[auc] = &escrowRecord{Auction: auc, Owner: seller, Item: it, State: escrowHeld}
	return it, nil
}

// FreezeGold 为竞价冻结金币：从可用栏搬到冻结栏，总量守恒。
func (e *Escrow) FreezeGold(p PlayerID, amount int64) error {
	if amount < 0 {
		return ErrNoGold
	}
	e.mu.Lock()
	defer e.mu.Unlock()
	a := e.accounts[p]
	if a == nil {
		return ErrNoGold
	}
	if a.Free < amount {
		return ErrNoGold
	}
	a.Free -= amount
	a.Frozen += amount
	return nil
}

// ReleaseGold 是回滚路径：把冻结金币原路退回可用栏。
func (e *Escrow) ReleaseGold(p PlayerID, amount int64) error {
	if amount < 0 {
		return ErrNoFrozen
	}
	e.mu.Lock()
	defer e.mu.Unlock()
	a := e.accounts[p]
	if a == nil || a.Frozen < amount {
		return ErrNoFrozen
	}
	a.Frozen -= amount
	a.Free += amount
	return nil
}

// ReleaseItem 把托管物品退回卖家背包（流拍、取消、超时都走这里）。
func (e *Escrow) ReleaseItem(auc AuctionID) error {
	e.mu.Lock()
	defer e.mu.Unlock()
	rec, ok := e.records[auc]
	if !ok || rec.State != escrowHeld {
		return ErrEscrowMissing
	}
	it := rec.Item
	it.Locked = false
	e.bag(rec.Owner).Items[it.InstID] = it
	rec.State = escrowReleased
	return nil
}

// DeliverItem 把托管物品交给买家（成交路径），与结算同属一个临界区。
func (e *Escrow) DeliverItem(auc AuctionID, winner PlayerID) (ItemStack, error) {
	e.mu.Lock()
	defer e.mu.Unlock()
	rec, ok := e.records[auc]
	if !ok || rec.State != escrowHeld {
		return ItemStack{}, ErrEscrowMissing
	}
	it := rec.Item
	it.Locked = false
	e.bag(winner).Items[it.InstID] = it
	rec.State = escrowSettled
	return it, nil
}

// Record 只读地回看一条托管记录，供审计与测试断言。
func (e *Escrow) Record(auc AuctionID) (ItemStack, escrowState, bool) {
	e.mu.Lock()
	defer e.mu.Unlock()
	rec, ok := e.records[auc]
	if !ok {
		return ItemStack{}, 0, false
	}
	return rec.Item, rec.State, true
}

CmdAuctionListReq = 0x0B01   // 上架 / 列拍品
CmdAuctionBidReq  = 0x0B02   // 出价

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

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