《游戏服务端架构·平台化与架构治理》3.3 客服工具与数据修复流程

// file: internal/csrepair/ticket.go
// tier: L1
// verify: go test ./internal/csrepair/
package csrepair

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

// State is the repair ticket's position in a deliberately boring workflow.
// Boring is the point: every step has a name, an actor, and a record.
type State string

const (
	StateDraft      State = "draft"
	StateReviewed   State = "reviewed"
	StateApproved   State = "approved"
	StateExecuting  State = "executing"
	StateVerified   State = "verified"
	StateRolledBack State = "rolled_back"
	StateFailed     State = "failed"
)

var (
	ErrBadTransition = errors.New("csrepair: illegal state transition")
	ErrSelfReview    = errors.New("csrepair: ticket owner cannot review own repair")
	ErrChecksPending = errors.New("csrepair: prechecks have not all passed")
	ErrNoDryRun      = errors.New("csrepair: dry-run evidence required")
	ErrEvidence      = errors.New("csrepair: evidence missing")
	ErrUnknownSystem = errors.New("csrepair: unknown system")
	ErrDuplicate     = errors.New("csrepair: duplicate system")
	ErrBadState      = errors.New("csrepair: operation not allowed in current state")
)

var transitions = map[State]map[State]bool{
	StateDraft:      {StateReviewed: true},
	StateReviewed:   {StateApproved: true, StateDraft: true},
	StateApproved:   {StateExecuting: true, StateDraft: true},
	StateExecuting:  {StateVerified: true, StateFailed: true, StateRolledBack: true},
	StateFailed:     {StateRolledBack: true, StateDraft: true},
	StateVerified:   {},
	StateRolledBack: {},
}

// Check is one precondition. Name is stable; Detail is for the reviewer.
type Check struct {
	Name   string
	Passed bool
	Detail string
}

// Evidence is one recorded action. Kind distinguishes dry-run from apply and
// rollback so a verifier can require the right proof at the right step.
type Evidence struct {
	Kind   string
	System string
	Actor  string
	At     time.Time
	Detail string
}

// Ticket is the repair case. Owner prepares, Reviewer approves, and the
// evidence slice is append-only by convention.
type Ticket struct {
	ID       string
	State    State
	Owner    string
	Reviewer string
	Checks   []Check
	Evidence []Evidence
}

// CanTransition reports whether the state edge exists.
func CanTransition(from, to State) bool { return transitions[from][to] }

// AllPassed is intentionally strict: a skipped check is a failed check.
func AllPassed(checks []Check) bool {
	if len(checks) == 0 {
		return false
	}
	for _, c := range checks {
		if !c.Passed {
			return false
		}
	}
	return true
}

// Move advances the ticket and appends a state evidence row. Guards are
// evaluated before the state changes, so a rejected move leaves no trace.
func (t *Ticket) Move(to State, actor string, now time.Time) error {
	if !CanTransition(t.State, to) {
		return fmt.Errorf("%w: %s -> %s", ErrBadTransition, t.State, to)
	}
	switch to {
	case StateReviewed:
		if actor == "" || actor == t.Owner {
			return ErrSelfReview
		}
		t.Reviewer = actor
	case StateApproved:
		if t.Reviewer == "" || actor != t.Reviewer {
			return ErrSelfReview
		}
		if !AllPassed(t.Checks) {
			return ErrChecksPending
		}
	case StateExecuting:
		if !hasEvidence(t.Evidence, "dry-run", "") {
			return ErrNoDryRun
		}
	case StateVerified:
		if !hasEvidence(t.Evidence, "apply", "") {
			return ErrEvidence
		}
	case StateRolledBack:
		if !hasEvidence(t.Evidence, "rollback", "") {
			return ErrEvidence
		}
	}
	t.State = to
	t.Evidence = append(t.Evidence, Evidence{Kind: string(to), Actor: actor, At: now})
	return nil
}

// Record attaches evidence without changing state. It is valid only while the
// case is approved or executing, which prevents evidence from being written
// after the ticket is closed.
func (t *Ticket) Record(kind, system, actor, detail string, now time.Time) error {
	if t.State != StateApproved && t.State != StateExecuting && t.State != StateFailed {
		return ErrBadState
	}
	if kind == "" || actor == "" || detail == "" {
		return ErrEvidence
	}
	if system != "" {
		if _, ok := systemRank[system]; !ok {
			return ErrUnknownSystem
		}
	}
	t.Evidence = append(t.Evidence, Evidence{Kind: kind, System: system, Actor: actor, At: now, Detail: detail})
	return nil
}

func hasEvidence(ev []Evidence, kind, system string) bool {
	for _, e := range ev {
		if e.Kind == kind && (system == "" || e.System == system) {
			return true
		}
	}
	return false
}

// systemRank encodes the repair order that prevents a later system from
// validating against a stale upstream value. Account is repaired first, then
// the commercial record, then the inventory derived from it, then mail.
var systemRank = map[string]int{
	"account":   0,
	"order":     1,
	"inventory": 2,
	"mail":      3,
}

// PlanSystems validates and orders a repair scope. Unknown or duplicated
// systems fail instead of being silently dropped.
func PlanSystems(systems []string) ([]string, error) {
	seen := map[string]bool{}
	plan := make([]string, 0, len(systems))
	for _, s := range systems {
		if _, ok := systemRank[s]; !ok {
			return nil, fmt.Errorf("%w: %s", ErrUnknownSystem, s)
		}
		if seen[s] {
			return nil, fmt.Errorf("%w: %s", ErrDuplicate, s)
		}
		seen[s] = true
		plan = append(plan, s)
	}
	sort.SliceStable(plan, func(i, j int) bool { return systemRank[plan[i]] < systemRank[plan[j]] })
	return plan, nil
}