《游戏服务端架构·平台化与架构治理》12.3 架构师的沟通与写作

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

import (
	"fmt"
	"regexp"
	"strings"
	"time"
	"unicode/utf8"
)

type Audience string

const (
	Executive Audience = "executive"
	Team      Audience = "team"
	CrossTeam Audience = "cross-team"
)

type Kind string

const (
	Conclusion   Kind = "conclusion"
	Evidence     Kind = "evidence"
	Options      Kind = "options"
	Consequences Kind = "consequences"
	Request      Kind = "request"
	Cost         Kind = "cost"
	Risk         Kind = "risk"
	Interfaces   Kind = "interfaces"
	Milestones   Kind = "milestones"
	Contract     Kind = "contract"
	Boundary     Kind = "boundary"
)

type Section struct {
	Heading string
	Body    string
}

type Document struct {
	Title    string
	Audience Audience
	Sections []Section
}

var aliases = map[Kind][]string{
	Conclusion:   {"结论", "conclusion", "decision"},
	Evidence:     {"证据", "数据", "evidence"},
	Options:      {"选项", "备选", "options", "alternatives"},
	Consequences: {"后果", "影响", "consequences", "impact"},
	Request:      {"请求", "需要", "ask", "request"},
	Cost:         {"成本", "预算", "cost", "budget"},
	Risk:         {"风险", "risk"},
	Interfaces:   {"接口", "interface", "api"},
	Milestones:   {"里程碑", "计划", "milestone", "timeline"},
	Contract:     {"契约", "协议", "contract"},
	Boundary:     {"边界", "职责", "boundary", "ownership"},
}

var baseKinds = []Kind{Conclusion, Evidence, Options, Consequences, Request}

// Required returns the section kinds a document must contain for an audience.
// The base five answer "what do you want me to decide"; the audience extras
// answer the questions that audience will ask first.
func Required(a Audience) []Kind {
	out := append([]Kind{}, baseKinds...)
	switch a {
	case Executive:
		out = append(out, Cost, Risk)
	case Team:
		out = append(out, Interfaces, Milestones)
	case CrossTeam:
		out = append(out, Contract, Boundary)
	default:
		return nil
	}
	return out
}

func normalize(s string) string {
	return strings.ToLower(strings.TrimSpace(s))
}

// classify returns every kind a heading mentions, so "接口与边界" satisfies
// both requirements instead of forcing authors to split one idea in two.
func classify(heading string) map[Kind]bool {
	h := normalize(heading)
	out := make(map[Kind]bool)
	for k, names := range aliases {
		for _, n := range names {
			if strings.Contains(h, strings.ToLower(n)) {
				out[k] = true
				break
			}
		}
	}
	return out
}

type Finding struct {
	Severity string
	Code     string
	Message  string
}

func errorf(code, format string, args ...any) Finding {
	return Finding{Severity: "error", Code: code, Message: fmt.Sprintf(format, args...)}
}

func warnf(code, format string, args ...any) Finding {
	return Finding{Severity: "warning", Code: code, Message: fmt.Sprintf(format, args...)}
}

var datePattern = regexp.MustCompile(`\d{4}-\d{2}-\d{2}`)

// Validate checks structure, audience fit, and the request section. It reports
// every finding instead of stopping at the first one so an author can fix the
// document in one pass.
func Validate(doc Document) []Finding {
	var fs []Finding
	if strings.TrimSpace(doc.Title) == "" {
		fs = append(fs, errorf("empty-title", "document has no title"))
	}
	if len(Required(doc.Audience)) == 0 {
		fs = append(fs, errorf("unknown-audience", "unknown audience %q", doc.Audience))
	}
	if len(doc.Sections) == 0 {
		fs = append(fs, errorf("empty-document", "document has no sections"))
		return fs
	}
	first := classify(doc.Sections[0].Heading)
	if !first[Conclusion] {
		fs = append(fs, errorf("conclusion-not-first", "first section %q is not a conclusion", doc.Sections[0].Heading))
	}
	present := make(map[Kind]bool)
	for _, s := range doc.Sections {
		kinds := classify(s.Heading)
		if len(kinds) == 0 {
			fs = append(fs, warnf("unknown-heading", "heading %q maps to no known kind", s.Heading))
		}
		if strings.TrimSpace(s.Body) == "" {
			fs = append(fs, errorf("empty-section", "section %q has no body", s.Heading))
		}
		for k := range kinds {
			if present[k] {
				fs = append(fs, warnf("duplicate-kind", "kind %s appears more than once", k))
			}
			present[k] = true
		}
	}
	for _, k := range Required(doc.Audience) {
		if !present[k] {
			fs = append(fs, errorf("missing-section", "missing required section %s for %s", k, doc.Audience))
		}
	}
	if first[Conclusion] && utf8.RuneCountInString(doc.Sections[0].Body) > 600 {
		fs = append(fs, warnf("long-conclusion", "conclusion is %d runes; put detail in evidence",
			utf8.RuneCountInString(doc.Sections[0].Body)))
	}
	for _, s := range doc.Sections {
		if !classify(s.Heading)[Request] {
			continue
		}
		body := s.Body
		if !strings.Contains(body, "负责人") && !strings.Contains(strings.ToLower(body), "owner") &&
			!strings.Contains(body, "@") {
			fs = append(fs, warnf("request-without-owner", "request has no owner marker"))
		}
		if !datePattern.MatchString(body) {
			fs = append(fs, warnf("request-without-date", "request has no YYYY-MM-DD date"))
		}
	}
	return fs
}

type Action struct {
	Text  string
	Owner string
	Due   string
	Done  bool
}

var (
	actionPattern = regexp.MustCompile(`^-\s*\[( |x|X)\]\s*(.+)$`)
	ownerPattern  = regexp.MustCompile(`@([^\s]+)`)
	duePattern    = regexp.MustCompile(`due:(\d{4}-\d{2}-\d{2})`)
)

// ExtractActions reads "- [ ]" checklist lines from every section. Owner and
// due date are mandatory: an action without either is a wish, and the parser
// returns an error rather than silently dropping it.
func ExtractActions(doc Document) ([]Action, []error) {
	var out []Action
	var errs []error
	for _, s := range doc.Sections {
		for _, line := range strings.Split(s.Body, "\n") {
			m := actionPattern.FindStringSubmatch(strings.TrimSpace(line))
			if m == nil {
				continue
			}
			a := Action{Text: m[2], Done: m[1] != " "}
			if o := ownerPattern.FindStringSubmatch(a.Text); o != nil {
				a.Owner = o[1]
				a.Text = strings.Replace(a.Text, o[0], "", 1)
			}
			if d := duePattern.FindStringSubmatch(a.Text); d != nil {
				a.Due = d[1]
				a.Text = strings.Replace(a.Text, d[0], "", 1)
			}
			a.Text = strings.Join(strings.Fields(a.Text), " ")
			if a.Owner == "" {
				errs = append(errs, fmt.Errorf("action %q: missing @owner", a.Text))
			}
			if a.Due == "" {
				errs = append(errs, fmt.Errorf("action %q: missing due:date", a.Text))
			} else if _, err := time.Parse("2006-01-02", a.Due); err != nil {
				errs = append(errs, fmt.Errorf("action %q: bad due date %q", a.Text, a.Due))
			}
			out = append(out, a)
		}
	}
	sortActions(out)
	return out, errs
}

func sortActions(as []Action) {
	for i := 1; i < len(as); i++ {
		for j := i; j > 0; j-- {
			if as[j].Due > as[j-1].Due || (as[j].Due == as[j-1].Due && as[j].Text >= as[j-1].Text) {
				break
			}
			as[j], as[j-1] = as[j-1], as[j]
		}
	}
}