《游戏服务端架构·平台化与架构治理》13.3 结语：架构是取舍，不是清单

// file: internal/closingtradeoff/tradeoff.go
// tier: L1
// verify: go test ./internal/closingtradeoff/
package closingtradeoff

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

// ErrRecord marks a tradeoff record that would not survive review.
var ErrRecord = errors.New("closingtradeoff: invalid record")

// Constraint is either a hard boundary or a soft preference. Hard constraints
// cannot be violated by the chosen option; violating a soft constraint is
// allowed, but it must be named as the price of the decision.
type Constraint struct {
	ID        string
	Statement string
	Hard      bool
}

// Alternative is an option considered and either chosen or rejected. Cost is
// mandatory for every alternative: an option with no downside is not an
// option, it is marketing.
type Alternative struct {
	Name     string
	Cost     string
	Violates []string
}

// Decision records one architectural choice. Context and RevisitTrigger are
// mandatory because a decision without context cannot be re-evaluated, and a
// decision without a trigger is never revisited.
type Decision struct {
	ID             string
	Title          string
	Context        string
	Chosen         string
	Alternatives   []Alternative
	Constraints    []string
	RevisitTrigger string
}

// Record is the reviewable set of constraints and decisions.
type Record struct {
	Constraints []Constraint
	Decisions   []Decision
}

// Outcome is the result of a later review.
type Outcome string

const (
	Held     Outcome = "held"
	Reversed Outcome = "reversed"
	Pending  Outcome = "pending"
)

func (o Outcome) valid() bool {
	switch o {
	case Held, Reversed, Pending:
		return true
	}
	return false
}

// Review is a retrospective entry for one decision.
type Review struct {
	DecisionID string
	Outcome    Outcome
	Reason     string
}

// Validate checks references and the hard-constraint rule. It deliberately
// allows soft violations: those are the tradeoffs the record exists to expose.
func (r Record) Validate() error {
	cons := make(map[string]Constraint, len(r.Constraints))
	for i, c := range r.Constraints {
		if c.ID == "" {
			return fmt.Errorf("%w: constraint[%d] has no id", ErrRecord, i)
		}
		if c.Statement == "" {
			return fmt.Errorf("%w: constraint %s has no statement", ErrRecord, c.ID)
		}
		if _, dup := cons[c.ID]; dup {
			return fmt.Errorf("%w: duplicate constraint id %s", ErrRecord, c.ID)
		}
		cons[c.ID] = c
	}
	seen := make(map[string]bool, len(r.Decisions))
	for i, d := range r.Decisions {
		switch {
		case d.ID == "":
			return fmt.Errorf("%w: decision[%d] has no id", ErrRecord, i)
		case d.Title == "":
			return fmt.Errorf("%w: decision %s has no title", ErrRecord, d.ID)
		case d.Context == "":
			return fmt.Errorf("%w: decision %s has no context", ErrRecord, d.ID)
		case d.Chosen == "":
			return fmt.Errorf("%w: decision %s has no chosen option", ErrRecord, d.ID)
		case d.RevisitTrigger == "":
			return fmt.Errorf("%w: decision %s has no revisit trigger", ErrRecord, d.ID)
		case len(d.Alternatives) < 2:
			return fmt.Errorf("%w: decision %s has fewer than two alternatives", ErrRecord, d.ID)
		}
		if seen[d.ID] {
			return fmt.Errorf("%w: duplicate decision id %s", ErrRecord, d.ID)
		}
		seen[d.ID] = true
		names := make(map[string]bool, len(d.Alternatives))
		for j, alt := range d.Alternatives {
			switch {
			case alt.Name == "":
				return fmt.Errorf("%w: decision %s alternative[%d] has no name", ErrRecord, d.ID, j)
			case alt.Cost == "":
				return fmt.Errorf("%w: decision %s alternative %s has no cost", ErrRecord, d.ID, alt.Name)
			case names[alt.Name]:
				return fmt.Errorf("%w: decision %s has duplicate alternative %s", ErrRecord, d.ID, alt.Name)
			}
			names[alt.Name] = true
			for _, ref := range alt.Violates {
				if _, ok := cons[ref]; !ok {
					return fmt.Errorf("%w: decision %s alternative %s violates unknown constraint %s",
						ErrRecord, d.ID, alt.Name, ref)
				}
			}
		}
		if !names[d.Chosen] {
			return fmt.Errorf("%w: decision %s chose unknown option %s", ErrRecord, d.ID, d.Chosen)
		}
		for _, ref := range d.Constraints {
			if _, ok := cons[ref]; !ok {
				return fmt.Errorf("%w: decision %s references unknown constraint %s", ErrRecord, d.ID, ref)
			}
		}
		chosen := chosenAlternative(d)
		for _, ref := range chosen.Violates {
			if cons[ref].Hard {
				return fmt.Errorf("%w: decision %s chose %s, which violates hard constraint %s",
					ErrRecord, d.ID, d.Chosen, ref)
			}
		}
	}
	return nil
}

func chosenAlternative(d Decision) Alternative {
	for _, alt := range d.Alternatives {
		if alt.Name == d.Chosen {
			return alt
		}
	}
	return Alternative{}
}

// Tradeoffs returns the soft constraints the chosen option accepts. These are
// the lines a reviewer should argue about; everything else is bookkeeping.
func (r Record) Tradeoffs() []string {
	cons := make(map[string]Constraint, len(r.Constraints))
	for _, c := range r.Constraints {
		cons[c.ID] = c
	}
	var out []string
	for _, d := range r.Decisions {
		for _, ref := range chosenAlternative(d).Violates {
			c, ok := cons[ref]
			if !ok || c.Hard {
				continue
			}
			out = append(out, fmt.Sprintf("decision %s chose %s, accepts %s: %s",
				d.ID, d.Chosen, c.ID, c.Statement))
		}
	}
	sort.Strings(out)
	return out
}

// Revisit lists decisions whose trigger matches, in id order. Triggers are
// plain strings so they can be produced by incidents, roadmap reviews or a
// scheduled capacity check without coupling this package to a calendar.
func (r Record) Revisit(trigger string) []string {
	var out []string
	for _, d := range r.Decisions {
		if d.RevisitTrigger == trigger {
			out = append(out, d.ID)
		}
	}
	sort.Strings(out)
	return out
}

// CheckReviews validates retrospective entries: unknown decisions, duplicate
// reviews, unknown outcomes, and reversals with no stated reason.
func (r Record) CheckReviews(reviews []Review) []string {
	known := make(map[string]bool, len(r.Decisions))
	for _, d := range r.Decisions {
		known[d.ID] = true
	}
	seen := make(map[string]bool, len(reviews))
	var out []string
	for _, rv := range reviews {
		switch {
		case !known[rv.DecisionID]:
			out = append(out, fmt.Sprintf("review for unknown decision %s", rv.DecisionID))
		case seen[rv.DecisionID]:
			out = append(out, fmt.Sprintf("decision %s reviewed twice", rv.DecisionID))
		case !rv.Outcome.valid():
			out = append(out, fmt.Sprintf("decision %s has unknown outcome %q", rv.DecisionID, rv.Outcome))
		case rv.Outcome == Reversed && rv.Reason == "":
			out = append(out, fmt.Sprintf("decision %s reversed without reason", rv.DecisionID))
		}
		seen[rv.DecisionID] = true
	}
	sort.Strings(out)
	return out
}