《游戏服务端架构·核心系统与契约》7.1 属性、成长与状态机

for layer in [base, equipment, buff, season]:
    value = value + sum(flat modifiers in layer)
    value = value * (10000 + sum(percent basis points in layer)) / 10000

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

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

// Layer fixes composition order. A season bonus must never be multiplied by
// a buff, so the order is part of the contract, not an implementation detail.
type Layer int

const (
	LayerBase Layer = iota
	LayerEquipment
	LayerBuff
	LayerSeason
	numLayers
)

// Op is deliberately small. Percent values are basis points: 1500 = +15%.
type Op int

const (
	OpAdd Op = iota
	OpPct
)

type Modifier struct {
	Layer Layer
	Stat  string
	Op    Op
	Value int64
}

var (
	ErrUnknownLayer = errors.New("growthfsm: unknown layer")
	ErrUnknownOp    = errors.New("growthfsm: unknown op")
	ErrEmptyStat    = errors.New("growthfsm: empty stat")
	ErrNegativeBase = errors.New("growthfsm: negative base stat")
	ErrNegativeStat = errors.New("growthfsm: negative composed stat")
)

// Stats are integers. Floats would let two servers disagree after a few
// thousand operations, and replay would stop matching.
type Stats map[string]int64

// Compose applies layers from base to season. Within one layer all flat adds
// are summed first, then all percentages are summed and applied once, so the
// order of modifiers in the input never changes the output.
func Compose(base Stats, mods []Modifier) (Stats, error) {
	out := make(Stats, len(base))
	for stat, v := range base {
		if strings.TrimSpace(stat) == "" {
			return nil, ErrEmptyStat
		}
		if v < 0 {
			return nil, fmt.Errorf("%w: %s=%d", ErrNegativeBase, stat, v)
		}
		out[stat] = v
	}
	flat := make([]map[string]int64, int(numLayers))
	pct := make([]map[string]int64, int(numLayers))
	for i := range flat {
		flat[i] = map[string]int64{}
		pct[i] = map[string]int64{}
	}
	for _, m := range mods {
		if strings.TrimSpace(m.Stat) == "" {
			return nil, ErrEmptyStat
		}
		if m.Layer < LayerBase || m.Layer >= numLayers {
			return nil, fmt.Errorf("%w: %d", ErrUnknownLayer, m.Layer)
		}
		switch m.Op {
		case OpAdd:
			flat[m.Layer][m.Stat] += m.Value
		case OpPct:
			pct[m.Layer][m.Stat] += m.Value
		default:
			return nil, fmt.Errorf("%w: %d", ErrUnknownOp, m.Op)
		}
	}
	for layer := LayerBase; layer < numLayers; layer++ {
		for stat, add := range flat[layer] {
			out[stat] += add
			if out[stat] < 0 {
				return nil, fmt.Errorf("%w: %s=%d", ErrNegativeStat, stat, out[stat])
			}
		}
		for stat, bp := range pct[layer] {
			if 10000+bp < 0 {
				return nil, fmt.Errorf("%w: %s percent=%d", ErrNegativeStat, stat, bp)
			}
			out[stat] = mulDiv(out[stat], 10000+bp, 10000)
		}
	}
	return out, nil
}

// mulDiv rounds half up. Only non-negative values reach it.
func mulDiv(v, mul, div int64) int64 {
	if v == 0 {
		return 0
	}
	return (v*mul + div/2) / div
}

// Snapshot is an immutable view plus a fingerprint. Combat caches compare the
// fingerprint instead of walking every stat.
type Snapshot struct {
	Stats       Stats
	Fingerprint string
}

// NewSnapshot copies the map: a caller still mutating its own Stats must not
// be able to invalidate a fingerprint that is already in flight.
func NewSnapshot(stats Stats) Snapshot {
	copied := make(Stats, len(stats))
	keys := make([]string, 0, len(stats))
	for k, v := range stats {
		copied[k] = v
		keys = append(keys, k)
	}
	sort.Strings(keys)
	h := sha256.New()
	for _, k := range keys {
		fmt.Fprintf(h, "%s=%d;", k, copied[k])
	}
	return Snapshot{Stats: copied, Fingerprint: hex.EncodeToString(h.Sum(nil))}
}

type Phase int

const (
	PhaseUnawakened Phase = iota
	PhaseAwakened
	PhaseAdvanced
)

// MaxLevel caps one phase. A level-up never crosses a phase; only a
// breakthrough does, and it costs materials.
func MaxLevel(p Phase) int {
	switch p {
	case PhaseUnawakened:
		return 20
	case PhaseAwakened:
		return 40
	case PhaseAdvanced:
		return 60
	default:
		return 0
	}
}

type State struct {
	Level int
	Phase Phase
	Class string
}

type ActionKind int

const (
	ActLevelUp ActionKind = iota
	ActBreakthrough
	ActChangeClass
)

type Action struct {
	Kind      ActionKind
	Class     string
	Materials int
}

const (
	breakthroughMaterials = 12
	classChangeLevel      = 50
)

var (
	ErrIllegalTransition = errors.New("growthfsm: illegal transition")
	ErrMaxLevel          = errors.New("growthfsm: level cap reached")
	ErrNotReady          = errors.New("growthfsm: transition prerequisite not met")
	ErrClassUnavailable  = errors.New("growthfsm: class unavailable")
	ErrMaterials         = errors.New("growthfsm: insufficient materials")
)

// Apply is the only mutation path. Rejecting replayed client packets matters
// more than accepting a legal action quickly.
func Apply(st State, act Action) (State, error) {
	if st.Level < 1 || st.Level > MaxLevel(st.Phase) {
		return st, fmt.Errorf("%w: level %d in phase %d", ErrIllegalTransition, st.Level, st.Phase)
	}
	switch act.Kind {
	case ActLevelUp:
		if st.Level == MaxLevel(st.Phase) {
			return st, fmt.Errorf("%w: phase %d at %d", ErrMaxLevel, st.Phase, st.Level)
		}
		st.Level++
		return st, nil
	case ActBreakthrough:
		if st.Phase == PhaseAdvanced {
			return st, fmt.Errorf("%w: phase %d is final", ErrIllegalTransition, st.Phase)
		}
		if st.Level != MaxLevel(st.Phase) {
			return st, fmt.Errorf("%w: need level %d, have %d", ErrNotReady, MaxLevel(st.Phase), st.Level)
		}
		if act.Materials < breakthroughMaterials {
			return st, fmt.Errorf("%w: need %d, have %d", ErrMaterials, breakthroughMaterials, act.Materials)
		}
		st.Level = MaxLevel(st.Phase) + 1
		st.Phase++
		return st, nil
	case ActChangeClass:
		if st.Phase != PhaseAdvanced || st.Level < classChangeLevel {
			return st, fmt.Errorf("%w: need advanced level %d", ErrNotReady, classChangeLevel)
		}
		if act.Class == "" || act.Class == st.Class {
			return st, fmt.Errorf("%w: %q", ErrClassUnavailable, act.Class)
		}
		st.Class = act.Class
		return st, nil
	default:
		return st, fmt.Errorf("%w: action %d", ErrIllegalTransition, act.Kind)
	}
}