《游戏服务端架构·核心系统与契约》13.1 三款产品共用平台的契约矩阵

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

import (
	"fmt"
	"slices"
	"strings"
)

// Relation describes how one product consumes one platform capability.
type Relation string

const (
	// SharedImpl means every product calls the same deployment and code path.
	SharedImpl Relation = "shared-impl"
	// SharedAPI means the interface is common but each product brings its own
	// implementation behind it.
	SharedAPI Relation = "shared-api"
	// Independent means the product owns the capability end to end.
	Independent Relation = "independent"
)

// Reason records why a cell exists in its current shape. A matrix is read
// differently when a difference comes from the genre than when it is only
// inherited history.
type Reason string

const (
	ReasonGenre      Reason = "genre"
	ReasonLegacy     Reason = "legacy"
	ReasonCompliance Reason = "compliance"
	ReasonScale      Reason = "scale"
)

// Cell is one product's use of one capability. SLA, Degrade and Owner live in
// the same cell on purpose: a capability without a degradation plan and a
// named owner is not a contract, it is an intention.
type Cell struct {
	Product    string
	Capability string
	Relation   Relation
	Impl       string
	Interface  string
	SLA        string
	Degrade    string
	Owner      string
	Reason     Reason
}

// Matrix is a product x capability table. It is a review artifact, not a
// runtime registry: Validate is what turns the plan into a contract that can
// be argued about.
type Matrix struct {
	products     []string
	capabilities []string
	cells        map[string]Cell
}

func key(product, capability string) string {
	return product + "\x00" + capability
}

// New creates an empty matrix. Duplicate names are rejected here because a
// duplicated axis silently breaks the completeness count.
func New(products, capabilities []string) (*Matrix, error) {
	if len(products) == 0 || len(capabilities) == 0 {
		return nil, fmt.Errorf("contractmatrix: both axes are required")
	}
	seen := make(map[string]bool, len(products))
	for _, p := range products {
		if strings.TrimSpace(p) == "" {
			return nil, fmt.Errorf("contractmatrix: empty product name")
		}
		if seen[p] {
			return nil, fmt.Errorf("contractmatrix: duplicate product %q", p)
		}
		seen[p] = true
	}
	seen = make(map[string]bool, len(capabilities))
	for _, c := range capabilities {
		if strings.TrimSpace(c) == "" {
			return nil, fmt.Errorf("contractmatrix: empty capability name")
		}
		if seen[c] {
			return nil, fmt.Errorf("contractmatrix: duplicate capability %q", c)
		}
		seen[c] = true
	}
	return &Matrix{
		products:     append([]string(nil), products...),
		capabilities: append([]string(nil), capabilities...),
		cells:        make(map[string]Cell),
	}, nil
}

// Set writes one cell. Field semantics belong to Validate; Set only guards the
// axes and accidental overwrite, so a draft can be filled in any order.
func (m *Matrix) Set(c Cell) error {
	if !m.hasProduct(c.Product) {
		return fmt.Errorf("contractmatrix: unknown product %q", c.Product)
	}
	if !m.hasCapability(c.Capability) {
		return fmt.Errorf("contractmatrix: unknown capability %q", c.Capability)
	}
	k := key(c.Product, c.Capability)
	if _, ok := m.cells[k]; ok {
		return fmt.Errorf("contractmatrix: cell %s/%s already set", c.Product, c.Capability)
	}
	m.cells[k] = c
	return nil
}

func (m *Matrix) hasProduct(name string) bool {
	return slices.Contains(m.products, name)
}

func (m *Matrix) hasCapability(name string) bool {
	return slices.Contains(m.capabilities, name)
}

func relationValid(r Relation) bool {
	switch r {
	case SharedImpl, SharedAPI, Independent:
		return true
	}
	return false
}

func reasonValid(r Reason) bool {
	switch r {
	case ReasonGenre, ReasonLegacy, ReasonCompliance, ReasonScale:
		return true
	}
	return false
}

func (m *Matrix) cellsFor(capability string) []Cell {
	out := make([]Cell, 0, len(m.products))
	for _, p := range m.products {
		if c, ok := m.cells[key(p, capability)]; ok {
			out = append(out, c)
		}
	}
	return out
}

// Validate checks completeness, required fields and the three relation rules:
// shared-impl cells for one capability must name one implementation and one
// owner; shared-api cells must name one interface but distinct implementations;
// independent cells must not reuse another product's implementation.
func (m *Matrix) Validate() []error {
	var errs []error
	for _, capability := range m.capabilities {
		cells := m.cellsFor(capability)
		if len(cells) != len(m.products) {
			errs = append(errs, fmt.Errorf("capability %q: %d of %d cells present", capability, len(cells), len(m.products)))
			continue
		}
		for _, c := range cells {
			if !relationValid(c.Relation) {
				errs = append(errs, fmt.Errorf("%s/%s: unknown relation %q", c.Product, c.Capability, c.Relation))
				continue
			}
			if !reasonValid(c.Reason) {
				errs = append(errs, fmt.Errorf("%s/%s: unknown reason %q", c.Product, c.Capability, c.Reason))
			}
			if strings.TrimSpace(c.Impl) == "" {
				errs = append(errs, fmt.Errorf("%s/%s: empty implementation id", c.Product, c.Capability))
			}
			if strings.TrimSpace(c.SLA) == "" || strings.TrimSpace(c.Degrade) == "" || strings.TrimSpace(c.Owner) == "" {
				errs = append(errs, fmt.Errorf("%s/%s: SLA, degrade and owner are required", c.Product, c.Capability))
			}
		}
		errs = append(errs, validateRelations(capability, cells)...)
	}
	return errs
}

func validateRelations(capability string, cells []Cell) []error {
	var errs []error
	sharedImplOwner := make(map[string]string)
	sharedAPIInterface := ""
	sharedAPIImpl := make(map[string]string)
	independentImpl := make(map[string]string)
	for _, c := range cells {
		switch c.Relation {
		case SharedImpl:
			if prev, ok := sharedImplOwner[c.Impl]; ok && prev != c.Owner {
				errs = append(errs, fmt.Errorf("capability %q: shared impl %q has owners %q and %q", capability, c.Impl, prev, c.Owner))
			}
			sharedImplOwner[c.Impl] = c.Owner
		case SharedAPI:
			if strings.TrimSpace(c.Interface) == "" {
				errs = append(errs, fmt.Errorf("%s/%s: shared-api needs an interface id", c.Product, c.Capability))
			} else if sharedAPIInterface == "" {
				sharedAPIInterface = c.Interface
			} else if sharedAPIInterface != c.Interface {
				errs = append(errs, fmt.Errorf("capability %q: shared interface is both %q and %q", capability, sharedAPIInterface, c.Interface))
			}
			if other, ok := sharedAPIImpl[c.Impl]; ok {
				errs = append(errs, fmt.Errorf("capability %q: shared-api impl %q is reused by %s and %s", capability, c.Impl, other, c.Product))
			}
			sharedAPIImpl[c.Impl] = c.Product
		case Independent:
			if other, ok := independentImpl[c.Impl]; ok {
				errs = append(errs, fmt.Errorf("capability %q: independent impl %q is shared by %s and %s", capability, c.Impl, other, c.Product))
			}
			independentImpl[c.Impl] = c.Product
		}
	}
	if len(sharedImplOwner) > 1 {
		names := make([]string, 0, len(sharedImplOwner))
		for impl := range sharedImplOwner {
			names = append(names, impl)
		}
		errs = append(errs, fmt.Errorf("capability %q: shared-impl cells name %d implementations: %s", capability, len(names), strings.Join(names, ", ")))
	}
	return errs
}

// Stats counts cells per relation. A capability that is mostly Independent is
// a platform-boundary question, not a code-sharing question.
func (m *Matrix) Stats() map[Relation]int {
	out := map[Relation]int{SharedImpl: 0, SharedAPI: 0, Independent: 0}
	for _, c := range m.cells {
		if relationValid(c.Relation) {
			out[c.Relation]++
		}
	}
	return out
}

// ReasonCounts separates genre-driven differences from legacy ones. A high
// legacy count is the signal to schedule migration, not to write more code.
func (m *Matrix) ReasonCounts() map[Reason]int {
	out := map[Reason]int{}
	for _, c := range m.cells {
		if reasonValid(c.Reason) {
			out[c.Reason]++
		}
	}
	return out
}

// Products returns the product axis in declaration order.
func (m *Matrix) Products() []string {
	return append([]string(nil), m.products...)
}

// Capabilities returns the capability axis in declaration order.
func (m *Matrix) Capabilities() []string {
	return append([]string(nil), m.capabilities...)
}