《后端架构设计·架构基础与边界》12.1 需求、约束与非功能目标

// file: internal/baseline/baseline.go
// tier: L2
// verify: go test ./internal/baseline/ -count=1
package baseline

import (
	"fmt"
	"math"
	"time"
)

type Status string

const (
	StatusTarget     Status = "target"
	StatusMeasured   Status = "measured"
	StatusUnverified Status = "unverified"
)

// Metric 的两个数值用指针，区分“没有数”和“数恰好是 0”。
type Metric struct {
	ID           string   `json:"id"`
	Name         string   `json:"name"`
	Unit         string   `json:"unit"`
	Target       *float64 `json:"target,omitempty"`
	Measured     *float64 `json:"measured,omitempty"`
	Status       Status   `json:"status"`
	Owner        string   `json:"owner"`
	Evidence     string   `json:"evidence,omitempty"`
	Verification string   `json:"verification,omitempty"`
	MeasuredOn   string   `json:"measured_on,omitempty"`
}

type Constraint struct {
	ID        string `json:"id"`
	Kind      string `json:"kind"`
	Statement string `json:"statement"`
	Impact    string `json:"impact"`
	Owner     string `json:"owner"`
}

type Baseline struct {
	Name        string       `json:"name"`
	Version     string       `json:"version"`
	Owners      []string     `json:"owners"`
	Metrics     []Metric     `json:"metrics"`
	Constraints []Constraint `json:"constraints"`
}

type Finding struct {
	Code    string `json:"code"`
	Ref     string `json:"ref"`
	Message string `json:"message"`
}

// Validate 只拦“口径自相矛盾”，目标值是否合理留给评审。
func (b Baseline) Validate() []Finding {
	var out []Finding
	add := func(code, ref, format string, args ...any) {
		out = append(out, Finding{Code: code, Ref: ref, Message: fmt.Sprintf(format, args...)})
	}
	if b.Name == "" || b.Version == "" {
		add("BASELINE_ID", "baseline", "name and version are required")
	}
	owners := map[string]bool{}
	for _, o := range b.Owners {
		if o == "" {
			add("OWNER_EMPTY", "owners", "owner must not be empty")
		} else if owners[o] {
			add("OWNER_DUPLICATE", o, "owner %q listed twice", o)
		}
		owners[o] = true
	}
	ids := map[string]string{}
	for i, m := range b.Metrics {
		ref := m.ID
		if ref == "" {
			ref = fmt.Sprintf("metrics[%d]", i)
			add("METRIC_ID", ref, "id is required")
		} else if prev, ok := ids[m.ID]; ok {
			add("ID_DUPLICATE", ref, "id %q also used by %s", m.ID, prev)
		} else {
			ids[m.ID] = "metric"
		}
		if m.Name == "" || m.Unit == "" {
			add("METRIC_TEXT", ref, "name and unit are required")
		}
		if !owners[m.Owner] {
			add("METRIC_OWNER", ref, "owner %q not in roster", m.Owner)
		}
		if m.Target != nil && !finite(*m.Target) {
			add("METRIC_TARGET", ref, "target must be finite and non-negative")
		}
		if m.Measured != nil && !finite(*m.Measured) {
			add("METRIC_MEASURED", ref, "measured must be finite and non-negative")
		}
		switch m.Status {
		case StatusTarget:
			if m.Target == nil {
				add("TARGET_MISSING", ref, "status target requires target")
			}
			if m.Measured != nil {
				add("TARGET_HAS_MEASURED", ref, "status target must not carry measured")
			}
			if m.Verification == "" {
				add("TARGET_NO_PLAN", ref, "target metric needs verification plan")
			}
		case StatusMeasured:
			if m.Measured == nil || m.Target == nil {
				add("MEASURED_INCOMPLETE", ref, "measured metric needs target and measured value")
			}
			if m.Evidence == "" {
				add("MEASURED_NO_EVIDENCE", ref, "measured metric needs evidence command or report")
			}
			if _, err := time.Parse(time.RFC3339, m.MeasuredOn); err != nil {
				add("MEASURED_NO_DATE", ref, "measured_on must be RFC3339")
			}
		case StatusUnverified:
			if m.Measured != nil {
				add("UNVERIFIED_HAS_MEASURED", ref, "unverified must not carry measured; use status measured")
			}
			if m.Target == nil || m.Verification == "" {
				add("UNVERIFIED_INCOMPLETE", ref, "unverified metric needs target and verification plan")
			}
		default:
			add("METRIC_STATUS", ref, "unknown status %q", m.Status)
		}
	}
	for i, c := range b.Constraints {
		ref := c.ID
		if ref == "" {
			ref = fmt.Sprintf("constraints[%d]", i)
			add("CONSTRAINT_ID", ref, "id is required")
		} else if prev, ok := ids[c.ID]; ok {
			add("ID_DUPLICATE", ref, "id %q also used by %s", c.ID, prev)
		} else {
			ids[c.ID] = "constraint"
		}
		switch c.Kind {
		case "business", "technical", "organizational":
		default:
			add("CONSTRAINT_KIND", ref, "kind %q is not business/technical/organizational", c.Kind)
		}
		if c.Statement == "" || c.Impact == "" {
			add("CONSTRAINT_TEXT", ref, "statement and impact are required")
		}
		if !owners[c.Owner] {
			add("CONSTRAINT_OWNER", ref, "owner %q not in roster", c.Owner)
		}
	}
	return out
}

func finite(v float64) bool {
	return !math.IsNaN(v) && !math.IsInf(v, 0) && v >= 0
}

// file: internal/baseline/baseline_test.go
// tier: L2
// verify: go test ./internal/baseline/ -run TestValidate -v
package baseline

import (
	"fmt"
	"testing"
)

func ptr(v float64) *float64 { return &v }

func fixture() Baseline {
	return Baseline{
		Name: "arch-lab 卷一基线", Version: "2026-10-baseline.1",
		Owners: []string{"team-order", "team-pay", "platform"},
		Metrics: []Metric{
			{ID: "NFR-01", Name: "创建订单延迟", Unit: "ms", Target: ptr(300), Status: StatusTarget, Owner: "team-order", Verification: "QA-PERF-01: staging 30 orders/s, p95 + error rate"},
			{ID: "NFR-02", Name: "订单查询延迟", Unit: "ms", Target: ptr(150), Status: StatusUnverified, Owner: "team-order", Verification: "QA-PERF-02: cache hit 90%, GET p99"},
			{ID: "NFR-03", Name: "月度可用性", Unit: "%", Target: ptr(99.9), Status: StatusTarget, Owner: "platform", Verification: "30-day 5xx + timeout ratio"},
			{ID: "NFR-05", Name: "基线校验耗时", Unit: "ms", Target: ptr(5), Measured: ptr(0.006), Status: StatusMeasured, Owner: "platform", Evidence: "go test -bench=BenchmarkValidate -benchtime=200x -count=3", MeasuredOn: "2026-11-02T10:00:00+08:00"},
			{ID: "NFR-06", Name: "恢复点目标 RPO", Unit: "min", Target: ptr(5), Status: StatusTarget, Owner: "platform", Verification: "QA-DR-01: primary failover drill"},
		},
		Constraints: []Constraint{
			{ID: "C-01", Kind: "technical", Statement: "Go 1.26，标准库优先", Impact: "不引入 Web 框架与 ORM", Owner: "platform"},
			{ID: "C-02", Kind: "organizational", Statement: "两个小队共用一个值班轮值", Impact: "跨模块故障需要联合 runbook", Owner: "platform"},
		},
	}
}

func metric(b *Baseline, id string) *Metric {
	for i := range b.Metrics {
		if b.Metrics[i].ID == id {
			return &b.Metrics[i]
		}
	}
	panic("metric not found: " + id)
}

func has(findings []Finding, code string) bool {
	for _, f := range findings {
		if f.Code == code {
			return true
		}
	}
	return false
}

func TestValidateClean(t *testing.T) {
	if got := fixture().Validate(); len(got) != 0 {
		t.Fatalf("clean baseline returned %v", got)
	}
}

func TestValidateRejectsConfusedStatuses(t *testing.T) {
	tests := []struct {
		name   string
		mutate func(*Baseline)
		code   string
	}{
		{"target carries measured", func(b *Baseline) { metric(b, "NFR-01").Measured = ptr(280) }, "TARGET_HAS_MEASURED"},
		{"measured without evidence", func(b *Baseline) { metric(b, "NFR-05").Evidence = "" }, "MEASURED_NO_EVIDENCE"},
		{"unverified carries measured", func(b *Baseline) { metric(b, "NFR-02").Measured = ptr(120) }, "UNVERIFIED_HAS_MEASURED"},
		{"unknown owner", func(b *Baseline) { metric(b, "NFR-03").Owner = "team-ghost" }, "METRIC_OWNER"},
		{"duplicate id", func(b *Baseline) { metric(b, "NFR-02").ID = "NFR-01" }, "ID_DUPLICATE"},
		{"target without plan", func(b *Baseline) { metric(b, "NFR-06").Verification = "" }, "TARGET_NO_PLAN"},
	}
	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			b := fixture()
			tc.mutate(&b)
			if findings := b.Validate(); !has(findings, tc.code) {
				t.Fatalf("want %s, got %v", tc.code, findings)
			}
		})
	}
}

// 64 条指标 + 16 条约束，模拟一次季度基线评审的规模。
func BenchmarkValidate(b *testing.B) {
	base := fixture()
	for i := len(base.Metrics); i < 64; i++ {
		base.Metrics = append(base.Metrics, Metric{ID: fmt.Sprintf("NFR-%02d", i+1), Name: "generated", Unit: "ms", Target: ptr(100), Status: StatusTarget, Owner: "team-order", Verification: "generated plan"})
	}
	for i := len(base.Constraints); i < 16; i++ {
		base.Constraints = append(base.Constraints, Constraint{ID: fmt.Sprintf("C-%02d", i+1), Kind: "technical", Statement: "generated", Impact: "generated", Owner: "platform"})
	}
	b.ReportAllocs()
	for i := 0; i < b.N; i++ {
		_ = base.Validate()
	}
}

$ go test ./internal/baseline -count=1
ok  	archlab/internal/baseline	0.599s

$ go test ./internal/baseline -run '^$' -bench=BenchmarkValidate -benchtime=200x -count=3
BenchmarkValidate-10    	     200	      5841 ns/op	    9289 B/op	      13 allocs/op
BenchmarkValidate-10    	     200	      5984 ns/op	    9289 B/op	      13 allocs/op
BenchmarkValidate-10    	     200	      5951 ns/op	    9289 B/op	      13 allocs/op
PASS
ok  	archlab/internal/baseline	0.350s