《MMO 服务器开发》13.1 入会、职位与权限

CmdGuildJoinReq  0x0801  客户端申请入会 / 审批请求
CmdGuildInfoSync 0x0802  服务端下发公会快照（成员、职位、仓库、战况）

// snippet: internal/guild/model.go（职位与权限部分）

// Rank is a guild member position, ordered from low to high. The numeric order
// is load-bearing: the rules in guild.go compare ranks directly.
type Rank uint8

const (
	RankMember     Rank = iota // 普通成员
	RankElite                  // 精英
	RankOfficer                // 官员
	RankViceLeader             // 副会长
	RankLeader                 // 会长
)

// Permission is a bitmask of actions a rank may perform.
type Permission uint32

const (
	PermInvite Permission = 1 << iota
	PermKick
	PermEditNotice
	PermStorageDeposit
	PermStorageWithdraw
	PermWarSignup
	PermPromote
	PermDisband
)

// rankPerms is the single source of truth for "which rank may do what". Keeping
// it in one table instead of scattering checks across call sites is what makes
// the permission model auditable: a reviewer reads one map, not forty branches.
var rankPerms = map[Rank]Permission{
	RankMember:     PermStorageDeposit,
	RankElite:      PermStorageDeposit,
	RankOfficer:    PermStorageDeposit | PermInvite | PermStorageWithdraw | PermEditNotice,
	RankViceLeader: PermStorageDeposit | PermInvite | PermStorageWithdraw | PermEditNotice | PermKick | PermPromote | PermWarSignup,
	RankLeader:     PermStorageDeposit | PermInvite | PermStorageWithdraw | PermEditNotice | PermKick | PermPromote | PermWarSignup | PermDisband,
}

// Can reports whether the rank holds perm.
func (r Rank) Can(perm Permission) bool { return rankPerms[r]&perm != 0 }

// file: internal/guild/guild.go
// tier: L1
// verify: go test ./internal/guild/ -run 'TestJoin|TestKick|TestRank|TestLeader' -v

package guild

import (
	"sort"
	"time"
)

// Guild holds the roster and the admission state of one guild. Every method is
// called from the guild's own single-threaded logic goroutine, so there is no
// mutex here on purpose: the locking discipline is "one guild, one executor",
// the same ownership rule as 卷二第 1 章.
type Guild struct {
	ID       GuildID
	Name     string
	Leader   PlayerID
	Policy   JoinPolicy
	Capacity int
	Members  map[PlayerID]*Member
	Pending  map[PlayerID]time.Time // 待审批申请：玩家 -> 申请时间
}

// NewGuild creates a guild whose founder is the first leader.
func NewGuild(id GuildID, name string, leader PlayerID, leaderName string, policy JoinPolicy, capacity int, now time.Time) *Guild {
	if capacity <= 0 {
		capacity = 50
	}
	g := &Guild{
		ID:       id,
		Name:     name,
		Leader:   leader,
		Policy:   policy,
		Capacity: capacity,
		Members:  make(map[PlayerID]*Member),
		Pending:  make(map[PlayerID]time.Time),
	}
	g.Members[leader] = &Member{PlayerID: leader, Name: leaderName, Rank: RankLeader, JoinedAt: now}
	return g
}

// can is the internal permission gate; it also rejects non-members.
func (g *Guild) can(actor PlayerID, perm Permission) bool {
	m, ok := g.Members[actor]
	if !ok {
		return false
	}
	return m.Rank.Can(perm)
}

// RequestJoin dispatches on policy: an open guild admits immediately and reports
// joined=true; an apply-only guild queues the request and reports joined=false.
// Both paths are idempotent — a duplicate never creates a second roster entry or
// a second pending row.
func (g *Guild) RequestJoin(p PlayerID, name string, now time.Time) (joined bool, err error) {
	if _, ok := g.Members[p]; ok {
		return false, ErrAlreadyMember
	}
	if len(g.Members) >= g.Capacity {
		return false, ErrGuildFull
	}
	if g.Policy == JoinOpen {
		g.Members[p] = &Member{PlayerID: p, Name: name, Rank: RankMember, JoinedAt: now}
		return true, nil
	}
	if _, ok := g.Pending[p]; ok {
		return false, ErrAlreadyApplied
	}
	g.Pending[p] = now
	return false, nil
}

// Approve admits a pending applicant. The actor must hold PermInvite, and the
// room is re-checked here because members may have filled the guild while the
// application sat in the queue.
func (g *Guild) Approve(actor, applicant PlayerID, name string, now time.Time) error {
	if !g.can(actor, PermInvite) {
		return ErrPermissionDenied
	}
	if _, ok := g.Pending[applicant]; !ok {
		return ErrNoApplication
	}
	if len(g.Members) >= g.Capacity {
		return ErrGuildFull
	}
	delete(g.Pending, applicant)
	g.Members[applicant] = &Member{PlayerID: applicant, Name: name, Rank: RankMember, JoinedAt: now}
	return nil
}

// Leave removes a member. The leader may not leave while others remain, or the
// guild would be headless — transferring leadership is a separate operation.
func (g *Guild) Leave(p PlayerID) error {
	m, ok := g.Members[p]
	if !ok {
		return ErrNotMember
	}
	if m.Rank == RankLeader && len(g.Members) > 1 {
		return ErrHeadlessGuild
	}
	delete(g.Members, p)
	return nil
}

// Kick removes target. The actor needs PermKick and may not remove a rank at or
// above their own — a vice-leader cannot kick a peer or the leader.
func (g *Guild) Kick(actor, target PlayerID) error {
	if !g.can(actor, PermKick) {
		return ErrPermissionDenied
	}
	t, ok := g.Members[target]
	if !ok {
		return ErrNotMember
	}
	if t.Rank >= g.Members[actor].Rank {
		return ErrBadRankChange
	}
	delete(g.Members, target)
	return nil
}

// SetRank changes target's rank. Two rules keep the hierarchy sane: the actor may
// not touch a rank at or above their own, and nobody may mint a second leader.
func (g *Guild) SetRank(actor, target PlayerID, r Rank) error {
	if !g.can(actor, PermPromote) {
		return ErrPermissionDenied
	}
	a, ok := g.Members[actor]
	if !ok {
		return ErrNotMember
	}
	t, ok := g.Members[target]
	if !ok {
		return ErrNotMember
	}
	if target == actor {
		return ErrBadRankChange
	}
	if t.Rank >= a.Rank || r >= a.Rank {
		return ErrBadRankChange
	}
	t.Rank = r
	return nil
}

// Roster returns members sorted by rank desc, then join time asc, then id. The
// order is fully deterministic so the client can render it without re-sorting,
// and 13.3 relies on it to snapshot a stable war roster.
func (g *Guild) Roster() []*Member {
	out := make([]*Member, 0, len(g.Members))
	for _, m := range g.Members {
		out = append(out, m)
	}
	sort.Slice(out, func(i, j int) bool {
		if out[i].Rank != out[j].Rank {
			return out[i].Rank > out[j].Rank
		}
		if !out[i].JoinedAt.Equal(out[j].JoinedAt) {
			return out[i].JoinedAt.Before(out[j].JoinedAt)
		}
		return out[i].PlayerID < out[j].PlayerID
	})
	return out
}

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

func TestJoinOpenRespectsCapacity(t *testing.T) {
	g := NewGuild(1, "晨曦骑士团", 100, "阿澈", JoinOpen, 3, base)
	for _, id := range []PlayerID{101, 102} {
		joined, err := g.RequestJoin(id, "p", base)
		if err != nil || !joined {
			t.Fatalf("join %d: joined=%v err=%v", id, joined, err)
		}
	}
	if _, err := g.RequestJoin(103, "p", base); !errors.Is(err, ErrGuildFull) {
		t.Fatalf("want ErrGuildFull, got %v", err)
	}
}

func TestApplyDedup(t *testing.T) {
	g := NewGuild(1, "g", 100, "leader", JoinApply, 10, base)
	if joined, err := g.RequestJoin(200, "p", base); err != nil || joined {
		t.Fatalf("first apply: joined=%v err=%v", joined, err)
	}
	if _, err := g.RequestJoin(200, "p", base); !errors.Is(err, ErrAlreadyApplied) {
		t.Fatalf("want ErrAlreadyApplied, got %v", err)
	}
	if len(g.Pending) != 1 {
		t.Fatalf("pending = %d, want 1", len(g.Pending))
	}
	if err := g.Approve(100, 200, "p", base); err != nil {
		t.Fatalf("approve: %v", err)
	}
	if _, err := g.RequestJoin(200, "p", base); !errors.Is(err, ErrAlreadyMember) {
		t.Fatalf("rejoin after approval: want ErrAlreadyMember, got %v", err)
	}
}