《后端架构设计·架构基础与边界》3.3 聚合、事务边界与一致性边界

// file: internal/order/order.go
// tier: L1
// verify: go test -race ./internal/order/
package order

import "time"

type Status string

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

type Code string

const (
	CodeInvalidState    Code = "INVALID_STATE"
	CodeOutOfStock      Code = "OUT_OF_STOCK"
	CodePaymentFailed   Code = "PAYMENT_FAILED"
	CodeVersionConflict Code = "VERSION_CONFLICT"
)

type Error struct {
	Code Code
	Op   string
}

func (e *Error) Error() string { return string(e.Code) + ": " + e.Op }

type OrderItem struct {
	SKU            string
	Quantity       int
	UnitPriceCents int64
}

// items 与 totalCents 不导出：外部只能读，无法绕过总额不变式。
type Order struct {
	ID, CustomerID, Currency string
	status                   Status
	items                    []OrderItem
	totalCents               int64
	Version                  int64
	PaidPaymentID            string
	CreatedAt, UpdatedAt     time.Time
}

func New(id, customerID, currency string, items []OrderItem, now time.Time) (*Order, error) {
	if id == "" || customerID == "" || currency == "" || len(items) == 0 {
		return nil, &Error{Code: CodeInvalidState, Op: "order.New: missing field"}
	}
	o := &Order{ID: id, CustomerID: customerID, Currency: currency,
		status: StatusCreated, Version: 1, CreatedAt: now, UpdatedAt: now}
	var total int64
	for _, item := range items {
		if item.SKU == "" || item.Quantity <= 0 || item.UnitPriceCents < 0 {
			return nil, &Error{Code: CodeInvalidState, Op: "order.New: invalid " + item.SKU}
		}
		o.items = append(o.items, item)
		total += int64(item.Quantity) * item.UnitPriceCents
	}
	o.totalCents = total
	return o, nil
}

var allowed = map[Status][]Status{
	StatusCreated:           {StatusInventoryReserved, StatusCancelled},
	StatusInventoryReserved: {StatusPaid, StatusCancelled},
	StatusPaid:              {StatusFulfilled, StatusRefunded},
	StatusFulfilled:         {},
	StatusCancelled:         {},
	StatusRefunded:          {},
}

func (o *Order) TransitionTo(next Status, now time.Time) error {
	for _, candidate := range allowed[o.status] {
		if candidate == next {
			o.status = next
			o.Version++
			o.UpdatedAt = now
			return nil
		}
	}
	return &Error{Code: CodeInvalidState, Op: "order.Transition: " + string(o.status) + " -> " + string(next)}
}

func (o *Order) ensurePayable() error {
	if o.PaidPaymentID != "" {
		return &Error{Code: CodeInvalidState, Op: "order.Pay: duplicate " + o.PaidPaymentID}
	}
	if o.status != StatusInventoryReserved {
		return &Error{Code: CodeInvalidState, Op: "order.Pay: not reserved"}
	}
	return nil
}

func (o *Order) MarkPaid(paymentID string, now time.Time) error {
	if err := o.ensurePayable(); err != nil {
		return err
	}
	if paymentID == "" {
		return &Error{Code: CodePaymentFailed, Op: "order.Pay: empty payment id"}
	}
	o.PaidPaymentID = paymentID
	return o.TransitionTo(StatusPaid, now)
}

func (o *Order) Status() Status             { return o.status }
func (o *Order) TotalCents() int64          { return o.totalCents }
func (o *Order) Cancel(now time.Time) error { return o.TransitionTo(StatusCancelled, now) }

// file: internal/order/checkout.go
// tier: L1
// verify: go test -race ./internal/order/
package order

import (
	"context"
	"time"
)

type InventoryPort interface {
	Reserve(ctx context.Context, orderID, sku string, qty int) (reservationID string, err error)
	Release(ctx context.Context, reservationID string) error
}

type PaymentPort interface {
	Charge(ctx context.Context, orderID string, amountCents int64) (paymentID string, err error)
	Refund(ctx context.Context, paymentID string) error
}

// Checkout 是应用服务：跨聚合的顺序与补偿放在这里，Order 聚合不持有库存。
type Checkout struct {
	Inventory InventoryPort
	Payments  PaymentPort
}

func (c *Checkout) PlaceAndReserve(ctx context.Context, o *Order, now time.Time) ([]string, error) {
	var reservations []string
	for _, item := range o.items {
		id, err := c.Inventory.Reserve(ctx, o.ID, item.SKU, item.Quantity)
		if err != nil {
			c.releaseAll(ctx, reservations)
			_ = o.Cancel(now)
			return nil, &Error{Code: CodeOutOfStock, Op: "reserve " + item.SKU + ": " + err.Error()}
		}
		reservations = append(reservations, id)
	}
	if err := o.TransitionTo(StatusInventoryReserved, now); err != nil {
		c.releaseAll(ctx, reservations)
		return nil, err
	}
	return reservations, nil
}

func (c *Checkout) Pay(ctx context.Context, o *Order, reservations []string, now time.Time) error {
	if err := o.ensurePayable(); err != nil {
		return err
	}
	paymentID, err := c.Payments.Charge(ctx, o.ID, o.totalCents)
	if err != nil {
		// 只有明确拒绝才补偿；超时歧义交给卷二的对账，不在这里猜。
		c.releaseAll(ctx, reservations)
		_ = o.Cancel(now)
		return &Error{Code: CodePaymentFailed, Op: "charge: " + err.Error()}
	}
	return o.MarkPaid(paymentID, now)
}

func (c *Checkout) releaseAll(ctx context.Context, ids []string) {
	for i := len(ids) - 1; i >= 0; i-- {
		_ = c.Inventory.Release(ctx, ids[i])
	}
}

// file: internal/order/aggregate_test.go
// tier: L1
// verify: go test -race ./internal/order/ -v
package order

import (
	"context"
	"errors"
	"fmt"
	"testing"
	"time"
)

var testNow = time.Unix(1_700_000_000, 0)

func newTestOrder(t *testing.T) *Order {
	o, err := New("ord-1", "cus-1", "CNY", []OrderItem{
		{SKU: "sku-a", Quantity: 2, UnitPriceCents: 1999},
		{SKU: "sku-b", Quantity: 1, UnitPriceCents: 500},
	}, testNow)
	if err != nil {
		t.Fatal(err)
	}
	return o
}

func requireCode(t *testing.T, err error, want Code) {
	var domainErr *Error
	if !errors.As(err, &domainErr) || domainErr.Code != want {
		t.Fatalf("error = %v, want code %s", err, want)
	}
}

func TestAggregateInvariants(t *testing.T) {
	items := []OrderItem{
		{SKU: "sku-a", Quantity: 2, UnitPriceCents: 1999},
		{SKU: "sku-b", Quantity: 1, UnitPriceCents: 500},
	}
	o, err := New("ord-1", "cus-1", "CNY", items, testNow)
	if err != nil {
		t.Fatal(err)
	}
	if o.TotalCents() != 4498 {
		t.Fatalf("total = %d, want 4498", o.TotalCents())
	}
	items[0].Quantity = 100
	if o.TotalCents() != 4498 {
		t.Fatal("New aliased caller slice")
	}
	requireCode(t, o.TransitionTo(StatusPaid, testNow), CodeInvalidState)
	if o.Status() != StatusCreated {
		t.Fatalf("illegal transition mutated status to %s", o.Status())
	}
	if err := o.TransitionTo(StatusInventoryReserved, testNow); err != nil {
		t.Fatal(err)
	}
	if err := o.MarkPaid("pay-1", testNow); err != nil {
		t.Fatal(err)
	}
	version := o.Version
	requireCode(t, o.MarkPaid("pay-2", testNow), CodeInvalidState)
	if o.Version != version || o.PaidPaymentID != "pay-1" {
		t.Fatalf("duplicate payment mutated order: version=%d paid=%s", o.Version, o.PaidPaymentID)
	}
}

type fakeInventory struct {
	failSKU  string
	seq      int
	released []string
}

func (f *fakeInventory) Reserve(_ context.Context, _, sku string, _ int) (string, error) {
	if sku == f.failSKU {
		return "", errors.New("warehouse rejected")
	}
	f.seq++
	return fmt.Sprintf("res-%d", f.seq), nil
}

func (f *fakeInventory) Release(_ context.Context, id string) error {
	f.released = append(f.released, id)
	return nil
}

func TestPlaceAndReserveCompensatesPartialFailure(t *testing.T) {
	inventory := &fakeInventory{failSKU: "sku-b"}
	checkout := &Checkout{Inventory: inventory}
	o := newTestOrder(t)

	_, err := checkout.PlaceAndReserve(context.Background(), o, testNow)
	requireCode(t, err, CodeOutOfStock)
	if o.Status() != StatusCancelled || len(inventory.released) != 1 || inventory.released[0] != "res-1" {
		t.Fatalf("status=%s released=%v, want CANCELLED/[res-1]", o.Status(), inventory.released)
	}
}

=== RUN   TestAggregateInvariants
--- PASS: TestAggregateInvariants (0.00s)
=== RUN   TestPlaceAndReserveCompensatesPartialFailure
--- PASS: TestPlaceAndReserveCompensatesPartialFailure (0.00s)
PASS
ok  	archlab/internal/order	1.575s