《互联网产品的服务端架构·交易、增长与平台化》1.3 库存对账与回补

Expected = LedgerIn - LedgerOut
Diff     = OnHand + Reserved - Expected

// file: internal/catalog/reconcile.go
// tier: L1
// verify: go test ./internal/catalog/

package catalog

import (
	"errors"
	"fmt"
)

// Snapshot is one SKU's inventory view at a point in time. LedgerIn and
// LedgerOut come from the append-only inventory journal; OnHand and Reserved
// come from the operational stock table. The journal is the source of truth:
// a snapshot that disagrees with it is drift, not a new balance.
type Snapshot struct {
	SKU       string
	LedgerIn  int64
	LedgerOut int64
	OnHand    int64
	Reserved  int64
}

var (
	ErrInvalidSnapshot  = errors.New("catalog: invalid snapshot")
	ErrInvalidTolerance = errors.New("catalog: tolerance must not be negative")
)

// Diff returns OnHand + Reserved - (LedgerIn - LedgerOut). A positive result
// means the stock table holds more units than the journal explains; a
// negative result means units are missing. Zero means the two views agree.
func Diff(s Snapshot) (int64, error) {
	if err := validateSnapshot(s); err != nil {
		return 0, err
	}
	expected := s.LedgerIn - s.LedgerOut
	// OnHand and Reserved are individually valid but their sum can still
	// overflow. Reject that instead of returning a wrapped number that would
	// look like a huge reconciliation difference.
	if s.OnHand > maxInt64-s.Reserved {
		return 0, fmt.Errorf("%w: stock sum overflow", ErrInvalidSnapshot)
	}
	return s.OnHand + s.Reserved - expected, nil
}

// Broken reports whether the absolute difference exceeds tolerance. The
// comparison avoids an abs() call so that no intermediate value can overflow.
func Broken(s Snapshot, tolerance int64) (bool, error) {
	if tolerance < 0 {
		return false, ErrInvalidTolerance
	}
	d, err := Diff(s)
	if err != nil {
		return false, err
	}
	return d > tolerance || d < -tolerance, nil
}

func validateSnapshot(s Snapshot) error {
	if s.SKU == "" {
		return fmt.Errorf("%w: empty sku", ErrInvalidSnapshot)
	}
	if s.LedgerIn < 0 || s.LedgerOut < 0 || s.OnHand < 0 || s.Reserved < 0 {
		return fmt.Errorf("%w: negative quantity", ErrInvalidSnapshot)
	}
	if s.LedgerOut > s.LedgerIn {
		return fmt.Errorf("%w: ledger out exceeds in", ErrInvalidSnapshot)
	}
	return nil
}

// file: internal/catalog/reconcile_test.go
// tier: L1
// verify: go test ./internal/catalog/

package catalog

import (
	"errors"
	"testing"
)

func TestDiffBalancedSnapshot(t *testing.T) {
	s := Snapshot{
		SKU:       "sku-1001",
		LedgerIn:  100,
		LedgerOut: 37,
		OnHand:    50,
		Reserved:  13,
	}
	got, err := Diff(s)
	if err != nil {
		t.Fatal(err)
	}
	if got != 0 {
		t.Fatalf("diff = %d, want 0", got)
	}
}

func TestDiffReportsBothDirections(t *testing.T) {
	base := Snapshot{SKU: "sku-1001", LedgerIn: 100, LedgerOut: 30}
	cases := []struct {
		name string
		s    Snapshot
		want int64
	}{
		{"over-stock", func() Snapshot { x := base; x.OnHand = 60; x.Reserved = 15; return x }(), 5},
		{"missing-stock", func() Snapshot { x := base; x.OnHand = 60; x.Reserved = 5; return x }(), -5},
		{"reserved-counts", func() Snapshot { x := base; x.OnHand = 60; x.Reserved = 10; return x }(), 0},
	}
	for _, c := range cases {
		t.Run(c.name, func(t *testing.T) {
			got, err := Diff(c.s)
			if err != nil {
				t.Fatal(err)
			}
			if got != c.want {
				t.Fatalf("diff = %d, want %d", got, c.want)
			}
		})
	}
}

func TestBrokenUsesInclusiveTolerance(t *testing.T) {
	s := Snapshot{SKU: "sku-1001", LedgerIn: 100, LedgerOut: 30, OnHand: 60, Reserved: 15}
	negative := Snapshot{SKU: "sku-1001", LedgerIn: 100, LedgerOut: 30, OnHand: 60, Reserved: 5}
	cases := []struct {
		name      string
		s         Snapshot
		tolerance int64
		want      bool
	}{
		{"positive-at-boundary", s, 5, false},
		{"positive-below-boundary", s, 4, true},
		{"positive-above-boundary", s, 6, false},
		{"negative-at-boundary", negative, 5, false},
	}
	for _, c := range cases {
		t.Run(c.name, func(t *testing.T) {
			got, err := Broken(c.s, c.tolerance)
			if err != nil {
				t.Fatal(err)
			}
			if got != c.want {
				t.Fatalf("broken = %v, want %v", got, c.want)
			}
		})
	}
}

func TestBrokenNegativeDrift(t *testing.T) {
	s := Snapshot{SKU: "sku-1001", LedgerIn: 100, LedgerOut: 30, OnHand: 60, Reserved: 5}
	got, err := Broken(s, 4)
	if err != nil {
		t.Fatal(err)
	}
	if !got {
		t.Fatal("negative drift of 5 should exceed tolerance 4")
	}
}

func TestReconcileRejectsInvalidInput(t *testing.T) {
	valid := Snapshot{SKU: "sku-1001", LedgerIn: 10, LedgerOut: 2, OnHand: 6, Reserved: 2}
	cases := []struct {
		name string
		fn   func() (int64, error)
		want error
	}{
		{"empty-sku", func() (int64, error) { return Diff(Snapshot{LedgerIn: 1}) }, ErrInvalidSnapshot},
		{"negative-on-hand", func() (int64, error) {
			x := valid
			x.OnHand = -1
			return Diff(x)
		}, ErrInvalidSnapshot},
		{"negative-reserved", func() (int64, error) {
			x := valid
			x.Reserved = -1
			return Diff(x)
		}, ErrInvalidSnapshot},
		{"ledger-out-exceeds-in", func() (int64, error) {
			x := valid
			x.LedgerOut = 11
			return Diff(x)
		}, ErrInvalidSnapshot},
		{"invalid-tolerance", func() (int64, error) {
			_, err := Broken(valid, -1)
			if err != nil {
				return 0, err
			}
			return 1, nil
		}, ErrInvalidTolerance},
	}
	for _, c := range cases {
		t.Run(c.name, func(t *testing.T) {
			if _, err := c.fn(); !errors.Is(err, c.want) {
				t.Fatalf("err = %v, want %v", err, c.want)
			}
		})
	}
}

func TestDiffRejectsStockSumOverflow(t *testing.T) {
	s := Snapshot{SKU: "sku-1001", LedgerIn: maxInt64, LedgerOut: 0, OnHand: maxInt64, Reserved: 1}
	if _, err := Diff(s); !errors.Is(err, ErrInvalidSnapshot) {
		t.Fatalf("err = %v, want ErrInvalidSnapshot", err)
	}
}

cd .local/checks/webapp-lab && go test ./internal/catalog/ -count=1

ok  	webapp/internal/catalog	0.228s