《MMO 服务器开发》6.3 留存、付费与活动转化分析

// file: internal/analytics/analysis.go
// tier: L1
// verify: go test ./internal/analytics/ -run 'TestRetention|TestFunnel|TestPayment'
//
// This file answers the three questions a live-ops team asks every morning:
// does the cohort come back (retention), do players pay (payment), and where
// does the activity funnel leak (conversion). All three are pure functions over
// constructed data, so all three are fully testable.
package analytics

import "sort"

// ActivityRecord is one raw "player was active on day" row. The same player can
// appear many times for one day (several sessions); retention must dedup them.
type ActivityRecord struct {
	Day      string
	PlayerID uint64
}

// ActiveByDay collapses raw records into day -> distinct players.
func ActiveByDay(records []ActivityRecord) map[string]map[uint64]struct{} {
	out := make(map[string]map[uint64]struct{})
	for _, r := range records {
		if out[r.Day] == nil {
			out[r.Day] = make(map[uint64]struct{})
		}
		out[r.Day][r.PlayerID] = struct{}{}
	}
	return out
}

// Cohort returns the players whose FIRST active day is exactly cohortDay: a
// player already active earlier is not a member, so retention is not diluted.
func Cohort(active map[string]map[uint64]struct{}, cohortDay string) map[uint64]struct{} {
	days := make([]string, 0, len(active))
	for d := range active {
		days = append(days, d)
	}
	sort.Strings(days)
	first := make(map[uint64]string)
	for _, d := range days {
		for pid := range active[d] {
			if _, ok := first[pid]; !ok {
				first[pid] = d
			}
		}
	}
	cohort := make(map[uint64]struct{})
	for pid, d := range first {
		if d == cohortDay {
			cohort[pid] = struct{}{}
		}
	}
	return cohort
}

// RetentionRate is day-N retention: of the cohort, the fraction active again on
// laterDay.
func RetentionRate(active map[string]map[uint64]struct{}, cohortDay, laterDay string) float64 {
	cohort := Cohort(active, cohortDay)
	if len(cohort) == 0 {
		return 0
	}
	retained := 0
	for pid := range cohort {
		if _, ok := active[laterDay][pid]; ok {
			retained++
		}
	}
	return float64(retained) / float64(len(cohort))
}

// FunnelStep is one stage of a conversion funnel with its headcount.
type FunnelStep struct {
	Name  string
	Users int
}

// FunnelResult is a step's headcount plus its step-over-step and overall rates.
type FunnelResult struct {
	Name        string
	Users       int
	StepRate    float64 // users / previous step
	OverallRate float64 // users / first step
}

// Analyze computes the conversion at each step; the first step's StepRate is 1.
func Analyze(steps []FunnelStep) []FunnelResult {
	out := make([]FunnelResult, 0, len(steps))
	if len(steps) == 0 {
		return out
	}
	first := steps[0].Users
	for i, s := range steps {
		r := FunnelResult{Name: s.Name, Users: s.Users}
		if i == 0 {
			r.StepRate = 1
		} else if prev := steps[i-1].Users; prev > 0 {
			r.StepRate = float64(s.Users) / float64(prev)
		}
		if first > 0 {
			r.OverallRate = float64(s.Users) / float64(first)
		}
		out = append(out, r)
	}
	return out
}

// BiggestDrop returns the index of the step with the largest drop (the funnel's
// bottleneck) and that step's rate.
func BiggestDrop(steps []FunnelStep) (int, float64) {
	if len(steps) < 2 {
		return -1, 0
	}
	worst, worstRate := -1, 1.0
	for i := 1; i < len(steps); i++ {
		if steps[i-1].Users == 0 {
			continue
		}
		if rate := float64(steps[i].Users) / float64(steps[i-1].Users); rate < worstRate {
			worst, worstRate = i, rate
		}
	}
	return worst, worstRate
}

// Payment is one order. A player with two orders in a day counts once as a
// payer but twice towards repurchase.
type Payment struct {
	OrderID  string
	PlayerID uint64
	Day      string
	Cents    int64
}

// PaymentReport is a day's payment analysis.
type PaymentReport struct {
	DAU            int
	Revenue        int64
	Payers         int
	PaymentRate    float64 // payers / DAU
	ARPU           float64 // revenue / DAU
	ARPPU          float64 // revenue / payers
	FirstPayers    int     // payers whose first-ever order is on this day
	Repurchasers   int     // payers with >= 2 orders on this day
	RepurchaseRate float64 // repurchasers / payers
}

// AnalyzePayments needs every order so far, not just today's, to know who is a
// first-time payer.
func AnalyzePayments(active map[uint64]struct{}, payments []Payment, day string) PaymentReport {
	r := PaymentReport{DAU: len(active)}
	firstDay := make(map[uint64]string)
	for _, p := range payments {
		if cur, ok := firstDay[p.PlayerID]; !ok || p.Day < cur {
			firstDay[p.PlayerID] = p.Day
		}
	}
	orders := make(map[uint64]int)
	for _, p := range payments {
		if p.Day != day {
			continue
		}
		r.Revenue += p.Cents
		orders[p.PlayerID]++
	}
	r.Payers = len(orders)
	for pid, n := range orders {
		if firstDay[pid] == day {
			r.FirstPayers++
		}
		if n >= 2 {
			r.Repurchasers++
		}
	}
	if r.DAU > 0 {
		r.PaymentRate = float64(r.Payers) / float64(r.DAU)
		r.ARPU = float64(r.Revenue) / float64(r.DAU)
	}
	if r.Payers > 0 {
		r.ARPPU = float64(r.Revenue) / float64(r.Payers)
		r.RepurchaseRate = float64(r.Repurchasers) / float64(r.Payers)
	}
	return r
}

// snippet: internal/analytics/analysis_test.go (节选)
// cohort size is 10, not 11: the duplicate row for player 1 must be deduped.
if len(Cohort(ActiveByDay(retentionRecords()), "2026-10-01")) != 10 {
	t.Fatal("cohort must dedup repeated sessions")
}
// D1=50%, D2=20%, D7=10%, D30=20% -- three points on one retention curve.
if got := RetentionRate(active, "2026-10-01", "2026-10-02"); !approx(got, 0.5) {
	t.Errorf("D1 retention = %.4f, want 0.50", got)
}

// the funnel's worst step is "报名 -> 完成", dropping to 0.40.
if idx, rate := BiggestDrop(steps); idx != 3 || !approx(rate, 0.4) {
	t.Errorf("bottleneck at step %d (%.4f), want step 3 at 0.40", idx, rate)
}

// p1 paid on 2026-09-30, so today it is a repurchase, not a first charge.
if r.FirstPayers != 2 || r.Repurchasers != 1 || !approx(r.RepurchaseRate, 1.0/3.0) {
	t.Errorf("first=%d repurchase=%d, want 2 and 1", r.FirstPayers, r.Repurchasers)
}

=== RUN   TestRetentionDedupsAndMeasuresCohort
--- PASS: TestRetentionDedupsAndMeasuresCohort (0.00s)
=== RUN   TestFunnelConversionAndBottleneck
--- PASS: TestFunnelConversionAndBottleneck (0.00s)
=== RUN   TestPaymentReport
--- PASS: TestPaymentReport (0.00s)
PASS
ok  	aegis/internal/analytics	0.885s