《游戏服务端架构·平台化与架构治理》13.1 四卷回顾：从品类到平台

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

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

// ErrIndex marks structural problems in a cross-volume theme index.
var ErrIndex = errors.New("volumeretro: invalid index")

// Volume identifies one book in the four-volume series.
type Volume int

const (
	VolumeCategory Volume = 1 // category and topology
	VolumeCore     Volume = 2 // core systems and contracts
	VolumeScale    Volume = 3 // scale, globalization and cost
	VolumePlatform Volume = 4 // platform and governance
)

// Name returns the stable label used in reports. Labels are English so that
// they can be compared in tests and pasted into tickets without encoding
// surprises; the article keeps the Chinese explanation.
func (v Volume) Name() string {
	switch v {
	case VolumeCategory:
		return "category-and-topology"
	case VolumeCore:
		return "core-systems-and-contracts"
	case VolumeScale:
		return "scale-global-and-cost"
	case VolumePlatform:
		return "platform-and-governance"
	}
	return "unknown"
}

func (v Volume) valid() bool { return v >= VolumeCategory && v <= VolumePlatform }

// Theme is one durable idea that survives a volume boundary. Decision and Cost
// are mandatory: a theme without a cost is an advertisement, not a decision.
// Upstream points at themes in earlier volumes, which is what makes the whole
// index traceable instead of a flat list.
type Theme struct {
	ID           string
	Title        string
	Volume       Volume
	Question     string
	Decision     string
	Cost         string
	Verification string
	Upstream     []string
}

// Index is the review artifact produced at the end of the series.
type Index struct {
	Themes []Theme
}

// Validate enforces structure and the direction of history: a theme may only
// point upstream, never sideways or forward. That single rule makes cycles
// impossible for a validated index, and it prevents "traceability" that was
// invented after the fact.
func (ix Index) Validate() error {
	byID := make(map[string]Theme, len(ix.Themes))
	for i, t := range ix.Themes {
		switch {
		case t.ID == "":
			return fmt.Errorf("%w: theme[%d] has no id", ErrIndex, i)
		case t.Title == "":
			return fmt.Errorf("%w: theme %s has no title", ErrIndex, t.ID)
		case !t.Volume.valid():
			return fmt.Errorf("%w: theme %s has unknown volume %d", ErrIndex, t.ID, t.Volume)
		case t.Question == "":
			return fmt.Errorf("%w: theme %s has no question", ErrIndex, t.ID)
		case t.Decision == "":
			return fmt.Errorf("%w: theme %s has no decision", ErrIndex, t.ID)
		case t.Cost == "":
			return fmt.Errorf("%w: theme %s has no cost", ErrIndex, t.ID)
		case t.Verification == "":
			return fmt.Errorf("%w: theme %s has no verification", ErrIndex, t.ID)
		}
		if _, dup := byID[t.ID]; dup {
			return fmt.Errorf("%w: duplicate theme id %s", ErrIndex, t.ID)
		}
		byID[t.ID] = t
	}
	for _, t := range ix.Themes {
		for _, up := range t.Upstream {
			if up == t.ID {
				return fmt.Errorf("%w: theme %s points at itself", ErrIndex, t.ID)
			}
			u, ok := byID[up]
			if !ok {
				return fmt.Errorf("%w: theme %s points at unknown %s", ErrIndex, t.ID, up)
			}
			if u.Volume >= t.Volume {
				return fmt.Errorf("%w: theme %s (%s) points at %s (%s); upstream must be earlier",
					ErrIndex, t.ID, t.Volume.Name(), up, u.Volume.Name())
			}
		}
	}
	return nil
}

// Trace returns the root-to-target chain, sorted at each node so the output is
// stable across map iteration and can be diffed in review. A shared ancestor
// appears once, not once per branch.
func (ix Index) Trace(id string) ([]string, error) {
	byID := make(map[string]Theme, len(ix.Themes))
	for _, t := range ix.Themes {
		byID[t.ID] = t
	}
	done := make(map[string]bool, len(byID))
	active := make(map[string]bool, len(byID))
	var path []string
	var walk func(string) error
	walk = func(cur string) error {
		if done[cur] {
			return nil
		}
		if active[cur] {
			return fmt.Errorf("%w: cycle at %s", ErrIndex, cur)
		}
		t, ok := byID[cur]
		if !ok {
			return fmt.Errorf("%w: unknown theme %s", ErrIndex, cur)
		}
		active[cur] = true
		ups := append([]string(nil), t.Upstream...)
		sort.Strings(ups)
		for _, up := range ups {
			if err := walk(up); err != nil {
				return err
			}
		}
		delete(active, cur)
		done[cur] = true
		path = append(path, cur)
		return nil
	}
	if err := walk(id); err != nil {
		return nil, err
	}
	return path, nil
}

// Coverage always contains all four volumes, including zeros. A missing key
// reads as "not applicable" in reports, which is exactly the wrong conclusion.
func (ix Index) Coverage() map[Volume]int {
	out := make(map[Volume]int, 4)
	for v := VolumeCategory; v <= VolumePlatform; v++ {
		out[v] = 0
	}
	for _, t := range ix.Themes {
		if t.Volume.valid() {
			out[t.Volume]++
		}
	}
	return out
}

// Gaps compares coverage with the review contract. Required counts live in the
// caller, not in this package, because a short review and a full retrospective
// need different depth.
func (ix Index) Gaps(required map[Volume]int) []string {
	cov := ix.Coverage()
	var out []string
	for v := VolumeCategory; v <= VolumePlatform; v++ {
		need := required[v]
		if need <= 0 || cov[v] >= need {
			continue
		}
		out = append(out, fmt.Sprintf("volume %d %s: %d theme(s), need %d", v, v.Name(), cov[v], need))
	}
	return out
}