《游戏服务端架构·品类、状态与拓扑》8.2 分区分服、跨服与合服

shard_id=1001  display_name="S1 晨曦"    status=active
shard_id=1002  display_name="S2 远航"    status=merged_into:1001
shard_id=1003  display_name="S3 群岛"    status=merged_into:1001

目标服已有玩家: 1..999,999
源服 S2 块:     1,000,000..1,099,999
源服 S3 块:     1,100,000..1,199,999
源服 S4 块:     1,200,000..1,299,999

// file: internal/merge/merge.go
// tier: L1
// verify: go test ./internal/merge/
package merge

import (
	"errors"
	"sort"
)

var (
	ErrBadTarget      = errors.New("merge: empty target or zero base")
	ErrNoSources      = errors.New("merge: no source shards")
	ErrDuplicateShard = errors.New("merge: duplicate source shard")
	ErrDuplicateOldID = errors.New("merge: duplicate id inside a shard")
	ErrZeroID         = errors.New("merge: id zero is reserved")
	ErrEmptyName      = errors.New("merge: empty display name")
	ErrMissingLeader  = errors.New("merge: guild leader is not a player of the shard")
	ErrMissingBlock   = errors.New("merge: source shard has no id block")
	ErrMissingMapping = errors.New("merge: source id has no mapping")
	ErrDuplicateDest  = errors.New("merge: duplicate destination id")
	ErrBlockMismatch  = errors.New("merge: destination id falls outside its block")
	ErrBlockOverlap   = errors.New("merge: id blocks overlap")
	ErrNameConflict   = errors.New("merge: destination name is not unique")
)

// Ref identifies an old row before the merge. IDs collide across shards, so a
// bare uint64 is never a safe key.
type Ref struct {
	Shard string
	ID    uint64
}

type Player struct {
	ID   uint64
	Name string
}

type Guild struct {
	ID     uint64
	Name   string
	Leader uint64
}

type Input struct {
	Shard   string
	Players []Player
	Guilds  []Guild
}

// Block is a half-open [Start, Start+Count) allocation for one source shard.
type Block struct {
	Start uint64
	Count uint64
}

func (b Block) Contains(id uint64) bool { return id >= b.Start && id < b.Start+b.Count }

type Conflict struct {
	Kind string
	Name string
	Refs []Ref
}

type Plan struct {
	Target        string
	PlayerBlocks  map[string]Block
	GuildBlocks   map[string]Block
	Players       map[Ref]uint64
	Guilds        map[Ref]uint64
	Leaders       map[Ref]uint64
	PlayerRenames map[Ref]string
	GuildRenames  map[Ref]string
	Conflicts     []Conflict
}

func sortedInputs(inputs []Input) []Input {
	out := append([]Input(nil), inputs...)
	sort.Slice(out, func(i, j int) bool { return out[i].Shard < out[j].Shard })
	return out
}

func sortRefs(refs []Ref) {
	sort.Slice(refs, func(i, j int) bool {
		if refs[i].Shard != refs[j].Shard {
			return refs[i].Shard < refs[j].Shard
		}
		return refs[i].ID < refs[j].ID
	})
}

// BuildPlan gives every source shard a disjoint block, remaps players, guilds
// and guild leaders, and resolves duplicate display names deterministically.
func BuildPlan(target string, base uint64, inputs []Input) (Plan, error) {
	if target == "" || base == 0 {
		return Plan{}, ErrBadTarget
	}
	if len(inputs) == 0 {
		return Plan{}, ErrNoSources
	}
	in := sortedInputs(inputs)
	if err := validateInputs(in); err != nil {
		return Plan{}, err
	}

	p := Plan{
		Target: target, PlayerBlocks: map[string]Block{}, GuildBlocks: map[string]Block{},
		Players: map[Ref]uint64{}, Guilds: map[Ref]uint64{}, Leaders: map[Ref]uint64{},
		PlayerRenames: map[Ref]string{}, GuildRenames: map[Ref]string{},
	}
	cursor := base
	for _, src := range in {
		ps := append([]Player(nil), src.Players...)
		sort.Slice(ps, func(i, j int) bool { return ps[i].ID < ps[j].ID })
		p.PlayerBlocks[src.Shard] = Block{Start: cursor, Count: uint64(len(ps))}
		for i, pl := range ps {
			p.Players[Ref{src.Shard, pl.ID}] = cursor + uint64(i)
		}
		cursor += uint64(len(ps))
	}
	for _, src := range in {
		gs := append([]Guild(nil), src.Guilds...)
		sort.Slice(gs, func(i, j int) bool { return gs[i].ID < gs[j].ID })
		p.GuildBlocks[src.Shard] = Block{Start: cursor, Count: uint64(len(gs))}
		for i, g := range gs {
			ref := Ref{src.Shard, g.ID}
			p.Guilds[ref] = cursor + uint64(i)
			p.Leaders[ref] = p.Players[Ref{src.Shard, g.Leader}]
		}
		cursor += uint64(len(gs))
	}

	playerNames := map[string][]Ref{}
	guildNames := map[string][]Ref{}
	takenPlayers := map[string]bool{}
	takenGuilds := map[string]bool{}
	for _, src := range in {
		for _, pl := range src.Players {
			ref := Ref{src.Shard, pl.ID}
			playerNames[pl.Name] = append(playerNames[pl.Name], ref)
			takenPlayers[pl.Name] = true
		}
		for _, g := range src.Guilds {
			ref := Ref{src.Shard, g.ID}
			guildNames[g.Name] = append(guildNames[g.Name], ref)
			takenGuilds[g.Name] = true
		}
	}
	p.Conflicts = resolve("player_name", playerNames, p.PlayerRenames, takenPlayers)
	p.Conflicts = append(p.Conflicts, resolve("guild_name", guildNames, p.GuildRenames, takenGuilds)...)
	sort.Slice(p.Conflicts, func(i, j int) bool {
		if p.Conflicts[i].Kind != p.Conflicts[j].Kind {
			return p.Conflicts[i].Kind < p.Conflicts[j].Kind
		}
		return p.Conflicts[i].Name < p.Conflicts[j].Name
	})
	if err := p.Validate(inputs); err != nil {
		return Plan{}, err
	}
	return p, nil
}

merge_batch_id | source_shard | old_id | new_id | kind   | created_at
2026-10-S1S4   | S2           | 1      | 1000000| player | 2026-10-23
2026-10-S1S4   | S2           | 10     | 1000500| guild  | 2026-10-23

$ cd .local/checks/gsarch-lab
$ gofmt -l internal/merge
$ go test -count=1 ./internal/merge/
ok  	gsarchlab/internal/merge	0.482s