《互联网产品的服务端架构·交易、增长与平台化》12.3 报表口径与数据一致性

// file: internal/admin/report.go
// tier: L1
// verify: go test ./internal/admin/

package admin

import (
	"errors"
	"fmt"
	"math"
	"strings"
)

var (
	// ErrEmptyDate 表示报表行没有日期，无法归属到任何口径。
	ErrEmptyDate = errors.New("admin: empty report date")
	// ErrDuplicateDate 表示同一份报表里出现了重复日期。
	ErrDuplicateDate = errors.New("admin: duplicate report date")
	// ErrNegativeAmount 表示金额或单量出现负数，通常是口径错误。
	ErrNegativeAmount = errors.New("admin: negative amount")
	// ErrOverflow 表示累加结果超出 int64 范围。
	ErrOverflow = errors.New("admin: report total overflow")
	// ErrNegativeTolerance 表示对账容差为负数。
	ErrNegativeTolerance = errors.New("admin: negative tolerance")
)

// Row 是一天的报表数据。金额单位是分，使用 int64 避免浮点误差；
// Orders 是有效订单数，Refunds 是退款单数，两者口径必须先定义清楚。
type Row struct {
	Date    string
	GMV     int64
	Orders  int64
	Refunds int64
}

// Totals 是一段时间内各指标的汇总。
type Totals struct {
	GMV     int64
	Orders  int64
	Refunds int64
}

// Aggregate 按行汇总报表。日期不能为空且不能重复；金额和单量不能为负；
// 任意字段累加溢出 int64 时返回 ErrOverflow，而不是悄悄回绕。
func Aggregate(rows []Row) (Totals, error) {
	var total Totals
	seen := make(map[string]struct{}, len(rows))
	for i, row := range rows {
		if strings.TrimSpace(row.Date) == "" {
			return Totals{}, fmt.Errorf("%w: index %d", ErrEmptyDate, i)
		}
		if _, ok := seen[row.Date]; ok {
			return Totals{}, fmt.Errorf("%w: %q", ErrDuplicateDate, row.Date)
		}
		seen[row.Date] = struct{}{}
		if row.GMV < 0 || row.Orders < 0 || row.Refunds < 0 {
			return Totals{}, fmt.Errorf("%w: date %q", ErrNegativeAmount, row.Date)
		}

		var ok bool
		if total.GMV, ok = addInt64(total.GMV, row.GMV); !ok {
			return Totals{}, fmt.Errorf("%w: gmv date %q", ErrOverflow, row.Date)
		}
		if total.Orders, ok = addInt64(total.Orders, row.Orders); !ok {
			return Totals{}, fmt.Errorf("%w: orders date %q", ErrOverflow, row.Date)
		}
		if total.Refunds, ok = addInt64(total.Refunds, row.Refunds); !ok {
			return Totals{}, fmt.Errorf("%w: refunds date %q", ErrOverflow, row.Date)
		}
	}
	return total, nil
}

// Check 比较业务库与财务库的汇总。订单数和退款数必须完全相等；
// GMV 允许 abs(biz-fin) <= toleranceCents 的差额，用来吸收手续费、
// 汇率或入账时点造成的分位差。容差为负直接报错，避免“负容差永远对不上”。
func Check(biz, fin Totals, toleranceCents int64) (bool, error) {
	if toleranceCents < 0 {
		return false, fmt.Errorf("%w: %d", ErrNegativeTolerance, toleranceCents)
	}
	if biz.Orders != fin.Orders || biz.Refunds != fin.Refunds {
		return false, nil
	}
	diff, ok := diffAbs(biz.GMV, fin.GMV)
	if !ok {
		return false, ErrOverflow
	}
	return diff <= toleranceCents, nil
}

func addInt64(a, b int64) (int64, bool) {
	if b > 0 && a > math.MaxInt64-b {
		return 0, false
	}
	if b < 0 && a < math.MinInt64-b {
		return 0, false
	}
	return a + b, true
}

func diffAbs(a, b int64) (int64, bool) {
	if a >= b {
		if b < 0 && a > math.MaxInt64+b {
			return 0, false
		}
		return a - b, true
	}
	return diffAbs(b, a)
}

// file: internal/admin/report_test.go
// tier: L1
// verify: go test ./internal/admin/

package admin

import (
	"errors"
	"math"
	"testing"
)

func TestAggregate(t *testing.T) {
	rows := []Row{
		{Date: "2026-10-01", GMV: 10000, Orders: 10, Refunds: 1},
		{Date: "2026-10-02", GMV: 25000, Orders: 20, Refunds: 2},
	}
	got, err := Aggregate(rows)
	if err != nil {
		t.Fatalf("Aggregate = %v, want nil", err)
	}
	want := Totals{GMV: 35000, Orders: 30, Refunds: 3}
	if got != want {
		t.Fatalf("Aggregate = %+v, want %+v", got, want)
	}
	if empty, err := Aggregate(nil); err != nil || empty != (Totals{}) {
		t.Fatalf("Aggregate(nil) = %+v, %v; want zero, nil", empty, err)
	}
}

func TestAggregateRejectsBadRows(t *testing.T) {
	cases := []struct {
		name string
		rows []Row
		want error
	}{
		{"empty date", []Row{{Date: " ", GMV: 1}}, ErrEmptyDate},
		{"duplicate date", []Row{{Date: "d", GMV: 1}, {Date: "d", GMV: 2}}, ErrDuplicateDate},
		{"negative gmv", []Row{{Date: "d", GMV: -1}}, ErrNegativeAmount},
		{"negative orders", []Row{{Date: "d", Orders: -1}}, ErrNegativeAmount},
		{"negative refunds", []Row{{Date: "d", Refunds: -1}}, ErrNegativeAmount},
	}
	for _, c := range cases {
		if _, err := Aggregate(c.rows); !errors.Is(err, c.want) {
			t.Fatalf("%s = %v, want %v", c.name, err, c.want)
		}
	}
}

func TestAggregateOverflow(t *testing.T) {
	rows := []Row{
		{Date: "d1", GMV: math.MaxInt64},
		{Date: "d2", GMV: 1},
	}
	if _, err := Aggregate(rows); !errors.Is(err, ErrOverflow) {
		t.Fatalf("gmv overflow = %v, want ErrOverflow", err)
	}

	rows = []Row{
		{Date: "d1", Orders: math.MaxInt64},
		{Date: "d2", Orders: 1},
	}
	if _, err := Aggregate(rows); !errors.Is(err, ErrOverflow) {
		t.Fatalf("orders overflow = %v, want ErrOverflow", err)
	}
}

func TestCheckWithinTolerance(t *testing.T) {
	biz := Totals{GMV: 100000, Orders: 100, Refunds: 5}
	fin := Totals{GMV: 99900, Orders: 100, Refunds: 5}
	ok, err := Check(biz, fin, 100)
	if err != nil || !ok {
		t.Fatalf("Check = %v, %v; want true, nil", ok, err)
	}
	if ok, err := Check(biz, fin, 99); err != nil || ok {
		t.Fatalf("Check tight = %v, %v; want false, nil", ok, err)
	}
}

func TestCheckMismatch(t *testing.T) {
	biz := Totals{GMV: 100000, Orders: 100, Refunds: 5}
	if ok, _ := Check(biz, Totals{GMV: 100000, Orders: 101, Refunds: 5}, 100); ok {
		t.Fatal("orders mismatch should fail")
	}
	if ok, _ := Check(biz, Totals{GMV: 100000, Orders: 100, Refunds: 6}, 100); ok {
		t.Fatal("refunds mismatch should fail")
	}
}

func TestCheckNegativeTolerance(t *testing.T) {
	if _, err := Check(Totals{}, Totals{}, -1); !errors.Is(err, ErrNegativeTolerance) {
		t.Fatalf("negative tolerance = %v, want ErrNegativeTolerance", err)
	}
}

cd .local/checks/webapp-lab && go test ./internal/admin/ -run 'TestAggregate|TestCheck' -count=1 -v

=== RUN   TestAggregate
--- PASS: TestAggregate (0.00s)
=== RUN   TestAggregateRejectsBadRows
--- PASS: TestAggregateRejectsBadRows (0.00s)
=== RUN   TestAggregateOverflow
--- PASS: TestAggregateOverflow (0.00s)
=== RUN   TestCheckWithinTolerance
--- PASS: TestCheckWithinTolerance (0.00s)
=== RUN   TestCheckMismatch
--- PASS: TestCheckMismatch (0.00s)
=== RUN   TestCheckNegativeTolerance
--- PASS: TestCheckNegativeTolerance (0.00s)
PASS
ok  	webapp/internal/admin	0.248s