《后端架构设计·演进与治理》11.3 平台度量：采纳率、交付效率与反悔成本

// file: internal/platform/idp/metrics.go
// tier: L1
// verify: go test ./internal/platform/idp/ -count=1 -run 'TestAdoption|TestRegret|TestAssessPlatform'
package idp

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

// AdoptionSample is one team's usage of one capability in a fixed window.
type AdoptionSample struct {
	Team, CapabilityID, Reason string
	Eligible, Adopted          int
}

// Adoption separates the seat-weighted rate from the per-team mean. A large
// gap means adoption is concentrated in small teams.
type Adoption struct {
	Weighted, Mean, Gap float64
	Adopted, Eligible   int
	Teams               int
}

// ComputeAdoption validates samples and returns both rates.
func ComputeAdoption(samples []AdoptionSample) (Adoption, error) {
	if len(samples) == 0 {
		return Adoption{}, errors.New("metrics: no adoption samples")
	}
	var a Adoption
	var sumRate float64
	seen := make(map[string]bool, len(samples))
	for i, s := range samples {
		if s.Team == "" {
			return Adoption{}, fmt.Errorf("metrics: sample[%d] has no team", i)
		}
		if s.Eligible <= 0 || s.Adopted < 0 || s.Adopted > s.Eligible {
			return Adoption{}, fmt.Errorf("metrics: team %q has invalid seats %d/%d", s.Team, s.Adopted, s.Eligible)
		}
		key := s.Team + "\x00" + s.CapabilityID
		if seen[key] {
			return Adoption{}, fmt.Errorf("metrics: duplicate sample for %q", key)
		}
		seen[key] = true
		a.Adopted += s.Adopted
		a.Eligible += s.Eligible
		a.Teams++
		sumRate += float64(s.Adopted) / float64(s.Eligible)
	}
	a.Weighted = float64(a.Adopted) / float64(a.Eligible)
	a.Mean = sumRate / float64(a.Teams)
	a.Gap = a.Mean - a.Weighted
	return a, nil
}

// ReasonCount explains why a team did not fully adopt a capability.
type ReasonCount struct {
	Reason      string
	Teams       int
	UnusedSeats int
}

// NonAdopterReasons aggregates free-text reasons under "unspecified" when
// missing, so silence cannot look like success.
func NonAdopterReasons(samples []AdoptionSample) []ReasonCount {
	byReason := make(map[string]*ReasonCount)
	for _, s := range samples {
		if s.Adopted >= s.Eligible {
			continue
		}
		reason := s.Reason
		if reason == "" {
			reason = "unspecified"
		}
		rc, ok := byReason[reason]
		if !ok {
			rc = &ReasonCount{Reason: reason}
			byReason[reason] = rc
		}
		rc.Teams++
		rc.UnusedSeats += s.Eligible - s.Adopted
	}
	out := make([]ReasonCount, 0, len(byReason))
	for _, rc := range byReason {
		out = append(out, *rc)
	}
	sort.Slice(out, func(i, j int) bool {
		if out[i].Teams != out[j].Teams {
			return out[i].Teams > out[j].Teams
		}
		return out[i].Reason < out[j].Reason
	})
	return out
}

// RegretInput is the cost model for one platform bet, in engineer-hours.
type RegretInput struct {
	Teams                                       int
	MigrationHours, OngoingHoursPerMonth        float64
	BenefitHoursPerMonth, HourlyCost, ExitHours float64
	Months                                      int
}

// Regret is the cost of having adopted, including the cost of leaving.
type Regret struct {
	MigrationCost, OngoingCost, Benefit, Net float64
	PaybackMonths, RegretRatio, ExitCost     float64
}

// ComputeRegret turns hours into money. Payback is infinite when the monthly
// net benefit is not positive.
func ComputeRegret(in RegretInput) (Regret, error) {
	if in.Teams <= 0 || in.Months <= 0 || in.HourlyCost <= 0 {
		return Regret{}, errors.New("metrics: teams, months and hourly cost must be positive")
	}
	if in.MigrationHours < 0 || in.OngoingHoursPerMonth < 0 || in.BenefitHoursPerMonth < 0 || in.ExitHours < 0 {
		return Regret{}, errors.New("metrics: hours must not be negative")
	}
	r := Regret{
		MigrationCost: in.MigrationHours * in.HourlyCost,
		OngoingCost:   in.OngoingHoursPerMonth * float64(in.Months) * in.HourlyCost,
		Benefit:       in.BenefitHoursPerMonth * float64(in.Months) * in.HourlyCost,
		ExitCost:      in.ExitHours * in.HourlyCost,
	}
	r.Net = r.Benefit - r.MigrationCost - r.OngoingCost
	monthlyNet := (in.BenefitHoursPerMonth - in.OngoingHoursPerMonth) * in.HourlyCost
	if monthlyNet <= 0 || r.MigrationCost == 0 {
		r.PaybackMonths = math.Inf(1)
	} else {
		r.PaybackMonths = r.MigrationCost / monthlyNet
	}
	if r.Benefit <= 0 {
		r.RegretRatio = math.Inf(1)
	} else {
		r.RegretRatio = (r.MigrationCost + r.OngoingCost) / r.Benefit
	}
	return r, nil
}

// MetricGate is the agreed threshold set for a platform review.
type MetricGate struct {
	MinAdoption, MaxAdoptionGap, MaxPaybackMonths, MaxRegretRatio float64
}

// Verdict is the review result. Reasons are empty only when Pass is true.
type Verdict struct {
	Pass    bool
	Reasons []string
}

// AssessPlatform checks adoption, concentration and regret together; a single
// good number must not hide a bad one.
func AssessPlatform(a Adoption, r Regret, g MetricGate) Verdict {
	var reasons []string
	if a.Weighted < g.MinAdoption {
		reasons = append(reasons, fmt.Sprintf("weighted adoption %.3f < %.3f", a.Weighted, g.MinAdoption))
	}
	if a.Gap > g.MaxAdoptionGap {
		reasons = append(reasons, fmt.Sprintf("mean-minus-weighted gap %.3f > %.3f", a.Gap, g.MaxAdoptionGap))
	}
	if r.PaybackMonths > g.MaxPaybackMonths {
		reasons = append(reasons, fmt.Sprintf("payback %.2f months > %.2f", r.PaybackMonths, g.MaxPaybackMonths))
	}
	if r.RegretRatio > g.MaxRegretRatio {
		reasons = append(reasons, fmt.Sprintf("regret ratio %.3f > %.3f", r.RegretRatio, g.MaxRegretRatio))
	}
	return Verdict{Pass: len(reasons) == 0, Reasons: reasons}
}

// file: internal/platform/idp/metrics_test.go
// tier: L1
// verify: go test ./internal/platform/idp/ -count=1 -run 'TestAdoption|TestRegret|TestAssessPlatform'
package idp

import (
	"math"
	"testing"
)

func sampleSet() []AdoptionSample {
	return []AdoptionSample{
		{Team: "order", CapabilityID: "cap-deploy", Eligible: 10, Adopted: 8, Reason: "missing audit logs"},
		{Team: "search", CapabilityID: "cap-deploy", Eligible: 4, Adopted: 4},
		{Team: "catalog", CapabilityID: "cap-deploy", Eligible: 20, Adopted: 5, Reason: "no docs"},
		{Team: "risk", CapabilityID: "cap-deploy", Eligible: 2, Adopted: 2},
		{Team: "payments", CapabilityID: "cap-deploy", Eligible: 40, Adopted: 10, Reason: "no docs"},
	}
}

func near(got, want float64) bool { return math.Abs(got-want) < 1e-9 }

func TestAdoptionWeightedVsMean(t *testing.T) {
	a, err := ComputeAdoption(sampleSet())
	if err != nil {
		t.Fatalf("ComputeAdoption: %v", err)
	}
	if a.Adopted != 29 || a.Eligible != 76 || a.Teams != 5 ||
		!near(a.Weighted, 29.0/76.0) || !near(a.Mean, 0.66) || !near(a.Gap, 0.66-29.0/76.0) {
		t.Fatalf("adoption = %+v", a)
	}
	t.Logf("weighted=%.4f mean=%.4f gap=%.4f seats=%d/%d", a.Weighted, a.Mean, a.Gap, a.Adopted, a.Eligible)

	reasons := NonAdopterReasons(sampleSet())
	if len(reasons) != 2 || reasons[0].Reason != "no docs" || reasons[0].Teams != 2 || reasons[0].UnusedSeats != 45 {
		t.Fatalf("reasons = %+v", reasons)
	}
	t.Logf("reasons=%+v", reasons)

	bad := [][]AdoptionSample{nil, {{Team: "order", Eligible: 0}},
		{{Team: "order", Eligible: 2, Adopted: 3}},
		{{Team: "order", CapabilityID: "c", Eligible: 2, Adopted: 1}, {Team: "order", CapabilityID: "c", Eligible: 2, Adopted: 1}}}
	for i, samples := range bad {
		if _, err := ComputeAdoption(samples); err == nil {
			t.Fatalf("bad case %d accepted", i)
		}
	}
}

func testRegret() RegretInput {
	return RegretInput{Teams: 5, MigrationHours: 320, OngoingHoursPerMonth: 40,
		BenefitHoursPerMonth: 120, Months: 12, HourlyCost: 100, ExitHours: 50}
}

func TestRegret(t *testing.T) {
	r, err := ComputeRegret(testRegret())
	if err != nil {
		t.Fatalf("ComputeRegret: %v", err)
	}
	if r.MigrationCost != 32000 || r.OngoingCost != 48000 || r.Benefit != 144000 || r.Net != 64000 ||
		!near(r.PaybackMonths, 4) || !near(r.RegretRatio, 80000.0/144000.0) || r.ExitCost != 5000 {
		t.Fatalf("regret = %+v", r)
	}
	t.Logf("migration=%.0f ongoing=%.0f benefit=%.0f net=%.0f payback=%.1f ratio=%.4f exit=%.0f",
		r.MigrationCost, r.OngoingCost, r.Benefit, r.Net, r.PaybackMonths, r.RegretRatio, r.ExitCost)

	noBenefit := testRegret()
	noBenefit.BenefitHoursPerMonth = 0
	r, err = ComputeRegret(noBenefit)
	if err != nil || !math.IsInf(r.PaybackMonths, 1) || !math.IsInf(r.RegretRatio, 1) {
		t.Fatalf("no-benefit = %+v, %v", r, err)
	}
}

func TestAssessPlatform(t *testing.T) {
	a, _ := ComputeAdoption(sampleSet())
	r, _ := ComputeRegret(testRegret())
	pass := AssessPlatform(a, r, MetricGate{MinAdoption: 0.35, MaxAdoptionGap: 0.30, MaxPaybackMonths: 6, MaxRegretRatio: 0.70})
	if !pass.Pass || len(pass.Reasons) != 0 {
		t.Fatalf("pass verdict = %+v", pass)
	}
	fail := AssessPlatform(a, r, MetricGate{MinAdoption: 0.60, MaxAdoptionGap: 0.15, MaxPaybackMonths: 3, MaxRegretRatio: 0.50})
	if fail.Pass || len(fail.Reasons) != 4 {
		t.Fatalf("fail verdict = %+v", fail)
	}
	for _, reason := range fail.Reasons {
		t.Logf("blocked: %s", reason)
	}
}

$ go test ./internal/platform/idp/ -count=1 -v -run 'TestAdoption|TestRegret|TestAssessPlatform'
=== RUN   TestAdoptionWeightedVsMean
    metrics_test.go:32: weighted=0.3816 mean=0.6600 gap=0.2784 seats=29/76
    metrics_test.go:38: reasons=[{Reason:no docs Teams:2 UnusedSeats:45} {Reason:missing audit logs Teams:1 UnusedSeats:2}]
--- PASS: TestAdoptionWeightedVsMean (0.00s)
=== RUN   TestRegret
    metrics_test.go:64: migration=32000 ongoing=48000 benefit=144000 net=64000 payback=4.0 ratio=0.5556 exit=5000
--- PASS: TestRegret (0.00s)
=== RUN   TestAssessPlatform
    metrics_test.go:87: blocked: weighted adoption 0.382 < 0.600
    metrics_test.go:87: blocked: mean-minus-weighted gap 0.278 > 0.150
    metrics_test.go:87: blocked: payback 4.00 months > 3.00
    metrics_test.go:87: blocked: regret ratio 0.556 > 0.500
--- PASS: TestAssessPlatform (0.00s)
PASS
ok  	archlab/internal/platform/idp	0.259s