《MMO 服务器开发》6.1 指标体系与口径

// file: internal/analytics/metric.go
// tier: L1
// verify: go test ./internal/analytics/ -run TestMetric
//
// Package analytics turns raw gameplay facts into the numbers an operations
// team argues about. The lesson of this file is that a metric is never just a
// number -- it is a number plus a caliber. "DAU = 3" and "DAU = 4" can both be
// correct for the same day if two teams pinned different calibers.
package analytics

import "fmt"

// Fact is one raw per-player-per-day record the engine aggregates over.
type Fact struct {
	PlayerID   uint64
	ServerID   uint16
	Day        string // "2026-10-01"
	LoginCount int    // successful logins that day
	OnlineSecs int    // seconds spent in the world that day
	PaidCents  int64  // amount paid that day, in cents
}

// Subject names the activity event a caliber counts over. The same word can
// mean two things -- "logged in" is not "was in the world" -- and that gap is
// exactly where reconciliations fail.
type Subject string

const (
	// SubjectLogin counts a player who authenticated, even if the client
	// crashed before entering the world.
	SubjectLogin Subject = "login"
	// SubjectOnline counts a player who was actually in the world.
	SubjectOnline Subject = "online"
)

// Caliber is the written-down definition of a metric. Two teams that share a
// Caliber get the same number; two teams that do not, will not.
type Caliber struct {
	Metric      string
	Unit        string
	Window      string
	Subject     Subject
	DedupKey    string
	Numerator   string
	Denominator string
}

// CanonicalDAU is the caliber aegis standardises on: a player is "active" only
// if they were in the world, not merely authenticated.
var CanonicalDAU = Caliber{
	Metric: "dau", Unit: "player", Window: "day",
	Subject: SubjectOnline, DedupKey: "player_id",
	Numerator: "distinct players with online_secs > 0",
}

func (c Caliber) counts(f Fact) bool {
	switch c.Subject {
	case SubjectLogin:
		return f.LoginCount > 0
	case SubjectOnline:
		return f.OnlineSecs > 0
	default:
		return false
	}
}

// Active returns the distinct players active on day under the caliber. Dedup is
// by PlayerID: a player with several sessions that day is counted once.
func Active(facts []Fact, day string, c Caliber) map[uint64]struct{} {
	set := make(map[uint64]struct{})
	for _, f := range facts {
		if f.Day == day && c.counts(f) {
			set[f.PlayerID] = struct{}{}
		}
	}
	return set
}

// DAU counts distinct active players on day under the caliber.
func DAU(facts []Fact, day string, c Caliber) int { return len(Active(facts, day, c)) }

// Revenue sums the day's payments in cents.
func Revenue(facts []Fact, day string) int64 {
	var sum int64
	for _, f := range facts {
		if f.Day == day {
			sum += f.PaidCents
		}
	}
	return sum
}

// Payers returns the distinct players who paid anything on day.
func Payers(facts []Fact, day string) map[uint64]struct{} {
	set := make(map[uint64]struct{})
	for _, f := range facts {
		if f.Day == day && f.PaidCents > 0 {
			set[f.PlayerID] = struct{}{}
		}
	}
	return set
}

// ARPU is revenue / DAU; ARPPU is revenue / payers. ARPPU >= ARPU always,
// because payers are a subset of active users.
func ARPU(facts []Fact, day string, c Caliber) float64 {
	if dau := DAU(facts, day, c); dau > 0 {
		return float64(Revenue(facts, day)) / float64(dau)
	}
	return 0
}

// ARPPU is average revenue per paying user.
func ARPPU(facts []Fact, day string) float64 {
	if p := len(Payers(facts, day)); p > 0 {
		return float64(Revenue(facts, day)) / float64(p)
	}
	return 0
}

// Reconciliation records why a team's reported number disagrees with canonical.
type Reconciliation struct {
	Team      string
	Reported  float64
	Canonical float64
	Matches   bool
	Reason    string
}

// Reconcile compares a team's reported value against the canonical value.
func Reconcile(team string, reported, canonical, tolerance float64) Reconciliation {
	r := Reconciliation{Team: team, Reported: reported, Canonical: canonical}
	diff := reported - canonical
	if diff < 0 {
		diff = -diff
	}
	r.Matches = diff <= tolerance
	if !r.Matches {
		r.Reason = fmt.Sprintf(
			"%s reports %.2f but the canonical caliber yields %.2f", team, reported, canonical)
	}
	return r
}

// file: internal/analytics/metric_test.go
// tier: L1
// verify: go test ./internal/analytics/ -run TestMetric
package analytics

import (
	"math"
	"testing"
)

// day1Facts is a hand-built day with a deliberate caliber trap: p2 and p5
// logged in but never reached the world (crash at loading), and p3 was still
// online from a session that started before midnight, so it never logged in.
func day1Facts() []Fact {
	return []Fact{
		{PlayerID: 1, ServerID: 1, Day: "2026-10-01", LoginCount: 1, OnlineSecs: 3600},
		{PlayerID: 2, ServerID: 1, Day: "2026-10-01", LoginCount: 1, OnlineSecs: 0},
		{PlayerID: 3, ServerID: 1, Day: "2026-10-01", LoginCount: 0, OnlineSecs: 1800, PaidCents: 500},
		{PlayerID: 4, ServerID: 1, Day: "2026-10-01", LoginCount: 2, OnlineSecs: 7200, PaidCents: 1500},
		{PlayerID: 5, ServerID: 1, Day: "2026-10-01", LoginCount: 1, OnlineSecs: 0},
	}
}

func loginCaliber() Caliber {
	c := CanonicalDAU
	c.Subject = SubjectLogin
	return c
}

func approx(a, b float64) bool { return math.Abs(a-b) <= 1e-6 }

func TestMetricDAUDependsOnCaliber(t *testing.T) {
	facts := day1Facts()
	loginDAU := DAU(facts, "2026-10-01", loginCaliber())
	onlineDAU := DAU(facts, "2026-10-01", CanonicalDAU)

	if loginDAU != 4 || onlineDAU != 3 {
		t.Fatalf("DAU login=%d online=%d, want 4 and 3", loginDAU, onlineDAU)
	}
	if loginDAU == onlineDAU {
		t.Fatal("the two calibers must disagree on this dataset, or the lesson is lost")
	}
}

func TestMetricActiveSetsAreDisjoint(t *testing.T) {
	facts := day1Facts()
	login := Active(facts, "2026-10-01", loginCaliber())
	online := Active(facts, "2026-10-01", CanonicalDAU)
	// login counts the crashed-at-loading players (2, 5); online counts the
	// player carried over midnight (3). Neither set contains the other.
	if _, ok := login[2]; !ok {
		t.Fatal("login caliber must count player 2, who crashed at loading")
	}
	if _, ok := login[3]; ok {
		t.Fatal("login caliber must not count player 3, who never logged in")
	}
	if _, ok := online[3]; !ok {
		t.Fatal("online caliber must count player 3, carried over midnight")
	}
	if _, ok := online[2]; ok {
		t.Fatal("online caliber must not count player 2, who never entered the world")
	}
}

func TestMetricRevenueAndRates(t *testing.T) {
	facts := day1Facts()
	const day = "2026-10-01"

	if got := Revenue(facts, day); got != 2000 {
		t.Fatalf("revenue = %d, want 2000", got)
	}
	if got := ARPU(facts, day, CanonicalDAU); !approx(got, 2000.0/3.0) {
		t.Fatalf("ARPU = %.4f, want %.4f", got, 2000.0/3.0)
	}
	if got := ARPPU(facts, day); !approx(got, 1000) {
		t.Fatalf("ARPPU = %.4f, want 1000", got)
	}
	if ARPPU(facts, day) < ARPU(facts, day, CanonicalDAU) {
		t.Fatal("ARPPU must never fall below ARPU")
	}
}

func TestMetricReconcileFlagsCaliberMismatch(t *testing.T) {
	facts := day1Facts()
	canonical := float64(DAU(facts, "2026-10-01", CanonicalDAU))

	marketing := Reconcile("marketing", 4, canonical, 0.001)
	if marketing.Matches || marketing.Reason == "" {
		t.Fatal("marketing's login-caliber DAU must not reconcile, and must explain why")
	}
	if ops := Reconcile("ops", 3, canonical, 0.001); !ops.Matches {
		t.Fatalf("ops reported the canonical value and must reconcile: %s", ops.Reason)
	}
}

=== RUN   TestMetricDAUDependsOnCaliber
--- PASS: TestMetricDAUDependsOnCaliber (0.00s)
=== RUN   TestMetricActiveSetsAreDisjoint
--- PASS: TestMetricActiveSetsAreDisjoint (0.00s)
=== RUN   TestMetricRevenueAndRates
--- PASS: TestMetricRevenueAndRates (0.00s)
=== RUN   TestMetricReconcileFlagsCaliberMismatch
--- PASS: TestMetricReconcileFlagsCaliberMismatch (0.00s)
PASS
ok  	aegis/internal/analytics	0.601s