《MMO 服务器开发》6.3 资产归属与跨服结算

// snippet: internal/crossserver/ticket.go（结算单与幂等键生成）
// SettlementTicket 是跨服战场产出的结算单，由玩家「母服」兑现。
type SettlementTicket struct {
	TicketID   string // 幂等键：battleID:playerID:rewardHash
	BattleID   uint64
	PlayerID   uint64
	HomeServer uint16 // 奖励归属的母服
	Items      []Reward
}

// NewTicket 按约定生成幂等键。奖励内容进 hash，改奖励就会换 key，避免旧单被顶掉。
func NewTicket(battleID, playerID uint64, home uint16, items []Reward) SettlementTicket {
	h := uint64(1469598103934665603) // FNV-1a 64 起点
	for _, r := range items {
		h ^= uint64(r.ItemID)
		h *= 1099511628211
		h ^= uint64(r.Count)
		h *= 1099511628211
	}
	return SettlementTicket{
		TicketID:   fmt.Sprintf("%d:%d:%016x", battleID, playerID, h),
		BattleID:   battleID,
		PlayerID:   playerID,
		HomeServer: home,
		Items:      append([]Reward(nil), items...),
	}
}

战场实例（无状态）                       母服（账本，唯一写入方）
────────────────                        ──────────────────────
结算：算出该发什么  ────ticket────►     Apply(ticket)
BattleLedger.Issue ─┐                    ├─ 幂等表命中？ → 忽略（不重复发奖）
                    │                    └─ 未命中       → 入账 + 记幂等表
                    ▼
             Reconcile：minted  ──必须等于──  credited

// file: internal/crossserver/settler.go
// tier: L1
// verify: go test ./internal/crossserver/ -run TestIdempotentReward
package crossserver

import (
	"errors"
	"sync"
)

var (
	ErrWrongServer = errors.New("crossserver: ticket not for this home server")
	ErrServerDown  = errors.New("crossserver: home server unavailable")
)

// Settler 在母服上兑现结算单。幂等：同一 TicketID 只入账一次。
type Settler struct {
	serverID uint16

	mu      sync.Mutex
	down    bool
	applied map[string]bool   // 幂等表：已兑现的 TicketID
	wallet  map[uint32]uint64 // ItemID -> 累计入账
}

func NewSettler(serverID uint16) *Settler {
	return &Settler{serverID: serverID, applied: make(map[string]bool), wallet: make(map[uint32]uint64)}
}

// Apply 兑现一张结算单，返回 (是否首次入账, error)。
// 重复的 TicketID 返回 (false, nil)——不报错、也不再入账。
func (s *Settler) Apply(t SettlementTicket) (bool, error) {
	s.mu.Lock()
	defer s.mu.Unlock()
	if s.down {
		return false, ErrServerDown
	}
	if t.HomeServer != s.serverID {
		return false, ErrWrongServer
	}
	if s.applied[t.TicketID] {
		return false, nil
	}
	for _, r := range t.Items {
		s.wallet[r.ItemID] += uint64(r.Count)
	}
	s.applied[t.TicketID] = true
	return true, nil
}

// SetDown 模拟母服不可用（测试用）。
func (s *Settler) SetDown(down bool) {
	s.mu.Lock()
	s.down = down
	s.mu.Unlock()
}

func (s *Settler) Balance(itemID uint32) uint64 {
	s.mu.Lock()
	defer s.mu.Unlock()
	return s.wallet[itemID]
}

func (s *Settler) AppliedCount() int {
	s.mu.Lock()
	defer s.mu.Unlock()
	return len(s.applied)
}

// file: internal/crossserver/delivery.go
// tier: L1
// verify: go test ./internal/crossserver/ -run TestRetryThenSucceed
package crossserver

import "errors"

var ErrNoSettler = errors.New("crossserver: no settler for home server")

// RetryingDeliverer 把结算单从战场侧回传到母服，失败重试。
// 关键点：因为 Settler.Apply 幂等，重试不会重复发奖——这是本卷资产安全的地基。
type RetryingDeliverer struct {
	settlers map[uint16]*Settler
	maxTries int
}

func NewRetryingDeliverer(maxTries int, settlers ...*Settler) *RetryingDeliverer {
	m := make(map[uint16]*Settler, len(settlers))
	for _, s := range settlers {
		m[s.serverID] = s
	}
	return &RetryingDeliverer{settlers: m, maxTries: maxTries}
}

// Deliver 回传一张结算单，返回尝试次数。
// 只有「母服暂时不可用」才重试；语义错误（比如单子投错了服）立即返回，不浪费重试。
func (d *RetryingDeliverer) Deliver(t SettlementTicket) (int, error) {
	s := d.settlers[t.HomeServer]
	if s == nil {
		return 0, ErrNoSettler
	}
	var lastErr error
	for i := 0; i < d.maxTries; i++ {
		if _, err := s.Apply(t); err == nil {
			return i + 1, nil
		} else if !errors.Is(err, ErrServerDown) {
			return i + 1, err // 永久错误：不重试
		} else {
			lastErr = err
		}
	}
	return d.maxTries, lastErr
}

// snippet: internal/crossserver/ledger.go（对账不变式）
// Reconcile 对账：战场侧产出总量必须等于各母服入账总量之和。
// 差额非零 = 回传丢失或重复入账，是资产守恒必须为零的不变式。
func Reconcile(l *BattleLedger, settlers map[uint16]*Settler, itemID uint32) (minted, credited uint64, ok bool) {
	minted = l.Minted(itemID)
	for _, s := range settlers {
		credited += s.Balance(itemID)
	}
	return minted, credited, minted == credited
}

=== RUN   TestIdempotentReward
--- PASS: TestIdempotentReward (0.00s)
=== RUN   TestAccountConservation
--- PASS: TestAccountConservation (0.00s)
=== RUN   TestRetryThenSucceed
--- PASS: TestRetryThenSucceed (0.00s)
=== RUN   TestReconcileDetectsLoss
--- PASS: TestReconcileDetectsLoss (0.00s)
=== RUN   TestWrongServerRejected
--- PASS: TestWrongServerRejected (0.00s)
ok  	aegis/internal/crossserver	1.692s