《游戏服务端编程实践》20.4 排行榜与社交模块

// file: ch20/social/social.go
// tier: L1
// verify: go test ./ch20/social/

package social

import (
	"errors"
	"sort"
	"sync"
	"time"
)

const (
	DefaultMemberLimit  = 50
	DefaultHelpLimit    = 20
	DefaultHelpCooldown = 10 * time.Minute
)

var (
	ErrInvalidPlayer   = errors.New("social: player id is empty")
	ErrInvalidRole     = errors.New("social: invalid role assignment")
	ErrInvalidPolicy   = errors.New("social: invalid help policy")
	ErrGuildFull       = errors.New("social: guild member limit reached")
	ErrDuplicateMember = errors.New("social: player already joined")
	ErrNotMember       = errors.New("social: player is not a guild member")
	ErrForbidden       = errors.New("social: role is not allowed")
	ErrLeaderImmutable = errors.New("social: leader cannot be removed or demoted")
	ErrHelpSelf        = errors.New("social: cannot help yourself")
	ErrHelpCooldown    = errors.New("social: help is still in cooldown")
	ErrHelpLimit       = errors.New("social: daily help limit reached")
	ErrInvalidScore    = errors.New("social: score must not be negative")
	ErrSeasonBackwards = errors.New("social: season must move forward")
)

// Role 的数值只用于比较权限，不用于对外展示。
type Role int

const (
	RoleMember Role = iota
	RoleElder
	RoleLeader
)

func (r Role) canInvite() bool { return r >= RoleElder }
func (r Role) canAssign() bool { return r == RoleLeader }

// Guild 把成员、职位和互助计数放在同一把锁下，避免出现
// “已经退盟但还能帮助”的中间态。
type Guild struct {
	mu           sync.Mutex
	id           string
	server       string
	memberLimit  int
	helpLimit    int
	helpCooldown time.Duration
	members      map[string]Role
	helpAt       map[string]time.Time
	helpDay      map[string]string
	helpCount    map[string]int
}

func NewGuild(id, server, leader string, memberLimit int) (*Guild, error) {
	if id == "" || leader == "" {
		return nil, ErrInvalidPlayer
	}
	if memberLimit <= 0 {
		memberLimit = DefaultMemberLimit
	}
	return &Guild{
		id: id, server: server, memberLimit: memberLimit,
		helpLimit: DefaultHelpLimit, helpCooldown: DefaultHelpCooldown,
		members:   map[string]Role{leader: RoleLeader},
		helpAt:    make(map[string]time.Time),
		helpDay:   make(map[string]string),
		helpCount: make(map[string]int),
	}, nil
}

// SetHelpPolicy 由运营配置调用，测试用短冷却验证边界。
func (g *Guild) SetHelpPolicy(limit int, cooldown time.Duration) error {
	if limit <= 0 || cooldown < 0 {
		return ErrInvalidPolicy
	}
	g.mu.Lock()
	defer g.mu.Unlock()
	g.helpLimit, g.helpCooldown = limit, cooldown
	return nil
}

// AddMember 处理入盟：副盟主及以上可以邀请，职位只能是成员或副盟主。
func (g *Guild) AddMember(actor, player string, role Role) error {
	if player == "" {
		return ErrInvalidPlayer
	}
	g.mu.Lock()
	defer g.mu.Unlock()
	actorRole, ok := g.members[actor]
	if !ok {
		return ErrNotMember
	}
	if !actorRole.canInvite() {
		return ErrForbidden
	}
	if role >= RoleLeader {
		return ErrInvalidRole
	}
	if _, exists := g.members[player]; exists {
		return ErrDuplicateMember
	}
	if len(g.members) >= g.memberLimit {
		return ErrGuildFull
	}
	g.members[player] = role
	return nil
}

// SetRole 只有盟主可以调用，且不能把成员设为盟主。
func (g *Guild) SetRole(actor, target string, role Role) error {
	if role >= RoleLeader {
		return ErrInvalidRole
	}
	g.mu.Lock()
	defer g.mu.Unlock()
	actorRole, ok := g.members[actor]
	if !ok {
		return ErrNotMember
	}
	if !actorRole.canAssign() {
		return ErrForbidden
	}
	targetRole, ok := g.members[target]
	if !ok {
		return ErrNotMember
	}
	if targetRole == RoleLeader {
		return ErrLeaderImmutable
	}
	if actor == target {
		return ErrForbidden
	}
	g.members[target] = role
	return nil
}

// Help 记录一次联盟帮助。冷却按“帮助者 + 被帮助者”计算，日限按帮助者
// 计算并以 UTC 自然日重置，避免玩家跨时区刷次数。
func (g *Guild) Help(helper, target string, now time.Time) error {
	if helper == "" || target == "" {
		return ErrInvalidPlayer
	}
	if helper == target {
		return ErrHelpSelf
	}
	g.mu.Lock()
	defer g.mu.Unlock()
	if _, ok := g.members[helper]; !ok {
		return ErrNotMember
	}
	if _, ok := g.members[target]; !ok {
		return ErrNotMember
	}
	key := helper + "|" + target
	if last, ok := g.helpAt[key]; ok && now.Sub(last) < g.helpCooldown {
		return ErrHelpCooldown
	}
	day := now.UTC().Format("2006-01-02")
	if g.helpDay[helper] != day {
		g.helpDay[helper] = day
		g.helpCount[helper] = 0
	}
	if g.helpCount[helper] >= g.helpLimit {
		return ErrHelpLimit
	}
	g.helpAt[key] = now
	g.helpCount[helper]++
	return nil
}

// Ranked 是排行榜的一行。并列使用竞赛排名（1、1、3），同分时按
// 玩家 ID 升序输出，保证每次查询顺序稳定。
type Ranked struct {
	Rank   int
	Player string
	Score  int64
}

// Board 不保存全量排序结果，查询时才对当前分数快照排序。
// 联盟榜可以复用同一结构，把 Player 换成联盟 ID 即可。
type Board struct {
	mu     sync.Mutex
	season int
	scores map[string]int64
}

func NewBoard(season int) *Board {
	return &Board{season: season, scores: make(map[string]int64)}
}

func (b *Board) Set(player string, score int64) error {
	if player == "" {
		return ErrInvalidPlayer
	}
	if score < 0 {
		return ErrInvalidScore
	}
	b.mu.Lock()
	defer b.mu.Unlock()
	b.scores[player] = score
	return nil
}

func (b *Board) Top(n int) []Ranked {
	b.mu.Lock()
	defer b.mu.Unlock()
	entries := make([]Ranked, 0, len(b.scores))
	for player, score := range b.scores {
		entries = append(entries, Ranked{Player: player, Score: score})
	}
	sort.Slice(entries, func(i, j int) bool {
		if entries[i].Score != entries[j].Score {
			return entries[i].Score > entries[j].Score
		}
		return entries[i].Player < entries[j].Player
	})
	rank := 0
	var prev int64
	for i := range entries {
		if i == 0 || entries[i].Score != prev {
			rank = i + 1
			prev = entries[i].Score
		}
		entries[i].Rank = rank
	}
	if n <= 0 || n > len(entries) {
		n = len(entries)
	}
	return entries[:n]
}

// ResetSeason 清空分数并推进赛季；赛季只能前进，防止误操作回滚榜单。
func (b *Board) ResetSeason(season int) error {
	b.mu.Lock()
	defer b.mu.Unlock()
	if season <= b.season {
		return ErrSeasonBackwards
	}
	b.season = season
	b.scores = make(map[string]int64)
	return nil
}

cd .local/checks/gs-practice-lab && gofmt -l ch20/social && go vet ./ch20/social/ && go test ./ch20/social/ -count=1

ok  	gspractice/ch20/social	0.312s