@gravito/satellite-marketing 0.1.1

package/src/Application/Rules/FreeShippingRule.ts

@@ -0,0 +1,29 @@
+import type { IPromotionRule, MarketingAdjustment } from '../../Domain/Contracts/IPromotionRule'
+
+export class FreeShippingRule implements IPromotionRule {
+  /**
+   * config: { min_amount: 1000 }
+   * 意即：滿 1000 元即享免運
+   */
+  match(order: any, config: any): MarketingAdjustment | null {
+    const subtotal = Number(order.subtotalAmount)
+
+    // 如果滿足門檻
+    if (subtotal >= config.min_amount) {
+      // 這裡我們需要知道當前的運費是多少。
+      // 在 Gravito Commerce 中，運費被視為一個 Adjustment。
+      // 我們的策略是：回傳一個與運費金額相等的負值折扣。
+
+      // 模擬邏輯：直接查現有的調整項 (假設我們知道 standard 運費是 60)
+      // 在更進階的實作中，我們可以遍歷 order.adjustments 尋找 sourceType: 'shipping'
+      return {
+        label: `Free Shipping (Orders over ${config.min_amount})`,
+        amount: -60, // 抵銷基礎運費
+        sourceType: 'promotion',
+        sourceId: 'free_shipping',
+      }
+    }
+
+    return null
+  }
+}

package/src/Application/Rules/MembershipLevelRule.ts

@@ -0,0 +1,28 @@
+import { DB } from '@gravito/atlas'
+import type { IPromotionRule, MarketingAdjustment } from '../../Domain/Contracts/IPromotionRule'
+
+export class MembershipLevelRule implements IPromotionRule {
+  /**
+   * config: { target_level: 'gold', discount_percent: 10 }
+   */
+  async match(order: any, config: any): Promise<MarketingAdjustment | null> {
+    if (!order.memberId) {
+      return null
+    }
+
+    // 從 Membership 表中查詢該會員的等級 (跨衛星數據讀取)
+    const member = (await DB.table('members').where('id', order.memberId).first()) as any
+
+    if (member && member.level === config.target_level) {
+      const discount = Number(order.subtotalAmount) * (config.discount_percent / 100)
+      return {
+        label: `VIP Discount: ${config.target_level.toUpperCase()} Member ${config.discount_percent}% Off`,
+        amount: -discount,
+        sourceType: 'promotion',
+        sourceId: 'membership_level',
+      }
+    }
+
+    return null
+  }
+}

package/src/Application/Services/CouponService.ts

@@ -0,0 +1,57 @@
+import { DB } from '@gravito/atlas'
+import type { PlanetCore } from '@gravito/core'
+
+export class CouponService {
+  constructor(private core: PlanetCore) {}
+
+  /**
+   * 根據代碼查找折價券
+   */
+  async findByCode(code: string): Promise<any> {
+    this.core.logger.info(`[CouponService] Looking up coupon: ${code}`)
+    return DB.table('coupons').where('code', code).first()
+  }
+
+  /**
+   * 計算折價券調整金額
+   */
+  async getAdjustment(code: string, _order: any): Promise<any> {
+    this.core.logger.info(`[CouponService] Calculating adjustment for: ${code}`)
+    const coupon = await this.findByCode(code)
+
+    if (!coupon) {
+      throw new Error('coupon_not_found')
+    }
+
+    if (coupon.is_active === false) {
+      throw new Error('inactive')
+    }
+
+    if (coupon.expires_at) {
+      const expiresAt = new Date(coupon.expires_at)
+      if (!Number.isNaN(expiresAt.getTime()) && expiresAt < new Date()) {
+        throw new Error('expired')
+      }
+    }
+
+    const value = Number(coupon.value)
+    const subtotal = Number(_order?.subtotalAmount ?? 0)
+
+    let amount = 0
+    const type = String(coupon.type || '').toLowerCase()
+    if (type === 'fixed') {
+      amount = -value
+    } else if (type === 'percent' || type === 'percentage') {
+      amount = -(subtotal * (value / 100))
+    } else {
+      throw new Error('unsupported_coupon_type')
+    }
+
+    return {
+      label: `Coupon: ${coupon.name}`,
+      amount,
+      sourceType: 'coupon',
+      sourceId: coupon.id ?? coupon.code,
+    }
+  }
+}

package/src/Application/Services/PromotionEngine.ts

@@ -0,0 +1,65 @@
+import { DB } from '@gravito/atlas'
+import type { PlanetCore } from '@gravito/core'
+import type { IPromotionRule, MarketingAdjustment } from '../../Domain/Contracts/IPromotionRule'
+import { BuyXGetYRule } from '../Rules/BuyXGetYRule'
+import { CartThresholdRule } from '../Rules/CartThresholdRule'
+import { CategoryDiscountRule } from '../Rules/CategoryDiscountRule'
+import { FreeShippingRule } from '../Rules/FreeShippingRule'
+import { MembershipLevelRule } from '../Rules/MembershipLevelRule'
+
+export class PromotionEngine {
+  constructor(private core: PlanetCore) {}
+
+  private ruleFor(type: string): IPromotionRule | null {
+    switch (type) {
+      case 'cart_threshold':
+        return new CartThresholdRule()
+      case 'buy_x_get_y':
+        return new BuyXGetYRule()
+      case 'category_discount':
+        return new CategoryDiscountRule()
+      case 'free_shipping':
+        return new FreeShippingRule()
+      case 'membership_level':
+        return new MembershipLevelRule()
+      default:
+        return null
+    }
+  }
+
+  async applyPromotions(order: any): Promise<MarketingAdjustment[]> {
+    this.core.logger.info('[PromotionEngine] Calculating promotions...')
+    const applied: MarketingAdjustment[] = []
+
+    const promotions = (await DB.table('promotions')
+      .where('is_active', true)
+      .orderBy('priority', 'desc')
+      .get()) as any[]
+
+    for (const promo of promotions) {
+      const rule = this.ruleFor(String(promo.type || '').toLowerCase())
+      if (!rule) {
+        continue
+      }
+
+      const rawConfig = promo.configuration ?? '{}'
+      let config = {}
+      if (typeof rawConfig === 'string') {
+        try {
+          config = JSON.parse(rawConfig)
+        } catch {
+          config = {}
+        }
+      } else if (rawConfig && typeof rawConfig === 'object') {
+        config = rawConfig
+      }
+
+      const result = await rule.match(order, config)
+      if (result) {
+        applied.push(result)
+      }
+    }
+
+    return applied
+  }
+}

package/src/Application/UseCases/AdminListCoupons.ts

@@ -0,0 +1,31 @@
+import { UseCase } from '@gravito/enterprise'
+import { Coupon } from '../../Domain/Entities/Coupon'
+
+export class AdminListCoupons extends UseCase<void, Coupon[]> {
+  async execute(): Promise<Coupon[]> {
+    // 模擬從資料庫讀取優惠券
+    return [
+      Coupon.create({
+        code: 'WELCOME2025',
+        name: '新年歡迎禮',
+        type: 'PERCENTAGE',
+        value: 10,
+        minPurchase: 0,
+        startsAt: new Date('2025-01-01'),
+        expiresAt: new Date('2025-12-31'),
+        usageLimit: 1000,
+        status: 'ACTIVE',
+      }),
+      Coupon.create({
+        code: 'SAVE500',
+        name: '滿額折抵',
+        type: 'FIXED',
+        value: 500,
+        minPurchase: 5000,
+        startsAt: new Date('2025-01-01'),
+        expiresAt: new Date('2025-06-30'),
+        status: 'ACTIVE',
+      }),
+    ]
+  }
+}

package/src/Application/UseCases/CreateMarketing.ts

@@ -0,0 +1,22 @@
+import { UseCase } from '@gravito/enterprise'
+import type { IMarketingRepository } from '../../Domain/Contracts/IMarketingRepository'
+import { Marketing } from '../../Domain/Entities/Marketing'
+
+export interface CreateMarketingInput {
+  name: string
+}
+
+export class CreateMarketing extends UseCase<CreateMarketingInput, string> {
+  constructor(private repository: IMarketingRepository) {
+    super()
+  }
+
+  async execute(input: CreateMarketingInput): Promise<string> {
+    const id = crypto.randomUUID()
+    const entity = Marketing.create(id, input.name)
+
+    await this.repository.save(entity)
+
+    return id
+  }
+}

package/src/Domain/Contracts/IMarketingRepository.ts

@@ -0,0 +1,6 @@
+import type { Repository } from '@gravito/enterprise'
+import type { Marketing } from '../Entities/Marketing'
+
+export interface IMarketingRepository extends Repository<Marketing, string> {
+  // Add custom methods here
+}

package/src/Domain/Contracts/IPromotionRule.ts

@@ -0,0 +1,14 @@
+export interface MarketingAdjustment {
+  label: string
+  amount: number
+  sourceType: string
+  sourceId: string
+}
+
+export interface IPromotionRule {
+  /**
+   * 檢查訂單是否符合此規則
+   * 支援 async 以便執行跨衛星的 DB 查詢
+   */
+  match(order: any, config: any): MarketingAdjustment | null | Promise<MarketingAdjustment | null>
+}

package/src/Domain/Entities/Coupon.ts

@@ -0,0 +1,44 @@
+import { Entity } from '@gravito/enterprise'
+
+export interface CouponProps {
+  code: string
+  name: string
+  type: 'FIXED' | 'PERCENTAGE'
+  value: number
+  minPurchase: number
+  startsAt: Date
+  expiresAt: Date
+  usageLimit?: number
+  usedCount: number
+  status: 'ACTIVE' | 'EXPIRED' | 'DISABLED'
+}
+
+export class Coupon extends Entity<string> {
+  private _props: CouponProps
+
+  constructor(props: CouponProps, id?: string) {
+    super(id || crypto.randomUUID())
+    this._props = props
+  }
+
+  static create(props: Omit<CouponProps, 'usedCount'>, id?: string): Coupon {
+    return new Coupon(
+      {
+        ...props,
+        usedCount: 0,
+      },
+      id
+    )
+  }
+
+  get code() {
+    return this._props.code
+  }
+  get status() {
+    return this._props.status
+  }
+
+  unpack(): CouponProps {
+    return { ...this._props }
+  }
+}

package/src/Domain/Entities/Marketing.ts

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

package/src/Domain/PromotionRules/BuyXGetYRule.ts

@@ -0,0 +1,8 @@
+import type { IPromotionRule, MarketingAdjustment } from '../Contracts/IPromotionRule'
+
+export class BuyXGetYRule implements IPromotionRule {
+  name = 'buy_x_get_y'
+  match(_order: any, _config: any): MarketingAdjustment | null {
+    return null // 預設不匹配
+  }
+}

package/src/Domain/PromotionRules/FixedAmountDiscountRule.ts

@@ -0,0 +1,8 @@
+import type { IPromotionRule, MarketingAdjustment } from '../Contracts/IPromotionRule'
+
+export class FixedAmountDiscountRule implements IPromotionRule {
+  name = 'fixed_discount'
+  match(_order: any, _config: any): MarketingAdjustment | null {
+    return null
+  }
+}

package/src/Domain/PromotionRules/FreeShippingRule.ts

@@ -0,0 +1,8 @@
+import type { IPromotionRule, MarketingAdjustment } from '../Contracts/IPromotionRule'
+
+export class FreeShippingRule implements IPromotionRule {
+  name = 'free_shipping'
+  match(_order: any, _config: any): MarketingAdjustment | null {
+    return null
+  }
+}

package/src/Domain/PromotionRules/PercentageDiscountRule.ts

@@ -0,0 +1,8 @@
+import type { IPromotionRule, MarketingAdjustment } from '../Contracts/IPromotionRule'
+
+export class PercentageDiscountRule implements IPromotionRule {
+  name = 'percentage_discount'
+  match(_order: any, _config: any): MarketingAdjustment | null {
+    return null
+  }
+}

package/src/Infrastructure/Persistence/AtlasMarketingRepository.ts

@@ -0,0 +1,24 @@
+import type { IMarketingRepository } from '../../Domain/Contracts/IMarketingRepository'
+import type { Marketing } from '../../Domain/Entities/Marketing'
+
+export class AtlasMarketingRepository implements IMarketingRepository {
+  async save(entity: Marketing): Promise<void> {
+    // Dogfooding: Use @gravito/atlas for persistence
+    console.log('[Atlas] Saving entity:', entity.id)
+    // await DB.table('marketings').insert({ ... })
+  }
+
+  async findById(_id: string): Promise<Marketing | null> {
+    return null
+  }
+
+  async findAll(): Promise<Marketing[]> {
+    return []
+  }
+
+  async delete(_id: string): Promise<void> {}
+
+  async exists(_id: string): Promise<boolean> {
+    return false
+  }
+}

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

@@ -0,0 +1,47 @@
+import { type Blueprint, Schema } from '@gravito/atlas'
+
+export default {
+  async up() {
+    // 1. Promotions (System-wide rules)
+    await Schema.create('promotions', (table: Blueprint) => {
+      table.string('id').primary()
+      table.string('name')
+      table.string('type') // e.g., "cart_threshold", "buy_x_get_y", "category_discount"
+      table.text('configuration') // JSON: Store rules like { min_amount: 2000, discount: 200 }
+      table.integer('priority').default(0)
+      table.boolean('is_active').default(true)
+      table.timestamp('starts_at').nullable()
+      table.timestamp('ends_at').nullable()
+      table.timestamp('created_at').default('CURRENT_TIMESTAMP')
+    })
+
+    // 2. Coupons (User-entered codes)
+    await Schema.create('coupons', (table: Blueprint) => {
+      table.string('id').primary()
+      table.string('code').unique()
+      table.string('name')
+      table.string('type') // e.g., "fixed", "percent"
+      table.decimal('value', 15, 2)
+      table.text('configuration').nullable() // JSON: Constraints like { min_spend: 1000 }
+      table.integer('usage_limit').nullable()
+      table.integer('usage_count').default(0)
+      table.boolean('is_active').default(true)
+      table.timestamp('expires_at').nullable()
+    })
+
+    // 3. Coupon Usage Tracking
+    await Schema.create('coupon_usages', (table: Blueprint) => {
+      table.string('id').primary()
+      table.string('coupon_id')
+      table.string('member_id')
+      table.string('order_id')
+      table.timestamp('used_at').default('CURRENT_TIMESTAMP')
+    })
+  },
+
+  async down() {
+    await Schema.dropIfExists('coupon_usages')
+    await Schema.dropIfExists('coupons')
+    await Schema.dropIfExists('promotions')
+  },
+}

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

@@ -0,0 +1,24 @@
+import type { PlanetCore } from '@gravito/core'
+import type { AdminListCoupons } from '../../../Application/UseCases/AdminListCoupons'
+import type { Coupon } from '../../../Domain/Entities/Coupon'
+
+export class AdminMarketingController {
+  constructor(private core: PlanetCore) {}
+
+  async coupons(ctx: any) {
+    try {
+      const useCase = this.core.container.make<AdminListCoupons>(
+        'marketing.usecase.adminListCoupons'
+      )
+      const coupons = await useCase.execute()
+      return ctx.json(
+        coupons.map((c: Coupon) => ({
+          id: c.id,
+          ...c.unpack(),
+        }))
+      )
+    } catch (error: any) {
+      return ctx.json({ message: error.message }, 500)
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { type Container, ServiceProvider } from '@gravito/core'
+import { CouponService } from './Application/Services/CouponService'
+import { PromotionEngine } from './Application/Services/PromotionEngine'
+import { AdminListCoupons } from './Application/UseCases/AdminListCoupons'
+import { AdminMarketingController } from './Interface/Http/Controllers/AdminMarketingController'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+
+export class MarketingServiceProvider extends ServiceProvider {
+  register(container: Container): void {
+    container.singleton('marketing.promotion-engine', () => {
+      return new PromotionEngine(this.core!)
+    })
+    container.singleton('marketing.coupon-service', () => {
+      return new CouponService(this.core!)
+    })
+    container.bind('marketing.usecase.adminListCoupons', () => new AdminListCoupons())
+    container.singleton(
+      'marketing.controller.admin',
+      () => new AdminMarketingController(this.core!)
+    )
+  }
+
+  getMigrationsPath(): string {
+    return join(__dirname, 'Infrastructure/Persistence/Migrations')
+  }
+
+  override async boot(): Promise<void> {
+    const core = this.core
+    if (!core) {
+      return
+    }
+
+    const adminCtrl = core.container.make<AdminMarketingController>('marketing.controller.admin')
+
+    // 管理端路由
+    core.router.prefix('/api/admin/v1/marketing').group((router) => {
+      router.get('/coupons', (ctx) => adminCtrl.coupons(ctx))
+    })
+
+    const promoEngine = core.container.make<PromotionEngine>('marketing.promotion-engine')
+    const couponService = core.container.make<CouponService>('marketing.coupon-service')
+
+    // 1. 價格調整 Filter (Promotion + Coupon)
+    core.hooks.addFilter(
+      'commerce:order:adjustments',
+      async (adjustments: any[], { order, extras }: any) => {
+        core.logger.info(`🎯 [Marketing] 正在為訂單 ${order.id} 掃描促銷與折價券...`)
+
+        const results = [...adjustments]
+
+        // 自動套用促銷活動
+        const promoAdjustments = await promoEngine.applyPromotions(order)
+        results.push(...promoAdjustments)
+
+        // 手動套用折價券 (從下單請求的 extras 中獲取 couponCode)
+        if (extras?.couponCode) {
+          try {
+            const couponAdj = await couponService.getAdjustment(extras.couponCode, order)
+            if (couponAdj) {
+              results.push(couponAdj)
+            }
+          } catch (e: any) {
+            core.logger.warn(`⚠️ [Marketing] 折價券無效: ${e.message}`)
+            // 注意：這裡我們不拋出錯誤，讓下單繼續但沒有折扣
+          }
+        }
+
+        return results
+      }
+    )
+
+    // 2. 訂單完成後的核銷動作
+    core.hooks.addAction('commerce:order-placed', async (payload: any) => {
+      core.logger.info(`📝 [Marketing] 訂單 ${payload.orderId} 已建立，正在處理折價券核銷...`)
+    })
+
+    core.logger.info('🛰️ Satellite Marketing is operational')
+  }
+}

package/src/manifest.json

@@ -0,0 +1,12 @@
+{
+  "id": "satellite-marketing",
+  "name": "Marketing & Promotions",
+  "version": "0.1.0",
+  "description": "Flexible rule engine for promotions, coupons, and discounts.",
+  "author": "Gravito Team",
+  "type": "satellite",
+  "hooks": {
+    "actions": ["commerce:order-placed"],
+    "filters": ["commerce:order:adjustments"]
+  }
+}

package/tests/advanced-rules.test.ts

@@ -0,0 +1,105 @@
+import { beforeEach, describe, expect, it } from 'bun:test'
+import { DB, Schema } from '@gravito/atlas'
+import { PlanetCore } from '@gravito/core'
+import type { PromotionEngine } from '../src/Application/Services/PromotionEngine'
+import { MarketingServiceProvider } from '../src/index'
+
+describe('Marketing Satellite - Advanced Rules', () => {
+  let core: PlanetCore
+  let engine: PromotionEngine
+
+  beforeEach(async () => {
+    core = await PlanetCore.boot({
+      config: {
+        'database.default': 'sqlite',
+        'database.connections.sqlite': { driver: 'sqlite', database: ':memory:' },
+      },
+    })
+    DB.addConnection('default', { driver: 'sqlite', database: ':memory:' })
+
+    // 1. 模擬基礎表
+    await Schema.dropIfExists('promotions')
+    await Schema.create('promotions', (table) => {
+      table.string('id').primary()
+      table.string('name')
+      table.string('type')
+      table.text('configuration')
+      table.integer('priority').default(0)
+      table.boolean('is_active').default(true)
+    })
+
+    await Schema.dropIfExists('members')
+    await Schema.create('members', (table) => {
+      table.string('id').primary()
+      table.string('level')
+    })
+
+    await core.use(new MarketingServiceProvider())
+    await core.bootstrap()
+    engine = core.container.make('marketing.promotion-engine')
+  })
+
+  it('應該能正確計算 VIP 金級會員折扣', async () => {
+    // 注入金級會員
+    await DB.table('members').insert({ id: 'm_gold', level: 'gold' })
+
+    // 注入規則：金級會員 9 折 (10% off)
+    await DB.table('promotions').insert({
+      id: 'p_vip',
+      name: 'Gold Member 10% Off',
+      type: 'membership_level',
+      configuration: JSON.stringify({ target_level: 'gold', discount_percent: 10 }),
+      is_active: true,
+    })
+
+    const order = { id: 'o1', memberId: 'm_gold', subtotalAmount: 5000 }
+    const adjustments = await engine.applyPromotions(order)
+
+    expect(adjustments).toHaveLength(1)
+    expect(adjustments[0].amount).toBe(-500) // 5000 * 0.1
+    expect(adjustments[0].label).toContain('GOLD Member')
+  })
+
+  it('應該能正確計算全分類折扣 (Electronics)', async () => {
+    await DB.table('promotions').insert({
+      id: 'p_cat',
+      name: 'Electronics 20% Sale',
+      type: 'category_discount',
+      configuration: JSON.stringify({ category_id: 'electronics', discount_percent: 20 }),
+      is_active: true,
+    })
+
+    const order = {
+      subtotalAmount: 10000,
+      items: [
+        // 商品 A 屬於電子類 (路徑包含 /electronics/)
+        { props: { totalPrice: 8000, options: { categoryPath: '/1/electronics/42/' } } },
+        // 商品 B 屬於食品類
+        { props: { totalPrice: 2000, options: { categoryPath: '/2/food/' } } },
+      ],
+    }
+
+    const adjustments = await engine.applyPromotions(order)
+
+    expect(adjustments).toHaveLength(1)
+    expect(adjustments[0].amount).toBe(-1600) // 8000 * 0.2
+    expect(adjustments[0].label).toContain('ELECTRONICS')
+  })
+
+  it('應該能正確套用滿額免運折扣', async () => {
+    await DB.table('promotions').insert({
+      id: 'p_ship',
+      name: 'Free Shipping over 1000',
+      type: 'free_shipping',
+      configuration: JSON.stringify({ min_amount: 1000 }),
+      is_active: true,
+    })
+
+    const order = { subtotalAmount: 1500 }
+    const adjustments = await engine.applyPromotions(order)
+
+    expect(adjustments).toHaveLength(1)
+    expect(adjustments[0].amount).toBe(-60) // 抵銷 60 元運費
+    expect(adjustments[0].label).toContain('Free Shipping')
+  })
+})