《游戏服务端架构·平台化与架构治理》2.1 活动编排与配置

// file: internal/liveopsconfig/validate.go
// tier: L1
// verify: go test ./internal/liveopsconfig/
package liveopsconfig

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

// Event is one LiveOps activity as the platform stores it. ActivityVersion
// changes when the design changes; ConfigVersion changes when any editable
// field changes. Keeping them separate lets an operator answer "which build
// of the event" and "which revision of the numbers" without conflating them.
type Event struct {
	ID              string
	Name            string
	Start           time.Time
	End             time.Time
	Timezone        string
	MutexGroup      string
	Requires        []string
	Rewards         []Reward
	ActivityVersion int
	ConfigVersion   int
}

// Reward is one row of the reward table. Count is validated before publish,
// because an overflow is cheaper to reject here than to reconcile after the
// first player claims it.
type Reward struct {
	ItemID string
	Count  int64
}

// Problem is a validation finding tied to one event and one field. Codes are
// stable so a UI or a CI gate can group them without parsing messages.
type Problem struct {
	EventID string
	Field   string
	Code    string
	Message string
}

func (p Problem) String() string {
	return fmt.Sprintf("%s.%s: %s (%s)", p.EventID, p.Field, p.Message, p.Code)
}

// Policy carries limits that operations may tune per environment. Zero means
// "use the default" for MaxWindow; tests set explicit values.
type Policy struct {
	MaxWindow      time.Duration
	MaxRewardCount int64
}

func DefaultPolicy() Policy {
	return Policy{MaxWindow: 30 * 24 * time.Hour, MaxRewardCount: 1_000_000}
}

func (p Policy) normalized() Policy {
	if p.MaxWindow <= 0 {
		p.MaxWindow = DefaultPolicy().MaxWindow
	}
	if p.MaxRewardCount <= 0 {
		p.MaxRewardCount = DefaultPolicy().MaxRewardCount
	}
	return p
}

// Validate checks structural problems that can be decided without a running
// server: windows, reward rows, dependencies and mutual exclusion. It never
// resolves item names or player eligibility; those need data owned by other
// services and belong to a publish-time check with those services online.
func (p Policy) Validate(events []Event) []Problem {
	p = p.normalized()
	var out []Problem
	byID := make(map[string]Event, len(events))
	for _, e := range events {
		if e.ID == "" {
			out = append(out, Problem{EventID: e.ID, Field: "id", Code: "empty_id", Message: "event id is empty"})
			continue
		}
		if _, dup := byID[e.ID]; dup {
			out = append(out, Problem{EventID: e.ID, Field: "id", Code: "duplicate_id", Message: "event id is duplicated"})
		}
		byID[e.ID] = e
		out = append(out, p.validateOne(e)...)
	}
	out = append(out, validateDependencies(events, byID)...)
	out = append(out, p.validateMutex(events)...)
	sort.SliceStable(out, func(i, j int) bool {
		if out[i].EventID != out[j].EventID {
			return out[i].EventID < out[j].EventID
		}
		if out[i].Field != out[j].Field {
			return out[i].Field < out[j].Field
		}
		return out[i].Code < out[j].Code
	})
	return out
}

func (p Policy) validateOne(e Event) []Problem {
	var out []Problem
	if e.Name == "" {
		out = append(out, Problem{e.ID, "name", "empty_name", "event name is empty"})
	}
	if e.Timezone == "" {
		out = append(out, Problem{e.ID, "timezone", "empty_timezone", "timezone is empty"})
	} else if _, err := time.LoadLocation(e.Timezone); err != nil {
		out = append(out, Problem{e.ID, "timezone", "unknown_timezone", err.Error()})
	}
	switch {
	case e.Start.IsZero() || e.End.IsZero():
		out = append(out, Problem{e.ID, "window", "window_zero", "start and end must be set"})
	case !e.End.After(e.Start):
		out = append(out, Problem{e.ID, "window", "window_inverted", "end must be after start"})
	case e.End.Sub(e.Start) > p.MaxWindow:
		out = append(out, Problem{e.ID, "window", "window_too_long", "window exceeds the configured maximum"})
	}
	seen := make(map[string]bool, len(e.Rewards))
	for _, r := range e.Rewards {
		if r.ItemID == "" {
			out = append(out, Problem{e.ID, "rewards", "empty_item", "reward item id is empty"})
			continue
		}
		if seen[r.ItemID] {
			out = append(out, Problem{e.ID, "rewards", "duplicate_item", "reward item appears twice: " + r.ItemID})
		}
		seen[r.ItemID] = true
		if r.Count <= 0 {
			out = append(out, Problem{e.ID, "rewards", "reward_non_positive", "reward count must be positive: " + r.ItemID})
		} else if r.Count > p.MaxRewardCount {
			out = append(out, Problem{e.ID, "rewards", "reward_overflow", "reward count exceeds the configured maximum: " + r.ItemID})
		}
	}
	if e.ActivityVersion <= 0 {
		out = append(out, Problem{e.ID, "activity_version", "bad_activity_version", "activity version must be positive"})
	}
	if e.ConfigVersion <= 0 {
		out = append(out, Problem{e.ID, "config_version", "bad_config_version", "config version must be positive"})
	}
	return out
}

func validateDependencies(events []Event, byID map[string]Event) []Problem {
	var out []Problem
	for _, e := range events {
		for _, req := range e.Requires {
			switch {
			case req == "":
				out = append(out, Problem{e.ID, "requires", "empty_dependency", "dependency id is empty"})
			case req == e.ID:
				out = append(out, Problem{e.ID, "requires", "self_dependency", "event depends on itself"})
			case byID[req].ID == "":
				out = append(out, Problem{e.ID, "requires", "unknown_dependency", "dependency does not exist: " + req})
			}
		}
	}
	color := make(map[string]int, len(byID))
	var visit func(string)
	visit = func(id string) {
		color[id] = 1
		for _, req := range byID[id].Requires {
			if byID[req].ID == "" || req == id {
				continue
			}
			switch color[req] {
			case 0:
				visit(req)
			case 1:
				out = append(out, Problem{id, "requires", "dependency_cycle", "dependency cycle through " + req})
			}
		}
		color[id] = 2
	}
	for _, e := range events {
		if e.ID != "" && color[e.ID] == 0 {
			visit(e.ID)
		}
	}
	return out
}

func (p Policy) validateMutex(events []Event) []Problem {
	var out []Problem
	for i := 0; i < len(events); i++ {
		for j := i + 1; j < len(events); j++ {
			a, b := events[i], events[j]
			if a.MutexGroup == "" || a.MutexGroup != b.MutexGroup {
				continue
			}
			if a.Start.IsZero() || a.End.IsZero() || b.Start.IsZero() || b.End.IsZero() {
				continue
			}
			if a.Start.Before(b.End) && b.Start.Before(a.End) {
				out = append(out, Problem{a.ID, "mutex_group", "mutex_overlap", "overlaps with " + b.ID})
				out = append(out, Problem{b.ID, "mutex_group", "mutex_overlap", "overlaps with " + a.ID})
			}
		}
	}
	return out
}

// ValidationError keeps every finding. A publish UI shows the whole list so
// one fix cycle is enough; returning only the first problem hides the rest.
type ValidationError struct {
	Problems []Problem
}

func (e *ValidationError) Error() string {
	parts := make([]string, 0, len(e.Problems))
	for _, p := range e.Problems {
		parts = append(parts, p.String())
	}
	return "liveopsconfig: " + strings.Join(parts, "; ")
}