《游戏服务端架构·规模化、全球化与成本》12.2 《群岛纪元》的全球同服

active members by zone (14d)
  eu: 40   ap: 25   na: 15
        │
        ▼
preferred zone = eu
        │
        ├─ claim neutral sectors in eu, value desc, capped per tick
        └─ alliance roster stays a global aggregate, read-only copies elsewhere

freeze shard
  ├─ reject writes, keep reads
  ├─ copy durable state to target zone
  ├─ switch ownership record
  ├─ invalidate caches and rebuild read replicas
  └─ unfreeze, resume writes in target zone

// file: internal/archglobal/world.go
// tier: L1
// verify: go test ./internal/archglobal/
// Package archglobal models the world layout of Archipelago Era: map sectors
// are partitioned into shards, a shard never crosses a data zone, alliances
// claim sectors near their active members, and war windows gate state moves.
package archglobal

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

var ErrBadInput = errors.New("archglobal: invalid input")

// Zone is a data zone. It is the unit of residency and the unit that owns a
// shard; it is deliberately coarser than a single datacenter.
type Zone string

// Sector is one block of the world map. Home is the zone that stores the
// durable state for the sector; Owner is the alliance that controls it.
type Sector struct {
	ID    string
	Ring  int // distance from the world center, used for contiguous shards
	Home  Zone
	Owner string // alliance ID; empty means neutral
	Value int    // war score weight, never negative
}

// Shard is a contiguous ring range inside one zone.
type Shard struct {
	ID       string
	Zone     Zone
	RingFrom int
	RingTo   int
	Sectors  []string
}

// Plan partitions every sector into contiguous shards inside its home zone.
// A zone with fewer sectors than requested shards yields one shard per sector
// rather than an empty shard, because an empty shard still costs a process.
func Plan(sectors []Sector, shardsPerZone int) ([]Shard, error) {
	if shardsPerZone <= 0 {
		return nil, fmt.Errorf("%w: shards per zone must be positive", ErrBadInput)
	}
	if len(sectors) == 0 {
		return nil, fmt.Errorf("%w: no sectors", ErrBadInput)
	}
	seen := map[string]bool{}
	byZone := map[Zone][]Sector{}
	for _, s := range sectors {
		if s.ID == "" || s.Home == "" {
			return nil, fmt.Errorf("%w: sector id and home zone are required", ErrBadInput)
		}
		if s.Ring < 0 || s.Value < 0 {
			return nil, fmt.Errorf("%w: sector %s has negative ring or value", ErrBadInput, s.ID)
		}
		if seen[s.ID] {
			return nil, fmt.Errorf("%w: duplicate sector %s", ErrBadInput, s.ID)
		}
		seen[s.ID] = true
		byZone[s.Home] = append(byZone[s.Home], s)
	}
	zones := make([]Zone, 0, len(byZone))
	for z := range byZone {
		zones = append(zones, z)
	}
	sort.Slice(zones, func(i, j int) bool { return zones[i] < zones[j] })
	out := make([]Shard, 0, len(zones)*shardsPerZone)
	for _, z := range zones {
		group := byZone[z]
		sort.Slice(group, func(i, j int) bool {
			if group[i].Ring != group[j].Ring {
				return group[i].Ring < group[j].Ring
			}
			return group[i].ID < group[j].ID
		})
		n := shardsPerZone
		if n > len(group) {
			n = len(group)
		}
		base, extra := len(group)/n, len(group)%n
		offset := 0
		for i := 0; i < n; i++ {
			size := base
			if i < extra {
				size++
			}
			part := group[offset : offset+size]
			ids := make([]string, 0, size)
			for _, s := range part {
				ids = append(ids, s.ID)
			}
			out = append(out, Shard{
				ID:       fmt.Sprintf("%s-%02d", z, i+1),
				Zone:     z,
				RingFrom: part[0].Ring,
				RingTo:   part[len(part)-1].Ring,
				Sectors:  ids,
			})
			offset += size
		}
	}
	sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID })
	return out, nil
}

// Member is one alliance member. LastActive is the last login or march order.
type Member struct {
	ID         string
	Zone       Zone
	LastActive time.Time
}

// Alliance is a cross-timezone group of players.
type Alliance struct {
	ID      string
	Members []Member
}

// PreferredZone returns the zone with the most recently active members. It is
// a load-balancing hint for claims, not a residency rule: the alliance still
// spans every zone its members live in.
func PreferredZone(a Alliance, now time.Time, activeWithin time.Duration) (Zone, error) {
	if a.ID == "" {
		return "", fmt.Errorf("%w: alliance id is empty", ErrBadInput)
	}
	if activeWithin <= 0 {
		return "", fmt.Errorf("%w: active window must be positive", ErrBadInput)
	}
	counts := map[Zone]int{}
	for _, m := range a.Members {
		if m.Zone == "" {
			return "", fmt.Errorf("%w: member %s has no zone", ErrBadInput, m.ID)
		}
		if now.Sub(m.LastActive) > activeWithin {
			continue
		}
		counts[m.Zone]++
	}
	var bestZone Zone
	best := 0
	for z, n := range counts {
		if n > best || (n == best && (bestZone == "" || z < bestZone)) {
			bestZone, best = z, n
		}
	}
	if best == 0 {
		return "", fmt.Errorf("%w: alliance %s has no active member", ErrBadInput, a.ID)
	}
	return bestZone, nil
}

// Claim returns neutral sectors in the preferred zone, highest value first.
// Limit is a hard cap: an alliance cannot absorb the whole map in one tick.
func Claim(world []Sector, a Alliance, now time.Time, activeWithin time.Duration, limit int) ([]string, error) {
	if limit <= 0 {
		return nil, fmt.Errorf("%w: claim limit must be positive", ErrBadInput)
	}
	zone, err := PreferredZone(a, now, activeWithin)
	if err != nil {
		return nil, err
	}
	candidates := make([]Sector, 0, len(world))
	for _, s := range world {
		if s.Home == zone && s.Owner == "" {
			candidates = append(candidates, s)
		}
	}
	sort.Slice(candidates, func(i, j int) bool {
		if candidates[i].Value != candidates[j].Value {
			return candidates[i].Value > candidates[j].Value
		}
		return candidates[i].ID < candidates[j].ID
	})
	out := make([]string, 0, limit)
	for i := 0; i < len(candidates) && i < limit; i++ {
		out = append(out, candidates[i].ID)
	}
	return out, nil
}