《后端架构设计·架构基础与边界》1.2 质量属性与无法回避的取舍

// file: internal/order/order.go
// tier: L1
// verify: go test ./internal/quality/ -run TestStateMachineInvariants
package order

import "fmt"

// 本节只保留断言需要的最小字段；完整聚合见 1.1。
type Status string

const (
	StatusCreated           Status = "CREATED"
	StatusInventoryReserved Status = "INVENTORY_RESERVED"
	StatusPaid              Status = "PAID"
	StatusFulfilled         Status = "FULFILLED"
	StatusCancelled         Status = "CANCELLED"
	StatusRefunded          Status = "REFUNDED"
)

type Order struct {
	ID      string
	Status  Status
	Version int64
}

type TransitionError struct {
	From Status
	To   Status
}

func (e *TransitionError) Error() string {
	return fmt.Sprintf("invalid transition: %s -> %s", e.From, e.To)
}

// allowed 用边列表表达，新增一条边只需加一行。
var allowed = [][2]Status{
	{StatusCreated, StatusInventoryReserved},
	{StatusCreated, StatusCancelled},
	{StatusInventoryReserved, StatusPaid},
	{StatusInventoryReserved, StatusCancelled},
	{StatusPaid, StatusFulfilled},
	{StatusPaid, StatusRefunded},
}

func CanTransition(from, to Status) bool {
	for _, edge := range allowed {
		if edge[0] == from && edge[1] == to {
			return true
		}
	}
	return false
}

func (o *Order) TransitionTo(next Status) error {
	if !CanTransition(o.Status, next) {
		return &TransitionError{From: o.Status, To: next}
	}
	o.Status = next
	o.Version++
	return nil
}

// file: internal/platform/idempotency/idempotency.go
// tier: L1
// verify: go test ./internal/quality/ -run TestIdempotencyReplayAndConflict
package idempotency

import (
	"errors"
	"sync"
)

var (
	ErrEmptyKey = errors.New("idempotency: key and fingerprint are required")
	ErrConflict = errors.New("idempotency: key reused with a different request")
)

type record struct {
	fingerprint string
	body        string
}

// Store 把“同 key + 同请求指纹”折叠成一次执行；失败不落库，允许重试。
type Store struct {
	mu   sync.Mutex
	seen map[string]record
}

func NewStore() *Store {
	return &Store{seen: make(map[string]record)}
}

// Do 返回 (结果, 是否命中重放, 错误)。并发同 key 时先落库者胜出。
func (s *Store) Do(key, fingerprint string, fn func() (string, error)) (string, bool, error) {
	if key == "" || fingerprint == "" {
		return "", false, ErrEmptyKey
	}
	s.mu.Lock()
	existing, found := s.seen[key]
	s.mu.Unlock()
	if found {
		if existing.fingerprint != fingerprint {
			return "", false, ErrConflict
		}
		return existing.body, true, nil
	}

	body, err := fn()
	if err != nil {
		return "", false, err
	}

	s.mu.Lock()
	defer s.mu.Unlock()
	if existing, found := s.seen[key]; found {
		if existing.fingerprint != fingerprint {
			return "", false, ErrConflict
		}
		return existing.body, true, nil
	}
	s.seen[key] = record{fingerprint: fingerprint, body: body}
	return body, false, nil
}

// file: internal/quality/quality_test.go
// tier: L1
// verify: go test ./internal/quality/ -v
package quality_test

import (
	"errors"
	"testing"

	"archlab/internal/order"
	"archlab/internal/platform/idempotency"
)

// 场景 1：状态机边与规格一致，终态无出边，非法流转不改聚合。
func TestStateMachineInvariants(t *testing.T) {
	legal := map[[2]order.Status]bool{
		{order.StatusCreated, order.StatusInventoryReserved}:   true,
		{order.StatusCreated, order.StatusCancelled}:           true,
		{order.StatusInventoryReserved, order.StatusPaid}:      true,
		{order.StatusInventoryReserved, order.StatusCancelled}: true,
		{order.StatusPaid, order.StatusFulfilled}:              true,
		{order.StatusPaid, order.StatusRefunded}:               true,
	}
	statuses := []order.Status{
		order.StatusCreated, order.StatusInventoryReserved, order.StatusPaid,
		order.StatusFulfilled, order.StatusCancelled, order.StatusRefunded,
	}
	terminal := map[order.Status]bool{
		order.StatusFulfilled: true, order.StatusCancelled: true, order.StatusRefunded: true,
	}

	for _, from := range statuses {
		exits := 0
		for _, to := range statuses {
			if got, want := order.CanTransition(from, to), legal[[2]order.Status{from, to}]; got != want {
				t.Errorf("CanTransition(%s, %s) = %v, want %v", from, to, got, want)
			}
			if order.CanTransition(from, to) {
				exits++
			}
		}
		if got, want := exits == 0, terminal[from]; got != want {
			t.Errorf("terminal(%s) = %v, want %v", from, got, want)
		}
	}

	o := &order.Order{ID: "ord-1", Status: order.StatusFulfilled, Version: 7}
	var transitionErr *order.TransitionError
	if !errors.As(o.TransitionTo(order.StatusPaid), &transitionErr) {
		t.Fatal("illegal transition did not return TransitionError")
	}
	if o.Status != order.StatusFulfilled || o.Version != 7 {
		t.Fatalf("illegal transition mutated aggregate: %s/%d", o.Status, o.Version)
	}
}

// 场景 2：同键同指纹只执行一次；同键不同指纹必须报冲突。
func TestIdempotencyReplayAndConflict(t *testing.T) {
	store := idempotency.NewStore()
	calls := 0
	create := func() (string, error) { calls++; return `{"id":"ord-1"}`, nil }

	first, replay, err := store.Do("key-1", "sha256:aaa", create)
	if err != nil || replay || calls != 1 {
		t.Fatalf("first = (%q, %v, %v), calls=%d", first, replay, err, calls)
	}
	second, replay, err := store.Do("key-1", "sha256:aaa", create)
	if err != nil || !replay || calls != 1 || second != first {
		t.Fatalf("replay = (%q, %v, %v), calls=%d", second, replay, err, calls)
	}
	if _, _, err := store.Do("key-1", "sha256:bbb", create); !errors.Is(err, idempotency.ErrConflict) {
		t.Fatalf("conflict = %v, want ErrConflict", err)
	}
	if _, _, err := store.Do("", "sha256:aaa", create); !errors.Is(err, idempotency.ErrEmptyKey) {
		t.Fatalf("empty key = %v, want ErrEmptyKey", err)
	}
}

ADR-<编号>：<一句话决策>
状态：提议 / 已接受 / 已废弃（被哪条取代）
背景：什么约束逼出了这个决策（2–3 句）
决策：选了什么，边界在哪
备选：A 方案与否决理由；B 方案与否决理由
后果：正面、负面、重新评估的触发条件

ADR-002：下单采用同步库存预留，而不是下单后异步补偿
状态：已接受（卷一）
背景：订单创建后用户立即进入支付；超卖的赔付与客诉成本高于短暂下单失败。
      当前没有成熟的对账任务，也没有跨服务的补偿事务框架。
决策：在创建订单的请求内同步调用库存预留；预留成功才把订单置为
      INVENTORY_RESERVED；预留超时 90 秒未支付则自动释放（示例参数）。
备选 A：事件驱动最终一致——订单先创建成功，异步预留，失败再取消订单。
      否决理由：用户可能已完成支付才发现无货，退款链路与客诉成本更高；
      异步补偿需要幂等消费与对账，卷一还不具备。
备选 B：预扣库存表 + 定时对账——先写本地预扣记录，后台对齐库存服务。
      否决理由：复杂度接近同步预留，却把不一致窗口留给了用户可见路径。
后果：正面——超卖在同步路径被挡住，状态与库存同成败；
      负面——库存服务故障时下单不可用，下单延迟受库存服务 P99 影响；
      重新评估触发条件——库存服务达到约定 SLA，且补偿对账连续运行一个季度无差异。