《后端架构设计·架构基础与边界》13.1 从需求到架构决策记录

ADR-001 模块化单体
  ├── ADR-002 下单同步预留库存
  │     └── ADR-003 PostgreSQL 单写库
  │           └── ADR-004 下单同步、履约异步
  │                 └── ADR-006 领域事件写入 outbox
  ├── ADR-005 模块间只经端口通信
  │     └── ADR-007 单部署单元与模块开关

// file: internal/adrindex/index.go
// tier: L1
// verify: go test ./internal/adrindex/ -count=1 -v
package adrindex

import (
	"regexp"
	"strings"
	"time"
)

type Status string

const (
	StatusProposed   Status = "proposed"
	StatusAccepted   Status = "accepted"
	StatusSuperseded Status = "superseded"
	StatusRejected   Status = "rejected"
)

func (s Status) Valid() bool {
	switch s {
	case StatusProposed, StatusAccepted, StatusSuperseded, StatusRejected:
		return true
	}
	return false
}

type Alternative struct {
	Name   string
	Reason string
}
type Consequences struct {
	Positive []string
	Negative []string
}
type Entry struct {
	ID           string
	Title        string
	Status       Status
	Date         string
	Drivers      []string
	DependsOn    []string
	Alternatives []Alternative
	Consequences Consequences
	SupersededBy string
}
type Index struct{ Entries []Entry }
type Issue struct {
	Code, ID, Detail string
}

const (
	CodeInvalidID           = "INVALID_ID"
	CodeDuplicateID         = "DUPLICATE_ID"
	CodeInvalidStatus       = "INVALID_STATUS"
	CodeInvalidDate         = "INVALID_DATE"
	CodeNoDriver            = "NO_DRIVER"
	CodeNoAlternative       = "NO_ALTERNATIVE"
	CodeAlternativeNoReason = "ALTERNATIVE_NO_REASON"
	CodeNoConsequence       = "NO_CONSEQUENCE"
	CodeDanglingDependency  = "DANGLING_DEPENDENCY"
	CodeDependencyCycle     = "DEPENDENCY_CYCLE"
	CodeIsolatedADR         = "ISOLATED_ADR"
	CodeSupersededMismatch  = "SUPERSEDED_MISMATCH"
)

var idPattern = regexp.MustCompile(`^ADR-\d{3}$`)

// Validate 只检查索引自洽，不判断决策内容是否正确。
func (in Index) Validate() []Issue {
	var issues []Issue
	seen := make(map[string]bool, len(in.Entries))
	for _, e := range in.Entries {
		if !idPattern.MatchString(e.ID) {
			issues = append(issues, Issue{CodeInvalidID, e.ID, "want ADR-NNN"})
		}
		if seen[e.ID] {
			issues = append(issues, Issue{CodeDuplicateID, e.ID, "declared twice"})
		}
		seen[e.ID] = true
		if !e.Status.Valid() {
			issues = append(issues, Issue{CodeInvalidStatus, e.ID, string(e.Status)})
		}
		if _, err := time.Parse(time.RFC3339, e.Date); err != nil {
			issues = append(issues, Issue{CodeInvalidDate, e.ID, e.Date})
		}
		if len(e.Drivers) == 0 {
			issues = append(issues, Issue{CodeNoDriver, e.ID, "no requirement driver"})
		}
		if len(e.Alternatives) < 2 {
			issues = append(issues, Issue{CodeNoAlternative, e.ID, "need two candidates"})
		}
		for _, alt := range e.Alternatives {
			if strings.TrimSpace(alt.Reason) == "" {
				issues = append(issues, Issue{CodeAlternativeNoReason, e.ID, alt.Name})
			}
		}
		if len(e.Consequences.Positive) == 0 || len(e.Consequences.Negative) == 0 {
			issues = append(issues, Issue{CodeNoConsequence, e.ID, "need both signs"})
		}
		if (e.Status == StatusSuperseded) != (e.SupersededBy != "") {
			issues = append(issues, Issue{CodeSupersededMismatch, e.ID, "status/target mismatch"})
		}
	}

	dependents := make(map[string]bool, len(in.Entries))
	for _, e := range in.Entries {
		for _, dep := range e.DependsOn {
			if !seen[dep] {
				issues = append(issues, Issue{CodeDanglingDependency, e.ID, dep})
				continue
			}
			dependents[dep] = true
		}
	}
	for _, e := range in.Entries {
		if len(e.DependsOn) == 0 && !dependents[e.ID] {
			issues = append(issues, Issue{CodeIsolatedADR, e.ID, "no edge in or out"})
		}
	}
	if in.hasCycle() {
		issues = append(issues, Issue{CodeDependencyCycle, "", "DependsOn contains a cycle"})
	}
	return issues
}

func (in Index) hasCycle() bool {
	graph := make(map[string][]string, len(in.Entries))
	for _, e := range in.Entries {
		graph[e.ID] = append(graph[e.ID], e.DependsOn...)
	}
	state := make(map[string]int, len(in.Entries))
	var visit func(string) bool
	visit = func(id string) bool {
		if state[id] == 1 {
			return true
		}
		if state[id] == 2 {
			return false
		}
		state[id] = 1
		for _, dep := range graph[id] {
			if visit(dep) {
				return true
			}
		}
		state[id] = 2
		return false
	}
	for id := range graph {
		if visit(id) {
			return true
		}
	}
	return false
}

// file: internal/adrindex/volume_one.go
// tier: L1
// verify: go test ./internal/adrindex/ -run TestVolumeOneIndex -v
package adrindex

// VolumeOne 是卷一七条决策的索引；正文论证仍留在各 ADR 文档里。
func VolumeOne() Index {
	return Index{Entries: []Entry{
		{ID: "ADR-001", Title: "模块化单体作为卷一形态", Status: StatusAccepted, Date: "2026-10-05T10:00:00+08:00", Drivers: []string{"REQ-01", "REQ-02"},
			Alternatives: []Alternative{{"按模块拆成四个微服务", "两人团队承担不起跨服务事务、发布和监控成本"}, {"纯分层大泥球", "没有模块边界，后续无法增量拆分"}},
			Consequences: Consequences{Positive: []string{"单事务、单部署、测试与运维成本最低"}, Negative: []string{"边界只能靠包约束和静态检查"}}},
		{ID: "ADR-002", Title: "创建订单时同步预留库存", Status: StatusAccepted, Date: "2026-10-06T09:00:00+08:00", Drivers: []string{"REQ-03"}, DependsOn: []string{"ADR-001"},
			Alternatives: []Alternative{{"下单后异步扣减库存", "用户可见路径出现超卖窗口"}, {"支付成功后再预留", "支付前库存可能已被其他订单占用"}},
			Consequences: Consequences{Positive: []string{"超卖在同步路径被挡住"}, Negative: []string{"下单延迟包含库存调用，库存故障会阻塞下单"}}},
		{ID: "ADR-003", Title: "订单主存储选用 PostgreSQL 单写库", Status: StatusAccepted, Date: "2026-10-06T10:00:00+08:00", Drivers: []string{"REQ-03", "REQ-06"}, DependsOn: []string{"ADR-001", "ADR-002"},
			Alternatives: []Alternative{{"内存存储作为生产主库", "重启丢单，无法多进程共享和审计"}, {"文档库存订单快照", "跨订单、库存、outbox 的事务与查询能力不足"}},
			Consequences: Consequences{Positive: []string{"订单与库存同事务提交，备份恢复路径单一"}, Negative: []string{"写吞吐受单主库限制，数据库成为下单可用性上限"}}},
		{ID: "ADR-004", Title: "下单同步、履约异步", Status: StatusAccepted, Date: "2026-10-06T11:00:00+08:00", Drivers: []string{"REQ-04"}, DependsOn: []string{"ADR-002", "ADR-003"},
			Alternatives: []Alternative{{"支付回调内同步履约", "回调延迟绑定仓库系统，重试会重复发货"}, {"连库存预留也异步", "把超卖窗口留给用户可见路径"}},
			Consequences: Consequences{Positive: []string{"支付回调快，履约故障可重试"}, Negative: []string{"PAID 与 FULFILLED 之间存在时间窗，消费者必须幂等"}}},
		{ID: "ADR-005", Title: "模块间只经端口接口通信", Status: StatusAccepted, Date: "2026-10-06T12:00:00+08:00", Drivers: []string{"REQ-05"}, DependsOn: []string{"ADR-001"},
			Alternatives: []Alternative{{"共享一个 repository 包", "改一张表波及所有模块，测试必须连库"}, {"允许跨模块直接 SQL join", "短期快，长期绕过不变量和归属校验"}},
			Consequences: Consequences{Positive: []string{"模块可独立测试、替换实现，未来可拆分"}, Negative: []string{"接口数量增加，跨模块事务需要显式 unit-of-work"}}},
		{ID: "ADR-006", Title: "领域事件写入 outbox", Status: StatusProposed, Date: "2026-10-06T14:00:00+08:00", Drivers: []string{"REQ-04", "REQ-05"}, DependsOn: []string{"ADR-003", "ADR-004"},
			Alternatives: []Alternative{{"提交后进程内 channel 发布", "崩溃即丢，无法重放"}, {"handler 内直接 produce Kafka", "数据库与 Kafka 双写，任一侧失败都会不一致"}},
			Consequences: Consequences{Positive: []string{"事件与状态同事务，可重放和审计"}, Negative: []string{"relay 带来延迟，outbox 需要清理与积压监控"}}},
		{ID: "ADR-007", Title: "单部署单元，按模块开关灰度", Status: StatusProposed, Date: "2026-10-06T16:00:00+08:00", Drivers: []string{"REQ-01", "REQ-05"}, DependsOn: []string{"ADR-001", "ADR-005"},
			Alternatives: []Alternative{{"每个模块独立部署", "发布与运维成本回到微服务"}, {"只做部署级 canary", "整个进程一起切，无法隔离单个模块的新路径"}},
			Consequences: Consequences{Positive: []string{"爆炸半径小，回滚快"}, Negative: []string{"开关组合增加测试矩阵，旧开关会变成永久分支"}}},
	}}
}

// file: internal/adrindex/index_test.go
// tier: L1
// verify: go test ./internal/adrindex/ -count=1 -v
package adrindex

import "testing"

func hasCode(issues []Issue, want string) bool {
	for _, issue := range issues {
		if issue.Code == want {
			return true
		}
	}
	return false
}
func TestVolumeOneIndex(t *testing.T) {
	idx := VolumeOne()
	if issues := idx.Validate(); len(issues) != 0 {
		t.Fatalf("VolumeOne() has %d issue(s): %v", len(issues), issues)
	}
	want := map[string]string{"ADR-003": "ADR-002", "ADR-004": "ADR-003", "ADR-006": "ADR-004"}
	for _, e := range idx.Entries {
		if dep, ok := want[e.ID]; ok {
			found := false
			for _, got := range e.DependsOn {
				found = found || got == dep
			}
			if !found {
				t.Fatalf("%s must depend on %s, got %v", e.ID, dep, e.DependsOn)
			}
		}
	}
}
func TestValidateRules(t *testing.T) {
	tests := []struct {
		name   string
		mutate func(*Index)
		want   string
	}{
		{"invalid id", func(in *Index) { in.Entries[0].ID = "ADR-1" }, CodeInvalidID},
		{"duplicate id", func(in *Index) { in.Entries[1].ID = in.Entries[0].ID }, CodeDuplicateID},
		{"invalid status", func(in *Index) { in.Entries[0].Status = "done" }, CodeInvalidStatus},
		{"invalid date", func(in *Index) { in.Entries[0].Date = "2026-10-05" }, CodeInvalidDate},
		{"no driver", func(in *Index) { in.Entries[0].Drivers = nil }, CodeNoDriver},
		{"one alternative", func(in *Index) { in.Entries[0].Alternatives = in.Entries[0].Alternatives[:1] }, CodeNoAlternative},
		{"alternative without reason", func(in *Index) { in.Entries[0].Alternatives[0].Reason = "" }, CodeAlternativeNoReason},
		{"no negative consequence", func(in *Index) { in.Entries[0].Consequences.Negative = nil }, CodeNoConsequence},
		{"dangling dependency", func(in *Index) { in.Entries[1].DependsOn = append(in.Entries[1].DependsOn, "ADR-999") }, CodeDanglingDependency},
		{"dependency cycle", func(in *Index) { in.Entries[0].DependsOn = []string{"ADR-006"} }, CodeDependencyCycle},
		{"isolated adr", func(in *Index) {
			in.Entries = append(in.Entries, Entry{ID: "ADR-099", Title: "占位", Status: StatusAccepted,
				Date: "2026-10-09T00:00:00+08:00", Drivers: []string{"REQ-99"},
				Alternatives: []Alternative{{"A", "r"}, {"B", "r"}},
				Consequences: Consequences{Positive: []string{"p"}, Negative: []string{"n"}}})
		}, CodeIsolatedADR},
		{"superseded without target", func(in *Index) { in.Entries[0].Status = StatusSuperseded }, CodeSupersededMismatch},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			idx := VolumeOne()
			tt.mutate(&idx)
			if !hasCode(idx.Validate(), tt.want) {
				t.Fatalf("issues = %v, want %s", idx.Validate(), tt.want)
			}
		})
	}
}

$ go test ./internal/adrindex/ -count=1
ok  	archlab/internal/adrindex	0.478s
$ go test ./internal/adrindex/ -run TestValidateRules -v | grep -c '^    --- PASS'
12