《游戏服务端架构·平台化与架构治理》8.1 架构评审与决策权

package archreview

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

var (
	ErrInvalidChange = errors.New("archreview: change is incomplete")
	ErrQuorum        = errors.New("archreview: required reviewer has not voted")
	ErrSelfApproval  = errors.New("archreview: author cannot decide own change")
	ErrCondition     = errors.New("archreview: condition needs owner, text and deadline")
	ErrBadVerdict    = errors.New("archreview: unknown verdict")
)

// Option is a seriously considered alternative. RejectedBecause is mandatory:
// options invented after the decision are not alternatives.
type Option struct {
	Name            string
	RejectedBecause string
}

// Change is the material a review acts on. The five sections map to the five
// things a reviewer needs before deciding: context, options, consequences,
// risks and rollback.
type Change struct {
	ID                  string
	Class               Class
	Author              string
	Services            []string
	Products            []string
	TouchesDataModel    bool
	TouchesMonetization bool
	Background          string
	Options             []Option
	Risks               []string
	Rollback            string
}

// Validate rejects incomplete material before any reviewer spends time on it.
// The validation is deliberately about presence, not quality: quality is what
// the review meeting is for.
func (c Change) Validate() error {
	if strings.TrimSpace(c.ID) == "" || strings.TrimSpace(c.Author) == "" {
		return fmt.Errorf("%w: id or author", ErrInvalidChange)
	}
	if _, ok := TierFor(c.Class); !ok {
		return fmt.Errorf("%w: unknown class %q", ErrInvalidChange, c.Class)
	}
	if strings.TrimSpace(c.Background) == "" {
		return fmt.Errorf("%w: background", ErrInvalidChange)
	}
	if len(c.Options) < 2 {
		return fmt.Errorf("%w: at least two options", ErrInvalidChange)
	}
	for _, o := range c.Options {
		if strings.TrimSpace(o.Name) == "" || strings.TrimSpace(o.RejectedBecause) == "" {
			return fmt.Errorf("%w: every option needs a rejection reason", ErrInvalidChange)
		}
	}
	if len(c.Risks) == 0 {
		return fmt.Errorf("%w: risks", ErrInvalidChange)
	}
	if strings.TrimSpace(c.Rollback) == "" {
		return fmt.Errorf("%w: rollback", ErrInvalidChange)
	}
	if c.Class == CrossService && len(c.Services) < 2 {
		return fmt.Errorf("%w: cross-service needs two services", ErrInvalidChange)
	}
	if c.Class == CrossProduct && len(c.Products) < 2 {
		return fmt.Errorf("%w: cross-product needs two products", ErrInvalidChange)
	}
	if c.Class == DataOrMonetized && !c.TouchesDataModel && !c.TouchesMonetization {
		return fmt.Errorf("%w: data-or-monetized needs a data or monetization flag", ErrInvalidChange)
	}
	return nil
}

type Verdict string

const (
	Approved               Verdict = "approved"
	ApprovedWithConditions Verdict = "approved-with-conditions"
	Rejected               Verdict = "rejected"
	Deferred               Verdict = "deferred"
)

type Vote struct {
	Seat    Seat
	Actor   string
	Verdict Verdict
	Comment string
}

// Condition is a binding follow-up. A condition without an owner or a
// deadline is not a condition, it is a wish.
type Condition struct {
	Text  string
	Owner string
	Due   time.Time
}

type Decision struct {
	ReviewID   string
	Verdict    Verdict
	DecidedBy  []string
	Conditions []Condition
	At         time.Time
}

// Decide computes the outcome from the votes that fill the required seats.
// Advisor votes are recorded but never change the outcome. A missing
// approver or veto seat returns ErrQuorum instead of silently approving.
func Decide(c Change, votes []Vote, conditions []Condition, at time.Time) (Decision, error) {
	if err := c.Validate(); err != nil {
		return Decision{}, err
	}
	seats, _ := Requirements(c.Class)
	bySeat := make(map[Seat]Vote, len(votes))
	for _, v := range votes {
		if v.Actor == c.Author && (v.Seat.Authority == Approver || v.Seat.Authority == Veto) {
			return Decision{}, ErrSelfApproval
		}
		if v.Seat.Authority == Approver || v.Seat.Authority == Veto {
			bySeat[v.Seat] = v
		}
	}
	for _, s := range seats {
		if s.Authority == Advisor {
			continue
		}
		if _, ok := bySeat[s]; !ok {
			return Decision{}, fmt.Errorf("%w: %s", ErrQuorum, s.Role)
		}
	}
	out := Approved
	for _, s := range seats {
		if s.Authority == Advisor {
			continue
		}
		v, ok := bySeat[s]
		if !ok {
			continue
		}
		switch v.Verdict {
		case Approved:
		case ApprovedWithConditions:
			if out == Approved {
				out = ApprovedWithConditions
			}
		case Deferred:
			if out != Rejected {
				out = Deferred
			}
		case Rejected:
			out = Rejected
		default:
			return Decision{}, fmt.Errorf("%w: %q", ErrBadVerdict, v.Verdict)
		}
	}
	if out == ApprovedWithConditions {
		if len(conditions) == 0 {
			return Decision{}, fmt.Errorf("%w: conditioned approval has no condition", ErrCondition)
		}
		for _, cond := range conditions {
			if strings.TrimSpace(cond.Text) == "" || strings.TrimSpace(cond.Owner) == "" || !cond.Due.After(at) {
				return Decision{}, ErrCondition
			}
		}
	} else if len(conditions) > 0 {
		return Decision{}, fmt.Errorf("%w: conditions require a conditioned approval", ErrCondition)
	}
	return Decision{
		ReviewID:   c.ID,
		Verdict:    out,
		DecidedBy:  deciders(seats, bySeat),
		Conditions: conditions,
		At:         at,
	}, nil
}

func deciders(seats []Seat, votes map[Seat]Vote) []string {
	seen := make(map[string]bool, len(votes))
	out := make([]string, 0, len(votes))
	for _, s := range seats {
		v, ok := votes[s]
		if !ok || v.Actor == "" || seen[v.Actor] {
			continue
		}
		seen[v.Actor] = true
		out = append(out, v.Actor)
	}
	sort.Strings(out)
	return out
}