《游戏服务端架构·规模化、全球化与成本》7.3 合服、迁移与玩家可见性

T-14d  公告、预发改名卡、关闭合服服的角色创建
T-1d   关闭跨服报名、拍卖行挂单、公会创建
T0     停服，源服切只读，目标服停止写入
T0+5m  全量快照，记录源服角色数、资产总额、邮件数
T0+10m 分批迁移，每批示例 5000 个角色
T0+40m 校验：数量、ID 映射、资产总额、抽样登录
T0+50m 开服，目标服接受写入
T0+72h 回滚窗口关闭，源服快照转为归档

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

import (
	"errors"
	"fmt"
	"sort"
	"strconv"
	"strings"
	"time"
)

var (
	ErrInvalidPlan = errors.New("mergemigration: invalid plan")
	ErrIncomplete  = errors.New("mergemigration: plan not fully applied")
)

// Subject 是源服一个角色的迁移输入。LocalID 只在源服内唯一，
// 合服后必须换成目标服的新 ID。
type Subject struct {
	LocalID   int64
	Name      string
	GuildName string
	RankScore int64
	Mails     int
}

// Mapping 是一个角色的新旧 ID 与最终名字。Renamed 为 true 时，
// 玩家会收到一张改名卡，而不是被静默改名。
type Mapping struct {
	OldID   int64
	NewID   int64
	Name    string
	Renamed bool
	Reason  string
}

// GuildRename 是按公会聚合的改名结果；同名公会的所有成员共用一条记录。
type GuildRename struct {
	Old     string
	New     string
	Renamed bool
}

// Plan 是一次合服的完整映射。Commit 之前源服仍是权威，
// Committed 为 true 表示已经越过分批迁移的切换点。
type Plan struct {
	Source    string
	Target    string
	Mappings  []Mapping
	Guilds    []GuildRename
	MailTotal int
	RankReset bool
	Committed bool
	CreatedAt time.Time
}

// BuildPlan 按 LocalID 升序生成新 ID，并处理玩家名与公会名冲突。
// targetPlayers 与 targetGuilds 是目标服已经占用的名字，比较不区分大小写。
func BuildPlan(source, target string, subjects []Subject, targetPlayers, targetGuilds []string, startID int64, now time.Time) (*Plan, error) {
	switch {
	case source == "" || target == "":
		return nil, fmt.Errorf("%w: empty source or target", ErrInvalidPlan)
	case source == target:
		return nil, fmt.Errorf("%w: source equals target", ErrInvalidPlan)
	case startID <= 0:
		return nil, fmt.Errorf("%w: start id must be positive", ErrInvalidPlan)
	case len(subjects) == 0:
		return nil, fmt.Errorf("%w: no subjects", ErrInvalidPlan)
	}

	seenID := make(map[int64]bool, len(subjects))
	for _, s := range subjects {
		if seenID[s.LocalID] {
			return nil, fmt.Errorf("%w: duplicate local id %d", ErrInvalidPlan, s.LocalID)
		}
		seenID[s.LocalID] = true
	}

	ordered := append([]Subject(nil), subjects...)
	sort.Slice(ordered, func(i, j int) bool { return ordered[i].LocalID < ordered[j].LocalID })

	usedPlayer := make(map[string]bool, len(targetPlayers)+len(ordered))
	for _, name := range targetPlayers {
		usedPlayer[strings.ToLower(name)] = true
	}
	mailTotal := 0
	mappings := make([]Mapping, 0, len(ordered))
	for i, s := range ordered {
		name := strings.TrimSpace(s.Name)
		if name == "" {
			return nil, fmt.Errorf("%w: empty name for local id %d", ErrInvalidPlan, s.LocalID)
		}
		m := Mapping{OldID: s.LocalID, NewID: startID + int64(i), Name: name}
		if usedPlayer[strings.ToLower(name)] {
			m.Name = uniqueName(name, s.LocalID, usedPlayer)
			m.Renamed = true
			m.Reason = "name_conflict"
		}
		usedPlayer[strings.ToLower(m.Name)] = true
		mailTotal += s.Mails
		mappings = append(mappings, m)
	}

	guilds, err := buildGuilds(ordered, targetGuilds, source)
	if err != nil {
		return nil, err
	}

	return &Plan{
		Source:    source,
		Target:    target,
		Mappings:  mappings,
		Guilds:    guilds,
		MailTotal: mailTotal,
		RankReset: true,
		CreatedAt: now,
	}, nil
}

func uniqueName(base string, oldID int64, used map[string]bool) string {
	candidate := base + "-" + strconv.FormatInt(oldID, 10)
	for i := 2; used[strings.ToLower(candidate)]; i++ {
		candidate = base + "-" + strconv.FormatInt(oldID, 10) + "-" + strconv.Itoa(i)
	}
	return candidate
}

func buildGuilds(subjects []Subject, targetGuilds []string, source string) ([]GuildRename, error) {
	used := make(map[string]bool, len(targetGuilds))
	for _, name := range targetGuilds {
		used[strings.ToLower(name)] = true
	}
	names := make([]string, 0, len(subjects))
	seen := make(map[string]bool, len(subjects))
	for _, s := range subjects {
		name := strings.TrimSpace(s.GuildName)
		if name == "" {
			continue
		}
		key := strings.ToLower(name)
		if seen[key] {
			continue
		}
		seen[key] = true
		names = append(names, name)
	}
	sort.Strings(names)

	var out []GuildRename
	for _, name := range names {
		g := GuildRename{Old: name, New: name}
		if used[strings.ToLower(name)] {
			g.New = uniqueGuild(name, source, used)
			g.Renamed = true
		}
		used[strings.ToLower(g.New)] = true
		out = append(out, g)
	}
	return out, nil
}

func uniqueGuild(base, source string, used map[string]bool) string {
	candidate := base + "-" + source
	for i := 2; used[strings.ToLower(candidate)]; i++ {
		candidate = base + "-" + source + "-" + strconv.Itoa(i)
	}
	return candidate
}

// Commit 只在全部映射都应用后允许提交；否则源服继续保持权威。
func (p *Plan) Commit(applied int) error {
	if applied != len(p.Mappings) {
		return fmt.Errorf("%w: %d/%d mappings applied", ErrIncomplete, applied, len(p.Mappings))
	}
	p.Committed = true
	return nil
}

cd .local/checks/gsarch-lab
gofmt -l internal/mergemigration
go vet ./internal/mergemigration/
go test -count=1 ./internal/mergemigration/
ok  	gsarchlab/internal/mergemigration