《游戏服务端架构·平台化与架构治理》12.2 技术选型与供应商评估

// file: internal/vendoreval/model.go
// tier: L1
// verify: go test ./internal/vendoreval/
package vendoreval

import (
	"errors"
	"fmt"
)

var (
	ErrWeights  = errors.New("vendoreval: invalid weights")
	ErrVendor   = errors.New("vendoreval: invalid vendor")
	ErrNoVendor = errors.New("vendoreval: no vendor passes hard constraints")
)

// Dimension is scored 0..5 in one direction: 5 is better. Cost is "cost fit"
// and lock-in is "lock-in resistance", not raw spend.
type Dimension string

const (
	Function    Dimension = "function"
	Performance Dimension = "performance"
	Reliability Dimension = "reliability"
	CostFit     Dimension = "cost-fit"
	Compliance  Dimension = "compliance"
	LockIn      Dimension = "lock-in-resistance"
	TeamFit     Dimension = "team-fit"
	Exit        Dimension = "exit-cheapness"
)

var Dimensions = []Dimension{Function, Performance, Reliability, CostFit, Compliance, LockIn, TeamFit, Exit}

type Weights map[Dimension]float64

// Validate rejects missing dimensions instead of treating them as zero: a
// missing weight means the evaluation is incomplete, not that it does not care.
func (w Weights) Validate() error {
	total := 0.0
	for _, d := range Dimensions {
		v, ok := w[d]
		if !ok {
			return fmt.Errorf("%w: missing weight for %s", ErrWeights, d)
		}
		if v < 0 || v > 1 {
			return fmt.Errorf("%w: weight for %s is %g, want [0,1]", ErrWeights, d, v)
		}
		total += v
	}
	if total < 0.999 || total > 1.001 {
		return fmt.Errorf("%w: weights sum to %g, want 1", ErrWeights, total)
	}
	return nil
}

// VendorRisk is a supplier-level risk. Severity 3+ requires a written
// mitigation; "we will watch it" is not a mitigation.
type VendorRisk struct {
	Kind       string
	Severity   int
	Mitigation string
}

func (r VendorRisk) Validate() error {
	if r.Kind == "" {
		return fmt.Errorf("%w: risk without kind", ErrVendor)
	}
	if r.Severity < 1 || r.Severity > 5 {
		return fmt.Errorf("%w: risk %s severity %d, want 1..5", ErrVendor, r.Kind, r.Severity)
	}
	if r.Severity >= 3 && r.Mitigation == "" {
		return fmt.Errorf("%w: risk %s severity %d without mitigation", ErrVendor, r.Kind, r.Severity)
	}
	return nil
}

// Vendor carries both scores and cost inputs. Money uses one unit for every
// vendor; callers must not mix currencies.
type Vendor struct {
	Name           string
	Scores         map[Dimension]float64
	LicensePerYear float64
	RunPerYear     float64
	Migration      float64
	ExitFee        float64
	Risks          []VendorRisk
}

func (v Vendor) Validate() error {
	if v.Name == "" {
		return fmt.Errorf("%w: vendor needs a name", ErrVendor)
	}
	for _, d := range Dimensions {
		s, ok := v.Scores[d]
		if !ok {
			return fmt.Errorf("%w: vendor %s has no score for %s", ErrVendor, v.Name, d)
		}
		if s < 0 || s > 5 {
			return fmt.Errorf("%w: vendor %s score for %s is %g, want [0,5]", ErrVendor, v.Name, d, s)
		}
	}
	for _, f := range []struct {
		name string
		val  float64
	}{
		{"license per year", v.LicensePerYear},
		{"run per year", v.RunPerYear},
		{"migration", v.Migration},
		{"exit fee", v.ExitFee},
	} {
		if f.val < 0 {
			return fmt.Errorf("%w: vendor %s has negative %s", ErrVendor, v.Name, f.name)
		}
	}
	for _, r := range v.Risks {
		if err := r.Validate(); err != nil {
			return fmt.Errorf("vendor %s: %w", v.Name, err)
		}
	}
	return nil
}

// file: internal/vendoreval/score.go
// tier: L1
// verify: go test ./internal/vendoreval/
package vendoreval

import (
	"fmt"
	"sort"
)

type Constraint struct {
	Dimension Dimension
	Min       float64
}

func (c Constraint) Validate() error {
	valid := false
	for _, d := range Dimensions {
		if c.Dimension == d {
			valid = true
			break
		}
	}
	if !valid {
		return fmt.Errorf("%w: unknown constraint dimension %q", ErrVendor, c.Dimension)
	}
	if c.Min < 0 || c.Min > 5 {
		return fmt.Errorf("%w: constraint %s min %g, want [0,5]", ErrVendor, c.Dimension, c.Min)
	}
	return nil
}

type Score struct {
	Name     string
	Weighted float64
	Pass     bool
	Failed   []Dimension
}

func scoreAll(w Weights, cs []Constraint, vs []Vendor) ([]Score, error) {
	if err := w.Validate(); err != nil {
		return nil, err
	}
	for _, c := range cs {
		if err := c.Validate(); err != nil {
			return nil, err
		}
	}
	if len(vs) == 0 {
		return nil, fmt.Errorf("%w: no vendors", ErrVendor)
	}
	out := make([]Score, 0, len(vs))
	for _, v := range vs {
		if err := v.Validate(); err != nil {
			return nil, err
		}
		s := Score{Name: v.Name, Pass: true}
		for _, c := range cs {
			if v.Scores[c.Dimension] < c.Min {
				s.Pass = false
				s.Failed = append(s.Failed, c.Dimension)
			}
		}
		for _, d := range Dimensions {
			s.Weighted += w[d] * v.Scores[d]
		}
		out = append(out, s)
	}
	return out, nil
}

// Assessment is a report row, not a single recommendation: the review still
// decides whether a cheap vendor with a high exit cost is acceptable.
type Assessment struct {
	Score
	TCO       TCO
	RiskScore int
	TopRisk   string
}

// Evaluate returns every vendor, passing ones first, then by weighted score,
// then annualized TCO, then name. The last tie-breaker keeps output stable
// without pretending the evaluation found a real preference.
func Evaluate(w Weights, cs []Constraint, vs []Vendor, years int) ([]Assessment, error) {
	scores, err := scoreAll(w, cs, vs)
	if err != nil {
		return nil, err
	}
	byName := make(map[string]Vendor, len(vs))
	for _, v := range vs {
		byName[v.Name] = v
	}
	out := make([]Assessment, 0, len(scores))
	for _, s := range scores {
		v := byName[s.Name]
		t, err := TotalCost(v, years)
		if err != nil {
			return nil, err
		}
		r, top := RiskLoad(v)
		out = append(out, Assessment{Score: s, TCO: t, RiskScore: r, TopRisk: top})
	}
	sort.SliceStable(out, func(i, j int) bool {
		if out[i].Pass != out[j].Pass {
			return out[i].Pass
		}
		if out[i].Weighted != out[j].Weighted {
			return out[i].Weighted > out[j].Weighted
		}
		if out[i].TCO.Annualized != out[j].TCO.Annualized {
			return out[i].TCO.Annualized < out[j].TCO.Annualized
		}
		return out[i].Name < out[j].Name
	})
	return out, nil
}

// Shortlist returns at most n passing vendors. It never promotes a vendor that
// failed a hard constraint just to fill the list.
func Shortlist(as []Assessment, n int) []Assessment {
	var pass []Assessment
	for _, a := range as {
		if a.Pass {
			pass = append(pass, a)
		}
	}
	if n <= 0 || n > len(pass) {
		n = len(pass)
	}
	return pass[:n]
}