《MMO 服务器开发》13.3 公会战报名与锁定

// file: internal/guild/war.go
// tier: L1
// verify: go test ./internal/guild/ -run 'TestWar' -v

package guild

import (
	"errors"
	"time"
)

var (
	ErrSignupClosed   = errors.New("war signup window is closed")
	ErrSignupDup      = errors.New("guild already signed up")
	ErrNotSignedUp    = errors.New("guild has not signed up")
	ErrNotLockable    = errors.New("roster cannot be locked before the deadline")
	ErrRosterTooSmall = errors.New("roster below the minimum size")
)

// WarSignup is one guild's entry in the current war. Roster is empty until Lock
// fills it; after that it is frozen.
type WarSignup struct {
	GuildID  GuildID
	SignupAt time.Time
	Roster   []PlayerID // 锁定时冻结的参战名单
	Locked   bool
	LockedAt time.Time
}

// WarRegistry holds the signup window and the locked rosters for one single-server
// war cycle. 卷二 only does the in-server signup and lock; what travels to another
// server in 卷三 is exactly this frozen roster, nothing more.
type WarRegistry struct {
	openAt  time.Time
	closeAt time.Time
	minSize int
	signups map[GuildID]*WarSignup
}

func NewWarRegistry(openAt, closeAt time.Time, minSize int) *WarRegistry {
	if minSize <= 0 {
		minSize = 5
	}
	return &WarRegistry{openAt: openAt, closeAt: closeAt, minSize: minSize, signups: make(map[GuildID]*WarSignup)}
}

// Signup records a guild's intent inside [openAt, closeAt). Only a member holding
// PermWarSignup may do it, and a guild signs up at most once per cycle.
func (r *WarRegistry) Signup(g *Guild, actor PlayerID, now time.Time) error {
	if now.Before(r.openAt) || !now.Before(r.closeAt) {
		return ErrSignupClosed
	}
	if !g.can(actor, PermWarSignup) {
		return ErrPermissionDenied
	}
	if _, ok := r.signups[g.ID]; ok {
		return ErrSignupDup
	}
	r.signups[g.ID] = &WarSignup{GuildID: g.ID, SignupAt: now}
	return nil
}

// Lock freezes a signed-up guild's roster at the deadline. Before closeAt a
// roster would follow live membership; at the deadline it is snapshotted once and
// never changes again, so a member who joins after the lock cannot play this cycle.
// Locking twice is a no-op, not an error.
func (r *WarRegistry) Lock(g *Guild, now time.Time) error {
	s, ok := r.signups[g.ID]
	if !ok {
		return ErrNotSignedUp
	}
	if s.Locked {
		return nil
	}
	if now.Before(r.closeAt) {
		return ErrNotLockable
	}
	if len(g.Members) < r.minSize {
		return ErrRosterTooSmall
	}
	s.Roster = make([]PlayerID, 0, len(g.Members))
	for _, m := range g.Roster() {
		s.Roster = append(s.Roster, m.PlayerID)
	}
	s.Locked = true
	s.LockedAt = now
	return nil
}

// Roster returns the frozen roster, or nil while the guild is still unlocked.
func (r *WarRegistry) Roster(gid GuildID) []PlayerID {
	s, ok := r.signups[gid]
	if !ok || !s.Locked {
		return nil
	}
	out := make([]PlayerID, len(s.Roster))
	copy(out, s.Roster)
	return out
}

// Enrolled reports whether p is on the locked roster. A member who joined after
// the lock is deliberately excluded.
func (r *WarRegistry) Enrolled(gid GuildID, p PlayerID) bool {
	s, ok := r.signups[gid]
	if !ok || !s.Locked {
		return false
	}
	for _, id := range s.Roster {
		if id == p {
			return true
		}
	}
	return false
}

  玩家/调度器              本服（卷二）                        另一台服（卷三）
  ───────────             ─────────────                       ──────────────
  Signup(openAt..closeAt) ─▶ WarSignup{GuildID, SignupAt}
                            │
  调度器到 closeAt 触发 Lock ─▶ 快照 g.Roster() ─▶ Roster []PlayerID（冻结）
                            │
                            │  ── 这份冻结名单，逐字节稳定 ──▶  跨服匹配 / 对战 / 结算
                            │
  Enrolled(gid, p)         ─▶ 查冻结名单，而非实时成员表

// snippet: internal/guild/war_test.go（节选）

func TestWarSignupWindowAndPermission(t *testing.T) {
	open := base
	close := base.Add(2 * time.Hour)
	r := NewWarRegistry(open, close, 3)
	g := NewGuild(1, "g", 100, "leader", JoinOpen, 10, base)
	g.RequestJoin(101, "m", base)

	// Before the window opens.
	if err := r.Signup(g, 100, open.Add(-time.Minute)); !errors.Is(err, ErrSignupClosed) {
		t.Fatalf("early signup: want ErrSignupClosed, got %v", err)
	}
	// A plain member lacks PermWarSignup.
	if err := r.Signup(g, 101, open.Add(time.Minute)); !errors.Is(err, ErrPermissionDenied) {
		t.Fatalf("member signup: want ErrPermissionDenied, got %v", err)
	}
	if err := r.Signup(g, 100, open.Add(time.Minute)); err != nil {
		t.Fatalf("leader signup: %v", err)
	}
	if err := r.Signup(g, 100, open.Add(time.Minute)); !errors.Is(err, ErrSignupDup) {
		t.Fatalf("dup signup: want ErrSignupDup, got %v", err)
	}
}

func TestWarLockFreezesRoster(t *testing.T) {
	open := base
	close := base.Add(time.Hour)
	r := NewWarRegistry(open, close, 3)
	g := NewGuild(1, "g", 100, "leader", JoinOpen, 10, base)
	for _, id := range []PlayerID{101, 102} {
		g.RequestJoin(id, "m", base)
	}
	if err := r.Signup(g, 100, open); err != nil {
		t.Fatalf("signup: %v", err)
	}
	// Locking before the deadline is refused.
	if err := r.Lock(g, close.Add(-time.Minute)); !errors.Is(err, ErrNotLockable) {
		t.Fatalf("early lock: want ErrNotLockable, got %v", err)
	}
	if err := r.Lock(g, close); err != nil {
		t.Fatalf("lock: %v", err)
	}
	if got := len(r.Roster(1)); got != 3 {
		t.Fatalf("roster = %d, want 3", got)
	}
	// A member who joins after the lock must not be enrolled.
	g.RequestJoin(103, "late", base)
	if r.Enrolled(1, 103) {
		t.Fatal("late joiner enrolled after lock")
	}
	if !r.Enrolled(1, 102) {
		t.Fatal("original member missing from locked roster")
	}
	// Locking again is a no-op.
	if err := r.Lock(g, close.Add(time.Hour)); err != nil {
		t.Fatalf("relock: %v", err)
	}
}