《后端架构设计·架构基础与边界》9.1 康威定律与团队拓扑

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

import (
	"fmt"
	"strings"
)

// TeamKind 对应 Team Topologies 的四类团队，决定跨团队协作的豁免范围。
type TeamKind string

const (
	StreamAligned TeamKind = "STREAM_ALIGNED"
	Platform      TeamKind = "PLATFORM"
	Enabling      TeamKind = "ENABLING"
	Complicated   TeamKind = "COMPLICATED_SUBSYSTEM"
)

// Team.TalksTo 是有向的：它表示本团队能主动向目标团队发起请求或升级故障。
// 平台群发公告不等于业务团队能向平台提单，所以方向必须记录。
type Team struct {
	ID      string
	Kind    TeamKind
	Members []string
	TalksTo []string
}

type Module struct {
	Path    string
	Owner   string
	Imports []string
}

type Map struct {
	Teams   []Team
	Modules []Module
}

type Finding struct {
	Code    string
	Subject string
	Detail  string
}

func (f Finding) String() string {
	return fmt.Sprintf("%s %s: %s", f.Code, f.Subject, f.Detail)
}

// Validate 检查四类问题：无主模块、跨多个流对齐团队的人、
// 未登记或方向相反的沟通通道、以及每条模块依赖是否有对应方向的通道。
func (m Map) Validate() []Finding {
	var out []Finding
	seen := make(map[string]bool, 16)
	add := func(code, subject, detail string) {
		key := code + "\x00" + subject
		if seen[key] {
			return
		}
		seen[key] = true
		out = append(out, Finding{Code: code, Subject: subject, Detail: detail})
	}

	teams := make(map[string]Team, len(m.Teams))
	for _, t := range m.Teams {
		teams[t.ID] = t
	}

	// 一人跨域：同一个人出现在两个流对齐团队里，说明注意力被切开。
	// 平台/赋能团队成员可以出现在业务团队中，这是协作方式，不是拆分。
	person := make(map[string][]string, len(m.Teams)*2)
	for _, t := range m.Teams {
		if t.Kind != StreamAligned {
			continue
		}
		within := make(map[string]bool, len(t.Members))
		for _, p := range t.Members {
			if p == "" || within[p] {
				continue
			}
			within[p] = true
			person[p] = append(person[p], t.ID)
			if len(person[p]) > 1 {
				add("SPLIT_ASSIGNMENT", p, strings.Join(person[p], ", "))
			}
		}
	}

	modules := make(map[string]Module, len(m.Modules))
	for _, mod := range m.Modules {
		modules[mod.Path] = mod
		if mod.Owner == "" {
			add("UNOWNED_MODULE", mod.Path, "no owner team")
			continue
		}
		if _, ok := teams[mod.Owner]; !ok {
			add("UNKNOWN_OWNER", mod.Path, mod.Owner)
		}
	}

	for _, t := range m.Teams {
		for _, target := range t.TalksTo {
			if _, ok := teams[target]; !ok {
				add("UNKNOWN_CHANNEL", t.ID, target)
			}
		}
	}

	// 依赖方向 consumer -> provider 要求通道方向 consumer -> provider。
	// 只有反方向通道时单独报 CHANNEL_DIRECTION_CONFLICT：图上“有箭头”，
	// 但下游无法向上游提需求，这是最难发现的一种错位。
	for _, mod := range m.Modules {
		owner, ok := teams[mod.Owner]
		if !ok {
			continue
		}
		for _, dep := range mod.Imports {
			provider, ok := modules[dep]
			if !ok {
				add("UNKNOWN_DEPENDENCY", mod.Path, dep)
				continue
			}
			providerTeam, ok := teams[provider.Owner]
			if !ok || provider.Owner == mod.Owner {
				continue
			}
			subject := owner.ID + " -> " + providerTeam.ID
			detail := mod.Path + " imports " + dep
			switch {
			case talksTo(owner, providerTeam.ID):
			case talksTo(providerTeam, owner.ID):
				add("CHANNEL_DIRECTION_CONFLICT", subject, detail+"; channel is reversed")
			default:
				add("MISSING_CHANNEL", subject, detail)
			}
		}
	}
	return out
}

func talksTo(t Team, target string) bool {
	for _, id := range t.TalksTo {
		if id == target {
			return true
		}
	}
	return false
}

// file: internal/orgmap/orgmap_test.go
// tier: L1
// verify: go test ./internal/orgmap/
package orgmap

import "testing"

// baseline 是 arch-lab 在 2026-10 的团队-模块映射：五个团队、十一个模块。
func baseline() Map {
	return Map{
		Teams: []Team{
			{ID: "team-order", Kind: StreamAligned, Members: []string{"alice", "bob"}, TalksTo: []string{"team-catalog", "team-inventory", "team-payments", "team-platform"}},
			{ID: "team-catalog", Kind: StreamAligned, Members: []string{"carol"}, TalksTo: []string{"team-platform"}},
			{ID: "team-inventory", Kind: StreamAligned, Members: []string{"dave"}, TalksTo: []string{"team-platform"}},
			{ID: "team-payments", Kind: StreamAligned, Members: []string{"erin"}, TalksTo: []string{"team-platform"}},
			{ID: "team-platform", Kind: Platform, Members: []string{"frank", "grace"}, TalksTo: []string{"team-order", "team-catalog", "team-inventory", "team-payments"}},
		},
		Modules: []Module{
			{Path: "cmd/orderd", Owner: "team-order", Imports: []string{"internal/order", "internal/platform/httpserver", "internal/platform/config", "internal/adapters/postgres"}},
			{Path: "internal/order", Owner: "team-order", Imports: []string{"internal/catalog", "internal/inventory", "internal/payment", "internal/ports", "internal/platform/idempotency"}},
			{Path: "internal/catalog", Owner: "team-catalog"},
			{Path: "internal/inventory", Owner: "team-inventory"},
			{Path: "internal/payment", Owner: "team-payments", Imports: []string{"internal/ports", "internal/platform/idempotency"}},
			{Path: "internal/ports", Owner: "team-platform"},
			{Path: "internal/adapters/memory", Owner: "team-platform", Imports: []string{"internal/ports"}},
			{Path: "internal/adapters/postgres", Owner: "team-platform", Imports: []string{"internal/ports", "internal/platform/config"}},
			{Path: "internal/platform/config", Owner: "team-platform"},
			{Path: "internal/platform/httpserver", Owner: "team-platform", Imports: []string{"internal/platform/config"}},
			{Path: "internal/platform/idempotency", Owner: "team-platform"},
		},
	}
}

func TestBaselineReport(t *testing.T) {
	m := baseline()
	owner := make(map[string]string, len(m.Modules))
	for _, mod := range m.Modules {
		owner[mod.Path] = mod.Owner
	}
	imports, cross := 0, 0
	for _, mod := range m.Modules {
		for _, dep := range mod.Imports {
			imports++
			if owner[dep] != mod.Owner {
				cross++
			}
		}
	}
	findings := m.Validate()
	t.Logf("teams=%d modules=%d imports=%d cross_team=%d findings=%d",
		len(m.Teams), len(m.Modules), imports, cross, len(findings))
	if len(findings) != 0 {
		t.Fatalf("baseline should be clean, got %v", findings)
	}
}

func TestValidateCatchesMappingsThatDrift(t *testing.T) {
	cases := []struct {
		name    string
		mutate  func(*Map)
		code    string
		subject string
	}{
		{"unowned module", func(m *Map) { m.Modules[modIndex(m, "internal/catalog")].Owner = "" }, "UNOWNED_MODULE", "internal/catalog"},
		{"one person, two stream teams", func(m *Map) {
			i := teamIndex(m, "team-catalog")
			m.Teams[i].Members = append(m.Teams[i].Members, "alice")
		}, "SPLIT_ASSIGNMENT", "alice"},
		{"dependency without channel", func(m *Map) {
			i := teamIndex(m, "team-order")
			m.Teams[i].TalksTo = remove(m.Teams[i].TalksTo, "team-inventory")
		}, "MISSING_CHANNEL", "team-order -> team-inventory"},
		{"channel against dependency", func(m *Map) {
			i := teamIndex(m, "team-order")
			m.Teams[i].TalksTo = remove(m.Teams[i].TalksTo, "team-catalog")
			j := teamIndex(m, "team-catalog")
			m.Teams[j].TalksTo = append(m.Teams[j].TalksTo, "team-order")
		}, "CHANNEL_DIRECTION_CONFLICT", "team-order -> team-catalog"},
	}
	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			m := baseline()
			tc.mutate(&m)
			if !has(m.Validate(), tc.code, tc.subject) {
				t.Fatalf("want %s on %q, got %v", tc.code, tc.subject, m.Validate())
			}
		})
	}
}

func modIndex(m *Map, path string) int {
	for i := range m.Modules {
		if m.Modules[i].Path == path {
			return i
		}
	}
	panic(path)
}

func teamIndex(m *Map, id string) int {
	for i := range m.Teams {
		if m.Teams[i].ID == id {
			return i
		}
	}
	panic(id)
}

func remove(values []string, want string) []string {
	out := values[:0]
	for _, v := range values {
		if v != want {
			out = append(out, v)
		}
	}
	return out
}

func has(findings []Finding, code, subject string) bool {
	for _, f := range findings {
		if f.Code == code && f.Subject == subject {
			return true
		}
	}
	return false
}

$ go test ./internal/orgmap/ -run TestBaselineReport -v
=== RUN   TestBaselineReport
    orgmap_test.go:47: teams=5 modules=11 imports=15 cross_team=10 findings=0
--- PASS: TestBaselineReport (0.00s)
PASS
ok  	archlab/internal/orgmap	0.231s