《后端架构设计·演进与治理》12.3 成本治理机制：预算、评审与责任到团队

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

import (
	"fmt"
	"sort"
	"strings"
)

// SpendPoint is one day of spend for a scope.
type SpendPoint struct {
	Day   int
	Cents int64
}

// BudgetStatus is the outcome of a budget evaluation.
type BudgetStatus string

const (
	BudgetOK     BudgetStatus = "ok"
	BudgetWarn   BudgetStatus = "warn"
	BudgetBreach BudgetStatus = "breach"
)

// Budget is a cap owned by one team or service.
type Budget struct {
	Scope      string
	LimitCents int64
	PeriodDays int
	WarnRatio  float64
}

// BudgetEval is the projected end-of-period position.
type BudgetEval struct {
	Scope         string
	SpentCents    int64
	ForecastCents int64
	LimitCents    int64
	Status        BudgetStatus
	ExhaustDay    int // first day cumulative spend exceeds the limit, or -1
}

// EvaluateBudget forecasts the period from the trailing seven days. The rule
// is intentionally naive: a gate must be explainable to the team paying.
func EvaluateBudget(b Budget, points []SpendPoint) (BudgetEval, error) {
	if strings.TrimSpace(b.Scope) == "" || b.LimitCents <= 0 || b.PeriodDays <= 0 {
		return BudgetEval{}, fmt.Errorf("cost: budget %q has invalid scope, limit, or period", b.Scope)
	}
	if b.WarnRatio <= 0 || b.WarnRatio > 1 {
		return BudgetEval{}, fmt.Errorf("cost: budget %q warn ratio must be within (0,1]", b.Scope)
	}
	pts := append([]SpendPoint(nil), points...)
	sort.Slice(pts, func(i, j int) bool { return pts[i].Day < pts[j].Day })

	eval := BudgetEval{Scope: b.Scope, LimitCents: b.LimitCents, ExhaustDay: -1}
	for i, p := range pts {
		if p.Cents < 0 {
			return BudgetEval{}, fmt.Errorf("cost: budget %q has negative spend on day %d", b.Scope, p.Day)
		}
		if i > 0 && p.Day == pts[i-1].Day {
			return BudgetEval{}, fmt.Errorf("cost: budget %q has duplicate day %d", b.Scope, p.Day)
		}
		eval.SpentCents += p.Cents
	}

	if n := len(pts); n > 0 {
		window := n
		if window > 7 {
			window = 7
		}
		var sum int64
		for _, p := range pts[n-window:] {
			sum += p.Cents
		}
		avg := float64(sum) / float64(window)
		eval.ForecastCents = int64(avg*float64(b.PeriodDays) + 0.5)
	}

	var cumulative int64
	for _, p := range pts {
		cumulative += p.Cents
		if cumulative > b.LimitCents {
			eval.ExhaustDay = p.Day
			break
		}
	}

	switch {
	case eval.ForecastCents > b.LimitCents:
		eval.Status = BudgetBreach
	case float64(eval.SpentCents) >= b.WarnRatio*float64(b.LimitCents):
		eval.Status = BudgetWarn
	default:
		eval.Status = BudgetOK
	}
	return eval, nil
}

// Anomaly is a day whose spend is far from the trailing median.
type Anomaly struct {
	Day    int
	Cents  int64
	Median int64
	MAD    int64
	Score  float64
}

// DetectSpikes flags days above the trailing median using a modified z-score.
// A zero MAD means a flat baseline, so the rule falls back to a 1.5x ratio
// instead of dividing by zero.
func DetectSpikes(points []SpendPoint, window int, threshold float64) []Anomaly {
	if window < 3 {
		window = 3
	}
	if threshold <= 0 {
		threshold = 3.5
	}
	pts := append([]SpendPoint(nil), points...)
	sort.Slice(pts, func(i, j int) bool { return pts[i].Day < pts[j].Day })

	var out []Anomaly
	for i := window; i < len(pts); i++ {
		win := make([]int64, 0, window)
		for _, p := range pts[i-window : i] {
			win = append(win, p.Cents)
		}
		med := medianInt64(win)
		mad := medianInt64(absoluteDeviations(win, med))
		var score float64
		spike := false
		if mad == 0 {
			if med > 0 && pts[i].Cents*2 > med*3 {
				spike, score = true, float64(pts[i].Cents)/float64(med)
			}
		} else {
			score = 0.6745 * float64(pts[i].Cents-med) / float64(mad)
			spike = score > threshold
		}
		if spike {
			out = append(out, Anomaly{Day: pts[i].Day, Cents: pts[i].Cents,
				Median: med, MAD: mad, Score: score})
		}
	}
	return out
}

func medianInt64(values []int64) int64 {
	if len(values) == 0 {
		return 0
	}
	sorted := append([]int64(nil), values...)
	sort.Slice(sorted, func(i, j int) bool { return sorted[i] < sorted[j] })
	mid := len(sorted) / 2
	if len(sorted)%2 == 1 {
		return sorted[mid]
	}
	return (sorted[mid-1] + sorted[mid]) / 2
}

func absoluteDeviations(values []int64, center int64) []int64 {
	out := make([]int64, 0, len(values))
	for _, v := range values {
		d := v - center
		if d < 0 {
			d = -d
		}
		out = append(out, d)
	}
	return out
}

// Owner resolves the accountable team for a scope. explicit is false when the
// scope falls back to the platform team, which the report must surface rather
// than hide.
func Owner(scope string, owners map[string]string) (team string, explicit bool) {
	if t := strings.TrimSpace(owners[scope]); t != "" {
		return t, true
	}
	return "team-platform", false
}

// file: internal/platform/cost/governance_test.go
// verify: go test ./internal/platform/cost/ -run 'TestEvaluateBudget|TestDetectSpikes|TestOwner' -count=1 -v
package cost

import "testing"

func monthOf(daily int64, days int) []SpendPoint {
	pts := make([]SpendPoint, 0, days)
	for d := 1; d <= days; d++ {
		pts = append(pts, SpendPoint{Day: d, Cents: daily})
	}
	return pts
}

func TestEvaluateBudgetStatuses(t *testing.T) {
	b := Budget{Scope: "team-order", LimitCents: 1000000, PeriodDays: 30, WarnRatio: 0.8}
	cases := []struct {
		name  string
		pts   []SpendPoint
		want  BudgetStatus
		spent int64
	}{
		{"on-track", monthOf(20000, 15), BudgetOK, 300000},
		{"warn", monthOf(30000, 30), BudgetWarn, 900000},
		{"breach", monthOf(40000, 30), BudgetBreach, 1200000},
	}
	for _, c := range cases {
		got, err := EvaluateBudget(b, c.pts)
		if err != nil {
			t.Fatalf("%s: %v", c.name, err)
		}
		if got.Status != c.want || got.SpentCents != c.spent {
			t.Fatalf("%s: status=%s spent=%d", c.name, got.Status, got.SpentCents)
		}
		t.Logf("case=%s spent=%d forecast=%d status=%s exhaust_day=%d",
			c.name, got.SpentCents, got.ForecastCents, got.Status, got.ExhaustDay)
	}
}

func TestDetectSpikesOnFlatBaseline(t *testing.T) {
	pts := append(monthOf(1000, 10), SpendPoint{Day: 11, Cents: 5000})
	got := DetectSpikes(pts, 5, 3.5)
	if len(got) != 1 || got[0].Day != 11 || got[0].MAD != 0 {
		t.Fatalf("anomalies = %+v", got)
	}
	t.Logf("day=%d cents=%d median=%d mad=%d score=%.2f",
		got[0].Day, got[0].Cents, got[0].Median, got[0].MAD, got[0].Score)
}

func TestDetectSpikesOnNoisyBaseline(t *testing.T) {
	daily := []int64{100, 120, 90, 110, 105, 100, 95, 100, 500}
	pts := make([]SpendPoint, 0, len(daily))
	for i, v := range daily {
		pts = append(pts, SpendPoint{Day: i + 1, Cents: v})
	}
	got := DetectSpikes(pts, 4, 3.5)
	if len(got) != 1 || got[0].Day != 9 {
		t.Fatalf("anomalies = %+v, want day 9 only", got)
	}
	t.Logf("day=%d cents=%d median=%d mad=%d score=%.2f",
		got[0].Day, got[0].Cents, got[0].Median, got[0].MAD, got[0].Score)
}

func TestOwnerFallsBackToPlatform(t *testing.T) {
	owners := map[string]string{"order-api": "team-order", "payment": " "}
	if team, ok := Owner("order-api", owners); team != "team-order" || !ok {
		t.Fatalf("owner = %q explicit=%v", team, ok)
	}
	if team, ok := Owner("payment", owners); team != "team-platform" || ok {
		t.Fatalf("fallback = %q explicit=%v", team, ok)
	}
	t.Logf("explicit=team-order fallback=team-platform")
}

$ go test ./internal/platform/cost/ -run 'TestEvaluateBudget|TestDetectSpikes|TestOwner' -v -count=1
=== RUN   TestEvaluateBudgetStatuses
    governance_test.go:33: case=on-track spent=300000 forecast=600000 status=ok exhaust_day=-1
    governance_test.go:33: case=warn spent=900000 forecast=900000 status=warn exhaust_day=-1
    governance_test.go:33: case=breach spent=1200000 forecast=1200000 status=breach exhaust_day=26
--- PASS: TestEvaluateBudgetStatuses (0.00s)
=== RUN   TestDetectSpikesOnFlatBaseline
    governance_test.go:44: day=11 cents=5000 median=1000 mad=0 score=5.00
--- PASS: TestDetectSpikesOnFlatBaseline (0.00s)
=== RUN   TestDetectSpikesOnNoisyBaseline
    governance_test.go:58: day=9 cents=500 median=100 mad=2 score=134.90
--- PASS: TestDetectSpikesOnNoisyBaseline (0.00s)
=== RUN   TestOwnerFallsBackToPlatform
    governance_test.go:70: explicit=team-order fallback=team-platform
--- PASS: TestOwnerFallsBackToPlatform (0.00s)
PASS
ok  	archlab/internal/platform/cost	0.251s