《后端架构设计·演进与治理》12.2 容量与成本：预留、弹性与闲置回收

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

import (
	"fmt"
	"sort"
)

// CapacityPlan is one monthly capacity decision: how much to reserve, what
// elasticity costs, and how much idle reserve is tolerated.
type CapacityPlan struct {
	Name              string
	BaselineUnits     int64 // p95 demand: capacity that must exist for the SLO
	ReservedUnits     int64
	ReservedUnitCents int64 // billed whether used or not
	OnDemandUnitCents int64 // billed only while serving
	IdleTolerance     float64
}

// CapacityResult is the price and the risk of a plan.
type CapacityResult struct {
	ReservedCost    int64
	ElasticCost     int64
	IdleCost        int64
	TotalCents      int64
	Coverage        float64
	Utilization     float64
	WasteUnits      int64
	WasteShare      float64
	BreakEvenUse    float64
	ReservePaysOff  bool
	WithinTolerance bool
}

// Evaluate prices the plan. Reserved units cover demand first; demand above
// the reservation is bought on demand; reserved units above demand are idle
// and still billed.
func (p CapacityPlan) Evaluate() (CapacityResult, error) {
	if p.BaselineUnits < 0 || p.ReservedUnits < 0 {
		return CapacityResult{}, fmt.Errorf("cost: plan %q has negative units", p.Name)
	}
	if p.ReservedUnitCents < 0 || p.OnDemandUnitCents < 0 {
		return CapacityResult{}, fmt.Errorf("cost: plan %q has negative price", p.Name)
	}
	if p.IdleTolerance < 0 || p.IdleTolerance > 1 {
		return CapacityResult{}, fmt.Errorf("cost: plan %q idle tolerance must be within [0,1]", p.Name)
	}

	used := p.ReservedUnits
	if p.BaselineUnits < used {
		used = p.BaselineUnits
	}
	elastic := p.BaselineUnits - used
	if elastic < 0 {
		elastic = 0
	}
	waste := p.ReservedUnits - used

	res := CapacityResult{
		ReservedCost: p.ReservedUnits * p.ReservedUnitCents,
		ElasticCost:  elastic * p.OnDemandUnitCents,
		IdleCost:     waste * p.ReservedUnitCents,
		WasteUnits:   waste,
	}
	res.TotalCents = res.ReservedCost + res.ElasticCost
	if p.BaselineUnits > 0 {
		res.Coverage = float64(used) / float64(p.BaselineUnits)
	}
	if p.ReservedUnits > 0 {
		res.Utilization = float64(used) / float64(p.ReservedUnits)
		res.WasteShare = float64(waste) / float64(p.ReservedUnits)
	}
	if p.OnDemandUnitCents > 0 {
		res.BreakEvenUse = float64(p.ReservedUnitCents) / float64(p.OnDemandUnitCents)
	}
	res.ReservePaysOff = res.Utilization >= res.BreakEvenUse
	res.WithinTolerance = res.WasteShare <= p.IdleTolerance
	return res, nil
}

// UtilizationSample is one resource's observed usage over a month.
type UtilizationSample struct {
	ResourceID     string
	AvgUtilization float64
	MonthlyCents   int64
}

// Reclaimable returns idle resources sorted by monthly cost descending, plus
// the total monthly saving if they are switched off. Threshold is the
// utilization below which a resource counts as idle.
func Reclaimable(samples []UtilizationSample, threshold float64) ([]UtilizationSample, int64) {
	if threshold <= 0 || threshold > 1 {
		threshold = 0.10
	}
	var idle []UtilizationSample
	var saving int64
	for _, s := range samples {
		if s.AvgUtilization < threshold && s.MonthlyCents > 0 {
			idle = append(idle, s)
			saving += s.MonthlyCents
		}
	}
	sort.Slice(idle, func(i, j int) bool {
		if idle[i].MonthlyCents != idle[j].MonthlyCents {
			return idle[i].MonthlyCents > idle[j].MonthlyCents
		}
		return idle[i].ResourceID < idle[j].ResourceID
	})
	return idle, saving
}

// file: internal/platform/cost/capacity_test.go
// verify: go test ./internal/platform/cost/ -run 'TestEvaluatePlan|TestReclaimable' -count=1 -v
package cost

import "testing"

func TestEvaluatePlanCoversDemandWithReserve(t *testing.T) {
	plan := CapacityPlan{
		Name:              "order-api-prod",
		BaselineUnits:     100,
		ReservedUnits:     80,
		ReservedUnitCents: 6000,
		OnDemandUnitCents: 10000,
		IdleTolerance:     0.20,
	}
	got, err := plan.Evaluate()
	if err != nil {
		t.Fatalf("Evaluate: %v", err)
	}
	if got.ReservedCost != 480000 || got.ElasticCost != 200000 || got.TotalCents != 680000 {
		t.Fatalf("cost = %+v", got)
	}
	if got.WasteUnits != 0 {
		t.Fatalf("waste units = %d, want 0", got.WasteUnits)
	}
	if got.Coverage != 0.8 {
		t.Fatalf("coverage = %v, want 0.8", got.Coverage)
	}
	if got.BreakEvenUse != 0.6 {
		t.Fatalf("break-even = %v, want 0.6", got.BreakEvenUse)
	}
	if !got.ReservePaysOff || !got.WithinTolerance {
		t.Fatalf("flags = %+v", got)
	}
	t.Logf("baseline=%d reserved=%d total=%d coverage=%.2f breakeven=%.2f",
		plan.BaselineUnits, plan.ReservedUnits, got.TotalCents, got.Coverage, got.BreakEvenUse)
}

func TestEvaluatePlanFlagsIdleReserve(t *testing.T) {
	plan := CapacityPlan{
		Name:              "settlement-overbought",
		BaselineUnits:     60,
		ReservedUnits:     100,
		ReservedUnitCents: 6000,
		OnDemandUnitCents: 10000,
		IdleTolerance:     0.20,
	}
	got, err := plan.Evaluate()
	if err != nil {
		t.Fatalf("Evaluate: %v", err)
	}
	if got.WasteUnits != 40 {
		t.Fatalf("waste units = %d, want 40", got.WasteUnits)
	}
	if got.IdleCost != 240000 {
		t.Fatalf("idle cost = %d, want 240000", got.IdleCost)
	}
	if got.Utilization != 0.6 || got.WasteShare != 0.4 {
		t.Fatalf("utilization = %v waste = %v", got.Utilization, got.WasteShare)
	}
	if got.WithinTolerance {
		t.Fatalf("expected idle reserve to exceed tolerance")
	}
	if !got.ReservePaysOff {
		t.Fatalf("at 60%% utilization the 0.6 break-even is still met")
	}
	t.Logf("waste_units=%d idle_cost=%d utilization=%.2f waste_share=%.2f within_tolerance=%v",
		got.WasteUnits, got.IdleCost, got.Utilization, got.WasteShare, got.WithinTolerance)
}

func TestEvaluatePlanRejectsInvalidInput(t *testing.T) {
	cases := []CapacityPlan{
		{Name: "negative", BaselineUnits: -1},
		{Name: "price", OnDemandUnitCents: -1},
		{Name: "tolerance", IdleTolerance: 1.5},
	}
	for _, c := range cases {
		if _, err := c.Evaluate(); err == nil {
			t.Fatalf("plan %q: expected error", c.Name)
		}
	}
}

func TestReclaimableSortsBySaving(t *testing.T) {
	samples := []UtilizationSample{
		{ResourceID: "vm-a", AvgUtilization: 0.03, MonthlyCents: 40000},
		{ResourceID: "vm-b", AvgUtilization: 0.01, MonthlyCents: 90000},
		{ResourceID: "vm-c", AvgUtilization: 0.55, MonthlyCents: 70000},
		{ResourceID: "vm-d", AvgUtilization: 0.00, MonthlyCents: 5000},
	}
	idle, saving := Reclaimable(samples, 0.10)
	if len(idle) != 3 {
		t.Fatalf("idle count = %d, want 3", len(idle))
	}
	if idle[0].ResourceID != "vm-b" || idle[1].ResourceID != "vm-a" {
		t.Fatalf("order = %v", idle)
	}
	if saving != 135000 {
		t.Fatalf("saving = %d, want 135000", saving)
	}
	t.Logf("idle=%d monthly_saving=%d first=%s", len(idle), saving, idle[0].ResourceID)
}

$ go test ./internal/platform/cost/ -run 'TestEvaluatePlan|TestReclaimable' -v -count=1
=== RUN   TestEvaluatePlanCoversDemandWithReserve
    capacity_test.go:33: baseline=100 reserved=80 total=680000 coverage=0.80 breakeven=0.60
--- PASS: TestEvaluatePlanCoversDemandWithReserve (0.00s)
=== RUN   TestEvaluatePlanFlagsIdleReserve
    capacity_test.go:65: waste_units=40 idle_cost=240000 utilization=0.60 waste_share=0.40 within_tolerance=false
--- PASS: TestEvaluatePlanFlagsIdleReserve (0.00s)
=== RUN   TestEvaluatePlanRejectsInvalidInput
--- PASS: TestEvaluatePlanRejectsInvalidInput (0.00s)
=== RUN   TestReclaimableSortsBySaving
    capacity_test.go:99: idle=3 monthly_saving=135000 first=vm-b
--- PASS: TestReclaimableSortsBySaving (0.00s)
PASS
ok  	archlab/internal/platform/cost	0.240s