《游戏服务端架构·平台化与架构治理》13.2 架构成熟度模型

dimension observability-slo: level 2 repeatable, target 4 managed
dimension cost-compliance: level 3 defined, target 4 managed

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

import (
	"errors"
	"fmt"
)

// ErrReport marks an assessment that cannot be defended in a review.
var ErrReport = errors.New("maturitymodel: invalid report")

// Dimension is one axis of the model. The list is closed on purpose: an
// organization that invents a seventh dimension every quarter never finishes
// a comparison.
type Dimension string

const (
	TopologyBoundary   Dimension = "topology-boundary"
	ContractData       Dimension = "contract-data"
	ScaleDR            Dimension = "scale-dr"
	ObservabilitySLO   Dimension = "observability-slo"
	PlatformGovernance Dimension = "platform-governance"
	CostCompliance     Dimension = "cost-compliance"
)

// Dimensions is the fixed assessment order, also used to keep reports stable.
var Dimensions = []Dimension{
	TopologyBoundary,
	ContractData,
	ScaleDR,
	ObservabilitySLO,
	PlatformGovernance,
	CostCompliance,
}

func validDimension(d Dimension) bool {
	for _, known := range Dimensions {
		if d == known {
			return true
		}
	}
	return false
}

// Level is deliberately small. A five-point scale is enough to separate
// "nothing exists" from "it runs itself"; more points invite false precision.
type Level int

const (
	LevelAdHoc      Level = 1
	LevelRepeatable Level = 2
	LevelDefined    Level = 3
	LevelManaged    Level = 4
	LevelOptimizing Level = 5
)

func (l Level) Name() string {
	switch l {
	case LevelAdHoc:
		return "ad-hoc"
	case LevelRepeatable:
		return "repeatable"
	case LevelDefined:
		return "defined"
	case LevelManaged:
		return "managed"
	case LevelOptimizing:
		return "optimizing"
	}
	return "unknown"
}

func (l Level) valid() bool { return l >= LevelAdHoc && l <= LevelOptimizing }

// EvidenceKind is the source of a claim. Interviews are useful context but
// they are self-report; only artifacts and drills survive an audit.
type EvidenceKind string

const (
	Interview EvidenceKind = "interview"
	Artifact  EvidenceKind = "artifact"
	Drill     EvidenceKind = "drill"
)

func (k EvidenceKind) valid() bool {
	switch k {
	case Interview, Artifact, Drill:
		return true
	}
	return false
}

// Supports is the core anti-inflation rule: a dimension claimed at level 3 or
// above needs at least one artifact or drill output to back it. Without this
// rule every team scores itself "defined" and the model becomes a survey.
func (k EvidenceKind) Supports(level Level) bool {
	if !k.valid() || !level.valid() {
		return false
	}
	return level <= LevelRepeatable || k == Artifact || k == Drill
}

// Evidence must point at something a reviewer can open or rerun. Ref is a
// path, ticket id or dashboard URL; it is not free-form praise.
type Evidence struct {
	Kind EvidenceKind
	Ref  string
}

// Assessment is one dimension's level plus its evidence. Note records the
// caveat the reviewer wants the next assessor to see.
type Assessment struct {
	Dimension Dimension
	Level     Level
	Evidence  []Evidence
	Note      string
}

// Report is a complete assessment. Completeness is structural: all six
// dimensions must appear exactly once before the score means anything.
type Report struct {
	Items []Assessment
}

// Validate rejects missing dimensions, duplicate dimensions, unknown levels,
// evidence-free claims and interview-only claims above level 2.
func (r Report) Validate() error {
	seen := make(map[Dimension]bool, len(Dimensions))
	for i, a := range r.Items {
		switch {
		case !validDimension(a.Dimension):
			return fmt.Errorf("%w: item[%d] has unknown dimension %q", ErrReport, i, a.Dimension)
		case seen[a.Dimension]:
			return fmt.Errorf("%w: dimension %s assessed twice", ErrReport, a.Dimension)
		case !a.Level.valid():
			return fmt.Errorf("%w: dimension %s has level %d", ErrReport, a.Dimension, a.Level)
		case len(a.Evidence) == 0:
			return fmt.Errorf("%w: dimension %s has no evidence", ErrReport, a.Dimension)
		}
		seen[a.Dimension] = true
		for j, e := range a.Evidence {
			switch {
			case !e.Kind.valid():
				return fmt.Errorf("%w: dimension %s evidence[%d] has unknown kind %q", ErrReport, a.Dimension, j, e.Kind)
			case e.Ref == "":
				return fmt.Errorf("%w: dimension %s evidence[%d] has no reference", ErrReport, a.Dimension, j)
			case !e.Kind.Supports(a.Level):
				return fmt.Errorf("%w: dimension %s level %s needs artifact or drill, not %s",
					ErrReport, a.Dimension, a.Level.Name(), e.Kind)
			}
		}
	}
	for _, d := range Dimensions {
		if !seen[d] {
			return fmt.Errorf("%w: dimension %s not assessed", ErrReport, d)
		}
	}
	return nil
}

// Overall returns the lowest level, not the average. Maturity is bounded by
// the weakest dimension: a brilliant topology cannot compensate for no SLO.
// An empty report returns 0 so callers can distinguish "no data" from level 1.
func (r Report) Overall() Level {
	if len(r.Items) == 0 {
		return 0
	}
	low := LevelOptimizing
	for _, a := range r.Items {
		if a.Level < low {
			low = a.Level
		}
	}
	return low
}

// Gaps lists every dimension below target in the canonical order. Missing
// dimensions are reported as "not assessed" rather than silently skipped.
func (r Report) Gaps(target Level) []string {
	byDim := make(map[Dimension]Assessment, len(r.Items))
	for _, a := range r.Items {
		byDim[a.Dimension] = a
	}
	var out []string
	for _, d := range Dimensions {
		a, ok := byDim[d]
		if !ok {
			out = append(out, fmt.Sprintf("dimension %s: not assessed", d))
			continue
		}
		if a.Level < target {
			out = append(out, fmt.Sprintf("dimension %s: level %d %s, target %d %s",
				d, a.Level, a.Level.Name(), target, target.Name()))
		}
	}
	return out
}