《游戏服务端架构·规模化、全球化与成本》10.1 版号、实名、防沉迷的架构落点

// file: internal/compliancerules/rules.go
// tier: L1
// verify: go test ./internal/compliancerules/
package compliancerules

import (
	"sort"
	"strings"
	"time"
)

// Gate is a point where the platform must make an allow/deny decision. The
// same account can pass one gate and fail the next; treating them as a single
// "login check" hides where a rule is actually enforced.
type Gate string

const (
	GateBeforeLogin   Gate = "before_login"
	GateBeforeEnter   Gate = "before_enter"
	GateBeforePayment Gate = "before_payment"
	GateCrossRegion   Gate = "cross_region"
)

// Severity separates a synchronous block from a review that may complete
// after the player is already online. A review is not a substitute for a
// block at a gate whose answer must be exact before the action proceeds.
type Severity string

const (
	SeverityBlock  Severity = "block"
	SeverityReview Severity = "review"
)

// Reason is a stable machine-readable code. Keeping it separate from the
// player-facing message lets support and analytics count denials without
// parsing prose, and lets one reason serve several gates.
type Reason string

const (
	ReasonRealNameMissing    Reason = "real_name_missing"
	ReasonRealNamePending    Reason = "real_name_pending"
	ReasonRealNameRejected   Reason = "real_name_rejected"
	ReasonAgeUnknown         Reason = "age_band_unknown"
	ReasonMinorBudgetUsedUp  Reason = "minor_budget_used_up"
	ReasonLicenseUnavailable Reason = "license_unavailable"
	ReasonResidencyReview    Reason = "residency_review"
)

func (r Reason) String() string { return string(r) }

// RealNameState is the cached result of an identity provider call. Unknown
// is not Pending: Unknown means no answer is cached, Pending means a call is
// in flight or the provider asked us to retry later.
type RealNameState string

const (
	RealNameVerified RealNameState = "verified"
	RealNamePending  RealNameState = "pending"
	RealNameRejected RealNameState = "rejected"
	RealNameUnknown  RealNameState = "unknown"
)

// AgeBand is deliberately coarse. The server needs to know whether minor
// limits apply and which budget to read, not a birth date.
type AgeBand string

const (
	AgeAdult   AgeBand = "adult"
	AgeMinor   AgeBand = "minor"
	AgeUnknown AgeBand = "unknown"
)

// AccountState is the subset of account facts a gate needs. Keeping it a
// value makes the rule table testable without a database, and makes it
// obvious which facts a new rule depends on.
type AccountState struct {
	RealName   RealNameState
	Age        AgeBand
	MinorLeft  time.Duration
	LicenseOK  bool
	HomeRegion string
}

// Request is one gate evaluation. RoleID is carried for logs only; limits
// are accounted per account, never per role, so a player cannot reset a
// budget by switching characters.
type Request struct {
	AccountID string
	RoleID    string
	Gate      Gate
	Region    string
	State     AccountState
	Now       time.Time
}

// Decision is the result of one pass over the rule table. Reviews are still
// allowed; blocks are not. A block always wins even if a review also fired,
// because an asynchronous follow-up cannot undo an action already taken.
type Decision struct {
	Allow   bool
	Blocks  []Reason
	Reviews []Reason
}

func (d Decision) Explain() string {
	if d.Allow && len(d.Reviews) == 0 {
		return "allow"
	}
	parts := make([]string, 0, 2)
	if len(d.Blocks) > 0 {
		parts = append(parts, "block:"+joinReasons(d.Blocks))
	}
	if len(d.Reviews) > 0 {
		parts = append(parts, "review:"+joinReasons(d.Reviews))
	}
	return strings.Join(parts, " ")
}

func joinReasons(rs []Reason) string {
	out := make([]string, len(rs))
	for i, r := range rs {
		out[i] = string(r)
	}
	sort.Strings(out)
	return strings.Join(out, ",")
}

// Rule is one condition at one gate. Rules are data so they can be reviewed,
// diffed and unit-tested; the evaluator itself only knows block/review.
type Rule struct {
	Gate     Gate
	Severity Severity
	Reason   Reason
	Match    func(Request) bool
}

// DefaultRules is the policy table used by the platform. Order is stable so
// that Explain output and tests do not depend on map iteration.
func DefaultRules() []Rule {
	return []Rule{
		{GateBeforeLogin, SeverityBlock, ReasonRealNameRejected, func(r Request) bool {
			return r.State.RealName == RealNameRejected
		}},
		{GateBeforeLogin, SeverityReview, ReasonRealNamePending, func(r Request) bool {
			return r.State.RealName == RealNamePending || r.State.RealName == RealNameUnknown
		}},
		{GateBeforeEnter, SeverityBlock, ReasonRealNameMissing, func(r Request) bool {
			return r.State.RealName != RealNameVerified
		}},
		{GateBeforeEnter, SeverityBlock, ReasonMinorBudgetUsedUp, func(r Request) bool {
			return r.State.Age == AgeMinor && r.State.MinorLeft <= 0
		}},
		{GateBeforeEnter, SeverityReview, ReasonAgeUnknown, func(r Request) bool {
			return r.State.Age == AgeUnknown
		}},
		{GateBeforePayment, SeverityBlock, ReasonRealNameMissing, func(r Request) bool {
			return r.State.RealName != RealNameVerified
		}},
		{GateBeforePayment, SeverityBlock, ReasonAgeUnknown, func(r Request) bool {
			return r.State.Age == AgeUnknown
		}},
		{GateBeforePayment, SeverityBlock, ReasonLicenseUnavailable, func(r Request) bool {
			return !r.State.LicenseOK
		}},
		{GateBeforePayment, SeverityBlock, ReasonMinorBudgetUsedUp, func(r Request) bool {
			return r.State.Age == AgeMinor && r.State.MinorLeft <= 0
		}},
		{GateCrossRegion, SeverityReview, ReasonResidencyReview, func(r Request) bool {
			return r.State.HomeRegion != "" && r.Region != r.State.HomeRegion
		}},
	}
}

// Evaluate applies every matching rule once. It never short-circuits: support
// needs the full reason list to explain a denial, and a second rule must not
// disappear just because the first one already blocked.
func Evaluate(req Request, rules []Rule) Decision {
	d := Decision{Allow: true}
	for _, rule := range rules {
		if rule.Gate != req.Gate || !rule.Match(req) {
			continue
		}
		if rule.Severity == SeverityBlock {
			d.Allow = false
			d.Blocks = append(d.Blocks, rule.Reason)
			continue
		}
		d.Reviews = append(d.Reviews, rule.Reason)
	}
	return d
}

// EvaluateDefault is the path used by request handlers. Tests that exercise
// a narrower policy can call Evaluate directly.
func EvaluateDefault(req Request) Decision {
	return Evaluate(req, DefaultRules())
}