《游戏服务端架构·品类、状态与拓扑》2.1 质量属性与无法回避的取舍

延迟：P0，必须行业领先
一致性：P0，绝不能丢数据
成本：P0，预算不能超
可修改性：P0，新玩法要能两周上线

// file: internal/quality/scenario.go
// tier: L1
// verify: go test ./internal/quality/
package quality

import (
	"fmt"
	"strings"
)

// Dimension is a quality attribute that a game backend can optimize for.
type Dimension string

const (
	Latency       Dimension = "latency"
	Consistency   Dimension = "consistency"
	Cost          Dimension = "cost"
	Modifiability Dimension = "modifiability"
)

var Dimensions = []Dimension{Latency, Consistency, Cost, Modifiability}

// Scenario is the six-part quality attribute scenario used in review.
type Scenario struct {
	ID          string
	Product     string
	Attribute   Dimension
	Source      string
	Stimulus    string
	Artifact    string
	Environment string
	Response    string
	Measure     string
}

func (d Dimension) Valid() bool {
	for _, known := range Dimensions {
		if d == known {
			return true
		}
	}
	return false
}

// Validate rejects incomplete scenarios, including blank strings.
func (s Scenario) Validate() error {
	var missing []string
	add := func(name, value string) {
		if strings.TrimSpace(value) == "" {
			missing = append(missing, name)
		}
	}
	add("id", s.ID)
	add("product", s.Product)
	add("attribute", string(s.Attribute))
	add("source", s.Source)
	add("stimulus", s.Stimulus)
	add("artifact", s.Artifact)
	add("environment", s.Environment)
	add("response", s.Response)
	add("measure", s.Measure)
	if len(missing) > 0 {
		return fmt.Errorf("scenario %q: missing %s", s.ID, strings.Join(missing, ", "))
	}
	if !s.Attribute.Valid() {
		return fmt.Errorf("scenario %q: unknown attribute %q", s.ID, s.Attribute)
	}
	return nil
}

// ValidateAll also rejects duplicate IDs, which would inflate coverage.
func ValidateAll(scenarios []Scenario) []error {
	var errs []error
	seen := make(map[string]bool, len(scenarios))
	for _, s := range scenarios {
		if err := s.Validate(); err != nil {
			errs = append(errs, err)
			continue
		}
		if seen[s.ID] {
			errs = append(errs, fmt.Errorf("scenario %q: duplicate id", s.ID))
			continue
		}
		seen[s.ID] = true
	}
	return errs
}

// Coverage summarizes how many scenarios exist per attribute and product.
type Coverage struct {
	Total       int
	ByDimension map[Dimension]int
	ByProduct   map[string]int
}

func Summarize(scenarios []Scenario) Coverage {
	c := Coverage{
		Total:       len(scenarios),
		ByDimension: make(map[Dimension]int),
		ByProduct:   make(map[string]int),
	}
	for _, s := range scenarios {
		c.ByDimension[s.Attribute]++
		c.ByProduct[s.Product]++
	}
	return c
}

// Missing returns the review dimensions that have no scenario at all.
func Missing(c Coverage) []Dimension {
	var out []Dimension
	for _, d := range Dimensions {
		if c.ByDimension[d] == 0 {
			out = append(out, d)
		}
	}
	return out
}

// file: internal/quality/scenario_test.go
// tier: L1
// verify: go test ./internal/quality/
package quality

import (
	"strings"
	"testing"
)

func validScenario() Scenario {
	return Scenario{
		ID:          "Q-LAT-01",
		Product:     "裂隙战场",
		Attribute:   Latency,
		Source:      "排位赛玩家",
		Stimulus:    "连续释放三个技能",
		Artifact:    "房间服战斗循环",
		Environment: "周五晚高峰，单房间 10 人",
		Response:    "三个技能在同一帧内完成结算并广播",
		Measure:     "操作 p99 不超过 120ms，帧 p99 不超过 50ms",
	}
}

func TestValidateRejectsEveryMissingField(t *testing.T) {
	cases := []struct {
		name   string
		mutate func(*Scenario)
	}{
		{"id", func(s *Scenario) { s.ID = "" }},
		{"product", func(s *Scenario) { s.Product = " " }},
		{"attribute", func(s *Scenario) { s.Attribute = "" }},
		{"source", func(s *Scenario) { s.Source = "" }},
		{"stimulus", func(s *Scenario) { s.Stimulus = "" }},
		{"artifact", func(s *Scenario) { s.Artifact = "" }},
		{"environment", func(s *Scenario) { s.Environment = "" }},
		{"response", func(s *Scenario) { s.Response = "" }},
		{"measure", func(s *Scenario) { s.Measure = "" }},
	}
	for _, c := range cases {
		t.Run(c.name, func(t *testing.T) {
			s := validScenario()
			c.mutate(&s)
			err := s.Validate()
			if err == nil {
				t.Fatalf("scenario without %s was accepted", c.name)
			}
			if !strings.Contains(err.Error(), c.name) {
				t.Fatalf("error %q does not name %q", err, c.name)
			}
		})
	}
}

func TestValidateRejectsUnknownAttributeAndDuplicateID(t *testing.T) {
	s := validScenario()
	s.Attribute = "security"
	if err := s.Validate(); err == nil {
		t.Fatal("unknown attribute was accepted")
	}

	a, b := validScenario(), validScenario()
	errs := ValidateAll([]Scenario{a, b})
	if len(errs) != 1 || !strings.Contains(errs[0].Error(), "duplicate") {
		t.Fatalf("got %v, want one duplicate error", errs)
	}
}

func TestSummarizeAndMissing(t *testing.T) {
	scenarios := []Scenario{
		validScenario(),
		{ID: "Q-CON-01", Product: "群岛纪元", Attribute: Consistency},
		{ID: "Q-CON-02", Product: "群岛纪元", Attribute: Consistency},
		{ID: "Q-COST-01", Product: "泡泡工坊", Attribute: Cost},
	}
	c := Summarize(scenarios)
	if c.Total != 4 || c.ByDimension[Consistency] != 2 || c.ByProduct["群岛纪元"] != 2 {
		t.Fatalf("unexpected coverage: %+v", c)
	}
	missing := Missing(c)
	if len(missing) != 1 || missing[0] != Modifiability {
		t.Fatalf("missing=%v, want [modifiability]", missing)
	}
}

$ cd .local/checks/gsarch-lab
$ gofmt -l .
$ go vet ./...
$ go test ./internal/quality/ -count=1 -v
=== RUN   TestValidateRejectsEveryMissingField
--- PASS: TestValidateRejectsEveryMissingField (0.00s)
=== RUN   TestValidateRejectsUnknownAttributeAndDuplicateID
--- PASS: TestValidateRejectsUnknownAttributeAndDuplicateID (0.00s)
=== RUN   TestSummarizeAndMissing
--- PASS: TestSummarizeAndMissing (0.00s)
PASS
ok  	gsarchlab/internal/quality	0.454s