《后端架构设计·分布式与数据一致性》13.3 进入卷四：演进与治理

// file: internal/handoff/handoff.go
// tier: L1
// verify: go test ./internal/handoff/ -count=1
package handoff

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

// Status says how much of an item is actually proven.
type Status string

const (
	Proven   Status = "proven"
	Partial  Status = "partial"
	Unproven Status = "unproven"
)

// Item is one question handed to the next volume.
type Item struct {
	ID       string
	Area     string
	Question string
	Owner    string
	Evidence string
	// Metric, Threshold and Window make acceptance machine-checkable.
	Metric    string
	Threshold string
	Window    string
	Status    Status
	// ResidualRisk and Due are mandatory unless the item is proven.
	ResidualRisk string
	Due          string
	Accepted     bool
}

// Checklist is the handoff document.
type Checklist struct {
	Version string
	Items   []Item
}

var requiredAreas = []string{"consensus_perf", "cross_cell_conflict", "drill_coverage", "org_cost"}

// Validate returns every reason the checklist is not acceptable, not just
// the first one. An empty slice means the handoff can be reviewed.
func (c Checklist) Validate() []error {
	var errs []error
	if strings.TrimSpace(c.Version) == "" {
		errs = append(errs, errors.New("version is empty"))
	}
	seen := make(map[string]bool)
	areas := make(map[string]bool)
	for i, it := range c.Items {
		where := fmt.Sprintf("item[%d]", i)
		if strings.TrimSpace(it.ID) == "" {
			errs = append(errs, fmt.Errorf("%s: id is empty", where))
		} else if seen[it.ID] {
			errs = append(errs, fmt.Errorf("%s: duplicate id %q", where, it.ID))
		}
		seen[it.ID] = true
		if it.Area == "" {
			errs = append(errs, fmt.Errorf("%s %s: area is empty", where, it.ID))
		} else {
			areas[it.Area] = true
		}
		if it.Owner == "" {
			errs = append(errs, fmt.Errorf("%s %s: owner is empty", where, it.ID))
		}
		if it.Question == "" {
			errs = append(errs, fmt.Errorf("%s %s: question is empty", where, it.ID))
		}
		if it.Metric == "" || it.Threshold == "" || it.Window == "" {
			errs = append(errs, fmt.Errorf("%s %s: acceptance is not machine-checkable", where, it.ID))
		}
		switch it.Status {
		case Proven:
			if it.Evidence == "" {
				errs = append(errs, fmt.Errorf("%s %s: proven without evidence", where, it.ID))
			}
		case Partial, Unproven:
			if it.ResidualRisk == "" {
				errs = append(errs, fmt.Errorf("%s %s: %s without residual risk", where, it.ID, it.Status))
			}
			if it.Due == "" {
				errs = append(errs, fmt.Errorf("%s %s: %s without due date", where, it.ID, it.Status))
			}
		default:
			errs = append(errs, fmt.Errorf("%s %s: invalid status %q", where, it.ID, it.Status))
		}
		if it.Accepted && it.Status != Proven {
			errs = append(errs, fmt.Errorf("%s %s: accepted while only %s", where, it.ID, it.Status))
		}
	}
	for _, area := range requiredAreas {
		if !areas[area] {
			errs = append(errs, fmt.Errorf("required area %q has no item", area))
		}
	}
	return errs
}

// Summary is the one-line state printed before a review.
func (c Checklist) Summary() string {
	byStatus := map[Status]int{}
	byArea := map[string]int{}
	for _, it := range c.Items {
		byStatus[it.Status]++
		byArea[it.Area]++
	}
	areas := make([]string, 0, len(byArea))
	for a := range byArea {
		areas = append(areas, a)
	}
	sort.Strings(areas)
	return fmt.Sprintf("items=%d proven=%d partial=%d unproven=%d areas=%s",
		len(c.Items), byStatus[Proven], byStatus[Partial], byStatus[Unproven], strings.Join(areas, ","))
}

=== RUN   TestValidate
    handoff_test.go:31: items=4 proven=0 partial=1 unproven=3 areas=consensus_perf,cross_cell_conflict,drill_coverage,org_cost
=== RUN   TestValidate/missing_owner
=== RUN   TestValidate/accepted_unproven
=== RUN   TestValidate/missing_area
=== RUN   TestValidate/unproven_without_due
=== RUN   TestValidate/duplicate_id
=== RUN   TestValidate/threshold_missing
--- PASS: TestValidate (0.00s)
PASS
ok  	archlab/internal/handoff	0.267s