《游戏服务端架构·平台化与架构治理》4.1 信号采集与误伤控制

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

import (
	"errors"
	"time"
)

// Layer is where a signal came from. Corroboration across layers matters
// more than stacking many signals from one layer.
type Layer string

const (
	LayerClient  Layer = "client_report"
	LayerServer  Layer = "server_behavior"
	LayerEconomy Layer = "economy_anomaly"
	LayerSocial  Layer = "social_graph"
	LayerDevice  Layer = "device_network"
)

var allLayers = []Layer{LayerClient, LayerServer, LayerEconomy, LayerSocial, LayerDevice}

func layerKnown(l Layer) bool {
	for _, v := range allLayers {
		if v == l {
			return true
		}
	}
	return false
}

// Signal is one observation. Weight is the maximum points it can add,
// Confidence scales that weight, and ForgeCost estimates how expensive the
// signal is for a cheater to fake: 0 is trivial, 1 is costly.
type Signal struct {
	ID         string
	Layer      Layer
	Weight     float64
	Confidence float64
	ForgeCost  float64
	At         time.Time
	TTL        time.Duration
}

// Validate rejects values that would let one malformed report dominate.
func Validate(s Signal) error {
	switch {
	case s.ID == "":
		return errors.New("risksignal: signal id is required")
	case !layerKnown(s.Layer):
		return errors.New("risksignal: unknown signal layer")
	case s.Weight < 0 || s.Weight > 100:
		return errors.New("risksignal: weight must be within [0,100]")
	case s.Confidence < 0 || s.Confidence > 1:
		return errors.New("risksignal: confidence must be within [0,1]")
	case s.ForgeCost < 0 || s.ForgeCost > 1:
		return errors.New("risksignal: forge cost must be within [0,1]")
	case s.TTL <= 0:
		return errors.New("risksignal: ttl must be positive")
	}
	return nil
}

// Policy is the enforcement gate. ObserveAt opens an observation window;
// EnforceAt is the minimum score for a restriction. MinLayers stops one noisy
// source from acting alone, and the two caps stop a single signal or layer
// from carrying the whole score.
type Policy struct {
	ObserveAt             float64
	EnforceAt             float64
	MinLayers             int
	MaxSingleContribution float64
	MaxPerLayer           float64
}

// ScoreResult keeps the breakdown so a reviewer can explain the number.
type ScoreResult struct {
	Total      float64
	ByLayer    map[Layer]float64
	UsedLayers int
	Expired    int
	Invalid    int
}

// Score sums decayed, confidence-scaled weights, caps each layer, and reports
// which layers actually contributed. Expired and invalid signals are counted
// but never scored.
func Score(signals []Signal, now time.Time, p Policy) ScoreResult {
	res := ScoreResult{ByLayer: map[Layer]float64{}}
	for _, s := range signals {
		if err := Validate(s); err != nil {
			res.Invalid++
			continue
		}
		if now.Before(s.At) {
			res.Invalid++
			continue
		}
		if now.Sub(s.At) > s.TTL {
			res.Expired++
			continue
		}
		// A cheap-to-fake signal still carries some weight, but never full
		// weight. The 0.5 floor keeps genuine but noisy signals usable.
		points := s.Weight * s.Confidence * (0.5 + 0.5*s.ForgeCost)
		if p.MaxSingleContribution > 0 && points > p.MaxSingleContribution {
			points = p.MaxSingleContribution
		}
		res.ByLayer[s.Layer] += points
	}
	// Iterate a fixed order so the total is stable across runs.
	for _, layer := range allLayers {
		v := res.ByLayer[layer]
		if v <= 0 {
			delete(res.ByLayer, layer)
			continue
		}
		if p.MaxPerLayer > 0 && v > p.MaxPerLayer {
			v = p.MaxPerLayer
			res.ByLayer[layer] = v
		}
		res.UsedLayers++
		res.Total += v
	}
	return res
}

// Action is the operational result of a score. Review means a human or a
// heavier policy must look before the account is restricted.
type Action string

const (
	ActionNone    Action = "none"
	ActionObserve Action = "observe"
	ActionReview  Action = "review"
)

// Decision records the action and the reason, so operators can audit why an
// account was or was not touched.
type Decision struct {
	Action Action
	Score  float64
	Reason string
}

// Decide applies the gate. A high score from fewer layers than policy
// requires is deliberately downgraded to observation, not enforcement.
func Decide(res ScoreResult, p Policy) Decision {
	switch {
	case res.Total > 0 && res.UsedLayers > 0 &&
		res.Total >= p.EnforceAt && res.UsedLayers >= p.MinLayers:
		return Decision{Action: ActionReview, Score: res.Total,
			Reason: "score and cross-layer corroboration meet the enforcement gate"}
	case res.Total > 0 && res.Total >= p.EnforceAt:
		return Decision{Action: ActionObserve, Score: res.Total,
			Reason: "high score from fewer layers than policy requires"}
	case res.Total > 0 && res.Total >= p.ObserveAt:
		return Decision{Action: ActionObserve, Score: res.Total,
			Reason: "score meets the observation gate"}
	default:
		return Decision{Action: ActionNone, Score: res.Total,
			Reason: "score is below the observation gate"}
	}
}

// ObservationOutcome is the result of watching an account that crossed the
// observation gate.
type ObservationOutcome string

const (
	ObservationPending    ObservationOutcome = "pending"
	ObservationConfirmed  ObservationOutcome = "confirmed"
	ObservationRolledBack ObservationOutcome = "rolled_back"
)

// ObservationResult reports whether confirmation arrived late, after the
// automatic restriction had already been rolled back.
type ObservationResult struct {
	Outcome      ObservationOutcome
	LateEvidence bool
}

// ResolveObservation closes an observation window. If nothing confirms the
// signal before the window ends, the temporary restriction is rolled back.
// Evidence that arrives later cannot retroactively justify the old action; it
// must open a new case, which is why LateEvidence is reported separately.
func ResolveObservation(startedAt time.Time, window time.Duration, now time.Time, confirmed bool) ObservationResult {
	elapsed := now.Sub(startedAt)
	if confirmed {
		if window > 0 && elapsed <= window {
			return ObservationResult{Outcome: ObservationConfirmed}
		}
		return ObservationResult{Outcome: ObservationRolledBack, LateEvidence: true}
	}
	if window > 0 && elapsed <= window {
		return ObservationResult{Outcome: ObservationPending}
	}
	return ObservationResult{Outcome: ObservationRolledBack}
}

// Counts is the sample used to measure false positives. Actions is the number
// of enforcement actions; Overturned is the subset later reversed on appeal.
type Counts struct {
	Actions    int
	Overturned int
}

// FalsePositiveRate returns the observed overturn ratio. It refuses a sample
// with no actions because a rate over an empty denominator is not evidence.
func FalsePositiveRate(c Counts) (float64, error) {
	if c.Actions < 0 || c.Overturned < 0 {
		return 0, errors.New("risksignal: counts must not be negative")
	}
	if c.Actions == 0 {
		return 0, errors.New("risksignal: no actions to measure")
	}
	if c.Overturned > c.Actions {
		return 0, errors.New("risksignal: overturned cannot exceed actions")
	}
	return float64(c.Overturned) / float64(c.Actions), nil
}

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