《游戏服务端架构·核心系统与契约》6.1 货币、产出与消耗

UPDATE wallet SET amount = amount + 100 WHERE player_id = ? AND currency = 'silver';

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

import (
	"errors"
	"fmt"
	"reflect"
	"sort"
	"strings"
)

var (
	ErrNoPostings  = errors.New("currencyledger: transaction has no postings")
	ErrUnbalanced  = errors.New("currencyledger: postings do not sum to zero")
	ErrMissingID   = errors.New("currencyledger: transaction id is empty")
	ErrDuplicateTx = errors.New("currencyledger: duplicate transaction id")
	ErrBadDelta    = errors.New("currencyledger: posting delta must be non-zero")
	ErrBadSource   = errors.New("currencyledger: posting source tag is empty")
	ErrCurrency    = errors.New("currencyledger: currency does not match ledger")
	ErrOverdraft   = errors.New("currencyledger: player account would go negative")
	ErrMismatch    = errors.New("currencyledger: journal and balances disagree")
)

// Source is the business reason attached to every posting. Reports group by
// this tag, so a missing or invented tag makes an inflation bug unattributable.
type Source string

const (
	SourceQuest  Source = "quest"
	SourceShop   Source = "shop"
	SourceTrade  Source = "trade"
	SourceEvent  Source = "event"
	SourceRefund Source = "refund"
	SourceGM     Source = "gm"
)

// System accounts hold the counter-entry of creation and destruction. They are
// allowed to go negative; player accounts are not.
const (
	AccountMint Account = "@mint"
	AccountSink Account = "@sink"
)

// Account identifies a wallet or a system counter-account.
type Account string

// Posting is one leg of a transaction. Delta is positive for a credit and
// negative for a debit. Note is for human audit only; nothing joins on it.
type Posting struct {
	Account Account
	Delta   int64
	Source  Source
	Note    string
}

// Transaction is an atomic set of postings in one currency. Postings must sum
// to zero, which is what makes the ledger double-entry rather than a balance
// table with extra columns.
type Transaction struct {
	ID       string
	Currency string
	Postings []Posting
}

// SourceTotal is the net movement attributed to one source tag.
type SourceTotal struct {
	Source Source
	Net    int64
}

// Ledger is an in-memory double-entry book for exactly one currency. One
// currency per ledger keeps sum-zero meaningful without an exchange table.
type Ledger struct {
	currency string
	seen     map[string]struct{}
	balances map[Account]int64
	sources  map[Source]int64
	journal  []Transaction
}

// New creates an empty ledger. The currency is fixed at construction so a
// misrouted transaction fails before it touches any balance.
func New(currency string) *Ledger {
	return &Ledger{
		currency: currency,
		seen:     make(map[string]struct{}),
		balances: make(map[Account]int64),
		sources:  make(map[Source]int64),
		journal:  make([]Transaction, 0, 64),
	}
}

// Post validates and applies one transaction. Validation is complete before
// any map is mutated, so a rejected transaction leaves no partial effect.
func (l *Ledger) Post(tx Transaction) error {
	if err := l.validate(tx); err != nil {
		return err
	}
	next := make(map[Account]int64, len(l.balances)+len(tx.Postings))
	for a, b := range l.balances {
		next[a] = b
	}
	for _, p := range tx.Postings {
		next[p.Account] += p.Delta
	}
	for a, b := range next {
		if !isSystem(a) && b < 0 {
			return fmt.Errorf("%w: %s", ErrOverdraft, a)
		}
	}
	for _, p := range tx.Postings {
		l.balances[p.Account] = next[p.Account]
		if !isSystem(p.Account) {
			l.sources[p.Source] += p.Delta
		}
	}
	l.seen[tx.ID] = struct{}{}
	l.journal = append(l.journal, cloneTx(tx))
	return nil
}

func (l *Ledger) validate(tx Transaction) error {
	if tx.ID == "" {
		return ErrMissingID
	}
	if _, ok := l.seen[tx.ID]; ok {
		return fmt.Errorf("%w: %s", ErrDuplicateTx, tx.ID)
	}
	if tx.Currency != l.currency {
		return fmt.Errorf("%w: %q", ErrCurrency, tx.Currency)
	}
	if len(tx.Postings) == 0 {
		return ErrNoPostings
	}
	var sum int64
	for _, p := range tx.Postings {
		if p.Delta == 0 {
			return fmt.Errorf("%w: %s", ErrBadDelta, p.Account)
		}
		if p.Source == "" {
			return fmt.Errorf("%w: %s", ErrBadSource, p.Account)
		}
		sum += p.Delta
	}
	if sum != 0 {
		return fmt.Errorf("%w: %d", ErrUnbalanced, sum)
	}
	return nil
}

// Balance returns the current balance of an account. Unknown accounts are 0.
func (l *Ledger) Balance(a Account) int64 { return l.balances[a] }

// SourceNet returns the net movement of player accounts tagged with a source.
// Mint and sink legs are excluded so a reward source reads positive and a
// consumption source reads negative instead of always cancelling to zero.
func (l *Ledger) SourceNet(s Source) int64 { return l.sources[s] }

// Minted is total currency created through the mint account.
func (l *Ledger) Minted() int64 { return -l.balances[AccountMint] }

// Burned is total currency destroyed through the sink account.
func (l *Ledger) Burned() int64 { return l.balances[AccountSink] }

// Circulation is the currency still held by player accounts.
func (l *Ledger) Circulation() int64 { return l.Minted() - l.Burned() }

// SourceTotals returns net movement per source in stable order for reports.
func (l *Ledger) SourceTotals() []SourceTotal {
	out := make([]SourceTotal, 0, len(l.sources))
	for s, net := range l.sources {
		out = append(out, SourceTotal{Source: s, Net: net})
	}
	sort.Slice(out, func(i, j int) bool { return out[i].Source < out[j].Source })
	return out
}

// Reconcile replays the journal and compares the result with the cached
// balances. It is the check run after a crash or an import, not on every post.
func (l *Ledger) Reconcile() error {
	balances := make(map[Account]int64, len(l.balances))
	sources := make(map[Source]int64, len(l.sources))
	var total int64
	for _, tx := range l.journal {
		var sum int64
		for _, p := range tx.Postings {
			sum += p.Delta
			total += p.Delta
			balances[p.Account] += p.Delta
			if !isSystem(p.Account) {
				sources[p.Source] += p.Delta
			}
		}
		if sum != 0 {
			return fmt.Errorf("%w: %s", ErrUnbalanced, tx.ID)
		}
	}
	if total != 0 {
		return fmt.Errorf("%w: total %d", ErrUnbalanced, total)
	}
	if !reflect.DeepEqual(balances, l.balances) || !reflect.DeepEqual(sources, l.sources) {
		return ErrMismatch
	}
	return nil
}

// Journal returns a deep copy. Callers may archive it, but cannot mutate the
// ledger through the returned slice.
func (l *Ledger) Journal() []Transaction {
	out := make([]Transaction, len(l.journal))
	for i, tx := range l.journal {
		out[i] = cloneTx(tx)
	}
	return out
}

func cloneTx(tx Transaction) Transaction {
	cp := tx
	cp.Postings = append([]Posting(nil), tx.Postings...)
	return cp
}

func isSystem(a Account) bool { return strings.HasPrefix(string(a), "@") }