《游戏服务端架构·规模化、全球化与成本》7.2 资产归属与跨服结算

produced --> in_transit --> applied --> reconciled
                  |
                  | 主服不可用/超时
                  v
               queued --> retry --> applied
                  |
                  | 达到重试上限
                  v
               escalated（转人工）

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

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

// Mode 决定跨服结果能写回主服的哪一部分。只读与冻结模式不产生资产转移，
// 带回模式才允许把奖励带回主服，并受上限约束。
type Mode string

const (
	ReadOnly  Mode = "read_only"
	Frozen    Mode = "frozen"
	BringBack Mode = "bring_back"
)

var ErrInvalidResult = errors.New("crosssettle: invalid result")

// Reward 是跨服产出的单项奖励。
type Reward struct {
	ItemID string
	Count  int64
}

// Result 是跨服实例回传的结算单。SettlementID 是全局幂等键，
// 由跨服侧一次比赛/一次活动只生成一个。
type Result struct {
	SettlementID string
	TicketID     string
	PlayerID     string
	HomeServer   string
	Mode         Mode
	Points       int64
	Rewards      []Reward
}

// Record 是主服已应用的结算记录，用于幂等查询与对账。
type Record struct {
	SettlementID string
	PlayerID     string
	Points       int64
	Items        map[string]int64
	Capped       []string
	AppliedAt    time.Time
}

// Normalize 校验结算单并执行带回上限。只读与冻结模式清零产出，
// 因此它们永远不能改变主服资产。
func Normalize(r Result, caps map[string]int64) (Result, []string, error) {
	switch r.Mode {
	case ReadOnly, Frozen, BringBack:
	default:
		return Result{}, nil, fmt.Errorf("%w: unknown mode %q", ErrInvalidResult, r.Mode)
	}
	if r.SettlementID == "" || r.PlayerID == "" || r.HomeServer == "" {
		return Result{}, nil, fmt.Errorf("%w: missing identity", ErrInvalidResult)
	}
	if r.Points < 0 {
		return Result{}, nil, fmt.Errorf("%w: negative points", ErrInvalidResult)
	}
	out := r
	out.Rewards = append([]Reward(nil), r.Rewards...)
	sort.Slice(out.Rewards, func(i, j int) bool { return out.Rewards[i].ItemID < out.Rewards[j].ItemID })

	if out.Mode != BringBack {
		out.Points = 0
		out.Rewards = nil
		return out, nil, nil
	}

	var notes []string
	for i := range out.Rewards {
		rw := &out.Rewards[i]
		if rw.Count < 0 {
			return Result{}, nil, fmt.Errorf("%w: negative reward %s", ErrInvalidResult, rw.ItemID)
		}
		limit, ok := caps[rw.ItemID]
		if ok && rw.Count > limit {
			notes = append(notes, fmt.Sprintf("capped %s %d->%d", rw.ItemID, rw.Count, limit))
			rw.Count = limit
		}
	}
	return out, notes, nil
}

// Job 是回传失败的补偿任务。同一 SettlementID 只允许一个任务。
type Job struct {
	SettlementID string
	Result       Result
	Attempts     int
	Max          int
	State        string
	NextAt       time.Time
	LastError    string
}

const (
	Pending   = "pending"
	Escalated = "escalated"
)

// Account 是主服角色账本的最小视图。
type Account struct {
	PlayerID string
	Points   int64
	Items    map[string]int64
}

// Store 持有已应用记录与补偿队列。单进程实现用于演示，
// 生产环境把两者落库，幂等键仍是 SettlementID。
type Store struct {
	records  map[string]Record
	accounts map[string]*Account
	queue    map[string]*Job
}

// NewStore 创建空账本。
func NewStore() *Store {
	return &Store{
		records:  make(map[string]Record),
		accounts: make(map[string]*Account),
		queue:    make(map[string]*Job),
	}
}

func (s *Store) account(playerID string) *Account {
	acc, ok := s.accounts[playerID]
	if !ok {
		acc = &Account{PlayerID: playerID, Items: make(map[string]int64)}
		s.accounts[playerID] = acc
	}
	return acc
}

// Apply 幂等写入主服账本。返回 applied=false 表示该结算单此前已应用，
// 本次调用没有产生任何变更。
func (s *Store) Apply(r Result, caps map[string]int64, now time.Time) (Record, bool, error) {
	normalized, notes, err := Normalize(r, caps)
	if err != nil {
		return Record{}, false, err
	}
	if rec, ok := s.records[normalized.SettlementID]; ok {
		return rec, false, nil
	}
	acc := s.account(normalized.PlayerID)
	acc.Points += normalized.Points
	items := make(map[string]int64, len(normalized.Rewards))
	for _, rw := range normalized.Rewards {
		acc.Items[rw.ItemID] += rw.Count
		items[rw.ItemID] += rw.Count
	}
	rec := Record{
		SettlementID: normalized.SettlementID,
		PlayerID:     normalized.PlayerID,
		Points:       normalized.Points,
		Items:        items,
		Capped:       notes,
		AppliedAt:    now,
	}
	s.records[normalized.SettlementID] = rec
	return rec, true, nil
}

// Account 返回只读快照，避免调用方直接修改账本。
func (s *Store) Account(playerID string) (Account, bool) {
	acc, ok := s.accounts[playerID]
	if !ok {
		return Account{}, false
	}
	items := make(map[string]int64, len(acc.Items))
	for k, v := range acc.Items {
		items[k] = v
	}
	return Account{PlayerID: acc.PlayerID, Points: acc.Points, Items: items}, true
}

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