《游戏服务端架构·核心系统与契约》13.3 进入卷三：规模与全球化

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

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

// Area groups checkpoints by the question they answer.
type Area string

const (
	AreaCapacity    Area = "capacity"
	AreaCrossRegion Area = "cross-region"
	AreaCost        Area = "cost"
	AreaMultiRegion Area = "multi-region"
)

// Status is deliberately about evidence, not optimism. Estimated means the
// number exists but was not produced by a run on the real topology.
type Status string

const (
	StatusMissing   Status = "missing"
	StatusEstimated Status = "estimated"
	StatusMeasured  Status = "measured"
)

// Checkpoint is one question that must be answered before volume three.
// Evidence is not decoration: a measured value without a command, report path
// or run id is treated as a claim.
type Checkpoint struct {
	ID       string
	Area     Area
	Question string
	Required bool
	Status   Status
	Value    float64
	Unit     string
	Evidence string
}

func areaValid(a Area) bool {
	switch a {
	case AreaCapacity, AreaCrossRegion, AreaCost, AreaMultiRegion:
		return true
	}
	return false
}

func statusValid(s Status) bool {
	switch s {
	case StatusMissing, StatusEstimated, StatusMeasured:
		return true
	}
	return false
}

func areaRank(a Area) int {
	switch a {
	case AreaCapacity:
		return 0
	case AreaCrossRegion:
		return 1
	case AreaCost:
		return 2
	case AreaMultiRegion:
		return 3
	}
	return 4
}

// Gate is the ordered checklist for entering volume three.
type Gate struct {
	checkpoints []Checkpoint
}

// New rejects malformed rows. Duplicate ids are rejected because a duplicated
// checkpoint silently weakens the readiness rule.
func New(checkpoints []Checkpoint) (*Gate, error) {
	seen := make(map[string]bool, len(checkpoints))
	for _, c := range checkpoints {
		if strings.TrimSpace(c.ID) == "" {
			return nil, fmt.Errorf("releaseready: empty checkpoint id")
		}
		if seen[c.ID] {
			return nil, fmt.Errorf("releaseready: duplicate checkpoint %q", c.ID)
		}
		seen[c.ID] = true
		if strings.TrimSpace(c.Question) == "" {
			return nil, fmt.Errorf("releaseready: checkpoint %q has no question", c.ID)
		}
		if !areaValid(c.Area) {
			return nil, fmt.Errorf("releaseready: checkpoint %q has unknown area %q", c.ID, c.Area)
		}
		if !statusValid(c.Status) {
			return nil, fmt.Errorf("releaseready: checkpoint %q has unknown status %q", c.ID, c.Status)
		}
	}
	return &Gate{checkpoints: append([]Checkpoint(nil), checkpoints...)}, nil
}

// satisfied is stricter than "the status says measured". A measured number
// without a unit or evidence is an estimate wearing a measured label.
func satisfied(c Checkpoint) bool {
	return c.Status == StatusMeasured && strings.TrimSpace(c.Unit) != "" && strings.TrimSpace(c.Evidence) != ""
}

func reason(c Checkpoint) string {
	if c.Status != StatusMeasured {
		return string(c.Status)
	}
	return "measured without unit or evidence"
}

func (g *Gate) sorted() []Checkpoint {
	out := append([]Checkpoint(nil), g.checkpoints...)
	sort.Slice(out, func(i, j int) bool {
		ri, rj := areaRank(out[i].Area), areaRank(out[j].Area)
		if ri != rj {
			return ri < rj
		}
		return out[i].ID < out[j].ID
	})
	return out
}

// Verdict is the launch decision. Ready is true only when every required
// checkpoint is satisfied and every cross-region or multi-region checkpoint
// has been measured. The second rule is the "no globalisation without
// measurement" guard.
type Verdict struct {
	Ready    bool
	Blockers []string
}

// Evaluate applies the two blocking rules and returns deterministic output.
func (g *Gate) Evaluate() Verdict {
	var blockers []string
	for _, c := range g.sorted() {
		if !c.Required || satisfied(c) {
			continue
		}
		blockers = append(blockers, fmt.Sprintf("%s (%s): %s", c.ID, c.Area, reason(c)))
	}
	for _, c := range g.sorted() {
		if c.Area != AreaCrossRegion && c.Area != AreaMultiRegion {
			continue
		}
		if c.Required && !satisfied(c) {
			continue // already reported by the required rule
		}
		if !satisfied(c) {
			blockers = append(blockers, fmt.Sprintf("%s (%s): global launch requires measurement", c.ID, c.Area))
		}
	}
	return Verdict{Ready: len(blockers) == 0, Blockers: blockers}
}

// Gaps returns every unsatisfied checkpoint, including optional ones, in the
// same order as Evaluate. Optional gaps are reported but do not block.
func (g *Gate) Gaps() []Checkpoint {
	var out []Checkpoint
	for _, c := range g.sorted() {
		if !satisfied(c) {
			out = append(out, c)
		}
	}
	return out
}

// Coverage is the measured/total count for one area.
type Coverage struct {
	Total    int
	Measured int
}

// Coverage reports progress per area. It is a planning view, not a gate.
func (g *Gate) Coverage() map[Area]Coverage {
	out := make(map[Area]Coverage)
	for _, c := range g.checkpoints {
		cov := out[c.Area]
		cov.Total++
		if satisfied(c) {
			cov.Measured++
		}
		out[c.Area] = cov
	}
	return out
}