《MMO 服务器开发》12.1 队伍状态与入口控制

StateForming  ── LockForMatch（且必须满员）──▶  StateLocked
StateForming  ◀── Unlock（匹配失败/取消）────  StateLocked
StateLocked   ── EnterDungeon ─────────────▶  StateInDungeon
StateInDungeon ── 结算回退 ────────────────▶  StateForming

// file: internal/party/party.go
// tier: L1
// verify: go test ./internal/party/

package party

import (
	"errors"
	"sync"
)

// PartyID 与 PlayerID 是卷二共享的服务端内部类型，全卷口径一致。
type (
	PartyID  uint64
	PlayerID uint64
)

// Role 只有两种：队长是唯一的「入口控制者」。
type Role uint8

const (
	RoleMember Role = iota
	RoleLeader
)

// State 是队伍的生命周期状态，决定谁能改队伍、队伍能不能被匹配。
type State uint8

const (
	StateForming   State = iota // 自由组建，队长可邀请/踢人
	StateLocked                 // 已锁定匹配，成员集合冻结
	StateInDungeon              // 已进入副本，仅允许结算后回退
)

// MaxMembers 是《晨曦大陆》小队上限，满员判断与容量预留都以它为准。
const MaxMembers = 4

// 入口控制的拒绝原因保持独立，方便网关按码回包而不是回一句含糊的失败。
var (
	ErrPartyFull     = errors.New("party: party is full")
	ErrNotLeader     = errors.New("party: caller is not the leader")
	ErrPartyLocked   = errors.New("party: party is locked")
	ErrAlreadyMember = errors.New("party: player is already a member")
	ErrNotMember     = errors.New("party: player is not a member")
	ErrNoLeader      = errors.New("party: no eligible leader")
)

// Member 是一个座位。Online 由会话层在掉线/重连时改写，不是队伍服务自己猜的。
type Member struct {
	PlayerID PlayerID
	Role     Role
	Online   bool
}

// Party 是单服内一支队伍的全部权威状态。所有字段都在 mu 之下，调用方绝不
// 在持有 *Party 的情况下发起网络调用。
type Party struct {
	mu      sync.Mutex
	id      PartyID
	state   State
	leader  PlayerID
	order   []PlayerID // 稳定加入顺序，队长迁移按它挑选
	members map[PlayerID]*Member
}

// NewParty 建一支只有队长一人的队伍。队长天然在线。
func NewParty(id PartyID, leader PlayerID) *Party {
	return &Party{
		id:      id,
		state:   StateForming,
		leader:  leader,
		order:   []PlayerID{leader},
		members: map[PlayerID]*Member{leader: {PlayerID: leader, Role: RoleLeader, Online: true}},
	}
}

func (p *Party) ID() PartyID { return p.id }

// State 返回当前状态快照。
func (p *Party) State() State {
	p.mu.Lock()
	defer p.mu.Unlock()
	return p.state
}

// Leader 返回当前队长。
func (p *Party) Leader() PlayerID {
	p.mu.Lock()
	defer p.mu.Unlock()
	return p.leader
}

// Count 只是读快照，不能拿它做「先判断再写入」的满员判断——那正是 12.2
// 要修的竞态。写路径一律走 TryJoin。
func (p *Party) Count() int {
	p.mu.Lock()
	defer p.mu.Unlock()
	return len(p.members)
}

// Snapshot 复制一份成员列表，按加入顺序返回。调用方拿到的切片可以随意
// 排序、序列化、发给客户端，不会影响队伍内部状态。
func (p *Party) Snapshot() []Member {
	p.mu.Lock()
	defer p.mu.Unlock()
	return p.snapshotLocked()
}

func (p *Party) snapshotLocked() []Member {
	out := make([]Member, 0, len(p.order))
	for _, id := range p.order {
		if m, ok := p.members[id]; ok {
			out = append(out, *m)
		}
	}
	return out
}

// entryAllowedLocked 是入口控制的唯一判据：谁、在什么状态下、能不能改成员
// 集合。所有写方法都先过它，避免规则散落在七八个 if 里各写一遍。
func (p *Party) entryAllowedLocked(actor PlayerID) error {
	if p.state != StateForming {
		return ErrPartyLocked
	}
	if actor != p.leader {
		return ErrNotLeader
	}
	return nil
}

// AddMember 是队长邀请入队。四道门依次过：状态可写、调用者是队长、目标
// 不在队里、未满员。任何一道不过，队伍状态一个字节都不改。
func (p *Party) AddMember(actor, target PlayerID) error {
	p.mu.Lock()
	defer p.mu.Unlock()
	if err := p.entryAllowedLocked(actor); err != nil {
		return err
	}
	// 先判重复再判满员：重复邀请的语义是「已入队」而非「满了」。
	if _, ok := p.members[target]; ok {
		return ErrAlreadyMember
	}
	if len(p.members) >= MaxMembers {
		return ErrPartyFull
	}
	p.members[target] = &Member{PlayerID: target, Role: RoleMember, Online: true}
	p.order = append(p.order, target)
	return nil
}

// RemoveMember 覆盖两种语义：队长踢人（actor 是队长），以及成员自己退出
// （actor == target）。队长不能踢自己——退位必须走迁移，否则队伍会没有队长。
func (p *Party) RemoveMember(actor, target PlayerID) error {
	p.mu.Lock()
	defer p.mu.Unlock()
	if p.state != StateForming {
		return ErrPartyLocked
	}
	if actor != p.leader && actor != target {
		return ErrNotLeader
	}
	if actor == target && actor == p.leader {
		return ErrNotLeader
	}
	if _, ok := p.members[target]; !ok {
		return ErrNotMember
	}
	p.removeLocked(target)
	return nil
}

func (p *Party) removeLocked(target PlayerID) {
	delete(p.members, target)
	for i, id := range p.order {
		if id == target {
			p.order = append(p.order[:i], p.order[i+1:]...)
			break
		}
	}
}

// setStateLocked 是状态机的唯一入口：组建 -> 锁定 -> 副本，以及回退。
func (p *Party) setStateLocked(next State) error {
	switch p.state {
	case StateForming:
		if next != StateLocked {
			return ErrPartyLocked
		}
	case StateLocked:
		if next != StateInDungeon && next != StateForming {
			return ErrPartyLocked
		}
	case StateInDungeon:
		if next != StateForming {
			return ErrPartyLocked
		}
	}
	p.state = next
	return nil
}

// snippet: internal/party/party_test.go（节选）

// TestEntryControl 钉死 12.1 的四道门：非队长不能改、满员不能进、重复不能进、
// 锁定后一律不能进。任何一条被绕过，都会让「谁能进副本」失控。
func TestEntryControl(t *testing.T) {
	leader, a, b, c, d := PlayerID(1), PlayerID(2), PlayerID(3), PlayerID(4), PlayerID(5)
	p := NewParty(PartyID(7), leader)

	if err := p.AddMember(a, b); !errors.Is(err, ErrNotLeader) {
		t.Fatalf("non-leader add: want ErrNotLeader, got %v", err)
	}
	if err := p.AddMember(leader, a); err != nil {
		t.Fatalf("leader add: %v", err)
	}
	if err := p.AddMember(leader, a); !errors.Is(err, ErrAlreadyMember) {
		t.Fatalf("duplicate add: want ErrAlreadyMember, got %v", err)
	}
	// ... 补满 b、c 后，第四个 d 必须被 ErrPartyFull 挡住
	// 队长不能把自己踢掉——退位必须走迁移
	if err := p.RemoveMember(leader, leader); !errors.Is(err, ErrNotLeader) {
		t.Fatalf("leader self-remove: want ErrNotLeader, got %v", err)
	}
}