《MMO 服务器开发》12.3 掉线处理与队长迁移

// file: internal/party/session.go
// tier: L1
// verify: go test ./internal/party/ -run TestDisconnect -race

package party

import "time"

// DisconnectResult 描述一次掉线对队伍造成的后果，交给上层决定要不要
// 发 CmdPartyInfoSync 0x0702 给剩下的人。
type DisconnectResult struct {
	// LeaderChanged 为真时 leader 字段已经换成新队长。
	LeaderChanged bool
	NewLeader     PlayerID
	// Dissolved 为真时队伍已无人在线，应当解散并回收 PartyID。
	Dissolved bool
}

// MarkOffline 处理一次成员掉线。它只改 Online 标志、不删座位——座位是留给
// 重连的（对应卷一 6.3 的重连票据：重连成功后拿同一 PlayerID 回到原座位）。
// 若掉线的是队长，立即把队长迁移给下一位在线成员；若无人可继，标记解散。
func (p *Party) MarkOffline(pid PlayerID) DisconnectResult {
	p.mu.Lock()
	defer p.mu.Unlock()
	m, ok := p.members[pid]
	if !ok {
		return DisconnectResult{}
	}
	m.Online = false

	var res DisconnectResult
	if p.leader == pid {
		if next, ok := p.nextOnlineLocked(); ok {
			p.members[next].Role = RoleLeader
			p.leader = next
			res.LeaderChanged = true
			res.NewLeader = next
		}
	}
	if !p.anyOnlineLocked() {
		res.Dissolved = true
	}
	return res
}

// MarkOnline 是重连成功的回调。它把座位点亮；但队长不会自动还回去——
// 顶号式地来回换队长会让队友看到的头像一直跳，迁移是一次性的。
func (p *Party) MarkOnline(pid PlayerID) bool {
	p.mu.Lock()
	defer p.mu.Unlock()
	m, ok := p.members[pid]
	if !ok {
		return false
	}
	m.Online = true
	return true
}

// MigrateLeader 是队长主动退位时的显式迁移：挑下一位在线成员当队长。
// 与 MarkOffline 的自动迁移共用同一个挑选函数，保证两处规则一致。
func (p *Party) MigrateLeader(actor PlayerID) (PlayerID, error) {
	p.mu.Lock()
	defer p.mu.Unlock()
	if actor != p.leader {
		return 0, ErrNotLeader
	}
	next, ok := p.nextOnlineLocked()
	if !ok {
		return 0, ErrNoLeader
	}
	p.members[next].Role = RoleLeader
	p.leader = next
	return next, nil
}

// nextOnlineLocked 按加入顺序找第一个在线的非队长成员。顺序稳定是关键：
// 队友看到的新队长是可预期的，而不是 map 迭代的随机结果。
func (p *Party) nextOnlineLocked() (PlayerID, bool) {
	for _, id := range p.order {
		if id == p.leader {
			continue
		}
		if m, ok := p.members[id]; ok && m.Online {
			return id, true
		}
	}
	return 0, false
}

func (p *Party) anyOnlineLocked() bool {
	for _, m := range p.members {
		if m.Online {
			return true
		}
	}
	return false
}

// ExpireOffline 是宽限期到期后的真正清理：把仍离线的成员从队伍里删掉。
// 宽限期内他们能靠重连票据回来；超时未回，座位才被回收。
func (p *Party) ExpireOffline(now time.Time, offlineSince map[PlayerID]time.Time, grace time.Duration) []PlayerID {
	p.mu.Lock()
	defer p.mu.Unlock()
	var dropped []PlayerID
	for _, id := range append([]PlayerID(nil), p.order...) {
		m, ok := p.members[id]
		if !ok || m.Online {
			continue
		}
		since, seen := offlineSince[id]
		if !seen || now.Sub(since) < grace {
			continue
		}
		if id == p.leader {
			continue // 队长位必须先迁移，不能直接删
		}
		p.removeLocked(id)
		dropped = append(dropped, id)
	}
	return dropped
}

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

// TestDisconnectLeaderMigration 钉死 12.3：队长掉线后队长位立刻给下一位
// 在线成员，且顺序稳定（按加入顺序，不是 map 随机）。
func TestDisconnectLeaderMigration(t *testing.T) {
	l := ids(3) // 100 队长, 101, 102
	p := NewParty(PartyID(5), l[0])
	for _, id := range l[1:] {
		if _, err := p.TryJoin(l[0], id); err != nil {
			t.Fatalf("join: %v", err)
		}
	}
	// 101 先掉线，队长交给 102。
	if r := p.MarkOffline(l[1]); r.LeaderChanged {
		t.Fatalf("non-leader offline should not migrate leader")
	}
	res := p.MarkOffline(l[0])
	if !res.LeaderChanged || res.NewLeader != l[2] {
		t.Fatalf("leader migration: got %+v, want NewLeader=%d", res, l[2])
	}
	// 重连不会把队长还回去。
	if !p.MarkOnline(l[0]) {
		t.Fatalf("reconnect should find the seat")
	}
	if p.Leader() != l[2] {
		t.Fatalf("leader should stay %d after reconnect, got %d", l[2], p.Leader())
	}
}