《游戏服务端架构·规模化、全球化与成本》13.3 进入卷四：平台化与治理

area release-governance: no item
item H1: platform item depends on product item H3
item H1: platform item has no contract

// file: internal/volfourhandoff/handoff.go
// tier: L1
// verify: go test ./internal/volfourhandoff/
package volfourhandoff

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

var ErrHandoff = errors.New("volfourhandoff: invalid checklist")

type Area string

const (
	Reuse    Area = "multi-product-reuse"
	Contract Area = "platform-contract"
	Release  Area = "release-governance"
	Cost     Area = "cost-governance"
)

var RequiredAreas = []Area{Reuse, Contract, Release, Cost}

type Owner string

const (
	Platform Owner = "platform"
	Product  Owner = "product"
)

// Item is one decision leaving volume three. ContractRef is the platform
// interface or SLA the item commits to; without it a "handoff" is only a wish.
type Item struct {
	ID          string
	Title       string
	Area        Area
	Owner       Owner
	ContractRef string
	DependsOn   []string
}

type Checklist struct {
	Items []Item
}

func (c Checklist) Validate() error {
	byID := make(map[string]Item, len(c.Items))
	for i, it := range c.Items {
		switch {
		case it.ID == "":
			return fmt.Errorf("%w: item[%d] has no id", ErrHandoff, i)
		case it.Title == "":
			return fmt.Errorf("%w: item %s has no title", ErrHandoff, it.ID)
		case !validArea(it.Area):
			return fmt.Errorf("%w: item %s has unknown area %q", ErrHandoff, it.ID, it.Area)
		case !validOwner(it.Owner):
			return fmt.Errorf("%w: item %s has unknown owner %q", ErrHandoff, it.ID, it.Owner)
		}
		if _, dup := byID[it.ID]; dup {
			return fmt.Errorf("%w: duplicate id %s", ErrHandoff, it.ID)
		}
		byID[it.ID] = it
	}
	for _, it := range c.Items {
		for _, dep := range it.DependsOn {
			if dep == it.ID {
				return fmt.Errorf("%w: item %s depends on itself", ErrHandoff, it.ID)
			}
			if _, ok := byID[dep]; !ok {
				return fmt.Errorf("%w: item %s depends on missing %s", ErrHandoff, it.ID, dep)
			}
		}
	}
	if cycle := findCycle(c.Items, byID); len(cycle) > 0 {
		return fmt.Errorf("%w: dependency cycle %v", ErrHandoff, cycle)
	}
	return nil
}

// Gaps reports policy problems that Validate deliberately allows: missing
// areas, platform items without a contract, ownership that contradicts the
// area, and platform items that depend on a single product.
func (c Checklist) Gaps() []string {
	var out []string
	seen := make(map[Area]int)
	byID := make(map[string]Item, len(c.Items))
	for _, it := range c.Items {
		seen[it.Area]++
		byID[it.ID] = it
	}
	for _, area := range RequiredAreas {
		if seen[area] == 0 {
			out = append(out, fmt.Sprintf("area %s: no item", area))
		}
	}
	for _, it := range c.Items {
		if it.Owner == Platform && it.ContractRef == "" {
			out = append(out, fmt.Sprintf("item %s: platform item has no contract", it.ID))
		}
		if (it.Area == Reuse || it.Area == Contract) && it.Owner != Platform {
			out = append(out, fmt.Sprintf("item %s: area %s must be owned by platform", it.ID, it.Area))
		}
		if it.Owner != Platform {
			continue
		}
		for _, dep := range it.DependsOn {
			if byID[dep].Owner == Product {
				out = append(out, fmt.Sprintf("item %s: platform item depends on product item %s", it.ID, dep))
			}
		}
	}
	sort.Strings(out)
	return out
}

func (c Checklist) ByOwner(o Owner) []Item {
	var out []Item
	for _, it := range c.Items {
		if it.Owner == o {
			out = append(out, it)
		}
	}
	return out
}

func (c Checklist) Coverage() map[Area]int {
	out := make(map[Area]int, len(RequiredAreas))
	for _, area := range RequiredAreas {
		out[area] = 0
	}
	for _, it := range c.Items {
		out[it.Area]++
	}
	return out
}

func findCycle(items []Item, byID map[string]Item) []string {
	const (
		white = 0
		grey  = 1
		black = 2
	)
	state := make(map[string]int, len(items))
	var stack []string
	var visit func(string) []string
	visit = func(id string) []string {
		switch state[id] {
		case grey:
			return append(append([]string{}, stack...), id)
		case black:
			return nil
		}
		state[id] = grey
		stack = append(stack, id)
		for _, dep := range byID[id].DependsOn {
			if cycle := visit(dep); len(cycle) > 0 {
				return cycle
			}
		}
		stack = stack[:len(stack)-1]
		state[id] = black
		return nil
	}
	for _, it := range items {
		if cycle := visit(it.ID); len(cycle) > 0 {
			return cycle
		}
	}
	return nil
}

func validArea(a Area) bool {
	switch a {
	case Reuse, Contract, Release, Cost:
		return true
	}
	return false
}

func validOwner(o Owner) bool {
	switch o {
	case Platform, Product:
		return true
	}
	return false
}