《游戏服务端架构·核心系统与契约》5.2 结算契约与防重复发奖

received --validate--> validated --settle--> settled --reverse--> reversed
    |                       |                    |
    +------- override ------+                    +--- 二次冲正：拒绝

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

import (
	"errors"
	"fmt"
)

type State string

const (
	Received  State = "received"
	Validated State = "validated"
	Settled   State = "settled"
	Reversed  State = "reversed"
)

type Outcome string

const (
	OutcomeWin        Outcome = "win"
	OutcomeDraw       Outcome = "draw"
	OutcomeDisconnect Outcome = "disconnect"
	OutcomeFlee       Outcome = "flee"
	OutcomeAbnormal   Outcome = "abnormal"
)

var (
	ErrInvalidSettlement = errors.New("settlecontract: invalid settlement")
	ErrBadTransition     = errors.New("settlecontract: illegal transition")
	ErrRuleVersion       = errors.New("settlecontract: rule version mismatch")
	ErrUnauthorized      = errors.New("settlecontract: authority too low")
	ErrReasonRequired    = errors.New("settlecontract: reason required")
	ErrAlreadyReversed   = errors.New("settlecontract: already reversed")
)

type Authority int

const (
	Agent Authority = iota
	SupportLead
	OpsManager
)

type Participant struct {
	PlayerID  string
	Team      int
	Score     int
	Connected bool
}

type Reward struct {
	Key      string
	PlayerID string
	Amount   int
}

type Settlement struct {
	BattleID     string
	RuleVersion  int
	Outcome      Outcome
	WinningTeam  int
	Participants []Participant
	State        State
	Revision     int
	Rewards      []Reward
	ReverseWhy   string
}

// NewSettlement creates a Received document. WinningTeam is ignored unless the
// outcome is a win, so a caller cannot smuggle a winner into a draw.
func NewSettlement(battleID string, ruleVersion int, outcome Outcome, winningTeam int, ps []Participant) *Settlement {
	s := &Settlement{BattleID: battleID, RuleVersion: ruleVersion, Outcome: outcome,
		WinningTeam: winningTeam, Participants: append([]Participant(nil), ps...), State: Received}
	if outcome != OutcomeWin {
		s.WinningTeam = -1
	}
	return s
}

// Validate checks the result shape and moves Received to Validated.
func (s *Settlement) Validate() error {
	if s.State == Reversed {
		return ErrBadTransition
	}
	if s.BattleID == "" || s.RuleVersion <= 0 || len(s.Participants) < 2 {
		return ErrInvalidSettlement
	}
	seen, best := map[string]bool{}, map[int]int{}
	for _, p := range s.Participants {
		if p.PlayerID == "" || seen[p.PlayerID] {
			return ErrInvalidSettlement
		}
		seen[p.PlayerID] = true
		if p.Score > best[p.Team] {
			best[p.Team] = p.Score
		}
	}
	switch s.Outcome {
	case OutcomeWin:
		top, ok := best[s.WinningTeam]
		if !ok {
			return ErrInvalidSettlement
		}
		for team, score := range best {
			if team != s.WinningTeam && score >= top {
				return ErrInvalidSettlement
			}
		}
	case OutcomeDraw:
		top, tied := -1, 0
		for _, score := range best {
			if score > top {
				top, tied = score, 1
			} else if score == top {
				tied++
			}
		}
		if len(best) < 2 || tied < 2 {
			return ErrInvalidSettlement
		}
	case OutcomeDisconnect, OutcomeFlee:
		offline := false
		for _, p := range s.Participants {
			offline = offline || !p.Connected
		}
		if !offline {
			return ErrInvalidSettlement
		}
	case OutcomeAbnormal:
	default:
		return ErrInvalidSettlement
	}
	s.State = Validated
	return nil
}

type RewardTable struct {
	Version  int
	Winner   int
	Loser    int
	Draw     int
	Abnormal int
}

// settle applies one reward operation to every grant, deduplicating through
// the ledger on retry.
func apply(rewards []Reward, op func(Reward) (bool, error)) (ApplyResult, error) {
	var r ApplyResult
	for _, w := range rewards {
		fresh, err := op(w)
		if err != nil {
			return r, err
		}
		if fresh {
			r.Granted++
		} else {
			r.Duplicates++
		}
	}
	return r, nil
}

type Ledger interface {
	Grant(key, playerID string, amount int) (bool, error)
	Revoke(key, playerID string, amount int) (bool, error)
}

type ApplyResult struct {
	Granted    int
	Duplicates int
}

// Settle plans rewards from the versioned table and grants them. The document
// stays Validated until every grant succeeds; a retry re-sends the same keys.
func (s *Settlement) Settle(l Ledger, table RewardTable) (ApplyResult, error) {
	if s.State == Settled {
		return ApplyResult{Duplicates: len(s.Rewards)}, nil
	}
	if s.State != Validated {
		return ApplyResult{}, fmt.Errorf("%w: %s -> settled", ErrBadTransition, s.State)
	}
	if table.Version != s.RuleVersion {
		return ApplyResult{}, ErrRuleVersion
	}
	if len(s.Rewards) == 0 {
		for _, p := range s.Participants {
			amount := table.Abnormal
			switch {
			case s.Outcome == OutcomeWin && p.Team == s.WinningTeam:
				amount = table.Winner
			case s.Outcome == OutcomeWin:
				amount = table.Loser
			case s.Outcome == OutcomeDraw:
				amount = table.Draw
			}
			key := fmt.Sprintf("battle:%s:r%d:%s", s.BattleID, s.RuleVersion, p.PlayerID)
			s.Rewards = append(s.Rewards, Reward{key, p.PlayerID, amount})
		}
	}
	r, err := apply(s.Rewards, func(w Reward) (bool, error) {
		return l.Grant(w.Key, w.PlayerID, w.Amount)
	})
	if err == nil {
		s.State = Settled
	}
	return r, err
}

// Reverse revokes all grants after review. A second reversal is rejected.
func (s *Settlement) Reverse(l Ledger, by Authority, reason string) (ApplyResult, error) {
	if s.State == Reversed {
		return ApplyResult{}, ErrAlreadyReversed
	}
	if s.State != Settled {
		return ApplyResult{}, fmt.Errorf("%w: %s -> reversed", ErrBadTransition, s.State)
	}
	if by < SupportLead {
		return ApplyResult{}, ErrUnauthorized
	}
	if reason == "" {
		return ApplyResult{}, ErrReasonRequired
	}
	r, err := apply(s.Rewards, func(w Reward) (bool, error) {
		return l.Revoke(w.Key, w.PlayerID, w.Amount)
	})
	if err == nil {
		s.State, s.ReverseWhy = Reversed, reason
	}
	return r, err
}

// Override changes the outcome before settlement and reopens validation.
func (s *Settlement) Override(by Authority, outcome Outcome, winningTeam int, reason string) error {
	if by < OpsManager {
		return ErrUnauthorized
	}
	if reason == "" {
		return ErrReasonRequired
	}
	if s.State != Received && s.State != Validated {
		return fmt.Errorf("%w: %s -> override", ErrBadTransition, s.State)
	}
	if outcome != OutcomeWin {
		winningTeam = -1
	}
	s.Outcome, s.WinningTeam = outcome, winningTeam
	s.Revision++
	s.State = Received
	s.Rewards = nil
	return nil
}

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