《游戏服务端架构·核心系统与契约》6.3 经济风控与价格指数

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

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

var (
	ErrWindow      = errors.New("economyrisk: window ticks must be positive")
	ErrPolicy      = errors.New("economyrisk: thresholds must be positive")
	ErrEmptyPlayer = errors.New("economyrisk: event player is empty")
	ErrBadAmount   = errors.New("economyrisk: amount must be positive")
	ErrBadTick     = errors.New("economyrisk: tick must be non-negative")
)

// Severity says how urgent an alert is, not what to do about it.
type Severity string

const (
	SeverityInfo Severity = "info"
	SeverityWarn Severity = "warn"
	SeverityHigh Severity = "high"
)

// Action is a recommendation for a human or a policy engine. No alert directly
// bans a player or deletes currency.
type Action string

const (
	ActionObserve  Action = "observe"
	ActionDelay    Action = "delay_credit"
	ActionReview   Action = "review"
	ActionFreeze   Action = "freeze"
	ActionRollback Action = "rollback"
)

// Alert is one evaluated signal. Detail carries the numbers that produced it
// so an appeal can be reviewed without replaying the whole window.
type Alert struct {
	Code     string
	Severity Severity
	Action   Action
	Detail   string
}

// Event is one economy observation. Price is zero for non-trade events; Amount
// is the quantity moved or the trade volume.
type Event struct {
	Tick         int
	Player       string
	Source       string
	Item         string
	Amount       int64
	Price        int64
	Counterparty string
}

// Policy holds the thresholds. They are configuration, not constants: a new
// season or a different product should retune them from observed baselines.
type Policy struct {
	WindowTicks      int
	SourceSpike      int64
	PriceBandBPS     int
	ConcentrationBPS int
	MinPriceSamples  int
}

type bucket struct {
	tick   int
	events []Event
}

// Monitor is a fixed-size ring of per-tick buckets. Record assumes ticks are
// non-decreasing; a late event from an expired tick is dropped by Evaluate
// anyway, and reusing its slot would corrupt a newer bucket.
type Monitor struct {
	policy  Policy
	buckets []bucket
}

// New validates the policy. MinPriceSamples defaults to 3 because two samples
// cannot tell a spike from a normal price change.
func New(p Policy) (*Monitor, error) {
	if p.WindowTicks <= 0 {
		return nil, ErrWindow
	}
	if p.SourceSpike <= 0 || p.PriceBandBPS <= 0 || p.ConcentrationBPS <= 0 {
		return nil, ErrPolicy
	}
	if p.MinPriceSamples <= 0 {
		p.MinPriceSamples = 3
	}
	return &Monitor{policy: p, buckets: make([]bucket, p.WindowTicks)}, nil
}

// Record appends an event to the bucket for its tick, replacing any bucket
// left over from an older window lap.
func (m *Monitor) Record(e Event) error {
	if e.Player == "" {
		return ErrEmptyPlayer
	}
	if e.Amount <= 0 {
		return ErrBadAmount
	}
	if e.Tick < 0 {
		return ErrBadTick
	}
	idx := e.Tick % len(m.buckets)
	if m.buckets[idx].tick != e.Tick {
		m.buckets[idx] = bucket{tick: e.Tick}
	}
	m.buckets[idx].events = append(m.buckets[idx].events, e)
	return nil
}

// Evaluate returns the alerts for one player at a given tick. It is a read
// path: calling it twice does not change the window.
func (m *Monitor) Evaluate(player string, now int) []Alert {
	events := m.window(player, now)
	if len(events) == 0 {
		return nil
	}
	alerts := make([]Alert, 0, 3)
	if alert, ok := m.sourceSpike(events); ok {
		alerts = append(alerts, alert)
	}
	if alert, ok := m.priceAnomaly(events); ok {
		alerts = append(alerts, alert)
	}
	if alert, ok := m.concentration(events); ok {
		alerts = append(alerts, alert)
	}
	sort.Slice(alerts, func(i, j int) bool { return alerts[i].Code < alerts[j].Code })
	return alerts
}

// PriceIndex returns the volume-weighted average price and sample count for an
// item over the window. It is an observation, never a settlement price.
func (m *Monitor) PriceIndex(item string, now int) (int64, int) {
	cutoff := now - m.policy.WindowTicks
	var sum, volume int64
	var samples int
	for _, b := range m.buckets {
		if b.tick <= cutoff || b.tick > now {
			continue
		}
		for _, e := range b.events {
			if e.Item != item || e.Price <= 0 {
				continue
			}
			sum += e.Price * e.Amount
			volume += e.Amount
			samples++
		}
	}
	if volume == 0 {
		return 0, 0
	}
	return sum / volume, samples
}

func (m *Monitor) window(player string, now int) []Event {
	cutoff := now - m.policy.WindowTicks
	var out []Event
	for _, b := range m.buckets {
		if b.tick <= cutoff || b.tick > now {
			continue
		}
		for _, e := range b.events {
			if e.Player == player {
				out = append(out, e)
			}
		}
	}
	return out
}

func (m *Monitor) sourceSpike(events []Event) (Alert, bool) {
	perSource := make(map[string]int64)
	for _, e := range events {
		perSource[e.Source] += e.Amount
	}
	bestSource, best := "", int64(0)
	for source, total := range perSource {
		if total > best || (total == best && source < bestSource) {
			bestSource, best = source, total
		}
	}
	if best <= m.policy.SourceSpike {
		return Alert{}, false
	}
	return Alert{
		Code:     "source_spike",
		Severity: SeverityHigh,
		Action:   ActionDelay,
		Detail:   fmt.Sprintf("source %s produced %d in window", bestSource, best),
	}, true
}

func (m *Monitor) priceAnomaly(events []Event) (Alert, bool) {
	byItem := make(map[string][]Event)
	for _, e := range events {
		if e.Price > 0 {
			byItem[e.Item] = append(byItem[e.Item], e)
		}
	}
	worstItem, worstDev := "", int64(-1)
	var worstPrice, worstMedian int64
	for item, itemEvents := range byItem {
		if len(itemEvents) < m.policy.MinPriceSamples {
			continue
		}
		sort.Slice(itemEvents, func(i, j int) bool { return itemEvents[i].Tick < itemEvents[j].Tick })
		latest := itemEvents[len(itemEvents)-1].Price
		previous := make([]int64, 0, len(itemEvents)-1)
		for _, e := range itemEvents[:len(itemEvents)-1] {
			previous = append(previous, e.Price)
		}
		baseline := median(previous)
		if baseline <= 0 {
			continue
		}
		deviation := abs64(latest-baseline) * 10000 / baseline
		if deviation > int64(m.policy.PriceBandBPS) &&
			(deviation > worstDev || (deviation == worstDev && item < worstItem)) {
			worstItem, worstDev, worstPrice, worstMedian = item, deviation, latest, baseline
		}
	}
	if worstDev < 0 {
		return Alert{}, false
	}
	return Alert{
		Code:     "price_anomaly",
		Severity: SeverityWarn,
		Action:   ActionReview,
		Detail:   fmt.Sprintf("item %s price %d vs median %d (%d bps)", worstItem, worstPrice, worstMedian, worstDev),
	}, true
}

func (m *Monitor) concentration(events []Event) (Alert, bool) {
	byParty := make(map[string]int64)
	var total int64
	for _, e := range events {
		if e.Counterparty == "" {
			continue
		}
		byParty[e.Counterparty] += e.Amount
		total += e.Amount
	}
	if total == 0 {
		return Alert{}, false
	}
	bestParty, best := "", int64(0)
	for party, volume := range byParty {
		if volume > best || (volume == best && party < bestParty) {
			bestParty, best = party, volume
		}
	}
	bps := best * 10000 / total
	if bps < int64(m.policy.ConcentrationBPS) {
		return Alert{}, false
	}
	return Alert{
		Code:     "counterparty_concentration",
		Severity: SeverityWarn,
		Action:   ActionFreeze,
		Detail:   fmt.Sprintf("counterparty %s took %d/%d volume (%d bps)", bestParty, best, total, bps),
	}, true
}

func median(xs []int64) int64 {
	if len(xs) == 0 {
		return 0
	}
	sort.Slice(xs, func(i, j int) bool { return xs[i] < xs[j] })
	return xs[len(xs)/2]
}

func abs64(v int64) int64 {
	if v < 0 {
		return -v
	}
	return v
}