《游戏服务端架构·平台化与架构治理》3.2 GM 命令的幂等与补偿

// file: internal/gmcommand/command.go
// tier: L1
// verify: go test ./internal/gmcommand/
package gmcommand

import (
	"errors"
	"fmt"
)

// Action is the effect, not the button label. The ledger stores the effect so
// a replay can be compared without trusting the caller's serialization.
type Action string

const (
	ActionGrant      Action = "inventory.grant"
	ActionDeduct     Action = "inventory.deduct"
	ActionCompensate Action = "compensation.issue"
)

var (
	ErrBadCommand   = errors.New("gmcommand: invalid command")
	ErrKeyConflict  = errors.New("gmcommand: idempotency key reused")
	ErrInsufficient = errors.New("gmcommand: balance cannot cover deduction")
	ErrBadAction    = errors.New("gmcommand: unknown action")
	ErrNoSource     = errors.New("gmcommand: compensation needs a grant receipt")
)

// Command is the unit a GM tool, a ticket bot, or a cross-server forwarder
// sends. Key is chosen by the caller and must survive retries unchanged.
type Command struct {
	ID            string
	Key           string
	Target        string
	Action        Action
	Amount        int64
	Issuer        string
	Ticket        string
	ForwardedFrom string
}

// Validate rejects shape errors before they can consume an idempotency key.
// Keeping the ticket mandatory is deliberate: an untraceable grant is worse
// than a failed request.
func (c Command) Validate() error {
	if c.ID == "" || c.Key == "" || c.Target == "" || c.Issuer == "" || c.Ticket == "" {
		return ErrBadCommand
	}
	if c.Amount <= 0 {
		return ErrBadCommand
	}
	switch c.Action {
	case ActionGrant, ActionDeduct:
		return nil
	default:
		return ErrBadAction
	}
}

// Receipt is the durable answer to one key. A replay returns the stored
// receipt instead of applying the effect again.
type Receipt struct {
	Key          string
	CommandID    string
	Target       string
	Action       Action
	Amount       int64
	Applied      bool
	Duplicate    bool
	BalanceAfter int64
	Ticket       string
}

// Compensation explains how much of an over-grant was actually recovered.
// Shortfall is not silently turned into a negative balance; it becomes a debt
// record for a human decision.
type Compensation struct {
	Key       string
	SourceKey string
	Target    string
	Requested int64
	Deducted  int64
	Shortfall int64
	NeedsHold bool
	Replay    bool
}

// Ledger is an append-only receipt map plus the derived balance. It is small
// enough to embed in a service and strict enough to expose the failure paths.
type Ledger struct {
	receipts      map[string]Receipt
	compensations map[string]Compensation
	balances      map[string]int64
	order         []string
}

func NewLedger() *Ledger {
	return &Ledger{
		receipts:      map[string]Receipt{},
		compensations: map[string]Compensation{},
		balances:      map[string]int64{},
	}
}

// Apply executes a command at most once per key. A conflicting reuse of the
// key is an error, not a duplicate: two different intentions must not share
// one receipt.
func (l *Ledger) Apply(c Command) (Receipt, error) {
	if err := c.Validate(); err != nil {
		return Receipt{}, err
	}
	if prev, ok := l.receipts[c.Key]; ok {
		if prev.CommandID != c.ID || prev.Target != c.Target || prev.Action != c.Action || prev.Amount != c.Amount {
			return Receipt{}, ErrKeyConflict
		}
		prev.Duplicate = true
		prev.Applied = false
		return prev, nil
	}

	balance := l.balances[c.Target]
	switch c.Action {
	case ActionGrant:
		balance += c.Amount
	case ActionDeduct:
		if balance < c.Amount {
			return Receipt{}, fmt.Errorf("%w: need %d have %d", ErrInsufficient, c.Amount, balance)
		}
		balance -= c.Amount
	default:
		return Receipt{}, ErrBadAction
	}

	r := Receipt{
		Key:          c.Key,
		CommandID:    c.ID,
		Target:       c.Target,
		Action:       c.Action,
		Amount:       c.Amount,
		Applied:      true,
		BalanceAfter: balance,
		Ticket:       c.Ticket,
	}
	l.balances[c.Target] = balance
	l.receipts[c.Key] = r
	l.order = append(l.order, c.Key)
	return r, nil
}

// Forward is the cross-server entry point. The forwarding hop is recorded but
// does not create a second idempotency namespace: the original key still
// decides whether the effect happened.
func (l *Ledger) Forward(c Command, from string) (Receipt, error) {
	c.ForwardedFrom = from
	return l.Apply(c)
}

// Compensate reverses part or all of a grant. It never drives the balance
// below zero; the uncovered part is reported as Shortfall with NeedsHold set.
// Repeating the same source key returns the first compensation unchanged.
func (l *Ledger) Compensate(sourceKey string, requested int64) (Compensation, error) {
	if requested <= 0 {
		return Compensation{}, ErrBadCommand
	}
	source, ok := l.receipts[sourceKey]
	if !ok || source.Action != ActionGrant {
		return Compensation{}, ErrNoSource
	}
	key := "cmp:" + sourceKey
	if prev, ok := l.compensations[key]; ok {
		prev.Replay = true
		return prev, nil
	}

	balance := l.balances[source.Target]
	deducted := requested
	if deducted > balance {
		deducted = balance
	}
	shortfall := requested - deducted
	l.balances[source.Target] = balance - deducted

	comp := Compensation{
		Key:       key,
		SourceKey: sourceKey,
		Target:    source.Target,
		Requested: requested,
		Deducted:  deducted,
		Shortfall: shortfall,
		NeedsHold: shortfall > 0,
	}
	l.compensations[key] = comp
	l.order = append(l.order, key)
	return comp, nil
}

// Balance returns the current balance for a target.
func (l *Ledger) Balance(target string) int64 { return l.balances[target] }

// Receipt returns the stored receipt for a key and whether it exists.
func (l *Ledger) Receipt(key string) (Receipt, bool) {
	r, ok := l.receipts[key]
	return r, ok
}

// Order returns the keys in apply order. It is the evidence trail a reviewer
// reads when two operators claim they acted first.
func (l *Ledger) Order() []string {
	out := make([]string, len(l.order))
	copy(out, l.order)
	return out
}