《游戏服务端架构·核心系统与契约》9.1 榜单模型与分段

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

import (
	"errors"
	"fmt"
	"sort"
)

var (
	ErrSeason    = errors.New("rankmodel: empty season")
	ErrScope     = errors.New("rankmodel: unknown scope")
	ErrPartition = errors.New("rankmodel: scope requires or forbids a partition")
	ErrLimit     = errors.New("rankmodel: limit must be positive")
	ErrPlayer    = errors.New("rankmodel: empty player id")
	ErrScore     = errors.New("rankmodel: negative score")
	ErrTime      = errors.New("rankmodel: negative achieved time")
	ErrTierOrder = errors.New("rankmodel: tier thresholds must be strictly increasing")
	ErrNotFound  = errors.New("rankmodel: player is not ranked")
)

// Scope names the audience a board is computed for. One season may run several
// scopes in parallel; they are independent write models, not filters applied to
// a single global list.
type Scope string

const (
	ScopeGlobal  Scope = "global"
	ScopeWarzone Scope = "warzone"
	ScopeFriends Scope = "friends"
	ScopeGuild   Scope = "guild"
)

func (s Scope) valid() bool {
	switch s {
	case ScopeGlobal, ScopeWarzone, ScopeFriends, ScopeGuild:
		return true
	default:
		return false
	}
}

// needsPartition reports whether the scope is meaningless without a zone,
// viewer or guild id.
func (s Scope) needsPartition() bool {
	return s == ScopeWarzone || s == ScopeFriends || s == ScopeGuild
}

// Key identifies one board. Friends and guild boards are per viewer or per
// guild, so Partition carries that owner id instead of a geographic zone.
type Key struct {
	Season    string
	Scope     Scope
	Partition string
}

// Validate rejects keys that would silently merge two different audiences.
func (k Key) Validate() error {
	if k.Season == "" {
		return ErrSeason
	}
	if !k.Scope.valid() {
		return fmt.Errorf("%w: %q", ErrScope, k.Scope)
	}
	if k.Scope.needsPartition() && k.Partition == "" {
		return fmt.Errorf("%w: %s needs a partition", ErrPartition, k.Scope)
	}
	if !k.Scope.needsPartition() && k.Partition != "" {
		return fmt.Errorf("%w: %s forbids a partition", ErrPartition, k.Scope)
	}
	return nil
}

// Tier is the display segment shown next to a rank. It is derived from the
// score, never stored on the entry, so changing a tier policy does not rewrite
// historical rows.
type Tier string

const (
	TierBronze  Tier = "bronze"
	TierSilver  Tier = "silver"
	TierGold    Tier = "gold"
	TierDiamond Tier = "diamond"
)

// TierPolicy holds inclusive lower bounds. A zero policy is invalid: the
// caller must state where silver starts.
type TierPolicy struct {
	Silver  int64
	Gold    int64
	Diamond int64
}

func (p TierPolicy) Validate() error {
	if p.Silver < 0 || p.Gold < 0 || p.Diamond < 0 {
		return ErrScore
	}
	if p.Silver >= p.Gold || p.Gold >= p.Diamond {
		return ErrTierOrder
	}
	return nil
}

// Of maps a score to a tier. The chain is ordered from the highest threshold
// so adjacent policy values cannot produce a gap.
func (p TierPolicy) Of(score int64) Tier {
	switch {
	case score >= p.Diamond:
		return TierDiamond
	case score >= p.Gold:
		return TierGold
	case score >= p.Silver:
		return TierSilver
	default:
		return TierBronze
	}
}

// Entry is one player's best result in a season.
type Entry struct {
	PlayerID string
	Score    int64
	At       int64 // unix milliseconds when the score was achieved
}

// better is the single ordering used by ranks, top lists and settlement. Score
// is descending; an earlier achievement wins a tie; the player id is the final
// stable key so two processes sort identically.
func better(a, b Entry) bool {
	if a.Score != b.Score {
		return a.Score > b.Score
	}
	if a.At != b.At {
		return a.At < b.At
	}
	return a.PlayerID < b.PlayerID
}

// Rank is the answer to "where am I", including players outside the displayed
// top list. InTop tells the caller whether the entry appears in Top.
type Rank struct {
	PlayerID string
	Rank     int
	Score    int64
	Tier     Tier
	InTop    bool
	Total    int
}

// Board is an in-memory leaderboard for one Key. It keeps every entry so rank
// queries remain exact; truncation happens only when a top list is rendered.
// It is not safe for concurrent use; callers serialize writes per board.
type Board struct {
	key     Key
	limit   int
	tiers   TierPolicy
	entries map[string]Entry
}

// NewBoard validates the key and the display limit. limit is the number of
// rows the client renders; it does not cap how many players can be ranked.
func NewBoard(key Key, limit int, tiers TierPolicy) (*Board, error) {
	if err := key.Validate(); err != nil {
		return nil, err
	}
	if limit <= 0 {
		return nil, ErrLimit
	}
	if err := tiers.Validate(); err != nil {
		return nil, err
	}
	return &Board{
		key:     key,
		limit:   limit,
		tiers:   tiers,
		entries: make(map[string]Entry),
	}, nil
}

// Submit applies a score with keep-best semantics. A lower score, or the same
// score achieved later, is acknowledged but does not change the board. The
// bool reports whether the stored entry changed.
func (b *Board) Submit(e Entry) (bool, error) {
	if e.PlayerID == "" {
		return false, ErrPlayer
	}
	if e.Score < 0 {
		return false, ErrScore
	}
	if e.At < 0 {
		return false, ErrTime
	}
	if old, ok := b.entries[e.PlayerID]; ok && !better(e, old) {
		return false, nil
	}
	b.entries[e.PlayerID] = e
	return true, nil
}

// Rank scans every entry because the board keeps the complete set. That is
// O(n) and intentional: an exact tail rank needs the full distribution. If a
// board grows past a few hundred thousand entries, move the counts into a
// sorted index instead of trading correctness for a truncated map.
func (b *Board) Rank(playerID string) (Rank, error) {
	e, ok := b.entries[playerID]
	if !ok {
		return Rank{}, fmt.Errorf("%w: %s", ErrNotFound, playerID)
	}
	rank := 1
	for _, other := range b.entries {
		if better(other, e) {
			rank++
		}
	}
	return Rank{
		PlayerID: playerID,
		Rank:     rank,
		Score:    e.Score,
		Tier:     b.tiers.Of(e.Score),
		InTop:    rank <= b.limit,
		Total:    len(b.entries),
	}, nil
}

// Top returns at most min(n, limit) entries in ranking order. n <= 0 means the
// board's full display limit.
func (b *Board) Top(n int) []Entry {
	out := make([]Entry, 0, len(b.entries))
	for _, e := range b.entries {
		out = append(out, e)
	}
	sort.Slice(out, func(i, j int) bool { return better(out[i], out[j]) })
	if n <= 0 || n > b.limit {
		n = b.limit
	}
	if n > len(out) {
		n = len(out)
	}
	return out[:n]
}