《后端架构设计·演进与治理》1.3 订单域的一次拆分演练：边界、共享数据与回退

// file: internal/platform/split/rehearsal.go
// tier: L1
// verify: go test ./internal/platform/split/ -count=1
package split

import (
	"errors"
	"fmt"
	"sync"
)

// Status is the arch-lab order state machine.
type Status string

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

var (
	ErrOutOfStock            = errors.New("split: out of stock")
	ErrDependencyUnavailable = errors.New("split: inventory dependency unavailable")
	ErrRollbackBlocked       = errors.New("split: rollback blocked")
)

// Stock is the inventory table. Reserve is idempotent per order id.
type Stock struct {
	mu        sync.Mutex
	available map[string]int
	reserved  map[string]bool
}

// NewStock copies initial stock and rejects negative quantities.
func NewStock(initial map[string]int) (*Stock, error) {
	s := &Stock{available: make(map[string]int, len(initial)), reserved: make(map[string]bool)}
	for sku, qty := range initial {
		if sku == "" || qty < 0 {
			return nil, fmt.Errorf("stock: invalid sku or quantity %q", sku)
		}
		s.available[sku] = qty
	}
	return s, nil
}

// Available returns current stock for sku.
func (s *Stock) Available(sku string) int {
	s.mu.Lock()
	defer s.mu.Unlock()
	return s.available[sku]
}

// Reserve decrements stock once per order and returns a deterministic id.
func (s *Stock) Reserve(orderID, sku string, qty int) (string, error) {
	if orderID == "" || sku == "" || qty <= 0 {
		return "", fmt.Errorf("stock: invalid reservation")
	}
	s.mu.Lock()
	defer s.mu.Unlock()
	if s.reserved[orderID] {
		return "res-" + orderID, nil
	}
	if s.available[sku] < qty {
		return "", ErrOutOfStock
	}
	s.available[sku] -= qty
	s.reserved[orderID] = true
	return "res-" + orderID, nil
}

// Order is the public order aggregate used in the rehearsal.
type Order struct {
	ID            string
	SKU           string
	Qty           int
	Status        Status
	ReservationID string
}

// Mode selects the deployment shape under test.
type Mode string

const (
	ModeMonolith   Mode = "monolith"
	ModeSplitSync  Mode = "split_sync"
	ModeSplitEvent Mode = "split_event"
)

func (m Mode) valid() bool {
	return m == ModeMonolith || m == ModeSplitSync || m == ModeSplitEvent
}

// Event is an outbox/inbox message.
type Event struct {
	Type          string
	OrderID       string
	SKU           string
	Qty           int
	ReservationID string
}

const (
	EventOrderCreated      = "order.created"
	EventInventoryReserved = "inventory.reserved"
	EventInventoryRejected = "inventory.rejected"
)

// Harness runs the same scenarios under three deployment shapes.
type Harness struct {
	mu            sync.Mutex
	mode          Mode
	stock         *Stock
	orders        map[string]*Order
	outbox        []Event
	brokerDown    bool
	inventoryDown bool
}

// NewHarness validates the mode and stock dependency.
func NewHarness(mode Mode, stock *Stock) (*Harness, error) {
	if stock == nil || !mode.valid() {
		return nil, fmt.Errorf("split: invalid harness")
	}
	return &Harness{mode: mode, stock: stock, orders: make(map[string]*Order)}, nil
}

// PlaceOrder is idempotent per order id. In monolith mode a failed reservation
// leaves no row; in split modes a failed remote step leaves CREATED.
func (h *Harness) PlaceOrder(id, sku string, qty int) (Order, error) {
	h.mu.Lock()
	defer h.mu.Unlock()
	if id == "" || sku == "" || qty <= 0 {
		return Order{}, fmt.Errorf("split: invalid order")
	}
	if o, ok := h.orders[id]; ok {
		if h.mode == ModeSplitSync && o.Status == StatusCreated {
			if err := h.reserveLocked(o); err != nil {
				return *o, err
			}
		}
		return *o, nil
	}
	o := &Order{ID: id, SKU: sku, Qty: qty, Status: StatusCreated}
	h.orders[id] = o
	switch h.mode {
	case ModeMonolith:
		if err := h.reserveLocked(o); err != nil {
			delete(h.orders, id)
			return Order{}, err
		}
	case ModeSplitSync:
		if err := h.reserveLocked(o); err != nil {
			return *o, err
		}
	case ModeSplitEvent:
		h.outbox = append(h.outbox, Event{Type: EventOrderCreated, OrderID: id, SKU: sku, Qty: qty})
	}
	return *o, nil
}

func (h *Harness) reserveLocked(o *Order) error {
	if h.inventoryDown {
		return ErrDependencyUnavailable
	}
	id, err := h.stock.Reserve(o.ID, o.SKU, o.Qty)
	if errors.Is(err, ErrOutOfStock) {
		o.Status = StatusCancelled
		return err
	}
	if err != nil {
		return err
	}
	o.Status, o.ReservationID = StatusInventoryReserved, id
	return nil
}

// DeliverOutbox moves order.created events to the inventory consumer. A down
// broker keeps them queued; a duplicate delivery sees a non-CREATED status
// and is ignored. At-least-once delivery plus a status guard is idempotent.
func (h *Harness) DeliverOutbox() int {
	h.mu.Lock()
	defer h.mu.Unlock()
	if h.brokerDown {
		return 0
	}
	delivered := 0
	next := h.outbox[:0]
	for _, ev := range h.outbox {
		o := h.orders[ev.OrderID]
		if o == nil || o.Status != StatusCreated {
			delivered++
			continue
		}
		if h.inventoryDown {
			next = append(next, ev)
			continue
		}
		id, err := h.stock.Reserve(ev.OrderID, ev.SKU, ev.Qty)
		switch {
		case err == nil:
			o.Status, o.ReservationID = StatusInventoryReserved, id
		case errors.Is(err, ErrOutOfStock):
			o.Status = StatusCancelled
		default:
			next = append(next, ev)
			continue
		}
		delivered++
	}
	h.outbox = next
	return delivered
}

// SwitchMode is the rollback switch. Returning to the monolith is blocked
// while events are undelivered or orders are still CREATED.
func (h *Harness) SwitchMode(next Mode) error {
	h.mu.Lock()
	defer h.mu.Unlock()
	if !next.valid() {
		return fmt.Errorf("split: unknown mode %q", next)
	}
	if next == ModeMonolith && h.mode != ModeMonolith {
		if len(h.outbox) > 0 {
			return fmt.Errorf("%w: %d undelivered events", ErrRollbackBlocked, len(h.outbox))
		}
		for _, o := range h.orders {
			if o.Status == StatusCreated {
				return fmt.Errorf("%w: order %s still CREATED", ErrRollbackBlocked, o.ID)
			}
		}
	}
	h.mode = next
	return nil
}

// Order returns a copy of one order.
func (h *Harness) Order(id string) (Order, bool) {
	h.mu.Lock()
	defer h.mu.Unlock()
	o, ok := h.orders[id]
	if !ok {
		return Order{}, false
	}
	return *o, true
}

// Fail injects broker and inventory outages.
func (h *Harness) Fail(broker, inventory bool) {
	h.mu.Lock()
	defer h.mu.Unlock()
	h.brokerDown, h.inventoryDown = broker, inventory
}

// file: internal/platform/split/rehearsal_test.go
// tier: L1
// verify: go test ./internal/platform/split/ -count=1
package split

import "testing"

func newHarness(t *testing.T, mode Mode, stock map[string]int) (*Harness, *Stock) {
	t.Helper()
	s, err := NewStock(stock)
	if err != nil {
		t.Fatalf("NewStock: %v", err)
	}
	h, err := NewHarness(mode, s)
	if err != nil {
		t.Fatalf("NewHarness: %v", err)
	}
	return h, s
}

func TestEventDelivery(t *testing.T) {
	h, stock := newHarness(t, ModeSplitEvent, map[string]int{"sku": 1})
	h.Fail(true, false)
	o, err := h.PlaceOrder("o1", "sku", 1)
	if err != nil || o.Status != StatusCreated {
		t.Fatalf("place: err=%v status=%s", err, o.Status)
	}
	if got := h.DeliverOutbox(); got != 0 {
		t.Fatalf("delivered=%d while broker down", got)
	}
	h.Fail(false, false)
	if got := h.DeliverOutbox(); got != 1 {
		t.Fatalf("delivered=%d, want 1", got)
	}
	if id, err := stock.Reserve("o1", "sku", 1); err != nil || id != "res-o1" {
		t.Fatalf("idempotent reserve id=%s err=%v", id, err)
	}
	o, _ = h.Order("o1")
	t.Logf("status=%s reservation=%s stock=%d", o.Status, o.ReservationID, stock.Available("sku"))
	if o.Status != StatusInventoryReserved || stock.Available("sku") != 0 {
		t.Fatalf("status=%s stock=%d", o.Status, stock.Available("sku"))
	}
}

$ cd .local/checks/be-arch-gov-ch01
$ gofmt -l .
$ go vet ./...
$ go test ./internal/platform/split/ -run '^(TestMonolithAtomicity|TestSplitSyncFailureAndRetry|TestEventDelivery|TestEventRejection|TestRollbackSwitch)$' -count=1 -v
=== RUN   TestMonolithAtomicity
    rehearsal_test.go:36: status=INVENTORY_RESERVED stock=0
--- PASS: TestMonolithAtomicity (0.00s)
=== RUN   TestSplitSyncFailureAndRetry
    rehearsal_test.go:57: retry status=INVENTORY_RESERVED reservation=res-o1 stock=0
--- PASS: TestSplitSyncFailureAndRetry (0.00s)
=== RUN   TestEventDelivery
    rehearsal_test.go:81: status=INVENTORY_RESERVED reservation=res-o1 stock=0
--- PASS: TestEventDelivery (0.00s)
=== RUN   TestEventRejection
    rehearsal_test.go:94: status=CANCELLED stock=0
--- PASS: TestEventRejection (0.00s)
=== RUN   TestRollbackSwitch
    rehearsal_test.go:118: order=o2 status=INVENTORY_RESERVED stock=0
--- PASS: TestRollbackSwitch (0.00s)
PASS
ok  	archlab/internal/platform/split	0.261s