《后端架构设计·架构基础与边界》6.1 订单数据该放什么存储：所有权与存储选型 ADR

// file: internal/order/order.go
// tier: L1
// verify: go test ./internal/contracttest/
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 Item struct {
	SKU            string
	Quantity       int
	UnitPriceCents int64
}

type Order struct {
	ID         string
	CustomerID string
	Status     Status
	Items      []Item
	TotalCents int64
	Currency   string
	Version    int
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

// Clone 隔离调用方与仓储内部状态；契约测试会验证切片没有被共享。
func (o Order) Clone() Order {
	o.Items = append([]Item(nil), o.Items...)
	return o
}

// file: internal/ports/order_repository.go
// tier: L1
// verify: go test ./internal/contracttest/
package ports

import (
	"context"
	"errors"

	"archlab/internal/order"
)

var (
	ErrNotFound = errors.New("order not found")
	ErrConflict = errors.New("order version conflict")
)

type OrderQuery struct {
	CustomerID string
	Status     order.Status
	Limit      int
}

// OrderRepository 是 orders/order_items 的唯一写入口。
// 其他上下文只能通过消息或查询接口读取，不能持有写连接。
type OrderRepository interface {
	Get(ctx context.Context, id string) (order.Order, error)
	List(ctx context.Context, q OrderQuery) ([]order.Order, error)
	Save(ctx context.Context, o order.Order, expectedVersion int) (order.Order, error)
}

// file: internal/adapters/memory/order_repo.go
// tier: L1
// verify: go test ./internal/contracttest/
package memory

import (
	"context"
	"fmt"
	"sort"
	"sync"

	"archlab/internal/order"
	"archlab/internal/ports"
)

type OrderRepo struct {
	mu     sync.RWMutex
	orders map[string]order.Order
}

func NewOrderRepo() *OrderRepo {
	return &OrderRepo{orders: make(map[string]order.Order)}
}

func (r *OrderRepo) Get(ctx context.Context, id string) (order.Order, error) {
	r.mu.RLock()
	defer r.mu.RUnlock()
	o, ok := r.orders[id]
	if !ok {
		return order.Order{}, fmt.Errorf("%w: %s", ports.ErrNotFound, id)
	}
	return o.Clone(), nil
}

func (r *OrderRepo) List(ctx context.Context, q ports.OrderQuery) ([]order.Order, error) {
	r.mu.RLock()
	defer r.mu.RUnlock()
	limit := q.Limit
	if limit <= 0 {
		limit = 50
	}
	if limit > 200 {
		limit = 200
	}
	out := make([]order.Order, 0, limit)
	for _, o := range r.orders {
		if q.CustomerID != "" && o.CustomerID != q.CustomerID {
			continue
		}
		if q.Status != "" && o.Status != q.Status {
			continue
		}
		out = append(out, o.Clone())
	}
	sort.Slice(out, func(i, j int) bool {
		if out[i].CreatedAt.Equal(out[j].CreatedAt) {
			return out[i].ID < out[j].ID
		}
		return out[i].CreatedAt.After(out[j].CreatedAt)
	})
	if len(out) > limit {
		out = out[:limit]
	}
	return out, nil
}

func (r *OrderRepo) Save(ctx context.Context, o order.Order, expectedVersion int) (order.Order, error) {
	r.mu.Lock()
	defer r.mu.Unlock()
	current, exists := r.orders[o.ID]
	if !exists {
		if expectedVersion != 0 {
			return order.Order{}, fmt.Errorf("%w: %s missing", ports.ErrNotFound, o.ID)
		}
		stored := o.Clone()
		stored.Version = 1
		r.orders[o.ID] = stored
		return stored.Clone(), nil
	}
	if current.Version != expectedVersion {
		return order.Order{}, fmt.Errorf("%w: %s at version %d, expected %d",
			ports.ErrConflict, o.ID, current.Version, expectedVersion)
	}
	stored := o.Clone()
	stored.Version = current.Version + 1
	r.orders[o.ID] = stored
	return stored.Clone(), nil
}

// file: internal/contracttest/order_repo_test.go
// tier: L1
// verify: go test ./internal/contracttest/
package contracttest

import (
	"context"
	"errors"
	"testing"
	"time"

	"archlab/internal/adapters/memory"
	"archlab/internal/order"
	"archlab/internal/ports"
)

func newOrder(id, customer string, createdAt time.Time) order.Order {
	return order.Order{
		ID: id, CustomerID: customer, Status: order.StatusCreated,
		Items: []order.Item{
			{SKU: "sku-1", Quantity: 2, UnitPriceCents: 500},
		},
		TotalCents: 1000, Currency: "CNY", CreatedAt: createdAt,
	}
}

func TestOrderRepositoryContract(t *testing.T) {
	ctx := context.Background()
	repo := memory.NewOrderRepo()
	t0 := time.Date(2026, 10, 8, 8, 0, 0, 0, time.UTC)

	t.Run("GetMissingReturnsNotFound", func(t *testing.T) {
		if _, err := repo.Get(ctx, "missing"); !errors.Is(err, ports.ErrNotFound) {
			t.Fatalf("err = %v, want ErrNotFound", err)
		}
	})

	saved, err := repo.Save(ctx, newOrder("o-1", "c-1", t0), 0)
	if err != nil || saved.Version != 1 {
		t.Fatalf("create: saved=%+v err=%v", saved, err)
	}

	t.Run("StaleVersionReturnsConflict", func(t *testing.T) {
		if _, err := repo.Save(ctx, newOrder("o-1", "c-1", t0), 99); !errors.Is(err, ports.ErrConflict) {
			t.Fatalf("err = %v, want ErrConflict", err)
		}
	})

	t.Run("ListFiltersCustomerStatusAndLimit", func(t *testing.T) {
		if _, err := repo.Save(ctx, newOrder("o-2", "c-1", t0.Add(time.Minute)), 0); err != nil {
			t.Fatal(err)
		}
		paid := newOrder("o-3", "c-2", t0.Add(2*time.Minute))
		paid.Status = order.StatusPaid
		if _, err := repo.Save(ctx, paid, 0); err != nil {
			t.Fatal(err)
		}
		got, err := repo.List(ctx, ports.OrderQuery{CustomerID: "c-1"})
		if err != nil {
			t.Fatal(err)
		}
		if len(got) != 2 || got[0].ID != "o-2" {
			t.Fatalf("customer filter: %+v", got)
		}
		got, err = repo.List(ctx, ports.OrderQuery{Status: order.StatusPaid, Limit: 1})
		if err != nil || len(got) != 1 || got[0].ID != "o-3" {
			t.Fatalf("status filter: %+v err=%v", got, err)
		}
	})

	t.Run("GetReturnsIsolatedCopy", func(t *testing.T) {
		got, err := repo.Get(ctx, "o-1")
		if err != nil {
			t.Fatal(err)
		}
		got.Items[0].Quantity = 99
		again, err := repo.Get(ctx, "o-1")
		if err != nil {
			t.Fatal(err)
		}
		if again.Items[0].Quantity != 2 {
			t.Fatalf("stored items mutated: %+v", again.Items)
		}
	})
}

$ gofmt -l .
$ go vet ./...
$ go test ./... -count=1 -v
=== RUN   TestOrderRepositoryContract
=== RUN   TestOrderRepositoryContract/GetMissingReturnsNotFound
=== RUN   TestOrderRepositoryContract/StaleVersionReturnsConflict
=== RUN   TestOrderRepositoryContract/ListFiltersCustomerStatusAndLimit
=== RUN   TestOrderRepositoryContract/GetReturnsIsolatedCopy
--- PASS: TestOrderRepositoryContract (0.00s)
PASS
ok  	archlab/internal/contracttest	0.247s