《游戏服务端架构·品类、状态与拓扑》12.3 架构决策的记录、评审与复盘

proposed ──> in-review ──> accepted ──> superseded
                  │              │
                  └──> rejected  └──> expired

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

import (
	"fmt"
	"sort"
	"strings"
	"time"
)

// Status is the lifecycle position of a decision, not its technical outcome.
type Status string

const (
	Proposed   Status = "proposed"
	InReview   Status = "in-review"
	Accepted   Status = "accepted"
	Rejected   Status = "rejected"
	Superseded Status = "superseded"
	Expired    Status = "expired"
)

var statuses = map[Status]bool{
	Proposed: true, InReview: true, Accepted: true,
	Rejected: true, Superseded: true, Expired: true,
}

// Decision is one node in the decision graph. Supersedes, DependsOn, and
// ConflictsWith point at other decision IDs.
type Decision struct {
	ID             string
	Title          string
	Status         Status
	Owner          string
	ReviewBy       time.Time
	ExitConditions []string
	Supersedes     []string
	DependsOn      []string
	ConflictsWith  []string
}

func active(s Status) bool {
	return s == Proposed || s == InReview || s == Accepted
}

func dead(s Status) bool {
	return s == Rejected || s == Superseded || s == Expired
}

// Validate checks one node. Active decisions must carry a review date and
// at least one exit condition; otherwise they cannot be re-evaluated.
func (d Decision) Validate() []error {
	var errs []error
	for _, f := range []struct{ name, value string }{
		{"id", d.ID}, {"title", d.Title}, {"owner", d.Owner},
	} {
		if strings.TrimSpace(f.value) == "" {
			errs = append(errs, fmt.Errorf("decision %q: empty %s", d.ID, f.name))
		}
	}
	if !statuses[d.Status] {
		errs = append(errs, fmt.Errorf("decision %q: unknown status %q", d.ID, d.Status))
	}
	if active(d.Status) {
		if d.ReviewBy.IsZero() {
			errs = append(errs, fmt.Errorf("decision %q: active without review date", d.ID))
		}
		if len(d.ExitConditions) == 0 {
			errs = append(errs, fmt.Errorf("decision %q: active without exit conditions", d.ID))
		}
	}
	if contains(d.Supersedes, d.ID) || contains(d.DependsOn, d.ID) || contains(d.ConflictsWith, d.ID) {
		errs = append(errs, fmt.Errorf("decision %q: references itself", d.ID))
	}
	return errs
}

// SupersedeCycle reports the first cycle in the replacement graph.
func SupersedeCycle(ds []Decision) []error {
	edges := make(map[string][]string, len(ds))
	for _, d := range ds {
		edges[d.ID] = append(edges[d.ID], d.Supersedes...)
	}
	state := make(map[string]int, len(ds)) // 1 visiting, 2 done
	var visit func(string) bool
	visit = func(id string) bool {
		switch state[id] {
		case 1:
			return true
		case 2:
			return false
		}
		state[id] = 1
		for _, next := range edges[id] {
			if visit(next) {
				return true
			}
		}
		state[id] = 2
		return false
	}
	for _, d := range ds {
		if state[d.ID] == 0 && visit(d.ID) {
			return []error{fmt.Errorf("supersede cycle involving %q", d.ID)}
		}
	}
	return nil
}

// ValidateAll checks references, replacement consistency, conflicts, and
// dependencies. It returns every error; callers decide how to report them.
func ValidateAll(ds []Decision) []error {
	var errs []error
	byID := make(map[string]Decision, len(ds))
	for _, d := range ds {
		errs = append(errs, d.Validate()...)
		if _, ok := byID[d.ID]; ok {
			errs = append(errs, fmt.Errorf("decision %q: duplicate id", d.ID))
		}
		byID[d.ID] = d
	}
	supersededBy := make(map[string]bool)
	for _, d := range ds {
		for _, ref := range d.Supersedes {
			target, ok := byID[ref]
			if !ok {
				errs = append(errs, fmt.Errorf("decision %q: supersedes unknown %q", d.ID, ref))
				continue
			}
			if d.Status != Accepted {
				errs = append(errs, fmt.Errorf("decision %q: only accepted decisions may supersede", d.ID))
			}
			if target.Status != Superseded {
				errs = append(errs, fmt.Errorf("decision %q: supersedes %q which is %s", d.ID, ref, target.Status))
				continue
			}
			supersededBy[ref] = true
		}
		for _, ref := range d.DependsOn {
			target, ok := byID[ref]
			if !ok {
				errs = append(errs, fmt.Errorf("decision %q: depends on unknown %q", d.ID, ref))
				continue
			}
			if active(d.Status) && dead(target.Status) {
				errs = append(errs, fmt.Errorf("decision %q: depends on %s decision %q", d.ID, target.Status, ref))
			}
		}
		for _, ref := range d.ConflictsWith {
			target, ok := byID[ref]
			if !ok {
				errs = append(errs, fmt.Errorf("decision %q: conflicts with unknown %q", d.ID, ref))
				continue
			}
			if !contains(target.ConflictsWith, d.ID) {
				errs = append(errs, fmt.Errorf("decision %q: conflict with %q is not symmetric", d.ID, ref))
			}
			if d.Status == Accepted && target.Status == Accepted {
				errs = append(errs, fmt.Errorf("decisions %q and %q are both accepted and conflict", d.ID, ref))
			}
		}
	}
	for _, d := range ds {
		if d.Status == Superseded && !supersededBy[d.ID] {
			errs = append(errs, fmt.Errorf("decision %q: superseded without accepted replacement", d.ID))
		}
	}
	errs = append(errs, SupersedeCycle(ds)...)
	return errs
}

// Due returns active decisions inside the review window, earliest first.
func Due(ds []Decision, now time.Time, window time.Duration) []Decision {
	cutoff := now.Add(window)
	var out []Decision
	for _, d := range ds {
		if !active(d.Status) || d.ReviewBy.IsZero() || d.ReviewBy.After(cutoff) {
			continue
		}
		out = append(out, d)
	}
	sort.SliceStable(out, func(i, j int) bool {
		if !out[i].ReviewBy.Equal(out[j].ReviewBy) {
			return out[i].ReviewBy.Before(out[j].ReviewBy)
		}
		return out[i].ID < out[j].ID
	})
	return out
}

func contains(list []string, want string) bool {
	for _, s := range list {
		if s == want {
			return true
		}
	}
	return false
}

$ cd .local/checks/gsarch-lab
$ go test -count=1 ./internal/decisionlog/
ok  	gsarchlab/internal/decisionlog	0.723s