《游戏服务端架构·规模化、全球化与成本》6.3 对账、补偿与定时任务

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

import (
	"sort"
)

// Entry 是对账两侧共用的最小账目字段。
type Entry struct {
	OrderID string
	Account string
	Amount  int64
	Status  string
}

// Kind 是差异分类；分类决定补偿动作，而不是由告警人手工判断。
type Kind string

const (
	MissingRemote Kind = "missing_remote"
	MissingLocal  Kind = "missing_local"
	AmountDiff    Kind = "amount_mismatch"
	StatusDiff    Kind = "status_mismatch"
	Duplicate     Kind = "duplicate"
)

// Diff 描述一条订单在两侧的差异。
type Diff struct {
	Kind     Kind
	OrderID  string
	Expected Entry
	Actual   Entry
}

// Reconcile 以订单号为主键比较两侧快照，输出按订单号排序，保证重跑结果稳定。
func Reconcile(expected, actual []Entry) []Diff {
	exp := make(map[string]Entry, len(expected))
	expDup := make(map[string]bool)
	for _, e := range expected {
		if _, ok := exp[e.OrderID]; ok {
			expDup[e.OrderID] = true
		}
		exp[e.OrderID] = e
	}
	act := make(map[string][]Entry, len(actual))
	for _, a := range actual {
		act[a.OrderID] = append(act[a.OrderID], a)
	}

	var diffs []Diff
	for id, e := range exp {
		rows := act[id]
		if len(rows) == 0 {
			diffs = append(diffs, Diff{Kind: MissingRemote, OrderID: id, Expected: e})
			continue
		}
		if len(rows) > 1 || expDup[id] {
			diffs = append(diffs, Diff{Kind: Duplicate, OrderID: id, Expected: e, Actual: rows[0]})
			continue
		}
		a := rows[0]
		if e.Amount != a.Amount {
			diffs = append(diffs, Diff{Kind: AmountDiff, OrderID: id, Expected: e, Actual: a})
			continue
		}
		if e.Status != a.Status {
			diffs = append(diffs, Diff{Kind: StatusDiff, OrderID: id, Expected: e, Actual: a})
		}
	}
	for id, rows := range act {
		if _, ok := exp[id]; ok {
			continue
		}
		diffs = append(diffs, Diff{Kind: MissingLocal, OrderID: id, Actual: rows[0]})
	}

	sort.Slice(diffs, func(i, j int) bool {
		if diffs[i].OrderID != diffs[j].OrderID {
			return diffs[i].OrderID < diffs[j].OrderID
		}
		return diffs[i].Kind < diffs[j].Kind
	})
	return diffs
}

// Task 是一条可执行的补偿任务；同一订单的多种差异合并为一条任务。
type Task struct {
	OrderID  string
	Kinds    []Kind
	Attempts int
	Max      int
	State    string
}

const (
	Pending   = "pending"
	Escalated = "escalated"
)

// Plan 把差异转成补偿任务。自动重试有上限，超过后转人工工单。
func Plan(diffs []Diff, maxAttempts int) []Task {
	if maxAttempts < 1 {
		maxAttempts = 1
	}
	byOrder := make(map[string][]Kind)
	for _, d := range diffs {
		byOrder[d.OrderID] = append(byOrder[d.OrderID], d.Kind)
	}
	tasks := make([]Task, 0, len(byOrder))
	for id, kinds := range byOrder {
		tasks = append(tasks, Task{
			OrderID: id,
			Kinds:   kinds,
			Max:     maxAttempts,
			State:   Pending,
		})
	}
	sort.Slice(tasks, func(i, j int) bool { return tasks[i].OrderID < tasks[j].OrderID })
	return tasks
}

// Fail 记录一次失败；返回 true 表示本次失败后应转人工。
func (t *Task) Fail() bool {
	t.Attempts++
	if t.Attempts >= t.Max {
		t.State = Escalated
	}
	return t.State == Escalated
}

cd .local/checks/gsarch-lab
go test -count=1 ./internal/reconjobs/
ok  gsarchlab/internal/reconjobs