《游戏服务端架构·规模化、全球化与成本》7.1 跨服匹配与报名

             Lock()                Consume()
  issued ------------> locked ------------> consumed
    |                    |
    | Cancel()/          | Cancel()/
    | Expire()/          | FailAllocate()
    | FailAllocate()     |
    v                    v
  voided <--------------+

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

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

// State 是报名票据的状态。票据只能沿 Issued -> Locked -> Consumed 前进，
// 任何未消费的票据都可以作废并释放冻结资产。
type State string

const (
	Issued   State = "issued"
	Locked   State = "locked"
	Consumed State = "consumed"
	Voided   State = "voided"
)

var (
	ErrDuplicateSignup   = errors.New("crossmatch: player already has an active ticket")
	ErrTicketNotFound    = errors.New("crossmatch: ticket not found")
	ErrInvalidTransition = errors.New("crossmatch: invalid state transition")
	ErrInvalidSignup     = errors.New("crossmatch: invalid signup")
)

// Ticket 是玩家带进跨服实例的凭据。Frozen 表示主服已冻结的资产数量，
// 跨服侧只看到副本，不能直接改写主服账本。
type Ticket struct {
	ID        string
	PlayerID  string
	HomeServ  string
	ZoneID    string
	Mode      string
	State     State
	Frozen    int64
	IssuedAt  time.Time
	ExpiresAt time.Time
}

// Compensation 记录一次因作废而需要退回主服的冻结资产。
type Compensation struct {
	TicketID string
	PlayerID string
	Amount   int64
	Reason   string
}

// SignupRequest 是报名入口的完整输入。TTL 由活动配置给出，不接受客户端指定。
type SignupRequest struct {
	PlayerID string
	HomeServ string
	ZoneID   string
	Mode     string
	Frozen   int64
	TTL      time.Duration
}

// Registry 是单进程内的报名簿；生产环境换成带唯一约束的存储，判据不变。
type Registry struct {
	tickets map[string]*Ticket
	active  map[string]string
	seq     int
	now     func() time.Time
}

// NewRegistry 注入时钟，便于测试过期与作废。
func NewRegistry(now func() time.Time) *Registry {
	if now == nil {
		now = time.Now
	}
	return &Registry{
		tickets: make(map[string]*Ticket),
		active:  make(map[string]string),
		now:     now,
	}
}

// Signup 校验后签发票据并冻结资产；同一 player+mode 只允许一张有效票据。
func (r *Registry) Signup(req SignupRequest) (*Ticket, error) {
	switch {
	case req.PlayerID == "" || req.HomeServ == "" || req.ZoneID == "" || req.Mode == "":
		return nil, fmt.Errorf("%w: missing required field", ErrInvalidSignup)
	case req.Frozen < 0:
		return nil, fmt.Errorf("%w: negative frozen amount", ErrInvalidSignup)
	case req.TTL <= 0:
		return nil, fmt.Errorf("%w: ttl must be positive", ErrInvalidSignup)
	}
	key := req.PlayerID + "|" + req.Mode
	if _, ok := r.active[key]; ok {
		return nil, ErrDuplicateSignup
	}
	now := r.now()
	r.seq++
	t := &Ticket{
		ID:        fmt.Sprintf("t-%04d", r.seq),
		PlayerID:  req.PlayerID,
		HomeServ:  req.HomeServ,
		ZoneID:    req.ZoneID,
		Mode:      req.Mode,
		State:     Issued,
		Frozen:    req.Frozen,
		IssuedAt:  now,
		ExpiresAt: now.Add(req.TTL),
	}
	r.tickets[t.ID] = t
	r.active[key] = t.ID
	return t, nil
}

// transition 是唯一的状态修改入口，避免业务代码绕过状态机。
func (r *Registry) transition(t *Ticket, to State) error {
	if !CanTransition(t.State, to) {
		return fmt.Errorf("%w: %s -> %s", ErrInvalidTransition, t.State, to)
	}
	t.State = to
	return nil
}

// Lock 在匹配成功、实例已分配后调用；票据仍可因进场失败而作废。
func (r *Registry) Lock(ticketID string) error {
	t, ok := r.tickets[ticketID]
	if !ok {
		return ErrTicketNotFound
	}
	return r.transition(t, Locked)
}

// Consume 在玩家成功进入跨服实例后调用，冻结资产转为跨服副本。
func (r *Registry) Consume(ticketID string) error {
	t, ok := r.tickets[ticketID]
	if !ok {
		return ErrTicketNotFound
	}
	if err := r.transition(t, Consumed); err != nil {
		return err
	}
	delete(r.active, t.PlayerID+"|"+t.Mode)
	return nil
}

// Cancel 处理玩家主动取消；未消费票据作废并生成资产退回记录。
func (r *Registry) Cancel(ticketID, reason string) (Compensation, error) {
	return r.void(ticketID, reason)
}

// FailAllocate 处理实例扩容失败：票据作废，冻结资产原路退回。
func (r *Registry) FailAllocate(ticketID string) (Compensation, error) {
	return r.void(ticketID, "allocate_failed")
}

func (r *Registry) void(ticketID, reason string) (Compensation, error) {
	t, ok := r.tickets[ticketID]
	if !ok {
		return Compensation{}, ErrTicketNotFound
	}
	if err := r.transition(t, Voided); err != nil {
		return Compensation{}, err
	}
	delete(r.active, t.PlayerID+"|"+t.Mode)
	return Compensation{TicketID: t.ID, PlayerID: t.PlayerID, Amount: t.Frozen, Reason: reason}, nil
}

// SweepExpired 作废所有到期未消费票据，按票据 ID 排序返回退回记录。
// 生产环境由定时任务驱动，重跑时已作废票据不会重复退回。
func (r *Registry) SweepExpired() []Compensation {
	now := r.now()
	var expired []*Ticket
	for _, t := range r.tickets {
		if t.State != Issued && t.State != Locked {
			continue
		}
		if !now.Before(t.ExpiresAt) {
			expired = append(expired, t)
		}
	}
	sort.Slice(expired, func(i, j int) bool { return expired[i].ID < expired[j].ID })
	out := make([]Compensation, 0, len(expired))
	for _, t := range expired {
		c, err := r.void(t.ID, "expired")
		if err == nil {
			out = append(out, c)
		}
	}
	return out
}

// CanTransition 是票据状态机的唯一真值表；消费与作废都是终态。
func CanTransition(from, to State) bool {
	switch from {
	case Issued:
		return to == Locked || to == Voided
	case Locked:
		return to == Consumed || to == Voided
	default:
		return false
	}
}

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