《游戏服务端架构·平台化与架构治理》4.2 处置、申诉与复核

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

import (
	"errors"
	"fmt"
	"time"
)

// Stage is the player-visible enforcement step, ordered from lightest to
// heaviest. Operations may skip a rung only as a documented emergency.
type Stage string

const (
	StageNotice   Stage = "notice"
	StageThrottle Stage = "throttle"
	StageIsolate  Stage = "isolate"
	StageTempBan  Stage = "temp_ban"
	StagePermBan  Stage = "perm_ban"
	StageClawback Stage = "clawback"
)

var ladder = []Stage{StageNotice, StageThrottle, StageIsolate, StageTempBan, StagePermBan, StageClawback}

func stageRank(s Stage) (int, bool) {
	for i, v := range ladder {
		if v == s {
			return i, true
		}
	}
	return 0, false
}

// Status tracks the case, not the account. A case can be active while the
// player keeps playing under a throttle.
type Status string

const (
	StatusActive     Status = "active"
	StatusAppealed   Status = "appealed"
	StatusOverturned Status = "overturned"
	StatusUpheld     Status = "upheld"
)

// Outcome is the review conclusion. It is empty until a reviewer decides.
type Outcome string

const (
	OutcomeNone       Outcome = ""
	OutcomeOverturned Outcome = "overturned"
	OutcomeUpheld     Outcome = "upheld"
)

// Appeal is the player's filing. Deadline is copied into the case so the
// decision survives a later policy change.
type Appeal struct {
	FiledAt   time.Time
	Deadline  time.Duration
	Statement string
	Evidence  []string
}

// Case is one enforcement action and everything that happened after it.
type Case struct {
	ID         string
	PlayerID   string
	Stage      Stage
	IssuedBy   string
	IssuedAt   time.Time
	ExpiresAt  time.Time
	Evidence   []string
	Status     Status
	Appeal     *Appeal
	Reviewer   string
	Outcome    Outcome
	ReopenedAt time.Time
}

// Escalate moves a case to a heavier stage. Skipping a rung requires both an
// emergency flag and a written reason; an empty evidence list never escalates.
func Escalate(c Case, target Stage, duration time.Duration, emergency bool, reason string, now time.Time) (Case, error) {
	if c.Status != StatusActive {
		return c, errors.New("enforcementappeal: only an active case can escalate")
	}
	cur, ok := stageRank(c.Stage)
	if !ok {
		return c, fmt.Errorf("enforcementappeal: unknown current stage %q", c.Stage)
	}
	next, ok := stageRank(target)
	if !ok {
		return c, fmt.Errorf("enforcementappeal: unknown target stage %q", target)
	}
	if next <= cur {
		return c, errors.New("enforcementappeal: target must be heavier than current stage")
	}
	if next-cur > 1 {
		if !emergency {
			return c, errors.New("enforcementappeal: skipping a stage requires emergency")
		}
		if reason == "" {
			return c, errors.New("enforcementappeal: emergency escalation requires a reason")
		}
	}
	if len(c.Evidence) == 0 {
		return c, errors.New("enforcementappeal: escalation requires at least one evidence item")
	}
	if target == StageTempBan && duration <= 0 {
		return c, errors.New("enforcementappeal: temporary ban requires a positive duration")
	}
	c.Stage = target
	c.IssuedAt = now
	c.ExpiresAt = time.Time{}
	if target == StageTempBan {
		c.ExpiresAt = now.Add(duration)
	}
	return c, nil
}

// FileAppeal records a player appeal inside the window measured from the last
// enforcement action. A late appeal is rejected here and must go to support.
func FileAppeal(c Case, now time.Time, statement string, evidence []string, window time.Duration) (Case, error) {
	if c.Status != StatusActive {
		return c, errors.New("enforcementappeal: case is not open for an appeal")
	}
	if statement == "" {
		return c, errors.New("enforcementappeal: appeal statement is required")
	}
	if window <= 0 {
		return c, errors.New("enforcementappeal: appeal window must be positive")
	}
	if now.Before(c.IssuedAt) {
		return c, errors.New("enforcementappeal: appeal cannot precede the action")
	}
	if now.Sub(c.IssuedAt) > window {
		return c, errors.New("enforcementappeal: appeal window has closed")
	}
	c.Appeal = &Appeal{
		FiledAt:   now,
		Deadline:  window,
		Statement: statement,
		Evidence:  append([]string(nil), evidence...),
	}
	c.Status = StatusAppealed
	return c, nil
}

// AssignReviewer enforces independence: the operator who issued the action
// cannot review it, and a case gets exactly one reviewer per round.
func AssignReviewer(c Case, reviewer string) (Case, error) {
	if c.Status != StatusAppealed || c.Appeal == nil {
		return c, errors.New("enforcementappeal: only an appealed case can be assigned")
	}
	if reviewer == "" {
		return c, errors.New("enforcementappeal: reviewer is required")
	}
	if reviewer == c.IssuedBy {
		return c, errors.New("enforcementappeal: issuer cannot review the same case")
	}
	if c.Reviewer != "" {
		return c, errors.New("enforcementappeal: case already has a reviewer")
	}
	c.Reviewer = reviewer
	return c, nil
}

// Review closes the current appeal. Overturning restores the player and makes
// the case eligible for compensation; upholding keeps the action in force.
func Review(c Case, outcome Outcome, note string, now time.Time) (Case, error) {
	if c.Status != StatusAppealed || c.Appeal == nil {
		return c, errors.New("enforcementappeal: no open appeal to review")
	}
	if c.Reviewer == "" {
		return c, errors.New("enforcementappeal: an independent reviewer must be assigned first")
	}
	if outcome != OutcomeOverturned && outcome != OutcomeUpheld {
		return c, errors.New("enforcementappeal: outcome must be overturned or upheld")
	}
	if note == "" {
		return c, errors.New("enforcementappeal: review note is required")
	}
	c.Outcome = outcome
	if outcome == OutcomeOverturned {
		c.Status = StatusOverturned
	} else {
		c.Status = StatusUpheld
	}
	return c, nil
}

// Reopen puts a decided case back into review when new evidence arrives. The
// reviewer is cleared so the new round cannot reuse the old conclusion, and
// the previous outcome is discarded rather than overwritten silently.
func Reopen(c Case, newEvidence []string, now time.Time) (Case, error) {
	if c.Status != StatusUpheld && c.Status != StatusOverturned {
		return c, errors.New("enforcementappeal: only a decided case can be reopened")
	}
	if len(newEvidence) == 0 {
		return c, errors.New("enforcementappeal: reopening requires new evidence")
	}
	c.Evidence = append(append([]string(nil), c.Evidence...), newEvidence...)
	c.Status = StatusAppealed
	c.Outcome = OutcomeNone
	c.Reviewer = ""
	c.ReopenedAt = now
	return c, nil
}

// Compensation is what the player receives after an overturned action. An
// empty compensation is rejected because a silent overturn does not repair
// trust.
type Compensation struct {
	Currency   int64
	Items      []string
	Reputation int
	Note       string
}

// Compensate validates and stamps the compensation for an overturned case.
func Compensate(c Case, comp Compensation) (Compensation, error) {
	if c.Status != StatusOverturned {
		return comp, errors.New("enforcementappeal: compensation requires an overturned case")
	}
	if comp.Currency < 0 || comp.Reputation < 0 {
		return comp, errors.New("enforcementappeal: compensation values must not be negative")
	}
	if comp.Currency == 0 && comp.Reputation == 0 && len(comp.Items) == 0 {
		return comp, errors.New("enforcementappeal: compensation must not be empty")
	}
	if comp.Note == "" {
		comp.Note = "处罚已撤销，补偿已发放"
	}
	return comp, nil
}

// SLABreached reports whether an open appeal has waited longer than the
// published review SLA. Decided cases never breach, even if they took long.
func SLABreached(c Case, now time.Time, sla time.Duration) bool {
	if c.Appeal == nil || c.Status != StatusAppealed || sla <= 0 {
		return false
	}
	return now.Sub(c.Appeal.FiledAt) > sla
}

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