《游戏服务端架构·平台化与架构治理》10.3 架构路线图与技术雷达

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

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

// Ring is one of the four radar rings.
type Ring string

const (
	// RingAdopt is approved for default use on new work.
	RingAdopt Ring = "adopt"
	// RingTrial is used in production by a named team with exit criteria.
	RingTrial Ring = "trial"
	// RingAssess is under evaluation with no production dependency.
	RingAssess Ring = "assess"
	// RingHold is deliberately paused or being retired.
	RingHold Ring = "hold"
)

var (
	ErrUnknownRing  = errors.New("techradar: unknown ring")
	ErrIllegalMove  = errors.New("techradar: illegal ring move")
	ErrSameRing     = errors.New("techradar: entry already in that ring")
	ErrInvalidEntry = errors.New("techradar: invalid entry")
	ErrInvalidItem  = errors.New("techradar: invalid roadmap item")
	ErrDuplicate    = errors.New("techradar: duplicate roadmap item")
	ErrUnknownItem  = errors.New("techradar: unknown roadmap dependency")
	ErrCycle        = errors.New("techradar: roadmap dependency cycle")
)

func (r Ring) Valid() bool {
	switch r {
	case RingAdopt, RingTrial, RingAssess, RingHold:
		return true
	default:
		return false
	}
}

func ParseRing(s string) (Ring, error) {
	r := Ring(s)
	if !r.Valid() {
		return "", fmt.Errorf("%w: %q", ErrUnknownRing, s)
	}
	return r, nil
}

// Entry is one technology on the radar. Evidence is not optional: a radar
// without evidence turns into a popularity poll.
type Entry struct {
	Name     string
	Ring     Ring
	Owner    string
	Evidence []string
}

func (e Entry) Validate() error {
	if e.Name == "" {
		return fmt.Errorf("%w: empty name", ErrInvalidEntry)
	}
	if !e.Ring.Valid() {
		return fmt.Errorf("%w: %s ring=%q", ErrInvalidEntry, e.Name, e.Ring)
	}
	if e.Owner == "" {
		return fmt.Errorf("%w: %s has no owner", ErrInvalidEntry, e.Name)
	}
	meaningful := false
	for _, item := range e.Evidence {
		if item != "" {
			meaningful = true
			break
		}
	}
	if !meaningful {
		return fmt.Errorf("%w: %s has no evidence", ErrInvalidEntry, e.Name)
	}
	return nil
}

// CanMove encodes the allowed ring transitions. Forward movement is gradual;
// Adopt can be demoted; Hold must re-enter through Assess.
func CanMove(from, to Ring) error {
	if !from.Valid() || !to.Valid() {
		return ErrUnknownRing
	}
	if from == to {
		return ErrSameRing
	}
	allowed := false
	switch from {
	case RingAssess:
		allowed = to == RingTrial || to == RingHold
	case RingTrial:
		allowed = to == RingAdopt || to == RingAssess || to == RingHold
	case RingAdopt:
		allowed = to == RingTrial || to == RingHold
	case RingHold:
		allowed = to == RingAssess
	}
	if !allowed {
		return fmt.Errorf("%w: %s -> %s", ErrIllegalMove, from, to)
	}
	return nil
}

// Move validates the entry before and after the transition so a partially
// filled entry cannot slip into a new ring.
func Move(e Entry, to Ring) (Entry, error) {
	if err := e.Validate(); err != nil {
		return e, err
	}
	if err := CanMove(e.Ring, to); err != nil {
		return e, err
	}
	moved := e
	moved.Ring = to
	return moved, nil
}

// Item is one roadmap line. Weeks is effort, not calendar duration.
type Item struct {
	ID              string
	EarliestQuarter int
	Weeks           int
	DependsOn       []string
}

func (i Item) Validate() error {
	switch {
	case i.ID == "":
		return fmt.Errorf("%w: empty id", ErrInvalidItem)
	case i.EarliestQuarter < 1:
		return fmt.Errorf("%w: %s earliest quarter=%d", ErrInvalidItem, i.ID, i.EarliestQuarter)
	case i.Weeks < 1:
		return fmt.Errorf("%w: %s weeks=%d", ErrInvalidItem, i.ID, i.Weeks)
	}
	for _, dep := range i.DependsOn {
		if dep == "" {
			return fmt.Errorf("%w: %s has empty dependency", ErrInvalidItem, i.ID)
		}
	}
	return nil
}

func indexItems(items []Item) (map[string]Item, error) {
	index := make(map[string]Item, len(items))
	for _, item := range items {
		if err := item.Validate(); err != nil {
			return nil, err
		}
		if _, exists := index[item.ID]; exists {
			return nil, fmt.Errorf("%w: %s", ErrDuplicate, item.ID)
		}
		index[item.ID] = item
	}
	for _, item := range items {
		for _, dep := range item.DependsOn {
			if _, ok := index[dep]; !ok {
				return nil, fmt.Errorf("%w: %s -> %s", ErrUnknownItem, item.ID, dep)
			}
		}
	}
	return index, nil
}

// Schedule returns the earliest start quarter of every item. An item starts
// after all dependencies finish and never before its own earliest quarter.
func Schedule(items []Item) (map[string]int, error) {
	index, err := indexItems(items)
	if err != nil {
		return nil, err
	}
	start := make(map[string]int, len(index))
	visiting := make(map[string]bool, len(index))

	var resolve func(id string) (int, error)
	resolve = func(id string) (int, error) {
		if quarter, ok := start[id]; ok {
			return quarter, nil
		}
		if visiting[id] {
			return 0, fmt.Errorf("%w: %s", ErrCycle, id)
		}
		visiting[id] = true
		item := index[id]
		quarter := item.EarliestQuarter
		for _, dep := range item.DependsOn {
			depStart, err := resolve(dep)
			if err != nil {
				return 0, err
			}
			finish := depStart + index[dep].Weeks
			if finish > quarter {
				quarter = finish
			}
		}
		delete(visiting, id)
		start[id] = quarter
		return quarter, nil
	}

	for id := range index {
		if _, err := resolve(id); err != nil {
			return nil, err
		}
	}
	return start, nil
}

// CriticalPath returns the longest dependency chain by effort and its total
// weeks. The chain is ordered from the oldest dependency to the final item.
func CriticalPath(items []Item) ([]string, int, error) {
	index, err := indexItems(items)
	if err != nil {
		return nil, 0, err
	}
	if _, err := Schedule(items); err != nil {
		return nil, 0, err
	}

	memoWeeks := make(map[string]int, len(index))
	memoChain := make(map[string][]string, len(index))

	var walk func(id string) (int, []string)
	walk = func(id string) (int, []string) {
		if weeks, ok := memoWeeks[id]; ok {
			return weeks, memoChain[id]
		}
		item := index[id]
		bestWeeks := 0
		var bestChain []string
		deps := append([]string(nil), item.DependsOn...)
		sort.Strings(deps)
		for _, dep := range deps {
			weeks, chain := walk(dep)
			if weeks > bestWeeks {
				bestWeeks = weeks
				bestChain = chain
			}
		}
		chain := append(append([]string(nil), bestChain...), id)
		memoWeeks[id] = bestWeeks + item.Weeks
		memoChain[id] = chain
		return memoWeeks[id], chain
	}

	ids := make([]string, 0, len(index))
	for id := range index {
		ids = append(ids, id)
	}
	sort.Strings(ids)

	bestTotal := -1
	var best []string
	for _, id := range ids {
		weeks, chain := walk(id)
		if weeks > bestTotal {
			bestTotal = weeks
			best = chain
		}
	}
	if bestTotal < 0 {
		return nil, 0, nil
	}
	return best, bestTotal, nil
}