《MMO 服务器开发》16.3 价格索引与经济风控

// file: internal/trade/index.go
// tier: L1
// verify: go test ./internal/trade/
package trade

import (
	"sort"
	"sync"
)

// TradeRecord 是一笔已成交记录：拍卖成交与玩家面对面交易都会落成它。
type TradeRecord struct {
	ItemID ItemID
	Price  int64
	Count  int64
	Buyer  PlayerID
	Seller PlayerID
	At     int64
}

// PriceIndex 按物品维护最近 window 笔成交，产出中位价与成交量加权均价（VWAP）。
// 用中位数而非均价做主参考，是因为单笔异常高价对中位数几乎没有影响。
type PriceIndex struct {
	mu            sync.Mutex
	window        int
	pairThreshold int
	byItem        map[ItemID][]TradeRecord
	pairs         map[pairKey]int // 窗口内同一对买卖双方的成交次数
}

type pairKey struct {
	Buyer, Seller PlayerID
}

func NewPriceIndex(window int) *PriceIndex {
	if window <= 0 {
		window = 200
	}
	return &PriceIndex{
		window:        window,
		pairThreshold: 5,
		byItem:        make(map[ItemID][]TradeRecord),
		pairs:         make(map[pairKey]int),
	}
}

// Add 追加一笔成交，并滑出窗口最旧的一笔；被滑出的那笔同时从对敲计数里扣掉，
// 否则「高频对敲」会因计数只增不减而永远误报。
func (p *PriceIndex) Add(r TradeRecord) {
	p.mu.Lock()
	defer p.mu.Unlock()
	rs := append(p.byItem[r.ItemID], r)
	if len(rs) > p.window {
		drop := rs[0]
		rs = rs[1:]
		if k := (pairKey{drop.Buyer, drop.Seller}); p.pairs[k] > 0 {
			p.pairs[k]--
		}
	}
	p.byItem[r.ItemID] = rs
	p.pairs[pairKey{r.Buyer, r.Seller}]++
}

// Median 返回窗口内的中位价；窗口为空时 ok=false，调用方须自行决定兜底价。
func (p *PriceIndex) Median(item ItemID) (int64, bool) {
	p.mu.Lock()
	defer p.mu.Unlock()
	rs := p.byItem[item]
	if len(rs) == 0 {
		return 0, false
	}
	prices := make([]int64, len(rs))
	for i, r := range rs {
		prices[i] = r.Price
	}
	sort.Slice(prices, func(i, j int) bool { return prices[i] < prices[j] })
	return prices[len(prices)/2], true
}

// VWAP 是成交量加权均价：大额成交对它的影响更大，适合做「大单是否异常」的基准。
func (p *PriceIndex) VWAP(item ItemID) (int64, bool) {
	p.mu.Lock()
	defer p.mu.Unlock()
	return p.vwapLocked(item)
}

func (p *PriceIndex) vwapLocked(item ItemID) (int64, bool) {
	rs := p.byItem[item]
	var sumPV, sumV int64
	for _, r := range rs {
		sumPV += r.Price * r.Count
		sumV += r.Count
	}
	if sumV == 0 {
		return 0, false
	}
	return sumPV / sumV, true
}

type RiskLevel uint8

const (
	RiskNone RiskLevel = iota
	RiskWatch
	RiskBlock
)

// 偏离阈值的单位是百分比：超过 watchPct 进观察，超过 blockPct 直接拦截。
const (
	watchPct = 150
	blockPct = 300
)

// Assess 对一笔拟成交记录打分。它是经济风控的第一道闸：自买自卖与严重偏离
// 直接拦；同一对手方高频对敲与轻度偏离先记观察，交人工复核。
func (p *PriceIndex) Assess(r TradeRecord) (RiskLevel, string) {
	if r.Buyer == r.Seller {
		return RiskBlock, "自买自卖：买卖双方为同一角色"
	}
	p.mu.Lock()
	defer p.mu.Unlock()
	if p.pairs[pairKey{r.Buyer, r.Seller}] >= p.pairThreshold {
		return RiskWatch, "同一对手方高频对敲"
	}
	ref, ok := p.vwapLocked(r.ItemID)
	if !ok {
		return RiskNone, ""
	}
	dev := r.Price - ref
	if dev < 0 {
		dev = -dev
	}
	switch {
	case dev*100 > ref*blockPct:
		return RiskBlock, "价格严重偏离指数（>300%）"
	case dev*100 > ref*watchPct:
		return RiskWatch, "价格偏离指数（>150%）"
	}
	return RiskNone, ""
}

// snippet: internal/trade/index_test.go（摘录）
func TestMedianResistsSingleOutlier(t *testing.T) {
	p := NewPriceIndex(100)
	for i := 0; i < 9; i++ {
		p.Add(TradeRecord{ItemID: 3001, Price: 1000, Count: 1, Buyer: PlayerID(i + 1), Seller: 900})
	}
	p.Add(TradeRecord{ItemID: 3001, Price: 999_999, Count: 1, Buyer: 77, Seller: 900})
	med, ok := p.Median(3001)
	if !ok || med != 1000 {
		t.Fatalf("中位价 = %d ok=%v，期望 1000（不受 999999 影响）", med, ok)
	}
}

func TestAssessBlocksSelfTradeAndExtremeDeviation(t *testing.T) {
	p := NewPriceIndex(100)
	for i := 0; i < 20; i++ {
		p.Add(TradeRecord{ItemID: 3001, Price: 1000, Count: 1, Buyer: PlayerID(i + 1), Seller: 900})
	}
	if lvl, reason := p.Assess(TradeRecord{ItemID: 3001, Price: 1000, Buyer: 5, Seller: 5}); lvl != RiskBlock {
		t.Fatalf("自买自卖 = %d (%s)，期望 RiskBlock", lvl, reason)
	}
	if lvl, _ := p.Assess(TradeRecord{ItemID: 3001, Price: 3000, Count: 1, Buyer: 55, Seller: 900}); lvl != RiskWatch {
		t.Fatalf("偏离 200%% = %d，期望 RiskWatch", lvl)
	}
	if lvl, _ := p.Assess(TradeRecord{ItemID: 3001, Price: 9999, Count: 1, Buyer: 55, Seller: 900}); lvl != RiskBlock {
		t.Fatalf("偏离 900%% = %d，期望 RiskBlock", lvl)
	}
}

$ go test ./internal/trade/
ok  aegis/internal/trade  0.587s   （15 个 test 全绿）

$ go test -race ./internal/trade/
ok  aegis/internal/trade           （无 data race）