《后端架构设计·架构基础与边界》11.3 有状态服务的边界

// file: internal/stateinv/inventory.go
// tier: L1
// verify: go test ./internal/stateinv/
package stateinv

// DataClass 决定一份状态丢失后的代价，而不是它存在哪种数据库里。
type DataClass string

const (
	Source    DataClass = "SOURCE_OF_TRUTH"
	Derived   DataClass = "DERIVED"
	Cache     DataClass = "CACHE"
	Ephemeral DataClass = "EPHEMERAL"
)

// Store 是状态清单的一项。Source 必须有备份、恢复步骤和校验步骤；
// Derived/Cache 必须能说清从哪个 Source 重建；Ephemeral 必须明确丢失无影响。
type Store struct {
	Name           string
	Kind           string
	Class          DataClass
	Owner          string
	Backup         string
	RestoreStep    string
	VerifyStep     string
	RTOMinutes     int
	RPOMinutes     int
	RebuildFrom    string
	RebuildStep    string
	RebuildMinutes int
	LossImpact     string
}

type Inventory struct {
	Stores []Store
}

type Finding struct {
	Code    string
	Subject string
	Detail  string
}

// Validate 检查状态清单是否自洽：无主、来源无恢复、派生无重建、
// 本地盘承载持久状态、临时状态丢失有影响。
func (inv Inventory) Validate() []Finding {
	var out []Finding
	seen := make(map[string]bool, 8)
	add := func(code, subject, detail string) {
		key := code + "\x00" + subject
		if !seen[key] {
			seen[key] = true
			out = append(out, Finding{Code: code, Subject: subject, Detail: detail})
		}
	}

	byName := make(map[string]Store, len(inv.Stores))
	for _, s := range inv.Stores {
		byName[s.Name] = s
	}
	for _, s := range inv.Stores {
		if s.Owner == "" {
			add("UNOWNED_STORE", s.Name, "no owning team")
		}
		// 本地盘只能放临时数据；持久状态放本地盘就无法随实例替换。
		if s.Kind == "local-disk" && s.Class != Ephemeral {
			add("LOCAL_DISK_STATE", s.Name, "persistent state on local disk")
		}
		switch s.Class {
		case Source:
			if s.Backup == "" {
				add("SOURCE_WITHOUT_BACKUP", s.Name, "no backup policy")
			}
			if s.RestoreStep == "" {
				add("SOURCE_WITHOUT_RESTORE", s.Name, "no restore procedure")
			}
			if s.VerifyStep == "" {
				add("SOURCE_WITHOUT_VERIFY", s.Name, "no post-restore check")
			}
			if s.RTOMinutes <= 0 {
				add("SOURCE_WITHOUT_RTO", s.Name, "no recovery time target")
			}
		case Derived, Cache:
			if s.RebuildFrom == "" || s.RebuildStep == "" || s.RebuildMinutes <= 0 {
				add("DERIVED_WITHOUT_REBUILD", s.Name, "no rebuild source or step")
				continue
			}
			src, ok := byName[s.RebuildFrom]
			if !ok {
				add("UNKNOWN_REBUILD_SOURCE", s.Name, s.RebuildFrom)
			} else if src.Class != Source {
				add("REBUILD_NOT_FROM_SOURCE", s.Name, s.RebuildFrom+" is not SOURCE_OF_TRUTH")
			}
		case Ephemeral:
			if s.LossImpact != "none" {
				add("EPHEMERAL_STATE_LOSS", s.Name, s.LossImpact)
			}
		}
	}
	return out
}

// RecoveryMinutes 返回该状态丢失后的目标恢复时长：Source 用 RTO，
// 派生状态用重建时长，临时状态为 0。未知名字返回 -1。
func (inv Inventory) RecoveryMinutes(name string) int {
	for _, s := range inv.Stores {
		if s.Name != name {
			continue
		}
		switch s.Class {
		case Source:
			return s.RTOMinutes
		case Derived, Cache:
			return s.RebuildMinutes
		default:
			return 0
		}
	}
	return -1
}

// Migration 描述一次 schema 变更。破坏性变更必须走扩展-收缩，
// 不可逆变更必须至少保留回滚路径，否则发布就变成单向门。
type Migration struct {
	ID             string
	Destructive    bool
	ExpandContract bool
	Reversible     bool
}

func CheckMigrations(ms []Migration) []Finding {
	var out []Finding
	for _, m := range ms {
		if m.Destructive && !m.ExpandContract {
			out = append(out, Finding{Code: "DESTRUCTIVE_MIGRATION", Subject: m.ID, Detail: "requires expand-contract"})
		}
		if !m.Reversible && !m.ExpandContract {
			out = append(out, Finding{Code: "NO_ROLLBACK_PATH", Subject: m.ID})
		}
	}
	return out
}

// file: internal/stateinv/inventory_test.go
// tier: L1
// verify: go test ./internal/stateinv/
package stateinv

import "testing"

// baseline 是 arch-lab 在 2026-10 的状态清单：三个事实来源、一个缓存、
// 一个可重放事件日志、一个只放临时文件的本地盘。
func baseline() Inventory {
	return Inventory{Stores: []Store{
		{Name: "orders-db", Kind: "postgres", Class: Source, Owner: "team-order", Backup: "continuous WAL archive", RestoreStep: "PITR to timestamp", VerifyStep: "row count + last order id", RTOMinutes: 90, RPOMinutes: 5},
		{Name: "inventory-db", Kind: "postgres", Class: Source, Owner: "team-inventory", Backup: "continuous WAL archive", RestoreStep: "PITR to timestamp", VerifyStep: "reservation sum per SKU", RTOMinutes: 90, RPOMinutes: 5},
		{Name: "catalog-db", Kind: "postgres", Class: Source, Owner: "team-catalog", Backup: "nightly snapshot", RestoreStep: "restore latest snapshot", VerifyStep: "checksum + SKU count", RTOMinutes: 15, RPOMinutes: 1440},
		{Name: "idempotency-redis", Kind: "redis", Class: Cache, Owner: "team-order", RebuildFrom: "orders-db", RebuildStep: "reload keys from idempotency_keys", RebuildMinutes: 2},
		{Name: "kafka-events", Kind: "kafka", Class: Derived, Owner: "team-platform", RebuildFrom: "orders-db", RebuildStep: "replay outbox with original offsets", RebuildMinutes: 30},
		{Name: "order-api-tmp", Kind: "local-disk", Class: Ephemeral, Owner: "team-order", LossImpact: "none"},
	}}
}

func TestBaselineInventoryIsRecoverable(t *testing.T) {
	inv := baseline()
	findings := inv.Validate()
	sources := 0
	for _, s := range inv.Stores {
		if s.Class == Source {
			sources++
		}
	}
	t.Logf("stores=%d sources=%d findings=%d", len(inv.Stores), sources, len(findings))
	if len(findings) != 0 {
		t.Fatalf("baseline should be recoverable, got %v", findings)
	}
}

func TestRecoveryMinutesMatchClass(t *testing.T) {
	inv := baseline()
	cases := map[string]int{
		"orders-db":         90,
		"idempotency-redis": 2,
		"kafka-events":      30,
		"order-api-tmp":     0,
		"missing":           -1,
	}
	for name, want := range cases {
		if got := inv.RecoveryMinutes(name); got != want {
			t.Fatalf("%s: want %d, got %d", name, want, got)
		}
	}
}

func TestValidateCatchesStateDrift(t *testing.T) {
	cases := []struct {
		name   string
		mutate func(*Inventory)
		code   string
	}{
		{"unowned store", func(inv *Inventory) {
			inv.Stores[storeIndex(inv, "catalog-db")].Owner = ""
		}, "UNOWNED_STORE"},
		{"source without backup", func(inv *Inventory) {
			inv.Stores[storeIndex(inv, "orders-db")].Backup = ""
		}, "SOURCE_WITHOUT_BACKUP"},
		{"derived without rebuild", func(inv *Inventory) {
			inv.Stores[storeIndex(inv, "kafka-events")].RebuildFrom = ""
		}, "DERIVED_WITHOUT_REBUILD"},
		{"persistent local disk", func(inv *Inventory) {
			inv.Stores[storeIndex(inv, "order-api-tmp")].Class = Cache
		}, "LOCAL_DISK_STATE"},
		{"ephemeral loss has impact", func(inv *Inventory) {
			inv.Stores[storeIndex(inv, "order-api-tmp")].LossImpact = "pending callback lost"
		}, "EPHEMERAL_STATE_LOSS"},
	}
	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			inv := baseline()
			tc.mutate(&inv)
			if !hasFinding(inv.Validate(), tc.code) {
				t.Fatalf("want %s, got %v", tc.code, inv.Validate())
			}
		})
	}
}

func TestMigrationGate(t *testing.T) {
	cases := []struct {
		name string
		m    Migration
		code string
	}{
		{"destructive without expand-contract", Migration{ID: "0042", Destructive: true, Reversible: false}, "DESTRUCTIVE_MIGRATION"},
		{"irreversible without rollback", Migration{ID: "0043", Reversible: false}, "NO_ROLLBACK_PATH"},
		{"expand-contract destructive", Migration{ID: "0044", Destructive: true, ExpandContract: true, Reversible: false}, ""},
	}
	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			findings := CheckMigrations([]Migration{tc.m})
			if tc.code == "" {
				if len(findings) != 0 {
					t.Fatalf("want clean, got %v", findings)
				}
				return
			}
			if !hasFinding(findings, tc.code) {
				t.Fatalf("want %s, got %v", tc.code, findings)
			}
		})
	}
}

func storeIndex(inv *Inventory, name string) int {
	for i := range inv.Stores {
		if inv.Stores[i].Name == name {
			return i
		}
	}
	panic(name)
}

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

$ go test ./internal/stateinv/ -run 'TestBaselineInventoryIsRecoverable|TestRecoveryMinutesMatchClass' -v
=== RUN   TestBaselineInventoryIsRecoverable
    inventory_test.go:30: stores=6 sources=3 findings=0
--- PASS: TestBaselineInventoryIsRecoverable (0.00s)
=== RUN   TestRecoveryMinutesMatchClass
--- PASS: TestRecoveryMinutesMatchClass (0.00s)
PASS
ok  	archlab/internal/stateinv	0.254s

$ go test -count=1 ./...
ok  	archlab/internal/stateinv	0.249s