《游戏服务端架构·平台化与架构治理》12.1 决策记录、风险台账与路线图

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

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

// RiskStatus is the handling state of a risk, not its technical category.
type RiskStatus string

const (
	RiskOpen       RiskStatus = "open"
	RiskMitigating RiskStatus = "mitigating"
	RiskAccepted   RiskStatus = "accepted"
	RiskClosed     RiskStatus = "closed"
)

var riskStatuses = map[RiskStatus]bool{
	RiskOpen: true, RiskMitigating: true, RiskAccepted: true, RiskClosed: true,
}

// Risk is an unresolved threat with an owner. Severity and Likelihood are
// scored 1..5, so Priority is a 1..25 review ordering, not a probability.
type Risk struct {
	ID         string
	Title      string
	Owner      string
	Severity   int
	Likelihood int
	Status     RiskStatus
	Mitigation string
	DecisionID string
	ReviewBy   time.Time
}

func (r Risk) Priority() int { return r.Severity * r.Likelihood }

func (r Risk) IsOpen() bool {
	return r.Status == RiskOpen || r.Status == RiskMitigating
}

// Validate checks one risk. Open and mitigating risks need a mitigation, a
// review date, and a decision they hang from; otherwise nobody is on the hook.
func (r Risk) Validate() []error {
	var errs []error
	for _, f := range []struct{ name, value string }{
		{"id", r.ID}, {"title", r.Title}, {"owner", r.Owner},
	} {
		if strings.TrimSpace(f.value) == "" {
			errs = append(errs, fmt.Errorf("risk %q: empty %s", r.ID, f.name))
		}
	}
	if !riskStatuses[r.Status] {
		errs = append(errs, fmt.Errorf("risk %q: unknown status %q", r.ID, r.Status))
	}
	if r.Severity < 1 || r.Severity > 5 {
		errs = append(errs, fmt.Errorf("risk %q: severity %d, want 1..5", r.ID, r.Severity))
	}
	if r.Likelihood < 1 || r.Likelihood > 5 {
		errs = append(errs, fmt.Errorf("risk %q: likelihood %d, want 1..5", r.ID, r.Likelihood))
	}
	if r.IsOpen() {
		if strings.TrimSpace(r.Mitigation) == "" {
			errs = append(errs, fmt.Errorf("risk %q: open without mitigation", r.ID))
		}
		if r.ReviewBy.IsZero() {
			errs = append(errs, fmt.Errorf("risk %q: open without review date", r.ID))
		}
		if strings.TrimSpace(r.DecisionID) == "" {
			errs = append(errs, fmt.Errorf("risk %q: open without decision", r.ID))
		}
	}
	if r.Status == RiskAccepted && r.ReviewBy.IsZero() {
		errs = append(errs, fmt.Errorf("risk %q: accepted without review date", r.ID))
	}
	return errs
}

// RoadmapItem is a planned change. Each item must point at at least one
// decision or risk; an item that traces to nothing is a wish, not a plan.
type RoadmapItem struct {
	ID         string
	Title      string
	Quarter    string
	Status     string
	DecisionID string
	RiskIDs    []string
}

var itemStatuses = map[string]bool{
	"planned": true, "active": true, "done": true, "dropped": true,
}

func (i RoadmapItem) Validate() []error {
	var errs []error
	for _, f := range []struct{ name, value string }{
		{"id", i.ID}, {"title", i.Title}, {"quarter", i.Quarter},
	} {
		if strings.TrimSpace(f.value) == "" {
			errs = append(errs, fmt.Errorf("roadmap item %q: empty %s", i.ID, f.name))
		}
	}
	if !itemStatuses[i.Status] {
		errs = append(errs, fmt.Errorf("roadmap item %q: unknown status %q", i.ID, i.Status))
	}
	if strings.TrimSpace(i.DecisionID) == "" && len(i.RiskIDs) == 0 {
		errs = append(errs, fmt.Errorf("roadmap item %q: no decision or risk traced", i.ID))
	}
	return errs
}

// ValidateRegister checks the three artifacts together. Decisions are checked
// by the existing lifecycle rules; this layer adds cross-artifact references.
func ValidateRegister(ds []Decision, risks []Risk, items []RoadmapItem) []error {
	errs := ValidateAll(ds)
	byDecision := make(map[string]Decision, len(ds))
	for _, d := range ds {
		byDecision[d.ID] = d
	}
	byRisk := make(map[string]Risk, len(risks))
	for _, r := range risks {
		errs = append(errs, r.Validate()...)
		if _, ok := byRisk[r.ID]; ok {
			errs = append(errs, fmt.Errorf("risk %q: duplicate id", r.ID))
		}
		byRisk[r.ID] = r
		if !r.IsOpen() || strings.TrimSpace(r.DecisionID) == "" {
			continue
		}
		d, ok := byDecision[r.DecisionID]
		if !ok {
			errs = append(errs, fmt.Errorf("risk %q: unknown decision %q", r.ID, r.DecisionID))
			continue
		}
		if dead(d.Status) {
			errs = append(errs, fmt.Errorf("risk %q: hangs from %s decision %q", r.ID, d.Status, d.ID))
		}
	}
	seenItem := make(map[string]bool, len(items))
	for _, i := range items {
		errs = append(errs, i.Validate()...)
		if seenItem[i.ID] {
			errs = append(errs, fmt.Errorf("roadmap item %q: duplicate id", i.ID))
		}
		seenItem[i.ID] = true
		if i.DecisionID != "" {
			if _, ok := byDecision[i.DecisionID]; !ok {
				errs = append(errs, fmt.Errorf("roadmap item %q: unknown decision %q", i.ID, i.DecisionID))
			}
		}
		for _, ref := range i.RiskIDs {
			r, ok := byRisk[ref]
			if !ok {
				errs = append(errs, fmt.Errorf("roadmap item %q: unknown risk %q", i.ID, ref))
				continue
			}
			if (i.Status == "planned" || i.Status == "active") && r.Status == RiskClosed {
				errs = append(errs, fmt.Errorf("roadmap item %q: addresses closed risk %q", i.ID, ref))
			}
		}
	}
	return errs
}

// ReviewQueue returns open risks due inside the window, highest priority
// first. Priority ties fall back to the earlier review date, then ID.
func ReviewQueue(risks []Risk, now time.Time, window time.Duration) []Risk {
	cutoff := now.Add(window)
	var out []Risk
	for _, r := range risks {
		if !r.IsOpen() || r.ReviewBy.IsZero() || r.ReviewBy.After(cutoff) {
			continue
		}
		out = append(out, r)
	}
	sort.SliceStable(out, func(i, j int) bool {
		if out[i].Priority() != out[j].Priority() {
			return out[i].Priority() > out[j].Priority()
		}
		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
}

// UncoveredRisks lists open risks that no live roadmap item addresses. It is a
// report, not a validation error: accepting a risk without planned work can be
// deliberate, but it should be visible in the monthly review.
func UncoveredRisks(risks []Risk, items []RoadmapItem) []string {
	covered := make(map[string]bool)
	for _, i := range items {
		if i.Status == "dropped" {
			continue
		}
		for _, ref := range i.RiskIDs {
			covered[ref] = true
		}
	}
	var out []string
	for _, r := range risks {
		if r.IsOpen() && !covered[r.ID] {
			out = append(out, r.ID)
		}
	}
	sort.Strings(out)
	return out
}