《游戏服务端架构·品类、状态与拓扑》13.3 进入卷二：把系统装进边界

// file: internal/handoff/handoff.go
// tier: L1
// verify: go test ./internal/handoff/
package handoff

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

var (
	ErrEmptyChecklist = errors.New("handoff: checklist needs a volume and at least one item")
	ErrMissingField   = errors.New("handoff: item needs id, topic, source and owner")
	ErrDuplicateID    = errors.New("handoff: duplicate item id")
	ErrBadState       = errors.New("handoff: state must be done, open or waived")
	ErrBadSource      = errors.New("handoff: source must look like chapter.section")
	ErrWaiverRequired = errors.New("handoff: waived item needs a reason and an approver")
)

type State string

const (
	Done   State = "done"
	Open   State = "open"
	Waived State = "waived"
)

// Item is one volume-one promise or unknown that volume two must consume. A
// blocking open item stops the handoff; a waiver is an explicit, owned choice.
type Item struct {
	ID       string
	Topic    string
	Source   string
	Owner    string
	State    State
	Blocking bool
	Waiver   string
	Approver string
}

type Checklist struct {
	Volume string
	Items  []Item
}

type Finding struct {
	ID      string
	Kind    string
	Message string
}

type Report struct {
	Ready     bool
	Blocking  []Finding
	Open      []Finding
	Waived    []Finding
	Questions []string
}

func validSource(s string) bool {
	parts := strings.Split(s, ".")
	if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
		return false
	}
	for _, p := range parts {
		for _, r := range p {
			if r < '0' || r > '9' {
				return false
			}
		}
	}
	return true
}

// Build validates the checklist, then produces the handoff report. Structural
// errors are returned as errors; unresolved risk is reported, not hidden.
func Build(c Checklist) (Report, error) {
	if strings.TrimSpace(c.Volume) == "" || len(c.Items) == 0 {
		return Report{}, ErrEmptyChecklist
	}
	seen := map[string]bool{}
	items := append([]Item(nil), c.Items...)
	for _, it := range items {
		if strings.TrimSpace(it.ID) == "" || strings.TrimSpace(it.Topic) == "" ||
			strings.TrimSpace(it.Source) == "" || strings.TrimSpace(it.Owner) == "" {
			return Report{}, fmt.Errorf("%w: %q", ErrMissingField, it.ID)
		}
		if !validSource(it.Source) {
			return Report{}, fmt.Errorf("%w: %s=%q", ErrBadSource, it.ID, it.Source)
		}
		if seen[it.ID] {
			return Report{}, fmt.Errorf("%w: %s", ErrDuplicateID, it.ID)
		}
		seen[it.ID] = true
		switch it.State {
		case Done, Open, Waived:
		default:
			return Report{}, fmt.Errorf("%w: %s=%q", ErrBadState, it.ID, it.State)
		}
		if it.State == Waived &&
			(strings.TrimSpace(it.Waiver) == "" || strings.TrimSpace(it.Approver) == "") {
			return Report{}, fmt.Errorf("%w: %s", ErrWaiverRequired, it.ID)
		}
	}
	sort.SliceStable(items, func(i, j int) bool { return items[i].ID < items[j].ID })

	report := Report{Ready: true}
	questions := map[string]bool{}
	for _, it := range items {
		finding := Finding{
			ID:   it.ID,
			Kind: string(it.State),
			Message: fmt.Sprintf("%s (from %s, owner %s)",
				it.Topic, it.Source, it.Owner),
		}
		switch it.State {
		case Done:
			continue
		case Waived:
			report.Waived = append(report.Waived, finding)
		case Open:
			questions[it.Topic] = true
			if it.Blocking {
				report.Blocking = append(report.Blocking, finding)
			} else {
				report.Open = append(report.Open, finding)
			}
		}
	}
	for q := range questions {
		report.Questions = append(report.Questions, q)
	}
	sort.Strings(report.Questions)
	report.Ready = len(report.Blocking) == 0
	return report, nil
}

// CanEnter is the one-question form used by the release gate.
func CanEnter(c Checklist) (bool, error) {
	report, err := Build(c)
	if err != nil {
		return false, err
	}
	return report.Ready, nil
}

ready=false blocking=3 open=2 waived=1 questions=5
H-01
H-02
H-03

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