重新梳理领域驱动设计（DDD）

flowchart LR
  subgraph Sales["销售上下文"]
    S["Order =<br/>结账后的购买意图"]
  end
  subgraph Logistics["物流上下文"]
    L["Order =<br/>带发货指令的可发货包裹"]
  end
  N["同样的 Order 可以有不同含义"]

  S -.-> N
  L -.-> N

  classDef context fill:#eef2ff,stroke:#6366f1,color:#312e81
  classDef note fill:#ffffff,stroke:#94a3b8,color:#334155,stroke-dasharray: 5 5
  class S,L context
  class N note

flowchart LR
  E1["🟧 已请求报价"] --> E2["🟧 已创建报价"] --> E3["🟧 已发送报价"]
  E3 --> C2["🟦 命令<br/>批准报价"] --> E4["🟧 已批准报价"] --> E5["🟧 已接受订单"]
  E3 --> C1["🟦 命令<br/>取消报价"] --> E6["🟧 已取消报价"]
  A1["🟪 聚合<br/>报价单"] -.触发事件的主体.-> E2
  R1["🟨 规则<br/>只有已批准的报价才能转换为订单"] -.约束.-> E5

  classDef event fill:#fdba74,stroke:#ea580c,color:#7c2d12
  classDef command fill:#bfdbfe,stroke:#2563eb,color:#1e3a8a
  classDef aggregate fill:#ddd6fe,stroke:#7c3aed,color:#4c1d95
  classDef rule fill:#fde68a,stroke:#ca8a04,color:#713f12
  class E1,E2,E3,E4,E5,E6 event
  class C1,C2 command
  class A1 aggregate
  class R1 rule

// ❌ 只是字符串
const email: string = "user@example.com";

// ✅ Value Object
class Email {
  constructor(private readonly value: string) {
    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
      throw new Error("无效的电子邮件地址");
    }
  }
  equals(other: Email): boolean {
    return this.value === other.value;
  }
  toString(): string {
    return this.value;
  }
}

class User {
  constructor(
    public readonly id: UserId,
    private name: UserName,
    private email: Email,
  ) {}

  changeEmail(newEmail: Email): void {
    this.email = newEmail;
  }

  equals(other: User): boolean {
    return this.id.equals(other.id);
  }
}

// 聚合根
class Order {
  private items: OrderItem[] = [];

  constructor(
    public readonly id: OrderId,
    private readonly userId: UserId,
  ) {}

  // 聚合内部的一致性由聚合根来守护。
  addItem(product: Product, quantity: number): void {
    if (this.items.length >= 100) {
      throw new Error("超出了单笔订单的条目上限");
    }
    this.items.push(new OrderItem(product.id, quantity, product.price));
  }

  totalPrice(): Money {
    return this.items.reduce(
      (sum, item) => sum.add(item.subtotal()),
      Money.zero(),
    );
  }
}

// 领域层：只定义接口。
interface OrderRepository {
  findById(id: OrderId): Promise<Order | null>;
  save(order: Order): Promise<void>;
}

// 基础设施层：实现放在外侧。
class PostgresOrderRepository implements OrderRepository {
  async findById(id: OrderId): Promise<Order | null> { /* ... */ }
  async save(order: Order): Promise<void> { /* ... */ }
}

// “电子邮件是否重复” 不是 User 单体能判断的。
class UserDuplicationChecker {
  constructor(private readonly userRepository: UserRepository) {}

  async exists(email: Email): Promise<boolean> {
    return (await this.userRepository.findByEmail(email)) !== null;
  }
}

flowchart TB
  Start["这段逻辑..."] --> Q1{"只是修改单个对象的状态吗？"}
  Q1 -- YES --> E["Entity 方法"]
  Q1 -- NO --> Q2{"需要跨多个聚合做判断吗？"}
  Q2 -- YES --> D["Domain Service"]
  Q2 -- NO --> Q3{"需要 repository 或外部服务吗？"}
  Q3 -- YES --> D
  Q3 -- NO --> Q4{"用动词表达比用名词更自然吗？"}
  Q4 -- YES --> D
  Q4 -- NO --> V["Entity / Value Object"]

  classDef question fill:#eef2ff,stroke:#6366f1,color:#312e81
  classDef answer fill:#ede9fe,stroke:#7c3aed,color:#4c1d95
  class Q1,Q2,Q3,Q4 question
  class E,D,V answer

class Order {
  private status: OrderStatus;
  private items: OrderItem[];

  // ✅ 自己保护自己的状态迁移
  cancel(): void {
    if (this.status === OrderStatus.SHIPPED) {
      throw new Error("已发货的订单不能取消");
    }
    this.status = OrderStatus.CANCELLED;
  }

  // ✅ 只根据自身数据计算的逻辑
  totalPrice(): Money {
    return this.items.reduce(
      (sum, item) => sum.add(item.subtotal()),
      Money.zero(),
    );
  }

  // ✅ 检查自己的不变量
  addItem(item: OrderItem): void {
    if (this.items.length >= 100) throw new Error("已超出上限");
    this.items.push(item);
  }
}

// ✅ 跨两个聚合的“转账”逻辑
class TransferService {
  transfer(from: Account, to: Account, amount: Money): void {
    from.withdraw(amount);
    to.deposit(amount);
    // “转账” 这个概念不属于任何一方账户
  }
}

// ✅ 需要 repository 的“重复检查”
class UserDuplicationChecker {
  constructor(private readonly userRepository: UserRepository) {}
  async exists(email: Email): Promise<boolean> {
    return (await this.userRepository.findByEmail(email)) !== null;
  }
}

// ❌ 不应该变成这样
class OrderService {
  cancel(order: Order): void {
    if (order.status === "SHIPPED") throw new Error(/* ... */);
    order.status = "CANCELLED";  // 通过 setter 改写
  }
  totalPrice(order: Order): Money { /* 遍历 items 计算总和 */ }
  addItem(order: Order, item: OrderItem): void { /* ... */ }
}
class Order {
  status: string;
  items: OrderItem[];
  // 只有 getter / setter ← 贫血领域模型
}

class OrderPlaced {
  constructor(
    public readonly orderId: OrderId,
    public readonly userId: UserId,
    public readonly occurredAt: Date,
  ) {}
}

flowchart TB
  P["Presentation 层<br/>UI / API"]
  A["Application 层<br/>用例"]
  D["Domain 层<br/>模型 / 业务规则<br/>主角"]
  I["Infrastructure 层<br/>DB / 外部 API"]

  P --> A --> D
  I --> D

  classDef layer fill:#eef2ff,stroke:#6366f1,color:#312e81
  classDef domain fill:#c7d2fe,stroke:#4338ca,color:#1e1b4b
  class P,A,I layer
  class D domain

// ✅ 好的 Controller：只负责转交
@Controller("orders")
class OrderController {
  constructor(private readonly placeOrder: PlaceOrderUseCase) {}

  @Post()
  async create(@Body() body: PlaceOrderRequest): Promise<OrderResponse> {
    // 1. 整理请求形状（转换成 DTO）
    const command = new PlaceOrderCommand(
      body.userId,
      body.items.map(i => ({ productId: i.productId, quantity: i.quantity })),
    );

    // 2. 委托给用例
    const result = await this.placeOrder.execute(command);

    // 3. 整理响应形状后返回
    return OrderResponse.from(result);
  }
}

// ✅ 好的 Application Service：只负责编排流程
class PlaceOrderUseCase {
  constructor(
    private readonly userRepository: UserRepository,
    private readonly productRepository: ProductRepository,
    private readonly orderRepository: OrderRepository,
    private readonly inventoryService: InventoryService,  // Domain Service
    private readonly transactionManager: TransactionManager,
    private readonly eventPublisher: EventPublisher,
  ) {}

  async execute(command: PlaceOrderCommand): Promise<OrderResult> {
    return this.transactionManager.run(async () => {
      // 1. 获取所需聚合
      const user = await this.userRepository.findById(command.userId);
      if (!user) throw new UserNotFoundError(command.userId);

      const products = await this.productRepository.findByIds(
        command.items.map(i => i.productId),
      );

      // 2. 把处理委托给领域（业务规则留在 Domain 内部）
      const order = Order.place(user, products, command.items);

      // 3. 调用领域服务（跨多个聚合的判断）
      await this.inventoryService.reserve(order);

      // 4. 持久化
      await this.orderRepository.save(order);

      // 5. 发布领域事件
      await this.eventPublisher.publishAll(order.pullEvents());

      return OrderResult.from(order);
    });
  }
}

// ❌ 反模式：业务规则泄漏到了 Application 层
class PlaceOrderUseCase {
  async execute(command: PlaceOrderCommand) {
    // ❌ 在这里判断库存 → 领域知识外泄
    if (product.stock < command.quantity) {
      throw new Error("库存不足");
    }
    // ❌ 在这里计算总金额 → 是 Order 的职责
    const total = command.items.reduce((s, i) => s + i.price * i.quantity, 0);
    // ❌ 在这里判断状态 → 是 Order 的职责
    if (user.status === "BLOCKED") throw new Error("账户已停用");

    await this.orderRepository.save({ /* ... */ });
  }
}

sequenceDiagram
  participant Browser
  participant Presentation as Presentation / OrderController
  participant Application as Application / PlaceOrderUseCase
  participant Domain as Domain / Order.place(...)
  participant Infrastructure as Infrastructure / Repository 实现

  Browser->>Presentation: POST /orders
  Presentation->>Application: 传递 PlaceOrderCommand
  Note over Application: 开始事务
  Application->>Infrastructure: userRepository.findById()
  Application->>Infrastructure: productRepository.findByIds()
  Infrastructure-->>Application: User / Product 聚合
  Application->>Domain: Order.place(user, products, items)
  activate Domain
  Domain->>Domain: 验证业务规则
  Domain->>Domain: 检查不变量
  Domain->>Domain: 生成 OrderPlaced 事件
  Domain-->>Application: Order 聚合与 OrderPlaced
  deactivate Domain
  Application->>Domain: inventoryService.reserve(order)
  Domain-->>Application: 库存预留结果
  Application->>Infrastructure: orderRepository.save(order)
  Application->>Infrastructure: eventPublisher.publishAll(...)
  Infrastructure-->>Application: 持久化完成
  Note over Application: 提交事务
  Application-->>Presentation: OrderResult
  Presentation-->>Browser: 201 Created

// Domain 层
class Order { /* 携带业务逻辑的聚合 */ }

// Application 层：输入 / 输出 DTO
class PlaceOrderCommand { /* 请求 DTO */ }
class OrderResult { /* 响应 DTO */ }

// Presentation 层：HTTP 类型
class PlaceOrderRequest { /* JSON schema */ }
class OrderResponse { /* 响应 JSON */ }

src/
├── controllers/
│   ├── user.controller.ts
│   ├── order.controller.ts
│   └── product.controller.ts
├── services/
│   ├── user.service.ts
│   ├── order.service.ts
│   └── product.service.ts
├── repositories/
│   ├── user.repository.ts
│   ├── order.repository.ts
│   └── product.repository.ts
└── entities/
    ├── user.entity.ts
    ├── order.entity.ts
    └── product.entity.ts

src/
├── contexts/                      ← 按 Bounded Context 组织
│   ├── ordering/                  ← 订单上下文
│   │   ├── domain/
│   │   │   ├── order.ts           (Entity / Aggregate Root)
│   │   │   ├── order-item.ts
│   │   │   ├── order-id.ts        (Value Object)
│   │   │   ├── order-status.ts
│   │   │   ├── order.repository.ts(仅 interface)
│   │   │   └── events/
│   │   │       └── order-placed.ts
│   │   ├── application/
│   │   │   ├── place-order.usecase.ts
│   │   │   └── cancel-order.usecase.ts
│   │   ├── infrastructure/
│   │   │   ├── postgres-order.repository.ts
│   │   │   └── stripe-payment.gateway.ts
│   │   └── presentation/
│   │       ├── order.controller.ts
│   │       └── dto/
│   │           ├── place-order.request.ts
│   │           └── order.response.ts
│   ├── catalog/                   ← 商品目录上下文
│   │   └── (相同结构)
│   └── shipping/                  ← 配送上下文
│       └── (相同结构)
├── shared-kernel/                 ← 所有上下文共享的 Value Object
│   ├── money.ts
│   ├── email.ts
│   └── user-id.ts
└── shared/                        ← 横切技术基础
    ├── logger.ts
    ├── transaction-manager.ts
    └── event-bus.ts

ordering/domain/
├── order/
│   ├── order.ts                   (聚合根)
│   ├── order-item.ts
│   ├── order-id.ts
│   ├── order-status.ts
│   ├── order.repository.ts
│   └── events/
│       ├── order-placed.ts
│       └── order-cancelled.ts
├── customer/
│   ├── customer.ts
│   └── customer.repository.ts
└── services/
    └── pricing.service.ts          (Domain Service)

monorepo/
├── apps/
│   ├── web/                       (Next.js 前端)
│   ├── api/                       (后端 API)
│   └── admin/                     (管理后台)
├── packages/
│   ├── ordering-context/          ← 打包后的 Bounded Context
│   ├── catalog-context/
│   ├── shipping-context/
│   └── shared-kernel/
└── package.json

[前端特有的关注点]
- 路由
- 页面状态（加载、错误、选中等）
- 表单校验（面向 UX）
- 动画
- 响应式重渲染

flowchart TB
  R["Pages / Routes 层<br/>Next.js 的 app/, pages/ 等"]
  C["Components 层<br/>UI 组件 / 视觉职责"]
  V["ViewModel / Hooks 层<br/>页面状态与用例调用"]
  A["Application 层<br/>用例 / API 客户端"]
  D["Domain 层<br/>前端侧最小领域模型"]

  R --> C --> V --> A --> D

  classDef layer fill:#eef2ff,stroke:#6366f1,color:#312e81
  classDef domain fill:#c7d2fe,stroke:#4338ca,color:#1e1b4b
  class R,C,V,A layer
  class D domain

// Domain 层：保留一层精简版的后端领域规则
class Order {
  constructor(
    public readonly id: string,
    public readonly status: OrderStatus,
    public readonly items: OrderItem[],
  ) {}

  // UI 中“能不能点取消按钮？”的判断集中在这里
  canCancel(): boolean {
    return this.status === "PENDING" || this.status === "CONFIRMED";
  }

  totalPrice(): number {
    return this.items.reduce((s, i) => s + i.price * i.quantity, 0);
  }
}

// Application 层：调用 API 的用例
class PlaceOrderUseCase {
  constructor(private readonly api: OrderApiClient) {}

  async execute(items: CartItem[]): Promise<Order> {
    const response = await this.api.placeOrder({ items });
    return Order.fromResponse(response);
  }
}

// ViewModel / Hooks 层：管理页面状态
function useOrderForm() {
  const [items, setItems] = useState<CartItem[]>([]);
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const placeOrder = useMemo(() => new PlaceOrderUseCase(orderApi), []);

  const submit = async () => {
    setIsSubmitting(true);
    try {
      await placeOrder.execute(items);
    } catch (e) {
      setError(formatError(e));
    } finally {
      setIsSubmitting(false);
    }
  };

  return { items, setItems, isSubmitting, error, submit };
}

// Components 层：只关注表现
function OrderForm() {
  const { items, isSubmitting, error, submit } = useOrderForm();
  return (
    <form onSubmit={(e) => { e.preventDefault(); submit(); }}>
      {/* JSX */}
    </form>
  );
}

flowchart TB
  Browser["浏览器"]
  BFF["BFF<br/>Next.js API Routes / Hono 等<br/>为页面优化的端点"]
  Ordering["订单服务"]
  Catalog["目录服务"]
  Inventory["库存服务"]
  Response["面向页面整形后的响应"]

  Browser --> BFF
  BFF --> Ordering
  BFF --> Catalog
  BFF --> Inventory
  Ordering --> BFF
  Catalog --> BFF
  Inventory --> BFF
  BFF --> Response --> Browser

  classDef layer fill:#eef2ff,stroke:#6366f1,color:#312e81
  classDef service fill:#e0e7ff,stroke:#4f46e5,color:#312e81
  classDef output fill:#ffffff,stroke:#94a3b8,color:#334155
  class Browser,BFF layer
  class Ordering,Catalog,Inventory service
  class Response output

App/
├── Domain/
│   ├── Entities/
│   │   ├── Recipe.swift
│   │   └── Ingredient.swift
│   ├── ValueObjects/
│   │   └── CookingTime.swift
│   ├── Repositories/
│   │   └── RecipeRepository.swift   (protocol / interface)
├── Application/
│   └── UseCases/
│       └── SearchRecipeUseCase.swift
├── Infrastructure/
│   ├── Repositories/
│   │   ├── CoreDataRecipeRepository.swift  (本地数据库)
│   │   └── ApiRecipeRepository.swift       (远程 API)
│   ├── Storage/
│   │   └── KeyValueStore.swift
│   └── Sync/
│       └── RecipeSyncService.swift
└── Presentation/
    ├── ViewModels/
    │   └── RecipeListViewModel.swift
    └── Views/
        └── RecipeListView.swift            (SwiftUI)

// Domain 层：抽象多个持久化目标
protocol RecipeRepository {
    func find(id: RecipeId) async throws -> Recipe?
    func save(_ recipe: Recipe) async throws
}

// Infrastructure 层：组合本地 + 远程
class HybridRecipeRepository: RecipeRepository {
    let local: CoreDataRecipeRepository
    let remote: ApiRecipeRepository

    func find(id: RecipeId) async throws -> Recipe? {
        // 即使离线也可以从本地读取
        if let cached = try await local.find(id: id) {
            return cached
        }
        let remote = try await remote.find(id: id)
        if let recipe = remote {
          try await local.save(recipe)  // 刷新缓存
        }
        return remote
    }
}

shared/
└── domain/                        ← Web 与 Mobile 共用
    ├── recipe.ts
    └── recipe.repository.ts
apps/
├── web/
│   └── infrastructure/
│       └── api-recipe.repository.ts
└── mobile/
    └── infrastructure/
        └── sqlite-recipe.repository.ts  (offline first)

// ✅ 更新设置页面，这样就够了
class UpdateSiteSettingsHandler {
  constructor(private readonly db: Database) {}

  async execute(input: UpdateSiteSettingsInput): Promise<void> {
    await this.db.siteSettings.update({
      where: { id: 1 },
      data: input,
    });
  }
}

src/contexts/
├── ordering/                ← 完整 DDD
│   ├── domain/
│   ├── application/
│   ├── infrastructure/
│   └── presentation/
├── inventory/               ← 完整 DDD
│   └── (同上)
├── catalog/                 ← 轻量 DDD（保留 Entity，Service 尽量少）
│   └── (简化版)
└── admin/                   ← 基于 CRUD
  ├── handlers/            (只放精简 handler)
    └── controllers/

// 写入通过聚合（严格）
class CancelOrderUseCase {
  async execute(orderId: OrderId): Promise<void> {
    const order = await this.orderRepository.findById(orderId);
    order.cancel();                    // 领域规则
    await this.orderRepository.save(order);
  }
}

// 只读查询可以直接用原生 SQL（针对页面优化）
class OrderListQuery {
  async findForAdmin(filter: AdminFilter): Promise<OrderListView[]> {
    return this.db.raw(`
      SELECT o.id, o.status, u.name AS user_name, p.name AS product_name, ...
      FROM orders o
      JOIN users u ON ...
      JOIN order_items oi ON ...
      WHERE ...
    `);
  }
}