《MMO 服务器开发》14.3 结算与赛季边界

// file: internal/rank/settlement.go
// tier: L1
// verify: go test ./internal/rank/ -run TestSettlement -v

package rank

// RewardTier assigns a reward to a contiguous, 1-based, inclusive rank range.
// Ranks are read from a frozen snapshot, so a late score update can never
// half-apply a tier.
type RewardTier struct {
	From   int
	To     int
	ItemID uint32
	Amount int64
}

// Grant is one item reward handed to a player.
type Grant struct {
	ItemID uint32
	Amount int64
}

// Settlement is the immutable result of closing one season. It is keyed by
// SeasonID so replaying the same season is a no-op: Deliver checks Delivered
// before it sends, which is how duplicate rewards are prevented.
type Settlement struct {
	SeasonID  int64
	FrozenAt  int64
	Ranks     map[uint64]int     // player -> final rank
	Rewards   map[uint64][]Grant // player -> grants
	Delivered map[uint64]bool
}

// Settle freezes a board's top standings into a Settlement. snapshot must be the
// TopK list captured under the season lock at frozenAt; anything submitted at or
// after frozenAt belongs to the next season, not this one.
func Settle(seasonID, frozenAt int64, snapshot []Entry, tiers []RewardTier) *Settlement {
	s := &Settlement{
		SeasonID:  seasonID,
		FrozenAt:  frozenAt,
		Ranks:     make(map[uint64]int, len(snapshot)),
		Rewards:   make(map[uint64][]Grant),
		Delivered: make(map[uint64]bool),
	}
	for i, e := range snapshot {
		rankNo := i + 1
		s.Ranks[e.PlayerID] = rankNo
		for _, t := range tiers {
			if rankNo >= t.From && rankNo <= t.To {
				s.Rewards[e.PlayerID] = append(s.Rewards[e.PlayerID], Grant{ItemID: t.ItemID, Amount: t.Amount})
			}
		}
	}
	return s
}

// Deliver hands a player their rewards exactly once. A second call for the same
// player is a no-op, which makes the whole settlement safe to retry after a
// crash in the middle of distribution.
func (s *Settlement) Deliver(id uint64, send func(itemID uint32, amount int64)) bool {
	if s.Delivered[id] {
		return false
	}
	for _, g := range s.Rewards[id] {
		send(g.ItemID, g.Amount)
	}
	s.Delivered[id] = true
	return true
}

// InSeason reports whether a score update timestamped at belongs to the season
// window [start, end). Updates at or after end are the next season's.
func InSeason(at, start, end int64) bool {
	return at >= start && at < end
}

// file: internal/rank/settlement_test.go
// tier: L1
// verify: go test ./internal/rank/ -run TestSettlement -v

package rank

import "testing"

func TestSettlementTiersAndIdempotency(t *testing.T) {
	snap := []Entry{
		{PlayerID: 10, Score: 500},
		{PlayerID: 20, Score: 400},
		{PlayerID: 30, Score: 300},
		{PlayerID: 40, Score: 200},
		{PlayerID: 50, Score: 100},
	}
	tiers := []RewardTier{
		{From: 1, To: 1, ItemID: 9001, Amount: 1},   // champion
		{From: 2, To: 3, ItemID: 9002, Amount: 1},   // runner-up band
		{From: 1, To: 5, ItemID: 9003, Amount: 100}, // participation
	}
	s := Settle(7, 1_000, snap, tiers)

	if s.Ranks[10] != 1 || s.Ranks[50] != 5 {
		t.Fatalf("ranks=%v", s.Ranks)
	}
	if len(s.Rewards[10]) != 2 { // champion + participation
		t.Fatalf("player10 rewards=%v", s.Rewards[10])
	}
	if len(s.Rewards[20]) != 2 { // runner-up + participation
		t.Fatalf("player20 rewards=%v", s.Rewards[20])
	}
	if len(s.Rewards[40]) != 1 || s.Rewards[40][0].ItemID != 9003 {
		t.Fatalf("player40 rewards=%v", s.Rewards[40])
	}

	sent := map[uint64]int{}
	mk := func(id uint64) func(uint32, int64) {
		return func(item uint32, amount int64) { sent[id]++ }
	}
	if !s.Deliver(10, mk(10)) {
		t.Fatal("first deliver should report true")
	}
	if s.Deliver(10, mk(10)) {
		t.Fatal("second deliver must be a no-op")
	}
	if sent[10] != 2 {
		t.Fatalf("player10 sends=%d want 2", sent[10])
	}
}

func TestSeasonBoundary(t *testing.T) {
	start, end := int64(1000), int64(2000)
	cases := []struct {
		at   int64
		want bool
	}{
		{999, false},  // before the season
		{1000, true},  // inclusive start
		{1999, true},  // last tick that belongs to the season
		{2000, false}, // exclusive end: the next season owns this tick
		{2001, false},
	}
	for _, c := range cases {
		if got := InSeason(c.at, start, end); got != c.want {
			t.Fatalf("InSeason(%d)=%v want %v", c.at, got, c.want)
		}
	}
}