《后端架构设计·架构基础与边界》2.3 一次真实评审记录与风险台账

{
  "risks": [
    {
      "id": "R-01",
      "title": "订单状态与库存预留不一致",
      "trigger": "订单写库成功，库存端口超时或返回未知结果",
      "impact": "订单显示已预留，实际库存未扣，峰值超卖并引发赔付",
      "probability": "medium",
      "impact_level": "high",
      "level": "high",
      "owner_role": "订单模块负责人",
      "mitigation": "预留与订单写入同一本地事务；端口结果未知时进入待对账",
      "closure": "注入 200 次提交后断连，账实差异为 0"
    }
  ]
}

// file: tools/riskreg/riskreg.go
// tier: L1
// verify: go test ./tools/riskreg/ -count=1 -v
package main

import (
	"encoding/json"
	"fmt"
	"os"
)

type Rating string

const (
	Low      Rating = "low"
	Medium   Rating = "medium"
	High     Rating = "high"
	Critical Rating = "critical"
)

type Risk struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	Trigger     string `json:"trigger"`
	Impact      string `json:"impact"`
	Probability Rating `json:"probability"`
	ImpactLevel Rating `json:"impact_level"`
	Level       Rating `json:"level"`
	OwnerRole   string `json:"owner_role"`
	Mitigation  string `json:"mitigation"`
	Closure     string `json:"closure"`
}

type Register struct {
	Risks []Risk `json:"risks"`
}

type Issue struct {
	Code string
	Ref  string
	Why  string
}

const (
	CodeMissingField   = "MISSING_FIELD"
	CodeDuplicateID    = "DUPLICATE_ID"
	CodeBadRating      = "BAD_RATING"
	CodeLevelMismatch  = "LEVEL_MISMATCH"
	CodeMissingClosure = "MISSING_CLOSURE"
)

func load(path string) (Register, error) {
	data, err := os.ReadFile(path)
	if err != nil {
		return Register{}, err
	}
	var reg Register
	if err := json.Unmarshal(data, &reg); err != nil {
		return Register{}, fmt.Errorf("parse %s: %w", path, err)
	}
	return reg, nil
}

func validProbability(r Rating) bool { return r == Low || r == Medium || r == High }

func validLevel(r Rating) bool {
	return r == Low || r == Medium || r == High || r == Critical
}

// expectedLevel 是概率 × 影响的固定矩阵，避免人工把 medium 写成 high。
func expectedLevel(probability, impact Rating) Rating {
	rank := map[Rating]int{Low: 0, Medium: 1, High: 2}
	switch sum := rank[probability] + rank[impact]; {
	case sum <= 1:
		return Low
	case sum == 2:
		return Medium
	case sum == 3:
		return High
	default:
		return Critical
	}
}

func (r Register) Validate() []Issue {
	var issues []Issue
	seen := make(map[string]bool, len(r.Risks))

	for _, risk := range r.Risks {
		if risk.ID == "" {
			issues = append(issues, Issue{CodeMissingField, "(empty)", "id"})
		} else if seen[risk.ID] {
			issues = append(issues, Issue{CodeDuplicateID, risk.ID, "declared twice"})
		}
		seen[risk.ID] = true

		required := []struct{ name, value string }{
			{"title", risk.Title}, {"trigger", risk.Trigger}, {"impact", risk.Impact},
			{"owner_role", risk.OwnerRole}, {"mitigation", risk.Mitigation},
		}
		for _, field := range required {
			if field.value == "" {
				issues = append(issues, Issue{CodeMissingField, risk.ID, field.name})
			}
		}
		if risk.Closure == "" {
			issues = append(issues, Issue{CodeMissingClosure, risk.ID, "closure"})
		}
		if !validProbability(risk.Probability) {
			issues = append(issues, Issue{CodeBadRating, risk.ID, "probability=" + string(risk.Probability)})
		}
		if !validProbability(risk.ImpactLevel) {
			issues = append(issues, Issue{CodeBadRating, risk.ID, "impact_level=" + string(risk.ImpactLevel)})
		}
		if !validLevel(risk.Level) {
			issues = append(issues, Issue{CodeBadRating, risk.ID, "level=" + string(risk.Level)})
		}
		if validProbability(risk.Probability) && validProbability(risk.ImpactLevel) &&
			validLevel(risk.Level) && risk.Level != expectedLevel(risk.Probability, risk.ImpactLevel) {
			want := expectedLevel(risk.Probability, risk.ImpactLevel)
			issues = append(issues, Issue{CodeLevelMismatch, risk.ID,
				"level=" + string(risk.Level) + " want=" + string(want)})
		}
	}
	return issues
}

// file: tools/riskreg/main.go
// tier: L1
// verify: go run ./tools/riskreg -file risk-register.json
package main

import (
	"flag"
	"fmt"
	"os"
)

func main() {
	file := flag.String("file", "risk-register.json", "path to risk register JSON")
	flag.Parse()

	reg, err := load(*file)
	if err != nil {
		fmt.Fprintln(os.Stderr, "riskreg:", err)
		os.Exit(2)
	}
	issues := reg.Validate()
	for _, issue := range issues {
		fmt.Println(issue.Code, issue.Ref, issue.Why)
	}
	if len(issues) > 0 {
		fmt.Fprintf(os.Stderr, "riskreg: %d issue(s) in %s\n", len(issues), *file)
		os.Exit(1)
	}
	fmt.Printf("riskreg: ok (%d risks)\n", len(reg.Risks))
}

// file: tools/riskreg/riskreg_test.go
// tier: L1
// verify: go test ./tools/riskreg/ -count=1 -v
package main

import (
	"os"
	"path/filepath"
	"testing"
)

func validRegister() Register {
	return Register{Risks: []Risk{
		{ID: "R-01", Title: "t", Trigger: "g", Impact: "i", Probability: Medium,
			ImpactLevel: High, Level: High, OwnerRole: "SRE", Mitigation: "m", Closure: "c"},
		{ID: "R-02", Title: "t", Trigger: "g", Impact: "i", Probability: Low,
			ImpactLevel: High, Level: Medium, OwnerRole: "SRE", Mitigation: "m", Closure: "c"},
	}}
}

func hasCode(issues []Issue, want string) bool {
	for _, issue := range issues {
		if issue.Code == want {
			return true
		}
	}
	return false
}

func TestValidRegister(t *testing.T) {
	if issues := validRegister().Validate(); len(issues) != 0 {
		t.Fatalf("valid register has %v", issues)
	}
}

func TestValidateTable(t *testing.T) {
	tests := []struct {
		name   string
		mutate func(*Register)
		want   string
	}{
		{"missing owner", func(r *Register) { r.Risks[0].OwnerRole = "" }, CodeMissingField},
		{"missing closure", func(r *Register) { r.Risks[0].Closure = "" }, CodeMissingClosure},
		{"bad probability", func(r *Register) { r.Risks[0].Probability = "likely" }, CodeBadRating},
		{"level mismatch", func(r *Register) { r.Risks[0].Level = Low }, CodeLevelMismatch},
		{"duplicate id", func(r *Register) { r.Risks[1].ID = "R-01" }, CodeDuplicateID},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			reg := validRegister()
			tt.mutate(&reg)
			if !hasCode(reg.Validate(), tt.want) {
				t.Fatalf("issues = %v, want %s", reg.Validate(), tt.want)
			}
		})
	}
}

func TestLoad(t *testing.T) {
	path := filepath.Join(t.TempDir(), "risks.json")
	body := `{"risks":[{"id":"R-01","title":"t","trigger":"g","impact":"i",` +
		`"probability":"medium","impact_level":"high","level":"high",` +
		`"owner_role":"SRE","mitigation":"m","closure":"c"}]}`
	if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
		t.Fatal(err)
	}
	reg, err := load(path)
	if err != nil {
		t.Fatal(err)
	}
	if issues := reg.Validate(); len(issues) != 0 {
		t.Fatalf("loaded register invalid: %v", issues)
	}
}

$ go run ./tools/riskreg -file risk-register.json
riskreg: ok (9 risks)

$ go run ./tools/riskreg -file bad-risk-register.json 2>&1
MISSING_FIELD R-01 owner_role
MISSING_CLOSURE R-01 closure
LEVEL_MISMATCH R-01 level=low want=high
riskreg: 3 issue(s) in bad-risk-register.json
exit status 1