《MMO 服务器开发》10.2 对账与数据修复工单

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

package recon

import (
	"fmt"
	"sort"
)

// Kind separates money-like entries (must match to the cent) from cosmetic
// ones (a display name may lag without anyone losing anything).
type Kind int

const (
	KindAmount  Kind = iota // 金额类：点券、物品数量、结算流水
	KindDisplay             // 展示类：昵称、外观、榜面文案
)

// Class is the verdict the reconciler assigns to one compared key.
type Class int

const (
	ClassMatch      Class = iota // both sides agree
	ClassTolerable               // display drift, no action
	ClassRepairable              // one side missing, mirror the other
	ClassTicket                  // amount mismatch, needs a human
)

// Entry is one line of a ledger. Key is the order id both sides share.
type Entry struct {
	Key      string
	PlayerID uint64
	Kind     Kind
	Value    int64
}

// Diff is the comparison of one key across the two sides.
type Diff struct {
	Key   string
	Kind  Kind
	Left  *Entry // nil when the key is absent on the left
	Right *Entry // nil when the key is absent on the right
	Class Class
}

// Ticket is the durable record of a difference a machine refused to fix.
type Ticket struct {
	ID         string
	Key        string
	PlayerID   uint64
	Kind       Kind
	LeftValue  int64
	RightValue int64
	Reason     string
	State      string // "open" until a human closes it
}

// Reconciler compares two ledgers keyed by order id.
type Reconciler struct{ seq int }

// Compare walks the union of both key sets and grades every key.
func (r *Reconciler) Compare(left, right map[string]Entry) []Diff {
	seen := map[string]bool{}
	keys := make([]string, 0, len(left)+len(right))
	for _, m := range []map[string]Entry{left, right} {
		for k := range m {
			if !seen[k] {
				seen[k] = true
				keys = append(keys, k)
			}
		}
	}
	sort.Strings(keys)
	out := make([]Diff, 0, len(keys))
	for _, k := range keys {
		d := Diff{Key: k}
		if l, ok := left[k]; ok {
			d.Left, d.Kind = &l, l.Kind
		}
		if rr, ok := right[k]; ok {
			d.Right, d.Kind = &rr, rr.Kind
		}
		d.Class = grade(d)
		out = append(out, d)
	}
	return out
}

// grade encodes the whole policy in one place: money mismatches go to a human,
// a one-sided money entry can be mirrored, display drift is ignored.
func grade(d Diff) Class {
	switch {
	case d.Left != nil && d.Right != nil && d.Left.Value == d.Right.Value:
		return ClassMatch
	case d.Kind == KindDisplay:
		return ClassTolerable
	case d.Left == nil || d.Right == nil:
		return ClassRepairable
	default:
		return ClassTicket
	}
}

// Apply fixes every repairable diff by writing the missing side, and returns
// the diffs that could not be fixed automatically as tickets.
func (r *Reconciler) Apply(left, right map[string]Entry, diffs []Diff) []Ticket {
	var tickets []Ticket
	for _, d := range diffs {
		switch d.Class {
		case ClassRepairable:
			if d.Left == nil {
				left[d.Key] = *d.Right
			} else {
				right[d.Key] = *d.Left
			}
		case ClassTicket:
			r.seq++
			tickets = append(tickets, Ticket{
				ID:         fmt.Sprintf("RPT-%04d", r.seq),
				Key:        d.Key,
				PlayerID:   pickPlayer(d),
				Kind:       d.Kind,
				LeftValue:  val(d.Left),
				RightValue: val(d.Right),
				Reason:     fmt.Sprintf("amount mismatch on %s: left=%d right=%d", d.Key, val(d.Left), val(d.Right)),
				State:      "open",
			})
		}
	}
	return tickets
}

func pickPlayer(d Diff) uint64 {
	if d.Left != nil {
		return d.Left.PlayerID
	}
	if d.Right != nil {
		return d.Right.PlayerID
	}
	return 0
}

func val(e *Entry) int64 {
	if e == nil {
		return 0
	}
	return e.Value
}

// file: internal/saga/recon/recon_test.go
// tier: L1
// verify: go test ./internal/saga/recon/ -v

package recon

import "testing"

func ledger(entries ...Entry) map[string]Entry {
	m := map[string]Entry{}
	for _, e := range entries {
		m[e.Key] = e
	}
	return m
}

func TestReconGradesRepairsAndTickets(t *testing.T) {
	// The game shard recorded four lines; the cross-server center recorded a
	// slightly different set. Every interesting case is present once.
	game := ledger(
		Entry{Key: "o1", PlayerID: 10, Kind: KindAmount, Value: 300}, // agree
		Entry{Key: "o2", PlayerID: 20, Kind: KindAmount, Value: 500}, // mismatch
		Entry{Key: "o3", PlayerID: 30, Kind: KindAmount, Value: 120}, // game-only
		Entry{Key: "o4", PlayerID: 40, Kind: KindDisplay, Value: 1},  // cosmetic drift
	)
	center := ledger(
		Entry{Key: "o1", PlayerID: 10, Kind: KindAmount, Value: 300},
		Entry{Key: "o2", PlayerID: 20, Kind: KindAmount, Value: 550},
		Entry{Key: "o4", PlayerID: 40, Kind: KindDisplay, Value: 2},
		Entry{Key: "o5", PlayerID: 50, Kind: KindAmount, Value: 90}, // center-only
	)

	r := &Reconciler{}
	diffs := r.Compare(game, center)
	want := map[string]Class{
		"o1": ClassMatch, "o2": ClassTicket, "o3": ClassRepairable,
		"o4": ClassTolerable, "o5": ClassRepairable,
	}
	for _, d := range diffs {
		if want[d.Key] != d.Class {
			t.Fatalf("key %s class=%v want %v", d.Key, d.Class, want[d.Key])
		}
	}

	tickets := r.Apply(game, center, diffs)
	if center["o3"].Value != 120 || game["o5"].Value != 90 {
		t.Fatalf("repairable rows not mirrored: o3=%+v o5=%+v", center["o3"], game["o5"])
	}
	if len(tickets) != 1 || tickets[0].Key != "o2" || tickets[0].State != "open" {
		t.Fatalf("tickets=%+v want exactly o2 open", tickets)
	}
	if tickets[0].LeftValue != 500 || tickets[0].RightValue != 550 || tickets[0].PlayerID != 20 {
		t.Fatalf("ticket fields=%+v", tickets[0])
	}
}