《后端架构设计·分布式与数据一致性》9.2 对账系统：T+1、实时与差异分类

平台支付成功 ──> 渠道 pending ──(宽限期内)──> deferred，不告警
                                └─(超过宽限期)─> status 差异，进入处置

// file: internal/platform/reconcile/reconcile.go
// tier: L1
// verify: go test ./internal/platform/reconcile/ -count=1
package reconcile

import (
	"fmt"
	"sort"
	"time"
)

// Direction separates a payment from its refund so both may share an order
// number without being netted into one row.
type Direction string

const (
	Pay    Direction = "pay"
	Refund Direction = "refund"
)

func (d Direction) valid() bool { return d == Pay || d == Refund }

// Status is the settlement state reported by one side.
type Status string

const (
	Success Status = "success"
	Failed  Status = "failed"
	Pending Status = "pending"
)

func (s Status) valid() bool { return s == Success || s == Failed || s == Pending }

// Txn is one normalized record. AmountCents is always positive; Direction
// carries the sign so refunds never rely on negative-amount parsing.
type Txn struct {
	ID          string
	OrderNo     string
	Direction   Direction
	AmountCents int64
	Status      Status
	OccurredAt  time.Time
}

func (t Txn) validate() error {
	if t.ID == "" || t.OrderNo == "" {
		return fmt.Errorf("reconcile: record needs id and order_no, got id=%q order_no=%q", t.ID, t.OrderNo)
	}
	if !t.Direction.valid() || !t.Status.valid() {
		return fmt.Errorf("reconcile: record %s has direction=%q status=%q", t.ID, t.Direction, t.Status)
	}
	if t.AmountCents <= 0 {
		return fmt.Errorf("reconcile: record %s has non-positive amount %d", t.ID, t.AmountCents)
	}
	return nil
}

// DiffKind is the classification an operator acts on.
type DiffKind string

const (
	MissingPlatform DiffKind = "missing_platform" // channel has money, platform has no order
	MissingChannel  DiffKind = "missing_channel"  // platform has an order, channel has no money
	AmountMismatch  DiffKind = "amount"
	StatusMismatch  DiffKind = "status"
	Duplicate       DiffKind = "duplicate"
)

// Options controls the settlement window.
type Options struct {
	Grace time.Duration
	AsOf  time.Time
}

func (o Options) validate() error {
	if o.Grace < 0 {
		return fmt.Errorf("reconcile: grace must not be negative, got %v", o.Grace)
	}
	if o.AsOf.IsZero() {
		return fmt.Errorf("reconcile: AsOf must be set")
	}
	return nil
}

// Diff is one actionable mismatch.
type Diff struct {
	OrderNo       string
	Direction     Direction
	Kind          DiffKind
	PlatformCount int
	ChannelCount  int
	PlatformCents int64
	ChannelCents  int64
	Detail        string
}

// Result is the outcome of one reconciliation run.
type Result struct {
	Matched  int
	Deferred int
	Diffs    []Diff
}

type groupKey struct {
	orderNo   string
	direction Direction
}

func aggregate(txns []Txn) map[groupKey][]Txn {
	out := make(map[groupKey][]Txn)
	for _, t := range txns {
		k := groupKey{orderNo: t.OrderNo, direction: t.Direction}
		out[k] = append(out[k], t)
	}
	return out
}

func sumCents(txns []Txn) int64 {
	var sum int64
	for _, t := range txns {
		sum += t.AmountCents
	}
	return sum
}

// dominantStatus collapses one side to a verdict. Success wins because a
// channel retry may leave a failed attempt beside the successful one.
func dominantStatus(txns []Txn) Status {
	status := Pending
	for _, t := range txns {
		if t.Status == Success {
			return Success
		}
		if t.Status == Failed {
			status = Failed
		}
	}
	return status
}

func newest(txns []Txn) time.Time {
	var latest time.Time
	for _, t := range txns {
		if t.OccurredAt.After(latest) {
			latest = t.OccurredAt
		}
	}
	return latest
}

// Run compares the platform ledger with the channel bill. Matching is keyed by
// (order_no, direction); amount and status only classify a matched pair.
func Run(platform, channel []Txn, opt Options) (Result, error) {
	if err := opt.validate(); err != nil {
		return Result{}, err
	}
	for _, t := range platform {
		if err := t.validate(); err != nil {
			return Result{}, err
		}
	}
	for _, t := range channel {
		if err := t.validate(); err != nil {
			return Result{}, err
		}
	}

	pg, cg := aggregate(platform), aggregate(channel)
	seen := make(map[groupKey]bool, len(pg)+len(cg))
	keys := make([]groupKey, 0, len(pg)+len(cg))
	for _, m := range []map[groupKey][]Txn{pg, cg} {
		for k := range m {
			if !seen[k] {
				seen[k] = true
				keys = append(keys, k)
			}
		}
	}
	sort.Slice(keys, func(i, j int) bool {
		if keys[i].orderNo != keys[j].orderNo {
			return keys[i].orderNo < keys[j].orderNo
		}
		return keys[i].direction < keys[j].direction
	})

	res := Result{}
	for _, k := range keys {
		p, c := pg[k], cg[k]
		d := Diff{OrderNo: k.orderNo, Direction: k.direction,
			PlatformCount: len(p), ChannelCount: len(c),
			PlatformCents: sumCents(p), ChannelCents: sumCents(c)}

		switch {
		case len(p) > 1 || len(c) > 1:
			d.Kind = Duplicate
			d.Detail = "more than one record for the same order and direction"
		case len(c) == 0:
			d.Kind, d.Detail = MissingChannel, "platform record has no channel settlement"
		case len(p) == 0:
			d.Kind, d.Detail = MissingPlatform, "channel settlement has no platform order"
		case d.PlatformCents != d.ChannelCents:
			d.Kind, d.Detail = AmountMismatch, "amount differs"
		case dominantStatus(p) != dominantStatus(c):
			if (dominantStatus(p) == Pending || dominantStatus(c) == Pending) &&
				opt.AsOf.Sub(newest(append(append([]Txn{}, p...), c...))) < opt.Grace {
				res.Deferred++
				continue
			}
			d.Kind = StatusMismatch
			d.Detail = fmt.Sprintf("status %s vs %s", dominantStatus(p), dominantStatus(c))
		default:
			res.Matched++
			continue
		}
		res.Diffs = append(res.Diffs, d)
	}
	return res, nil
}

$ go test ./internal/platform/reconcile/ -count=1 -v
=== RUN   TestRunTable/exact_match
    reconcile_test.go:116: case="exact match" matched=2 deferred=0 diffs=[]
=== RUN   TestRunTable/platform_only_means_no_money_arrived
    reconcile_test.go:116: case="platform only means no money arrived" matched=0 deferred=0 diffs=[missing_channel:o-3]
=== RUN   TestRunTable/channel_only_means_money_without_an_order
    reconcile_test.go:116: case="channel only means money without an order" matched=0 deferred=0 diffs=[missing_platform:o-4]
=== RUN   TestRunTable/amount_mismatch
    reconcile_test.go:116: case="amount mismatch" matched=0 deferred=0 diffs=[amount:o-5]
=== RUN   TestRunTable/duplicate_channel_record
    reconcile_test.go:116: case="duplicate channel record" matched=0 deferred=0 diffs=[duplicate:o-6]
=== RUN   TestRunTable/pending_within_grace_is_deferred
    reconcile_test.go:116: case="pending within grace is deferred" matched=0 deferred=1 diffs=[]
=== RUN   TestRunTable/failed_versus_success_is_a_status_diff
    reconcile_test.go:116: case="failed versus success is a status diff" matched=0 deferred=0 diffs=[status:o-9]
PASS
ok  	archlab/internal/platform/reconcile	0.354s