《游戏服务端架构·品类、状态与拓扑》2.3 一次真实的架构评审与风险台账

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

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

// Risk is one row of the review register. Probability and Impact are
// limited to 1..5: a ten-point scale invites false precision.
type Risk struct {
	ID          string
	Title       string
	Probability int
	Impact      int
	Owner       string
	Trigger     string
	Mitigation  string
	Accepted    bool
}

// Score is probability times impact, in the range 1..25.
func (r Risk) Score() int {
	return r.Probability * r.Impact
}

func (r Risk) Band() string {
	return Band(r.Score())
}

// Band maps a score to the review vocabulary; boundaries are tested.
func Band(score int) string {
	switch {
	case score >= 17:
		return "critical"
	case score >= 10:
		return "high"
	case score >= 5:
		return "medium"
	case score >= 1:
		return "low"
	default:
		return "invalid"
	}
}

func (r Risk) Validate() error {
	var missing []string
	add := func(name, value string) {
		if strings.TrimSpace(value) == "" {
			missing = append(missing, name)
		}
	}
	add("id", r.ID)
	add("title", r.Title)
	add("owner", r.Owner)
	add("trigger", r.Trigger)
	add("mitigation", r.Mitigation)
	if len(missing) > 0 {
		return fmt.Errorf("risk %q: missing %s", r.ID, strings.Join(missing, ", "))
	}
	if r.Probability < 1 || r.Probability > 5 {
		return fmt.Errorf("risk %q: probability %d outside 1..5", r.ID, r.Probability)
	}
	if r.Impact < 1 || r.Impact > 5 {
		return fmt.Errorf("risk %q: impact %d outside 1..5", r.ID, r.Impact)
	}
	return nil
}

// Rank returns a sorted copy: higher score first, then ID ascending.
func Rank(risks []Risk) ([]Risk, error) {
	for _, r := range risks {
		if err := r.Validate(); err != nil {
			return nil, err
		}
	}
	out := append([]Risk(nil), risks...)
	sort.SliceStable(out, func(i, j int) bool {
		si, sj := out[i].Score(), out[j].Score()
		if si != sj {
			return si > sj
		}
		return out[i].ID < out[j].ID
	})
	return out, nil
}

// TopN is the list the review meeting actually discusses.
func TopN(risks []Risk, n int) ([]Risk, error) {
	ranked, err := Rank(risks)
	if err != nil {
		return nil, err
	}
	if n <= 0 {
		return []Risk{}, nil
	}
	if n > len(ranked) {
		n = len(ranked)
	}
	return ranked[:n], nil
}

// file: internal/risk/register_test.go
// tier: L1
// verify: go test ./internal/risk/
package risk

import (
	"fmt"
	"strings"
	"testing"
)

func validRisk(id string, probability, impact int) Risk {
	return Risk{
		ID:          id,
		Title:       "测试风险",
		Probability: probability,
		Impact:      impact,
		Owner:       "世界组",
		Trigger:     "触发信号",
		Mitigation:  "缓解动作",
	}
}

func TestBandAndScoreBoundaries(t *testing.T) {
	cases := []struct {
		probability int
		impact      int
		score       int
		band        string
	}{
		{1, 1, 1, "low"},
		{1, 4, 4, "low"},
		{1, 5, 5, "medium"},
		{3, 3, 9, "medium"},
		{2, 5, 10, "high"},
		{4, 4, 16, "high"},
		{5, 4, 20, "critical"},
		{5, 5, 25, "critical"},
	}
	for _, c := range cases {
		r := validRisk("R-1", c.probability, c.impact)
		if r.Score() != c.score || r.Band() != c.band {
			t.Fatalf("%dx%d: got score=%d band=%s", c.probability, c.impact, r.Score(), r.Band())
		}
	}
	if Band(0) != "invalid" || Band(26) != "critical" {
		t.Fatal("band did not handle out-of-range scores")
	}
}

func TestValidateRejectsOutOfRange(t *testing.T) {
	cases := [][2]int{{0, 3}, {6, 3}, {3, 0}, {3, 6}}
	for _, c := range cases {
		if err := validRisk("R-1", c[0], c[1]).Validate(); err == nil {
			t.Fatalf("p=%d i=%d was accepted", c[0], c[1])
		}
	}
}

func TestRankOrdersByScoreThenID(t *testing.T) {
	risks := []Risk{
		validRisk("R-B", 2, 5), // 10
		validRisk("R-A", 2, 5), // 10
		validRisk("R-C", 5, 5), // 25
		validRisk("R-D", 1, 1), // 1
	}
	ranked, err := Rank(risks)
	if err != nil {
		t.Fatalf("Rank: %v", err)
	}
	want := []string{"R-C", "R-A", "R-B", "R-D"}
	for i, r := range ranked {
		if r.ID != want[i] {
			t.Fatalf("position %d = %s, want %s", i, r.ID, want[i])
		}
	}
	if risks[0].ID != "R-B" {
		t.Fatal("Rank mutated the input slice")
	}
}

func TestTopNEdgeCases(t *testing.T) {
	risks := []Risk{validRisk("R-1", 5, 5), validRisk("R-2", 3, 3)}
	for _, n := range []int{-1, 0} {
		got, err := TopN(risks, n)
		if err != nil || len(got) != 0 {
			t.Fatalf("TopN(%d) = %d risks, err=%v", n, len(got), err)
		}
	}
	got, err := TopN(risks, 10)
	if err != nil || len(got) != 2 {
		t.Fatalf("TopN(10) = %d risks, err=%v", len(got), err)
	}
}

func ExampleTopN() {
	riskList := []Risk{
		validRisk("R-01", 4, 4),
		validRisk("R-02", 2, 5),
		validRisk("R-03", 5, 4),
		validRisk("R-04", 3, 3),
		validRisk("R-06", 4, 3),
	}
	top, err := TopN(riskList, 3)
	if err != nil {
		fmt.Println(err)
		return
	}
	for _, r := range top {
		fmt.Printf("%s score=%d band=%s\n", r.ID, r.Score(), r.Band())
	}
	// Output:
	// R-03 score=20 band=critical
	// R-01 score=16 band=high
	// R-06 score=12 band=high
}

func TestValidateRejectsMissingOwner(t *testing.T) {
	r := validRisk("R-1", 3, 3)
	r.Owner = ""
	if err := r.Validate(); err == nil || !strings.Contains(err.Error(), "owner") {
		t.Fatalf("got %v, want owner error", err)
	}
}

$ cd .local/checks/gsarch-lab
$ gofmt -l .
$ go vet ./...
$ go test ./internal/risk/ -count=1
ok  	gsarchlab/internal/risk	1.135s