《游戏服务端架构·核心系统与契约》4.2 分线、副本与主城/野外

一线（源）                          二线（目标）
   │ 1. BeginTransfer：冻结玩家       │
   │ 2. 生成 token + seq + epoch      │
   │──────────── handoff ────────────>│
   │                                  │ 3. 校验 token 与 epoch
   │                                  │ 4. 写入目标线，返回 ack
   │<──────────── ack ────────────────│
   │ 5. 删除源线副本，解冻             │
   │ 6. 客户端重新拉取视野             │

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

import (
	"errors"
	"fmt"
)

var (
	ErrBadCapacity       = errors.New("worldline: capacity must be positive")
	ErrNoLines           = errors.New("worldline: at least one line is required")
	ErrEmptyLine         = errors.New("worldline: empty line id")
	ErrDuplicateLine     = errors.New("worldline: duplicate line id")
	ErrUnknownLine       = errors.New("worldline: unknown line")
	ErrEmptyPlayer       = errors.New("worldline: empty player id")
	ErrUnknownPlayer     = errors.New("worldline: unknown player")
	ErrWorldFull         = errors.New("worldline: every line is at capacity")
	ErrLineFull          = errors.New("worldline: target line is at capacity")
	ErrSameLine          = errors.New("worldline: source and target are the same line")
	ErrTransferPending   = errors.New("worldline: transfer already pending")
	ErrNoTransfer        = errors.New("worldline: no pending transfer")
	ErrTokenMismatch     = errors.New("worldline: handoff token does not match")
	ErrFrozen            = errors.New("worldline: player is frozen during transfer")
	ErrWrongLine         = errors.New("worldline: write delivered to a non-owning line")
	ErrStaleEpoch        = errors.New("worldline: target line epoch changed")
	ErrDuplicateTransfer = errors.New("worldline: transfer already completed")
	ErrLineNotEmpty      = errors.New("worldline: line still has players")
)

// Line is one copy of the same scene. Epoch changes when the line is reset, so
// a handoff prepared against the old incarnation cannot commit.
type Line struct {
	ID       string
	Epoch    uint64
	Capacity int
	members  map[string]struct{}
}

func (l *Line) Load() int { return len(l.members) }

func (l *Line) Has(player string) bool {
	_, ok := l.members[player]
	return ok
}

// Handoff binds one player move to a sequence number and a target epoch.
type Handoff struct {
	Player string
	From   string
	To     string
	Token  string
	Seq    uint64
	Epoch  uint64
}

// World owns line membership. A player has one home line, and that line is
// frozen for the player between BeginTransfer and Complete or Abort.
type World struct {
	capacity int
	lines    map[string]*Line
	order    []string
	home     map[string]string
	pending  map[string]Handoff
	done     map[string]bool
	seq      uint64
}

// NewWorld keeps the given order as the least-loaded tie-breaker.
func NewWorld(capacity int, lineIDs ...string) (*World, error) {
	if capacity <= 0 {
		return nil, ErrBadCapacity
	}
	if len(lineIDs) == 0 {
		return nil, ErrNoLines
	}
	w := &World{
		capacity: capacity,
		lines:    make(map[string]*Line, len(lineIDs)),
		home:     make(map[string]string),
		pending:  make(map[string]Handoff),
		done:     make(map[string]bool),
	}
	for _, id := range lineIDs {
		if id == "" {
			return nil, ErrEmptyLine
		}
		if _, ok := w.lines[id]; ok {
			return nil, fmt.Errorf("%w: %s", ErrDuplicateLine, id)
		}
		w.lines[id] = &Line{ID: id, Epoch: 1, Capacity: capacity, members: make(map[string]struct{})}
		w.order = append(w.order, id)
	}
	return w, nil
}

// Assign is idempotent for a player that already has a home.
func (w *World) Assign(player string) (string, error) {
	if player == "" {
		return "", ErrEmptyPlayer
	}
	if line, ok := w.home[player]; ok {
		return line, nil
	}
	best := ""
	for _, id := range w.order {
		line := w.lines[id]
		if line.Load() >= line.Capacity {
			continue
		}
		if best == "" || line.Load() < w.lines[best].Load() {
			best = id
		}
	}
	if best == "" {
		return "", ErrWorldFull
	}
	w.lines[best].members[player] = struct{}{}
	w.home[player] = best
	return best, nil
}

func (w *World) Locate(player string) (string, bool) {
	line, ok := w.home[player]
	return line, ok
}

func (w *World) Load(line string) (int, error) {
	l, ok := w.lines[line]
	if !ok {
		return 0, fmt.Errorf("%w: %s", ErrUnknownLine, line)
	}
	return l.Load(), nil
}

// BeginTransfer freezes the player but does not move ownership yet, so a
// crash leaves exactly one owner: the source.
func (w *World) BeginTransfer(player, to string) (Handoff, error) {
	from, ok := w.home[player]
	if !ok {
		return Handoff{}, fmt.Errorf("%w: %s", ErrUnknownPlayer, player)
	}
	if _, ok := w.pending[player]; ok {
		return Handoff{}, fmt.Errorf("%w: %s", ErrTransferPending, player)
	}
	if from == to {
		return Handoff{}, ErrSameLine
	}
	target, ok := w.lines[to]
	if !ok {
		return Handoff{}, fmt.Errorf("%w: %s", ErrUnknownLine, to)
	}
	if target.Load() >= target.Capacity {
		return Handoff{}, fmt.Errorf("%w: %s", ErrLineFull, to)
	}
	w.seq++
	h := Handoff{
		Player: player,
		From:   from,
		To:     to,
		Token:  fmt.Sprintf("%s:%s:%d", player, to, w.seq),
		Seq:    w.seq,
		Epoch:  target.Epoch,
	}
	w.pending[player] = h
	return h, nil
}

// Write is the guard every line calls before applying a command. It rejects a
// frozen player even on the owning line, closing the migration window.
func (w *World) Write(player, line string) error {
	home, ok := w.home[player]
	if !ok {
		return fmt.Errorf("%w: %s", ErrUnknownPlayer, player)
	}
	if _, frozen := w.pending[player]; frozen {
		return fmt.Errorf("%w: %s", ErrFrozen, player)
	}
	if home != line {
		return fmt.Errorf("%w: %s owns %s, not %s", ErrWrongLine, home, player, line)
	}
	return nil
}

// Complete commits a handoff. A repeated token is rejected, not applied twice.
func (w *World) Complete(h Handoff) error {
	pending, ok := w.pending[h.Player]
	if !ok {
		if w.done[h.Token] {
			return fmt.Errorf("%w: %s", ErrDuplicateTransfer, h.Token)
		}
		return fmt.Errorf("%w: %s", ErrNoTransfer, h.Player)
	}
	if pending.Token != h.Token {
		return fmt.Errorf("%w: got %q want %q", ErrTokenMismatch, h.Token, pending.Token)
	}
	target, ok := w.lines[h.To]
	if !ok {
		return fmt.Errorf("%w: %s", ErrUnknownLine, h.To)
	}
	if target.Epoch != h.Epoch {
		return fmt.Errorf("%w: got %d want %d", ErrStaleEpoch, h.Epoch, target.Epoch)
	}
	if target.Load() >= target.Capacity {
		return fmt.Errorf("%w: %s", ErrLineFull, h.To)
	}
	if source, ok := w.lines[h.From]; ok {
		delete(source.members, h.Player)
	}
	target.members[h.Player] = struct{}{}
	w.home[h.Player] = h.To
	delete(w.pending, h.Player)
	w.done[h.Token] = true
	return nil
}

// Abort releases the freeze without moving ownership.
func (w *World) Abort(h Handoff) error {
	pending, ok := w.pending[h.Player]
	if !ok {
		return fmt.Errorf("%w: %s", ErrNoTransfer, h.Player)
	}
	if pending.Token != h.Token {
		return fmt.Errorf("%w: got %q want %q", ErrTokenMismatch, h.Token, pending.Token)
	}
	delete(w.pending, h.Player)
	return nil
}

// ResetLine advances a drained line's epoch, invalidating old handoffs.
func (w *World) ResetLine(line string) (uint64, error) {
	l, ok := w.lines[line]
	if !ok {
		return 0, fmt.Errorf("%w: %s", ErrUnknownLine, line)
	}
	if l.Load() != 0 {
		return 0, fmt.Errorf("%w: %s has %d players", ErrLineNotEmpty, line, l.Load())
	}
	l.Epoch++
	return l.Epoch, nil
}

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