@gravito/satellite-commerce 0.1.0

package/src/Application/UseCases/DeductInventory.ts

@@ -0,0 +1,86 @@
+/**
+ * 扣減庫存 Use Case
+ *
+ * 當支付成功時執行此 Use Case：
+ * 1. 驗證訂單存在且狀態為 PAID
+ * 2. 呼叫 Flash-Sale Satellite 扣減庫存
+ * 3. 更新訂單狀態為 CONFIRMED
+ * 4. 發送 OrderConfirmed 事件
+ */
+
+import type { PlanetCore } from '@gravito/core'
+import { DeductInventoryRequest, type OrderStatusTransition } from '../../Domain/Models'
+
+export interface DeductInventoryResponse {
+  success: boolean
+  orderId: string
+  message: string
+  newStatus: string
+}
+
+/**
+ * DeductInventory Use Case
+ *
+ * 這是 Commerce ← Payment 流程的核心
+ * 當支付服務通知支付成功時，此 Use Case 執行庫存扣減
+ */
+export class DeductInventory {
+  constructor(private core: PlanetCore) {}
+
+  /**
+   * 執行 Use Case
+   *
+   * @param orderId - 訂單 ID
+   * @param productId - 商品 ID
+   * @param quantity - 扣減數量
+   */
+  async execute(
+    orderId: string,
+    productId: string,
+    quantity: number
+  ): Promise<DeductInventoryResponse> {
+    // 1. 驗證請求
+    const request = new DeductInventoryRequest(orderId, productId, quantity)
+    const validationErrors = request.validate()
+
+    if (validationErrors.length > 0) {
+      throw new Error(`Validation failed: ${validationErrors.join(', ')}`)
+    }
+
+    this.core.logger.info(`[Commerce] Starting inventory deduction for order ${orderId}`)
+
+    // 2. TODO: 查詢訂單驗證狀態為 PAID
+    // const order = await this.orderRepository.findById(orderId)
+    // if (!order) {
+    //   throw new Error(`Order not found: ${orderId}`)
+    // }
+    // if (order.status !== OrderStatus.PAID) {
+    //   throw new Error(`Order not in PAID status: ${order.status}`)
+    // }
+
+    // 3. TODO: 呼叫 Flash-Sale Satellite 扣減庫存
+    // const productService = this.core.container.make('product.service')
+    // await productService.deductStock(productId, quantity)
+
+    // 4. TODO: 發送訂單狀態轉移事件
+    // const transition: OrderStatusTransition = {
+    //   orderId,
+    //   fromStatus: OrderStatus.PAID,
+    //   toStatus: OrderStatus.CONFIRMED,
+    //   timestamp: new Date(),
+    // }
+    // this.core.events.dispatch(new OrderStatusChanged(transition))
+
+    // 5. TODO: 更新訂單狀態
+    // await this.orderRepository.updateStatus(orderId, OrderStatus.CONFIRMED)
+
+    this.core.logger.info(`[Commerce] Inventory deducted for order ${orderId}`)
+
+    return {
+      success: true,
+      orderId,
+      message: 'Inventory deducted successfully',
+      newStatus: 'CONFIRMED',
+    }
+  }
+}

package/src/Application/UseCases/PlaceOrder.ts

@@ -0,0 +1,122 @@
+import { DB } from '@gravito/atlas'
+import type { PlanetCore } from '@gravito/core'
+import { UseCase } from '@gravito/enterprise'
+import type { CacheManager } from '@gravito/stasis'
+import { LineItem, Order } from '../../Domain/Entities/Order'
+import { AdjustmentCalculator } from '../Services/AdjustmentCalculator'
+import { ProductResolver } from '../Services/ProductResolver'
+
+export interface PlaceOrderInput {
+  memberId: string | null
+  idempotencyKey?: string
+  items: {
+    variantId: string
+    quantity: number
+  }[]
+}
+
+export class PlaceOrder extends UseCase<PlaceOrderInput, any> {
+  constructor(private core: PlanetCore) {
+    super()
+  }
+
+  async execute(input: PlaceOrderInput): Promise<any> {
+    const adjCalculator = new AdjustmentCalculator(this.core)
+    const mode = process.env.COMMERCE_MODE || 'standard'
+    const useCache = mode === 'sport'
+
+    const cache = this.core.container.make<CacheManager>('cache')
+    const productResolver = new ProductResolver(cache)
+
+    return await DB.transaction(async (db) => {
+      const order = Order.create(crypto.randomUUID(), input.memberId)
+
+      for (const reqItem of input.items) {
+        const variantInfo = await productResolver.resolve(reqItem.variantId, useCache)
+
+        const variant = (await db
+          .table('product_variants')
+          .where('id', reqItem.variantId)
+          .select('stock', 'version', 'sku', 'price')
+          .first()) as any
+
+        if (!variant) {
+          throw new Error(`Variant ${reqItem.variantId} not found`)
+        }
+        if (Number(variant.stock) < reqItem.quantity) {
+          throw new Error('Insufficient stock')
+        }
+
+        const affectedRows = await db
+          .table('product_variants')
+          .where('id', reqItem.variantId)
+          .where('version', variant.version)
+          .update({
+            stock: Number(variant.stock) - reqItem.quantity,
+            version: Number(variant.version) + 1,
+            updated_at: new Date(),
+          })
+
+        if (affectedRows === 0) {
+          throw new Error('Concurrency conflict: Please try again')
+        }
+
+        const lineItem = new LineItem(crypto.randomUUID(), {
+          variantId: variantInfo.id,
+          sku: variantInfo.sku,
+          name: variantInfo.name,
+          unitPrice: variantInfo.price,
+          quantity: reqItem.quantity,
+          totalPrice: variantInfo.price * reqItem.quantity,
+        })
+        order.addItem(lineItem)
+      }
+
+      await adjCalculator.calculate(order)
+
+      await db.table('orders').insert({
+        id: order.id,
+        member_id: order.memberId,
+        idempotency_key: input.idempotencyKey,
+        status: order.status,
+        subtotal_amount: order.subtotalAmount,
+        adjustment_amount: order.adjustmentAmount,
+        total_amount: order.totalAmount,
+        created_at: order.createdAt,
+      })
+
+      for (const item of order.items) {
+        await db.table('order_items').insert({
+          id: item.id,
+          order_id: order.id,
+          variant_id: item.props.variantId,
+          sku: item.props.sku,
+          name: item.props.name,
+          unit_price: item.props.unitPrice,
+          quantity: item.props.quantity,
+          total_price: item.props.totalPrice,
+        })
+      }
+
+      for (const adj of order.adjustments) {
+        await db.table('order_adjustments').insert({
+          id: adj.id,
+          order_id: order.id,
+          label: adj.props.label,
+          amount: adj.props.amount,
+          source_type: adj.props.sourceType,
+          source_id: adj.props.sourceId,
+        })
+      }
+
+      await this.core.hooks.doAction('commerce:order-placed', { orderId: order.id })
+
+      return {
+        orderId: order.id,
+        status: order.status,
+        total: order.totalAmount,
+        adjustments: order.adjustments.map((a) => a.props.label),
+      }
+    })
+  }
+}

package/src/CommerceServiceProvider.ts

@@ -0,0 +1,59 @@
+/**
+ * Commerce Service Provider
+ *
+ * 註冊訂單管理系統的所有服務與事件監聽
+ */
+
+import type { Container, PlanetCore } from '@gravito/core'
+import { ServiceProvider } from '@gravito/core'
+
+/**
+ * CommerceServiceProvider
+ *
+ * 負責：
+ * 1. 訂單生命週期管理
+ * 2. 庫存扣減協調
+ * 3. 跨 Satellite 事件通訊
+ */
+export class CommerceServiceProvider extends ServiceProvider {
+  /**
+   * 註冊階段
+   */
+  register(container: Container): void {
+    // TODO: 當 Repository 實現時解開註解
+    // container.singleton('order.repository', () => {
+    //   return new AtlasOrderRepository()
+    // })
+    // TODO: 註冊 Use Cases
+    // container.bind('commerce.usecase.deductInventory', (c) => {
+    //   return new DeductInventory(this.core!)
+    // })
+  }
+
+  /**
+   * 啟動階段
+   */
+  override boot(): void {
+    const core = this.core
+    if (!core) {
+      return
+    }
+
+    core.logger.info('🛰️ Satellite Commerce is booting')
+
+    // 監聽支付成功事件（來自 Payment Satellite）
+    // core.hooks.addAction('payment:succeeded', async (orderId: string, amount: number) => {
+    //   core.logger.info(`[Commerce] Payment succeeded for order ${orderId}`)
+    //   // 執行庫存扣減
+    //   // 更新訂單狀態
+    // })
+
+    // 監聽訂單建立事件（來自 Flash-Sale Satellite）
+    // core.events.listen(OrderCreated, async (event: OrderCreated) => {
+    //   core.logger.info(`[Commerce] Order created: ${event.order.id}`)
+    //   // 記錄訂單事件
+    // })
+
+    core.logger.info('✅ Satellite Commerce booted successfully')
+  }
+}

package/src/Domain/Entities/Commerce.ts

@@ -0,0 +1,26 @@
+import { Entity } from '@gravito/enterprise'
+
+export interface CommerceProps {
+  name: string
+  createdAt: Date
+}
+
+export class Commerce extends Entity<string> {
+  constructor(
+    id: string,
+    private props: CommerceProps
+  ) {
+    super(id)
+  }
+
+  static create(id: string, name: string): Commerce {
+    return new Commerce(id, {
+      name,
+      createdAt: new Date(),
+    })
+  }
+
+  get name() {
+    return this.props.name
+  }
+}

package/src/Domain/Entities/Order.ts

@@ -0,0 +1,164 @@
+import { AggregateRoot, Entity } from '@gravito/enterprise'
+
+export interface AdjustmentProps {
+  label: string
+  amount: number
+  sourceType: string | null
+  sourceId: string | null
+}
+
+export class Adjustment extends Entity<string> {
+  constructor(
+    id: string,
+    public readonly props: AdjustmentProps
+  ) {
+    super(id)
+  }
+}
+
+export interface LineItemProps {
+  variantId: string
+  sku: string
+  name: string
+  unitPrice: number
+  quantity: number
+  totalPrice: number
+  options?: Record<string, string>
+}
+
+export class LineItem extends Entity<string> {
+  constructor(
+    id: string,
+    public readonly props: LineItemProps
+  ) {
+    super(id)
+  }
+}
+
+export interface OrderProps {
+  memberId: string | null
+  idempotencyKey?: string
+  status:
+    | 'pending'
+    | 'paid'
+    | 'processing'
+    | 'shipped'
+    | 'completed'
+    | 'cancelled'
+    | 'requested_refund'
+    | 'refunded'
+  subtotalAmount: number
+  adjustmentAmount: number
+  totalAmount: number
+  currency: string
+  items: LineItem[]
+  adjustments: Adjustment[]
+  createdAt: Date
+  updatedAt?: Date
+}
+
+export class Order extends AggregateRoot<string> {
+  private constructor(
+    id: string,
+    private readonly props: OrderProps
+  ) {
+    super(id)
+  }
+
+  static create(id: string, memberId: string | null = null, currency = 'TWD'): Order {
+    return new Order(id, {
+      memberId,
+      status: 'pending',
+      subtotalAmount: 0,
+      adjustmentAmount: 0,
+      totalAmount: 0,
+      currency,
+      items: [],
+      adjustments: [],
+      createdAt: new Date(),
+    })
+  }
+
+  // Public Getters for Persistence & Logic
+  get memberId() {
+    return this.props.memberId
+  }
+  get status() {
+    return this.props.status
+  }
+  get subtotalAmount() {
+    return this.props.subtotalAmount
+  }
+  get adjustmentAmount() {
+    return this.props.adjustmentAmount
+  }
+  get totalAmount() {
+    return this.props.totalAmount
+  }
+  get createdAt() {
+    return this.props.createdAt
+  }
+  get items() {
+    return [...this.props.items]
+  }
+  get adjustments() {
+    return [...this.props.adjustments]
+  }
+
+  public addItem(item: LineItem): void {
+    if (this.props.status !== 'pending') {
+      throw new Error('Order is not in pending state')
+    }
+    this.props.items.push(item)
+    this.recalculate()
+  }
+
+  public addAdjustment(adj: Adjustment): void {
+    if (this.props.status !== 'pending') {
+      throw new Error('Order is not in pending state')
+    }
+    this.props.adjustments.push(adj)
+    this.recalculate()
+  }
+
+  private recalculate(): void {
+    ;(this.props as any).subtotalAmount = this.props.items.reduce(
+      (sum, item) => sum + item.props.totalPrice,
+      0
+    )
+    ;(this.props as any).adjustmentAmount = this.props.adjustments.reduce(
+      (sum, adj) => sum + adj.props.amount,
+      0
+    )
+    ;(this.props as any).totalAmount = Math.max(
+      0,
+      this.props.subtotalAmount + this.props.adjustmentAmount
+    )
+    ;(this.props as any).updatedAt = new Date()
+  }
+
+  public markAsPaid(): void {
+    if (this.props.status !== 'pending') {
+      throw new Error('Invalid status transition')
+    }
+    ;(this.props as any).status = 'paid'
+    ;(this.props as any).updatedAt = new Date()
+  }
+
+  public requestRefund(): void {
+    const allowedStatuses = ['paid', 'processing', 'completed']
+    if (!allowedStatuses.includes(this.props.status)) {
+      throw new Error(`Refund cannot be requested for order in ${this.props.status} state`)
+    }
+    ;(this.props as any).status = 'requested_refund'
+    ;(this.props as any).updatedAt = new Date()
+  }
+
+  public markAsRefunded(): void {
+    if (this.props.status !== 'requested_refund') {
+      throw new Error('Order must be in requested_refund state')
+    }
+    ;(this.props as any).status = 'refunded'
+    ;(this.props as any).updatedAt = new Date()
+  }
+}

package/src/Domain/Models.ts

@@ -0,0 +1,95 @@
+/**
+ * Commerce Satellite 領域模型
+ *
+ * 專注於訂單的狀態管理與庫存扣減流程
+ */
+
+/**
+ * 庫存扣減請求
+ *
+ * 當支付成功時，Commerce 會發送此請求到 Flash-Sale Satellite
+ * 來扣減庫存
+ */
+export class DeductInventoryRequest {
+  constructor(
+    public orderId: string,
+    public productId: string,
+    public quantity: number
+  ) {}
+
+  validate(): string[] {
+    const errors: string[] = []
+
+    if (!this.orderId?.trim()) {
+      errors.push('orderId is required')
+    }
+
+    if (!this.productId?.trim()) {
+      errors.push('productId is required')
+    }
+
+    if (this.quantity <= 0) {
+      errors.push('quantity must be greater than 0')
+    }
+
+    return errors
+  }
+}
+
+/**
+ * 訂單狀態轉移事件
+ */
+export interface OrderStatusTransition {
+  orderId: string
+  fromStatus: string
+  toStatus: string
+  reason?: string
+  timestamp: Date
+}
+
+/**
+ * 訂單確認請求
+ *
+ * 當庫存扣減成功時，Commerce 會建立訂單確認
+ */
+export class ConfirmOrderRequest {
+  constructor(
+    public orderId: string,
+    public inventoryLockId?: string
+  ) {}
+
+  validate(): string[] {
+    const errors: string[] = []
+
+    if (!this.orderId?.trim()) {
+      errors.push('orderId is required')
+    }
+
+    return errors
+  }
+}
+
+/**
+ * 訂單退款請求
+ */
+export class RefundOrderRequest {
+  constructor(
+    public orderId: string,
+    public reason: string,
+    public restoreInventory = true
+  ) {}
+
+  validate(): string[] {
+    const errors: string[] = []
+
+    if (!this.orderId?.trim()) {
+      errors.push('orderId is required')
+    }
+
+    if (!this.reason?.trim()) {
+      errors.push('reason is required')
+    }
+
+    return errors
+  }
+}

package/src/Infrastructure/Persistence/Migrations/20250101_create_commerce_tables.ts

@@ -0,0 +1,64 @@
+import { type Blueprint, Schema } from '@gravito/atlas'
+
+/**
+ * Migration to create Commerce tables and Patch inventory for Optimistic Locking.
+ */
+export default {
+  async up() {
+    // 1. Orders Table
+    await Schema.create('orders', (table: Blueprint) => {
+      table.string('id').primary()
+      table.string('member_id').nullable()
+      table.string('idempotency_key').unique().nullable()
+      table.string('status').default('pending') // pending, paid, processing, shipped, completed, cancelled
+      table.decimal('subtotal_amount', 15, 2)
+      table.decimal('adjustment_amount', 15, 2).default(0)
+      table.decimal('total_amount', 15, 2)
+      table.string('currency').default('TWD')
+      table.timestamp('created_at').default('CURRENT_TIMESTAMP')
+      table.timestamp('updated_at').nullable()
+      table.text('metadata').nullable()
+    })
+
+    // 2. Order Items (Snapshotting)
+    await Schema.create('order_items', (table: Blueprint) => {
+      table.string('id').primary()
+      table.string('order_id')
+      table.string('variant_id')
+      table.string('sku')
+      table.string('name')
+      table.decimal('unit_price', 15, 2)
+      table.integer('quantity')
+      table.decimal('total_price', 15, 2)
+      table.text('options').nullable()
+    })
+
+    // 3. Order Adjustments (Marketing/Tax/Shipping)
+    await Schema.create('order_adjustments', (table: Blueprint) => {
+      table.string('id').primary()
+      table.string('order_id')
+      table.string('label') // e.g., "Christmas Sale -10%", "Shipping Fee"
+      table.decimal('amount', 15, 2)
+      table.string('source_type').nullable() // e.g., "coupon", "tax"
+      table.string('source_id').nullable()
+    })
+
+    // 4. Patch Inventory for Optimistic Locking
+    // We add 'version' to support atomic updates:
+    // UPDATE ... SET stock = stock - ?, version = version + 1 WHERE id = ? AND version = ?
+    try {
+      await Schema.table('product_variants', (table: Blueprint) => {
+        table.integer('version').default(1)
+      })
+    } catch (_e) {
+      // Column might already exist, ignore in review environment
+    }
+  },
+
+  async down() {
+    await Schema.dropIfExists('order_adjustments')
+    await Schema.dropIfExists('order_items')
+    await Schema.dropIfExists('orders')
+    // We don't drop 'version' column in down to avoid losing catalog data
+  },
+}

package/src/Interface/Http/Controllers/AdminOrderController.ts

@@ -0,0 +1,21 @@
+import type { PlanetCore } from '@gravito/core'
+import type { AdminListOrders } from '../../../Application/UseCases/AdminListOrders'
+
+export class AdminOrderController {
+  constructor(private core: PlanetCore) {}
+
+  async index(ctx: any) {
+    try {
+      const useCase = this.core.container.make<AdminListOrders>('commerce.usecase.adminListOrders')
+      const orders = await useCase.execute()
+      return ctx.json(orders)
+    } catch (error: any) {
+      return ctx.json({ message: error.message }, 500)
+    }
+  }
+
+  async update(ctx: any) {
+    // 變更訂單狀態邏輯
+    return ctx.json({ success: true })
+  }
+}

package/src/Interface/Http/Controllers/CheckoutController.ts

@@ -0,0 +1,50 @@
+import type { GravitoContext } from '@gravito/core'
+import type { PlaceOrder } from '../../../Application/UseCases/PlaceOrder'
+
+export class CheckoutController {
+  /**
+   * 結帳下單接口
+   * POST /api/commerce/checkout
+   */
+  async store(c: GravitoContext) {
+    const core = c.get('core' as any) as any
+    const placeOrder = core.container.make('commerce.place-order') as PlaceOrder
+
+    // 獲取下單數據
+    const body = (await c.req.json()) as any
+
+    // 獲取冪等 Key
+    const idempotencyKey = c.req.header('X-Idempotency-Key') || body.idempotencyKey
+
+    // 獲取會員 ID (相容 Membership 插件)
+    const auth = c.get('auth' as any) as any
+    const memberId = auth?.user ? auth.user()?.id : null
+
+    try {
+      const result = await placeOrder.execute({
+        memberId,
+        idempotencyKey,
+        items: body.items,
+      })
+
+      return c.json(
+        {
+          success: true,
+          message: 'Order placed successfully',
+          data: result,
+        },
+        201
+      )
+    } catch (error: any) {
+      // 處理併發衝突或庫存不足
+      const status = error.message.includes('Concurrency') ? 409 : 400
+      return c.json(
+        {
+          success: false,
+          error: error.message,
+        },
+        status
+      )
+    }
+  }
+}