《后端架构设计·演进与治理》12.1 成本归因：标签、分摊与单位经济

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

import (
	"fmt"
	"sort"
)

// Resource is one billable line from a cloud bill.
type Resource struct {
	ID           string
	MonthlyCents int64
	Tags         map[string]string
}

// Dimension is an attribution axis every resource must carry.
type Dimension string

const (
	DimTenant  Dimension = "tenant"
	DimService Dimension = "service"
	DimEnv     Dimension = "env"
	DimOwner   Dimension = "owner"
)

// RequiredDimensions is the minimum tag set finance accepts as attributable.
var RequiredDimensions = []Dimension{DimTenant, DimService, DimEnv, DimOwner}

// Attribution is cost grouped by tag value plus the bucket nobody owns.
type Attribution struct {
	ByDimension map[Dimension]map[string]int64
	Allocated   int64
	Unallocated int64
	Reasons     map[string]int64
}

// Total returns all cost, including the unallocated bucket. It must not sum
// ByDimension, because each resource appears once per dimension.
func (a Attribution) Total() int64 { return a.Allocated + a.Unallocated }

// UnallocatedShare is the fraction of total cost with no owner.
func (a Attribution) UnallocatedShare() float64 {
	if a.Total() == 0 {
		return 0
	}
	return float64(a.Unallocated) / float64(a.Total())
}

// Attribute groups resources by every required dimension. A resource is
// unallocated when a required tag is missing, empty, or the literal "shared".
func Attribute(resources []Resource) Attribution {
	a := Attribution{
		ByDimension: make(map[Dimension]map[string]int64, len(RequiredDimensions)),
		Reasons:     make(map[string]int64),
	}
	for _, d := range RequiredDimensions {
		a.ByDimension[d] = make(map[string]int64)
	}
	for _, r := range resources {
		reason := ""
		for _, d := range RequiredDimensions {
			v := r.Tags[string(d)]
			if v == "" {
				reason = "missing:" + string(d)
				break
			}
			if v == "shared" {
				reason = "shared:" + string(d)
				break
			}
		}
		if reason != "" {
			a.Unallocated += r.MonthlyCents
			a.Reasons[reason] += r.MonthlyCents
			continue
		}
		for _, d := range RequiredDimensions {
			a.ByDimension[d][r.Tags[string(d)]] += r.MonthlyCents
		}
		a.Allocated += r.MonthlyCents
	}
	return a
}

// SharedPool is untagged platform cost split by a driver such as request
// count or active tenant count.
type SharedPool struct {
	Name    string
	Cents   int64
	Weights map[string]int64
}

// Split uses the largest remainder method so shares always sum to Cents.
// Ties are broken by key, which makes the result reproducible.
func (p SharedPool) Split() (map[string]int64, error) {
	if p.Cents < 0 {
		return nil, fmt.Errorf("cost: pool %q has negative amount", p.Name)
	}
	if len(p.Weights) == 0 {
		return nil, fmt.Errorf("cost: pool %q has no weights", p.Name)
	}
	keys := make([]string, 0, len(p.Weights))
	var total int64
	for k, w := range p.Weights {
		if w < 0 {
			return nil, fmt.Errorf("cost: pool %q has negative weight for %q", p.Name, k)
		}
		total += w
		keys = append(keys, k)
	}
	if total == 0 {
		return nil, fmt.Errorf("cost: pool %q weight sum is zero", p.Name)
	}
	sort.Strings(keys)
	out := make(map[string]int64, len(keys))
	type rem struct {
		key string
		r   int64
	}
	rems := make([]rem, 0, len(keys))
	var assigned int64
	for _, k := range keys {
		exact := p.Cents * p.Weights[k]
		out[k] = exact / total
		assigned += out[k]
		rems = append(rems, rem{key: k, r: exact % total})
	}
	sort.Slice(rems, func(i, j int) bool {
		if rems[i].r != rems[j].r {
			return rems[i].r > rems[j].r
		}
		return rems[i].key < rems[j].key
	})
	for i := int64(0); i < p.Cents-assigned; i++ {
		out[rems[i%int64(len(rems))].key]++
	}
	return out, nil
}

// UnitEconomics turns a monthly bill into a per-order number. FixedCents does
// not shrink when volume drops: reserved capacity and control-plane spend.
type UnitEconomics struct {
	TotalCents int64
	FixedCents int64
	OrderCount int64
}

// CostPerOrder is fully loaded cost divided by orders.
func (u UnitEconomics) CostPerOrder() float64 {
	if u.OrderCount <= 0 {
		return 0
	}
	return float64(u.TotalCents) / float64(u.OrderCount)
}

// MarginalCostPerOrder removes fixed spend; it is the number that should
// drive discount approval.
func (u UnitEconomics) MarginalCostPerOrder() float64 {
	if u.OrderCount <= 0 {
		return 0
	}
	variable := u.TotalCents - u.FixedCents
	if variable < 0 {
		variable = 0
	}
	return float64(variable) / float64(u.OrderCount)
}

// ContributionCents is revenue minus fully loaded cost.
func (u UnitEconomics) ContributionCents(revenueCents int64) int64 {
	return revenueCents - u.TotalCents
}

// file: internal/platform/cost/attribution_test.go
// verify: go test ./internal/platform/cost/ -run 'TestAttribute|TestShared|TestUnit' -count=1 -v
package cost

import "testing"

func TestAttributeGroupsAndUnallocated(t *testing.T) {
	resources := []Resource{
		{ID: "vm-web-1", MonthlyCents: 120000, Tags: map[string]string{
			"tenant": "acme", "service": "order-api", "env": "prod", "owner": "team-order"}},
		{ID: "db-order", MonthlyCents: 300000, Tags: map[string]string{
			"tenant": "acme", "service": "order-db", "env": "prod", "owner": "team-order"}},
		{ID: "vm-batch", MonthlyCents: 50000, Tags: map[string]string{
			"tenant": "acme", "service": "settlement", "env": "prod"}},
		{ID: "nat-gw", MonthlyCents: 80000, Tags: map[string]string{
			"tenant": "shared", "service": "platform", "env": "prod", "owner": "team-platform"}},
	}
	got := Attribute(resources)
	if got.Total() != 550000 || got.Unallocated != 130000 {
		t.Fatalf("total=%d unallocated=%d", got.Total(), got.Unallocated)
	}
	if got.Reasons["missing:owner"] != 50000 || got.Reasons["shared:tenant"] != 80000 {
		t.Fatalf("reasons = %v", got.Reasons)
	}
	if got.ByDimension[DimOwner]["team-order"] != 420000 {
		t.Fatalf("owner = %v", got.ByDimension[DimOwner])
	}
	t.Logf("total=%d unallocated=%d share=%.4f owner.team-order=%d",
		got.Total(), got.Unallocated, got.UnallocatedShare(),
		got.ByDimension[DimOwner]["team-order"])
}

func TestAttributeTreatsEmptyTagAsMissing(t *testing.T) {
	got := Attribute([]Resource{{
		ID: "vm-orphan", MonthlyCents: 10000,
		Tags: map[string]string{"tenant": "acme", "service": "", "env": "prod", "owner": "team-order"},
	}})
	if got.Unallocated != 10000 || got.Reasons["missing:service"] != 10000 {
		t.Fatalf("attribution = %+v", got)
	}
}

func TestSharedPoolSplitKeepsTotal(t *testing.T) {
	pool := SharedPool{
		Name:    "observability",
		Cents:   100000,
		Weights: map[string]int64{"order-api": 1, "inventory": 1, "payment": 1},
	}
	shares, err := pool.Split()
	if err != nil {
		t.Fatalf("Split: %v", err)
	}
	var sum int64
	for k, v := range shares {
		sum += v
		t.Logf("pool=%s key=%s share=%d", pool.Name, k, v)
	}
	if sum != pool.Cents {
		t.Fatalf("sum = %d, want %d", sum, pool.Cents)
	}
	if shares["inventory"] != 33334 || shares["order-api"] != 33333 {
		t.Fatalf("tie-break = %v", shares)
	}
}

func TestSharedPoolRejectsBadInput(t *testing.T) {
	for _, c := range []SharedPool{
		{Name: "empty", Cents: 100},
		{Name: "zero", Cents: 100, Weights: map[string]int64{"a": 0}},
		{Name: "negative", Cents: -1, Weights: map[string]int64{"a": 1}},
	} {
		if _, err := c.Split(); err == nil {
			t.Fatalf("pool %q: expected error", c.Name)
		}
	}
}

func TestUnitEconomicsSeparatesFixed(t *testing.T) {
	u := UnitEconomics{TotalCents: 1000000, FixedCents: 400000, OrderCount: 20000}
	if got := u.CostPerOrder(); got != 50 {
		t.Fatalf("cost per order = %v, want 50", got)
	}
	if m := u.MarginalCostPerOrder(); m != 30 {
		t.Fatalf("marginal = %v, want 30", m)
	}
	if c := u.ContributionCents(1200000); c != 200000 {
		t.Fatalf("contribution = %d, want 200000", c)
	}
	t.Logf("orders=%d fully_loaded=%.2f marginal=%.2f", u.OrderCount,
		u.CostPerOrder(), u.MarginalCostPerOrder())
}

$ go test ./internal/platform/cost/ -run 'TestAttribute|TestShared|TestUnit' -v -count=1
=== RUN   TestAttributeGroupsAndUnallocated
    attribution_test.go:26: total=550000 unallocated=130000 share=0.2364 owner.team-order=420000
--- PASS: TestAttributeGroupsAndUnallocated (0.00s)
=== RUN   TestAttributeTreatsEmptyTagAsMissing
--- PASS: TestAttributeTreatsEmptyTagAsMissing (0.00s)
=== RUN   TestSharedPoolSplitKeepsTotal
    attribution_test.go:54: pool=observability key=order-api share=33333
    attribution_test.go:54: pool=observability key=payment share=33333
    attribution_test.go:54: pool=observability key=inventory share=33334
--- PASS: TestSharedPoolSplitKeepsTotal (0.00s)
=== RUN   TestSharedPoolRejectsBadInput
--- PASS: TestSharedPoolRejectsBadInput (0.00s)
=== RUN   TestUnitEconomicsSeparatesFixed
    attribution_test.go:87: orders=20000 fully_loaded=50.00 marginal=30.00
--- PASS: TestUnitEconomicsSeparatesFixed (0.00s)
PASS
ok  	archlab/internal/platform/cost	0.258s