《游戏服务端架构·品类、状态与拓扑》9.2 回合制卡牌的确定性与回放

种子 seed + 出牌动作序列 actions + 规则版本 rules_version
                         │
                         ▼
              确定性结算引擎（纯函数式推进）
                         │
                         ▼
              最终状态 state → SHA-256 → 状态哈希

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

import (
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"fmt"
	"sort"
	"strings"
)

const (
	StartHP       = 20
	HandSize      = 3
	EnergyPerTurn = 3
	KindPlay      = "play"
	KindEnd       = "end"
)

var (
	ErrBadPlayers      = errors.New("cardgame: need two distinct players")
	ErrNotYourTurn     = errors.New("cardgame: not your turn")
	ErrUnknownCard     = errors.New("cardgame: card not in hand")
	ErrNotEnoughEnergy = errors.New("cardgame: not enough energy")
	ErrGameOver        = errors.New("cardgame: game already over")
	ErrBadAction       = errors.New("cardgame: malformed action")
	ErrReplayMismatch  = errors.New("cardgame: replay hash mismatch")
)

// Card IDs are unique per copy. Two copies of "strike" are "strike-0" and
// "strike-1", so an action can never be ambiguous.
type Card struct {
	ID     string
	Cost   int
	Damage int
	Heal   int
}

var blueprints = []struct {
	name         string
	cost, damage int
	heal         int
}{
	{"strike", 1, 3, 0},
	{"guard", 1, 0, 2},
	{"bolt", 2, 5, 0},
	{"mend", 2, 0, 4},
	{"jab", 0, 1, 0},
	{"focus", 0, 0, 1},
}

func buildDeck() []Card {
	deck := make([]Card, 0, len(blueprints)*2)
	for _, b := range blueprints {
		for i := 0; i < 2; i++ {
			deck = append(deck, Card{
				ID: fmt.Sprintf("%s-%d", b.name, i), Cost: b.cost,
				Damage: b.damage, Heal: b.heal,
			})
		}
	}
	return deck
}

// SplitMix64 is fixed in this package. The Go runtime may change math/rand
// internals between releases, which would silently break old replays.
func splitmix(x *uint64) uint64 {
	*x += 0x9E3779B97F4A7C15
	z := *x
	z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9
	z = (z ^ (z >> 27)) * 0x94D049BB133111EB
	return z ^ (z >> 31)
}

// Shuffle is Fisher-Yates over splitmix64. Same seed and deck always produce
// the same order on every platform.
func Shuffle(cards []Card, seed uint64) []Card {
	out := append([]Card(nil), cards...)
	x := seed
	for i := len(out) - 1; i > 0; i-- {
		j := int(splitmix(&x) % uint64(i+1))
		out[i], out[j] = out[j], out[i]
	}
	return out
}

type Action struct {
	Kind   string
	Player string
	CardID string
}

// State is the complete authoritative game state. Maps are always serialized
// in sorted player order by Hash.
type State struct {
	Seed     uint64
	Players  []string
	Deck     []Card
	Hands    map[string][]Card
	HP       map[string]int
	Energy   map[string]int
	Turn     string
	Finished bool
	Winner   string
}

func NewGame(seed uint64, players []string) (*State, error) {
	if len(players) != 2 || players[0] == "" || players[1] == "" ||
		players[0] == players[1] {
		return nil, ErrBadPlayers
	}
	s := &State{
		Seed: seed, Players: append([]string(nil), players...),
		Deck:  Shuffle(buildDeck(), seed),
		Hands: map[string][]Card{}, HP: map[string]int{},
		Energy: map[string]int{}, Turn: players[0],
	}
	for _, p := range players {
		s.HP[p] = StartHP
		s.Energy[p] = EnergyPerTurn
	}
	for i := 0; i < HandSize; i++ {
		for _, p := range players {
			s.draw(p)
		}
	}
	return s, nil
}

func (s *State) draw(player string) bool {
	if len(s.Deck) == 0 {
		return false
	}
	card := s.Deck[0]
	s.Deck = s.Deck[1:]
	s.Hands[player] = append(s.Hands[player], card)
	return true
}

func (s *State) other(player string) string {
	if player == s.Players[0] {
		return s.Players[1]
	}
	return s.Players[0]
}

// Apply is the only mutation path. The client sends actions, never a claimed
// result; the server (or the replay verifier) recomputes the state.
func (s *State) Apply(a Action) error {
	if s.Finished {
		return ErrGameOver
	}
	if a.Player != s.Turn {
		return ErrNotYourTurn
	}
	switch a.Kind {
	case KindEnd:
		s.endTurn()
		return nil
	case KindPlay:
		return s.play(a)
	default:
		return ErrBadAction
	}
}

func (s *State) play(a Action) error {
	hand := s.Hands[a.Player]
	idx := -1
	for i, c := range hand {
		if c.ID == a.CardID {
			idx = i
			break
		}
	}
	if idx < 0 {
		return ErrUnknownCard
	}
	card := hand[idx]
	if s.Energy[a.Player] < card.Cost {
		return ErrNotEnoughEnergy
	}
	s.Energy[a.Player] -= card.Cost
	s.Hands[a.Player] = append(append([]Card{}, hand[:idx]...), hand[idx+1:]...)
	target := s.other(a.Player)
	if card.Damage > 0 {
		s.HP[target] -= card.Damage
	}
	if card.Heal > 0 {
		s.HP[a.Player] += card.Heal
	}
	if s.HP[target] <= 0 {
		s.Finished = true
		s.Winner = a.Player
	}
	return nil
}

func (s *State) endTurn() {
	next := s.other(s.Turn)
	s.Turn = next
	s.Energy[next] = EnergyPerTurn
	s.draw(next)
}

// Hash is the replay fingerprint. It covers every field that can change the
// outcome, including deck order and each hand's order.
func (s *State) Hash() string {
	var b strings.Builder
	fmt.Fprintf(&b, "cardgame-v1|seed=%d|turn=%s|finished=%t|winner=%s",
		s.Seed, s.Turn, s.Finished, s.Winner)
	players := append([]string(nil), s.Players...)
	sort.Strings(players)
	for _, p := range players {
		fmt.Fprintf(&b, "|p=%s,hp=%d,energy=%d,hand=", p, s.HP[p], s.Energy[p])
		for _, c := range s.Hands[p] {
			b.WriteString(c.ID)
			b.WriteByte(',')
		}
	}
	b.WriteString("|deck=")
	for _, c := range s.Deck {
		b.WriteString(c.ID)
		b.WriteByte(',')
	}
	sum := sha256.Sum256([]byte(b.String()))
	return hex.EncodeToString(sum[:])
}

type Replay struct {
	Seed         uint64
	Players      []string
	Actions      []Action
	ExpectedHash string
}

// Verify rebuilds the game from the seed and action log. A tampered action is
// caught either as an illegal move or as a different final hash.
func (r Replay) Verify() (*State, error) {
	if r.ExpectedHash == "" {
		return nil, ErrBadAction
	}
	s, err := NewGame(r.Seed, r.Players)
	if err != nil {
		return nil, err
	}
	for i, a := range r.Actions {
		if err := s.Apply(a); err != nil {
			return nil, fmt.Errorf("action %d: %w", i, err)
		}
	}
	if got := s.Hash(); got != r.ExpectedHash {
		return nil, fmt.Errorf("%w: got %s want %s", ErrReplayMismatch, got, r.ExpectedHash)
	}
	return s, nil
}

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

fbf8aef75cc3b123d05288a1f718d7d57d1c883d036d4e68643d364ca1e13c27