《MMO 服务器开发》10.3 事件溯源与审计

// file: internal/saga/audit/audit.go
// tier: L1
// verify: go test ./internal/saga/audit/

package audit

// Event is one immutable line of a player's asset history. The log is
// append-only: nothing is ever edited or deleted, so history can always be
// replayed to prove the current state.
type Event struct {
	Seq      uint64 // strictly increasing, assigned on append
	PlayerID uint64
	Type     string // "grant" / "spend" / "cross_settle" / "rollback"
	ItemID   uint32
	Delta    int64  // positive to grant, negative to spend
	At       int64  // server-stamped unix milliseconds
	Ref      string // correlation id, e.g. a battle or order id
}

// State is the asset snapshot produced by replaying a prefix of the log.
type State struct {
	Seq    uint64
	At     int64
	Assets map[uint32]int64
}

// Store is an in-memory append-only event log with periodic snapshots.
type Store struct {
	events []Event
	snaps  map[uint64]State // player -> latest snapshot
	next   uint64
}

// NewStore returns an empty log.
func NewStore() *Store {
	return &Store{snaps: map[uint64]State{}, next: 1}
}

// Append stamps and stores one event, returning the assigned sequence number.
func (s *Store) Append(e Event) uint64 {
	e.Seq = s.next
	s.next++
	s.events = append(s.events, e)
	return e.Seq
}

// Events returns every event for a player with Seq in [from, to] inclusive.
func (s *Store) Events(pid, from, to uint64) []Event {
	var out []Event
	for _, e := range s.events {
		if e.PlayerID == pid && e.Seq >= from && e.Seq <= to {
			out = append(out, e)
		}
	}
	return out
}

// Snapshot records the state at the current head. Replay must always reproduce
// this exact value, which is the whole point of an audit log.
func (s *Store) Snapshot(pid uint64, at int64) State {
	st := Replay(s.Events(pid, 0, ^uint64(0)))
	st.At = at
	s.snaps[pid] = st
	return st
}

// Replay folds events into asset state. It is pure: the same events always
// produce the same State, so it can be re-run on demand or after a restore.
func Replay(events []Event) State {
	st := State{Assets: map[uint32]int64{}}
	for _, e := range events {
		st.Assets[e.ItemID] += e.Delta
		if st.Assets[e.ItemID] == 0 {
			delete(st.Assets, e.ItemID)
		}
		st.Seq = e.Seq
	}
	return st
}

// Explanation answers "why did this player's assets change". It returns the
// before/after state of the window plus the events that caused the change, so a
// support engineer can read the story instead of diffing two tables.
type Explanation struct {
	PlayerID uint64
	From     int64
	To       int64
	Before   State
	After    State
	Events   []Event
}

// Explain replays the log up to the window start, then within the window, and
// returns both the boundary states and the in-window events.
func (s *Store) Explain(pid uint64, from, to int64) Explanation {
	all := s.Events(pid, 0, ^uint64(0))
	ex := Explanation{PlayerID: pid, From: from, To: to}
	ex.Before = State{Assets: map[uint32]int64{}}
	for _, e := range all {
		if e.At < from {
			ex.Before.Assets[e.ItemID] += e.Delta
			if ex.Before.Assets[e.ItemID] == 0 {
				delete(ex.Before.Assets, e.ItemID)
			}
			ex.Before.Seq = e.Seq
		} else if e.At <= to {
			ex.Events = append(ex.Events, e)
		}
	}
	// Copy the map: After must not alias Before, or applying the window would
	// silently rewrite the "before" picture too.
	ex.After = State{Assets: map[uint32]int64{}, Seq: ex.Before.Seq}
	for k, v := range ex.Before.Assets {
		ex.After.Assets[k] = v
	}
	for _, e := range ex.Events {
		ex.After.Assets[e.ItemID] += e.Delta
		if ex.After.Assets[e.ItemID] == 0 {
			delete(ex.After.Assets, e.ItemID)
		}
		ex.After.Seq = e.Seq
	}
	return ex
}

// file: internal/saga/audit/audit_test.go
// tier: L1
// verify: go test ./internal/saga/audit/ -v

package audit

import "testing"

// One day in milliseconds, used to build a readable timeline.
const day = int64(86_400_000)

func seed(s *Store, pid uint64) {
	// Morning: a battle reward, then a purchase. Afternoon: a cross-server
	// settlement and a rollback of a duplicated grant.
	s.Append(Event{PlayerID: pid, Type: "grant", ItemID: 7001, Delta: 3, At: 1 * day, Ref: "battle-1"})
	s.Append(Event{PlayerID: pid, Type: "spend", ItemID: 7001, Delta: -1, At: 1*day + 1_000, Ref: "shop-9"})
	s.Append(Event{PlayerID: pid, Type: "cross_settle", ItemID: 7002, Delta: 1, At: 2 * day, Ref: "order-A"})
	s.Append(Event{PlayerID: pid, Type: "grant", ItemID: 7002, Delta: 1, At: 2*day + 5_000, Ref: "order-A"})
	s.Append(Event{PlayerID: pid, Type: "rollback", ItemID: 7002, Delta: -1, At: 2*day + 6_000, Ref: "order-A"})
}

func TestReplayMatchesSnapshot(t *testing.T) {
	s := NewStore()
	seed(s, 10)

	snap := s.Snapshot(10, 2*day+7_000)
	full := Replay(s.Events(10, 0, ^uint64(0)))

	if full.Assets[7001] != 2 || full.Assets[7002] != 1 {
		t.Fatalf("replay assets=%v want 7001:2 7002:1", full.Assets)
	}
	if snap.Assets[7001] != full.Assets[7001] || snap.Assets[7002] != full.Assets[7002] {
		t.Fatalf("snapshot %v != replay %v", snap.Assets, full.Assets)
	}
	// Replaying twice is deterministic.
	if again := Replay(s.Events(10, 0, ^uint64(0))); again.Assets[7002] != full.Assets[7002] {
		t.Fatalf("replay not deterministic: %v vs %v", again.Assets, full.Assets)
	}
}

func TestExplainAnswersWhyAssetsChanged(t *testing.T) {
	s := NewStore()
	seed(s, 10)

	// "Why did this player's items change on day 2?"
	ex := s.Explain(10, 2*day, 2*day+day)

	if ex.Before.Assets[7001] != 2 || ex.Before.Assets[7002] != 0 {
		t.Fatalf("before=%v want 7001:2 7002:0", ex.Before.Assets)
	}
	if len(ex.Events) != 3 {
		t.Fatalf("day-2 events=%d want 3", len(ex.Events))
	}
	if ex.Events[0].Ref != "order-A" || ex.Events[2].Type != "rollback" {
		t.Fatalf("events out of order: %+v", ex.Events)
	}
	// Net effect of day 2: +1 of 7002 (settle +grant then -1 rollback).
	if ex.After.Assets[7002] != 1 {
		t.Fatalf("after=%v want 7002:1", ex.After.Assets)
	}
}