《游戏服务端架构·规模化、全球化与成本》9.1 成本归因与单位经济

// file: internal/costattribution/costattribution.go
// tier: L1
// verify: go test ./internal/costattribution/
package costattribution

import (
	"errors"
	"fmt"
	"sort"
)

// Category is the billing dimension a line belongs to. It deliberately
// matches how the invoice is read, not how the service is deployed.
type Category string

const (
	Compute    Category = "compute"
	Bandwidth  Category = "bandwidth"
	Storage    Category = "storage"
	Database   Category = "database"
	CDN        Category = "cdn"
	ThirdParty Category = "third_party"
)

// Line is one metered cost line. An empty Product marks a shared line
// (gateway, observability, control plane) that must be allocated.
type Line struct {
	Product  string
	Category Category
	Micros   int64
	Tag      string
}

// Total sums every line, including shared lines.
func Total(lines []Line) int64 {
	var sum int64
	for _, l := range lines {
		sum += l.Micros
	}
	return sum
}

// TotalByCategory is the first view finance and engineering must agree on.
func TotalByCategory(lines []Line) map[Category]int64 {
	out := make(map[Category]int64)
	for _, l := range lines {
		out[l.Category] += l.Micros
	}
	return out
}

// AllocateShared assigns lines with an empty Product by integer weights
// (DAU, room-hours, requests). Integer truncation is intentional: the
// remainder is reported as unattributed instead of being invented.
func AllocateShared(lines []Line, weights map[string]int64) (map[string]int64, int64) {
	out := make(map[string]int64)
	var unattributed int64

	names := make([]string, 0, len(weights))
	var totalWeight int64
	for name, w := range weights {
		if w <= 0 {
			continue
		}
		names = append(names, name)
		totalWeight += w
	}
	sort.Strings(names)

	for _, l := range lines {
		if l.Product != "" {
			out[l.Product] += l.Micros
			continue
		}
		if totalWeight == 0 {
			unattributed += l.Micros
			continue
		}
		var given int64
		for _, name := range names {
			share := l.Micros * weights[name] / totalWeight
			out[name] += share
			given += share
		}
		unattributed += l.Micros - given
	}
	return out, unattributed
}

// Units is the denominator set for unit economics. All four are counted
// over the same period as the cost snapshot.
type Units struct {
	DAU       int64
	RoomHours int64
	Matches   int64
	StorageGB int64
}

// UnitCosts is expressed in micros of currency per unit. A zero denominator
// yields zero rather than NaN so a sparse product does not poison a report.
type UnitCosts struct {
	PerDAU             float64
	PerRoomHour        float64
	PerThousandMatches float64
	PerGBStorage       float64
}

// UnitEconomics converts a total into the four denominators the studio uses
// in reviews. Matches are scaled to thousands to keep the number readable.
func UnitEconomics(totalMicros int64, u Units) UnitCosts {
	var c UnitCosts
	if u.DAU > 0 {
		c.PerDAU = float64(totalMicros) / float64(u.DAU)
	}
	if u.RoomHours > 0 {
		c.PerRoomHour = float64(totalMicros) / float64(u.RoomHours)
	}
	if u.Matches > 0 {
		c.PerThousandMatches = float64(totalMicros) * 1000 / float64(u.Matches)
	}
	if u.StorageGB > 0 {
		c.PerGBStorage = float64(totalMicros) / float64(u.StorageGB)
	}
	return c
}

// Snapshot is one period of cost plus the units it served.
type Snapshot struct {
	Period      string
	TotalMicros int64
	Units       Units
}

// Delta compares two periods in absolute micros and percent.
type Delta struct {
	AbsoluteMicros int64
	Percent        float64
	PerDAUPercent  float64
}

// ErrNoBaseline is returned when the previous period has no cost, because a
// percentage against zero is not a trend.
var ErrNoBaseline = errors.New("costattribution: previous total is zero")

// Compare reports period-over-period movement. It refuses to divide by a
// zero baseline instead of printing an infinite percentage.
func Compare(current, previous Snapshot) (Delta, error) {
	if previous.TotalMicros == 0 {
		return Delta{}, ErrNoBaseline
	}
	d := Delta{AbsoluteMicros: current.TotalMicros - previous.TotalMicros}
	d.Percent = float64(d.AbsoluteMicros) / float64(previous.TotalMicros) * 100

	if previous.Units.DAU > 0 && current.Units.DAU > 0 {
		prevPerDAU := float64(previous.TotalMicros) / float64(previous.Units.DAU)
		curPerDAU := float64(current.TotalMicros) / float64(current.Units.DAU)
		if prevPerDAU != 0 {
			d.PerDAUPercent = (curPerDAU - prevPerDAU) / prevPerDAU * 100
		}
	}
	return d, nil
}

// BalanceError names the gap between the invoice total and the sum of
// product allocations plus the explicit unattributed bucket.
type BalanceError struct {
	Total        int64
	Attributed   int64
	Unattributed int64
}

func (e *BalanceError) Error() string {
	return fmt.Sprintf("costattribution: total=%d attributed=%d unattributed=%d gap=%d",
		e.Total, e.Attributed, e.Unattributed,
		e.Total-e.Attributed-e.Unattributed)
}

// CheckBalance enforces "attributed + unattributed == invoice total". A
// non-zero result means the tagging pipeline lost or duplicated a line.
func CheckBalance(total int64, perProduct map[string]int64, unattributed int64) error {
	var attributed int64
	for _, v := range perProduct {
		attributed += v
	}
	if attributed+unattributed != total {
		return &BalanceError{Total: total, Attributed: attributed, Unattributed: unattributed}
	}
	return nil
}

cd .local/checks/gsarch-lab
go test -count=1 ./internal/costattribution/
ok  gsarchlab/internal/costattribution