《游戏服务端编程实践》4.1.2 多角色与跨区机制

客户端 -> 登录服：渠道凭证 / 密码 / 短信码
登录服 -> 账号中心：校验凭证
账号中心 -> 登录服：account_id + 账号状态
登录服 -> 客户端：account_token（短有效期）

// file: ch04/identity/roster.go
// tier: L1
// verify: go test ./ch04/identity/

package identity

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

type RegionID string
type ShardID string

// NameScope decides where a character name must be unique.
type NameScope int

const (
	NamePerRegion NameScope = iota
	NamePerTenant
)

// Region is a public zone. Shard is where the zone currently runs; several
// regions may share one shard, so neither value can replace the other.
type Region struct {
	ID        RegionID
	Shard     ShardID
	NameScope NameScope
}

type Character struct {
	PlayerRef
	Level     int
	UpdatedAt time.Time
}

// Selection is the region-scoped session obtained after choosing a character.
type Selection struct {
	AccountID AccountID
	PlayerID  PlayerID
	Region    RegionID
	Shard     ShardID
	Epoch     uint64
}

var (
	ErrRegionNotFound = errors.New("identity: region not found")
	ErrCharacterLimit = errors.New("identity: character limit reached")
	ErrNameInvalid    = errors.New("identity: character name is empty")
	ErrNameTaken      = errors.New("identity: character name already taken")
	ErrNotOwner       = errors.New("identity: character belongs to another account")
	ErrWrongRegion    = errors.New("identity: character is not in this region")
	ErrStaleSession   = errors.New("identity: selection session is stale")
)

// Roster keeps the account-to-character relationship. Character data stays
// with the region; this service only owns the roster projection.
type Roster struct {
	maxPerAccount int
	regions       map[RegionID]Region
	characters    map[PlayerID]*Character
	byAccount     map[AccountID][]PlayerID
	names         map[string]PlayerID
	sessions      map[AccountID]Selection
	nextPlayer    PlayerID
	epoch         uint64
}

func NewRoster(maxPerAccount int) *Roster {
	if maxPerAccount <= 0 {
		maxPerAccount = 4
	}
	return &Roster{
		maxPerAccount: maxPerAccount,
		regions:       make(map[RegionID]Region),
		characters:    make(map[PlayerID]*Character),
		byAccount:     make(map[AccountID][]PlayerID),
		names:         make(map[string]PlayerID),
		sessions:      make(map[AccountID]Selection),
	}
}

// AddRegion registers a public region and its current placement.
func (r *Roster) AddRegion(region Region) {
	r.regions[region.ID] = region
}

func (r *Roster) nameKey(region Region, tenant TenantID, name string) string {
	normalized := strings.ToLower(strings.TrimSpace(name))
	if region.NameScope == NamePerTenant {
		return string(tenant) + "|tenant|" + normalized
	}
	return string(tenant) + "|region|" + string(region.ID) + "|" + normalized
}

// Create adds a character in one region. A character belongs to exactly one
// region at a time.
func (r *Roster) Create(accountID AccountID, tenant TenantID, regionID RegionID, name string, now time.Time) (Character, error) {
	region, ok := r.regions[regionID]
	if !ok {
		return Character{}, ErrRegionNotFound
	}
	if strings.TrimSpace(name) == "" {
		return Character{}, ErrNameInvalid
	}
	if len(r.byAccount[accountID]) >= r.maxPerAccount {
		return Character{}, ErrCharacterLimit
	}
	key := r.nameKey(region, tenant, name)
	if _, exists := r.names[key]; exists {
		return Character{}, ErrNameTaken
	}

	r.nextPlayer++
	ch := &Character{
		PlayerRef: PlayerRef{
			ID:        r.nextPlayer,
			AccountID: accountID,
			Tenant:    tenant,
			Region:    string(regionID),
			Name:      strings.TrimSpace(name),
		},
		Level:     1,
		UpdatedAt: now.UTC(),
	}
	r.characters[ch.ID] = ch
	r.byAccount[accountID] = append(r.byAccount[accountID], ch.ID)
	r.names[key] = ch.ID
	return *ch, nil
}

// List returns the account's characters in stable player-ID order.
func (r *Roster) List(accountID AccountID) []Character {
	ids := append([]PlayerID(nil), r.byAccount[accountID]...)
	sort.Slice(ids, func(i, j int) bool { return ids[i] < ids[j] })

	out := make([]Character, 0, len(ids))
	for _, id := range ids {
		if ch, ok := r.characters[id]; ok {
			out = append(out, *ch)
		}
	}
	return out
}

// Select exchanges one character for a region-scoped session. Selecting the
// same account again invalidates the previous selection.
func (r *Roster) Select(accountID AccountID, playerID PlayerID, regionID RegionID) (Selection, error) {
	ch, ok := r.characters[playerID]
	if !ok {
		return Selection{}, ErrNotOwner
	}
	if ch.AccountID != accountID {
		return Selection{}, ErrNotOwner
	}
	if ch.Region != string(regionID) {
		return Selection{}, ErrWrongRegion
	}
	region := r.regions[regionID]
	r.epoch++
	sel := Selection{
		AccountID: accountID,
		PlayerID:  playerID,
		Region:    regionID,
		Shard:     region.Shard,
		Epoch:     r.epoch,
	}
	r.sessions[accountID] = sel
	return sel, nil
}

// Validate checks that a selection still points at the live character and has
// not been invalidated by another selection or a transfer.
func (r *Roster) Validate(sel Selection) error {
	cur, ok := r.sessions[sel.AccountID]
	if !ok || cur.Epoch != sel.Epoch || cur.PlayerID != sel.PlayerID {
		return ErrStaleSession
	}
	ch, ok := r.characters[sel.PlayerID]
	if !ok || ch.Region != string(sel.Region) {
		return ErrStaleSession
	}
	return nil
}

// Transfer moves one character profile to another region. It never moves the
// account's other characters and it invalidates the account's selection.
func (r *Roster) Transfer(accountID AccountID, playerID PlayerID, target RegionID, now time.Time) error {
	ch, ok := r.characters[playerID]
	if !ok {
		return ErrNotOwner
	}
	if ch.AccountID != accountID {
		return ErrNotOwner
	}
	toRegion, ok := r.regions[target]
	if !ok {
		return ErrRegionNotFound
	}
	if ch.Region == string(target) {
		return nil
	}

	fromRegion := r.regions[RegionID(ch.Region)]
	oldKey := r.nameKey(fromRegion, ch.Tenant, ch.Name)
	newKey := r.nameKey(toRegion, ch.Tenant, ch.Name)
	if owner, exists := r.names[newKey]; exists && owner != ch.ID {
		return ErrNameTaken
	}

	delete(r.names, oldKey)
	ch.Region = string(target)
	ch.UpdatedAt = now.UTC()
	r.names[newKey] = ch.ID
	delete(r.sessions, accountID)
	return nil
}