@gravito/satellite-commerce 0.1.1

package/src/Application/Services/ProductResolver.ts

@@ -0,0 +1,46 @@
+import { DB } from '@gravito/atlas'
+import type { CacheManager } from '@gravito/stasis'
+
+export interface ProductSnapshot {
+  id: string
+  sku: string
+  name: string
+  price: number
+}
+
+export class ProductResolver {
+  constructor(private cache: CacheManager) {}
+
+  async resolve(variantId: string, useCache: boolean): Promise<ProductSnapshot> {
+    const cacheKey = `product:variant:${variantId}`
+
+    if (useCache) {
+      const cached = await this.cache.get<ProductSnapshot>(cacheKey)
+      if (cached) {
+        return cached
+      }
+    }
+
+    const variant = (await DB.table('product_variants')
+      .where('id', variantId)
+      .select('id', 'sku', 'name', 'price')
+      .first()) as any
+
+    if (!variant) {
+      throw new Error(`Product variant ${variantId} not found`)
+    }
+
+    const snapshot: ProductSnapshot = {
+      id: String(variant.id),
+      sku: String(variant.sku),
+      name: String(variant.name || 'Unnamed'),
+      price: Number(variant.price),
+    }
+
+    if (useCache) {
+      await this.cache.put(cacheKey, snapshot, 60)
+    }
+
+    return snapshot
+  }
+}

package/src/Application/Subscribers/RewardSubscriber.ts

@@ -0,0 +1,27 @@
+import { DB } from '@gravito/atlas'
+import type { PlanetCore } from '@gravito/core'
+
+export class RewardSubscriber {
+  constructor(private core: PlanetCore) {}
+
+  async handleOrderPlaced(payload: { orderId: string }) {
+    const logger = this.core.logger
+    const order = (await DB.table('orders').where('id', payload.orderId).first()) as any
+
+    if (!order || !order.member_id) {
+      return
+    }
+
+    const points = Math.floor(Number(order.total_amount) / 100)
+
+    if (points > 0) {
+      logger.info(
+        `🎁 [Rewards] 為會員 ${order.member_id} 分配 ${points} 點紅利 (訂單: ${payload.orderId})`
+      )
+      await this.core.hooks.doAction('rewards:assigned', {
+        memberId: order.member_id,
+        points,
+      })
+    }
+  }
+}

package/src/Application/UseCases/AdminListOrders.ts

@@ -0,0 +1,34 @@
+import { UseCase } from '@gravito/enterprise'
+
+export class AdminListOrders extends UseCase<any, any[]> {
+  async execute(): Promise<any[]> {
+    // 模擬從資料庫獲取所有訂單
+    // 真實情境應注入 IOrderRepository
+    return [
+      {
+        id: 'ORD-2025122901',
+        customerName: 'Carl',
+        totalAmount: 1250,
+        paymentStatus: 'PAID',
+        shippingStatus: 'SHIPPED',
+        createdAt: new Date('2025-12-29T10:00:00Z'),
+      },
+      {
+        id: 'ORD-2025122902',
+        customerName: 'Alice',
+        totalAmount: 3200,
+        paymentStatus: 'PAID',
+        shippingStatus: 'PENDING',
+        createdAt: new Date('2025-12-29T11:30:00Z'),
+      },
+      {
+        id: 'ORD-2025122903',
+        customerName: 'Bob',
+        totalAmount: 450,
+        paymentStatus: 'UNPAID',
+        shippingStatus: 'PENDING',
+        createdAt: new Date('2025-12-29T14:20:00Z'),
+      },
+    ]
+  }
+}

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/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/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
+      )
+    }
+  }
+}

package/src/Interface/Http/Requests/PlaceOrderRequest.ts

@@ -0,0 +1,18 @@
+export class PlaceOrderRequest {
+  /**
+   * 這是簡易版的驗證邏輯，未來可與 @gravito/impulse 深度整合
+   */
+  static validate(data: any) {
+    if (!data.items || !Array.isArray(data.items) || data.items.length === 0) {
+      throw new Error('Order items are required')
+    }
+
+    for (const item of data.items) {
+      if (!item.variantId || typeof item.quantity !== 'number' || item.quantity <= 0) {
+        throw new Error(
+          'Invalid item structure: each item must have a variantId and a positive quantity'
+        )
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { type Container, ServiceProvider } from '@gravito/core'
+import { RewardSubscriber } from './Application/Subscribers/RewardSubscriber'
+import { AdminListOrders } from './Application/UseCases/AdminListOrders'
+import { PlaceOrder } from './Application/UseCases/PlaceOrder'
+import { AdminOrderController } from './Interface/Http/Controllers/AdminOrderController'
+import { CheckoutController } from './Interface/Http/Controllers/CheckoutController'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+
+export class CommerceServiceProvider extends ServiceProvider {
+  register(container: Container): void {
+    container.bind('commerce.usecase.adminListOrders', () => new AdminListOrders())
+    container.singleton('commerce.controller.admin', () => new AdminOrderController(this.core!))
+    // Bind the core order engine
+    container.singleton('commerce.place-order', () => {
+      return new PlaceOrder(this.core!)
+    })
+  }
+
+  getMigrationsPath(): string {
+    return `${__dirname}/Infrastructure/Persistence/Migrations`
+  }
+
+  override async boot(): Promise<void> {
+    const core = this.core
+    if (!core) {
+      return
+    }
+
+    const checkoutCtrl = new CheckoutController()
+    const rewardSub = new RewardSubscriber(core)
+
+    // 註冊事件監聽
+    core.hooks.addAction('commerce:order-placed', (payload: any) => {
+      rewardSub.handleOrderPlaced(payload as { orderId: string })
+    })
+
+    /**
+     * GASS 聯動：監聽支付成功 (來自 Payment 衛星)
+     */
+    core.hooks.addAction('payment:succeeded', async (payload: { orderId: string }) => {
+      core.logger.info(`[Commerce] Order ${payload.orderId} confirmed as PAID.`)
+      // 這裡通常會調用 Order.markAsPaid() 並持久化，目前暫由 Log 表現閉環
+    })
+
+    // Register Routes
+    core.router.prefix('/api/commerce').group((router) => {
+      router.post('/checkout', (c) => checkoutCtrl.store(c))
+    })
+
+    core.logger.info('🛰️ Satellite Commerce is operational')
+
+    const adminCtrl = core.container.make<AdminOrderController>('commerce.controller.admin')
+
+    // 管理端路由
+    core.router.prefix('/api/admin/v1/commerce').group((router) => {
+      router.get('/orders', (ctx) => adminCtrl.index(ctx))
+      router.patch('/orders/:id', (ctx) => adminCtrl.update(ctx))
+    })
+  }
+}

package/src/manifest.json

@@ -0,0 +1,12 @@
+{
+  "id": "satellite-commerce",
+  "name": "Commerce Engine",
+  "version": "0.1.0",
+  "description": "High-performance transaction & order engine with Turbo support.",
+  "author": "Gravito Team",
+  "type": "satellite",
+  "hooks": {
+    "actions": ["commerce:order-placed", "rewards:assigned"],
+    "filters": ["commerce:order:adjustments"]
+  }
+}