@gravito/satellite-marketing 0.1.1

package/.dockerignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+.git
+.env
+*.log
+.vscode
+.idea
+tests

package/.env.example

@@ -0,0 +1,19 @@
+# Application
+APP_NAME="marketing"
+APP_ENV=development
+APP_KEY=
+APP_DEBUG=true
+APP_URL=http://localhost:3000
+
+# Server
+PORT=3000
+
+# Database
+DB_CONNECTION=sqlite
+DB_DATABASE=database/database.sqlite
+
+# Cache
+CACHE_DRIVER=memory
+
+# Logging
+LOG_LEVEL=debug

package/ARCHITECTURE.md

@@ -0,0 +1,22 @@
+# Marketing Satellite 架構說明 🎯
+
+## 1. 規則策略模式 (Strategy Pattern)
+我們將每一種行銷玩法抽象為 `IPromotionRule`。
+當 `PromotionEngine` 運行時，它會根據資料庫中活動的 `type` 動態加載對應的策略類別執行 `match(order, config)`。這確保了系統可以在不改動引擎代碼的情況下，透過增加檔案來支援無限的新玩法。
+
+## 2. 三段推進實作 (Marketing Stages)
+
+### Stage 1: Standard
+- 直接查詢 SQL 中的 `promotions` 與 `coupons` 表。
+- 適用於日常運作。
+
+### Stage 2: Sport (內存加速)
+- 將「進行中」的系統促銷規則（如滿額折抵）加載至內存快取。
+- 下單時無需查詢 DB 即可完成規則匹配。
+
+### Stage 3: Turbo (分佈式鎖)
+- 針對限量的折價券，核銷張數由 Redis `DECR` 原子操作控制。
+- 確保在 K8s 叢集環境下，折價券不會被「超領」。
+
+## 3. 數據快照與法律一致性
+Marketing 產生的 `Adjustment` 會被 Commerce 永久保存至 `order_adjustments`。這意味著即便活動結束或規則被刪除，歷史訂單的折扣紀錄依然完整且具備法律效力。

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @gravito/satellite-marketing
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @gravito/atlas@1.0.1
+  - @gravito/core@1.0.0
+  - @gravito/enterprise@1.0.0

package/Dockerfile

@@ -0,0 +1,25 @@
+FROM oven/bun:1.0 AS base
+WORKDIR /usr/src/app
+
+# Install dependencies
+FROM base AS install
+RUN mkdir -p /temp/dev
+COPY package.json bun.lockb /temp/dev/
+RUN cd /temp/dev && bun install --frozen-lockfile
+
+# Build application
+FROM base AS build
+COPY --from=install /temp/dev/node_modules node_modules
+COPY . .
+ENV NODE_ENV=production
+RUN bun run build
+
+# Final production image
+FROM base AS release
+COPY --from=build /usr/src/app/dist/bootstrap.js index.js
+COPY --from=build /usr/src/app/package.json .
+
+# Create a non-root user for security
+USER bun
+EXPOSE 3000/tcp
+ENTRYPOINT [ "bun", "run", "index.js" ]

package/README.md

@@ -0,0 +1,24 @@
+# @gravito/satellite-marketing 🎯
+
+這是 Gravito Galaxy 的行銷與促銷規則引擎。它設計用於在不侵入核心交易邏輯的前提下，動態注入折扣、折價券與贈品。
+
+## 🌟 核心特性
+
+- **策略驅動引擎**: 基於規則策略模式，輕鬆擴充新的促銷玩法（如買幾送幾）。
+- **折價券生命週期**: 支援 Code 核銷、張數限制、有效期與最低消費限制。
+- **非侵入式聯動**: 透過 Hook 注入 `Adjustment`，完全解耦 Commerce 與 Marketing。
+- **高併發預留**: 支持 Sport 模式內存快取規則，與 Turbo 模式 Redis 原子核銷。
+
+## 🚀 促銷玩法 (Built-in Rules)
+
+| 類型 | 標籤 | 描述 |
+| :--- | :--- | :--- |
+| `cart_threshold` | 滿額折抵 | 當購物車小計超過門檻，扣除固定金額。 |
+| `buy_x_get_y` | 買 X 送 Y | 針對特定 SKU，每買 X 個就折抵 Y 個的金額。 |
+| `coupon` | 折價券 | 使用者輸入代碼，套用固定或百分比折扣。 |
+
+## 🔗 Galaxy 聯動
+
+本插件主要監聽 Commerce 的價格計算過濾器：
+- **Filter**: `commerce:order:adjustments`
+- **Action**: `commerce:order-placed` (用於核銷折價券次數)

package/WHITEPAPER.md

@@ -0,0 +1,29 @@
+# Whitepaper: Gravito Marketing Satellite (Algorithmic Promotion Engine)
+**Version:** 1.0.0 | **Author:** Gravito Engineering Team
+
+## 1. Abstract
+The Gravito Marketing Satellite is a decoupled logic injector designed to handle complex commercial incentives. By utilizing a "Passive Observer" pattern, it enables highly dynamic marketing campaigns (Coupons, B2G1, Tiered Pricing) to influence transactions within the Commerce engine without creating hard-coded dependencies.
+
+## 2. Architectural Philosophy: The Decoupled Injector
+Traditional e-commerce systems often suffer from "Spaghetti Promotion Logic," where discount checks are scattered across the checkout code. Gravito solves this via **Polymorphic Adjustments**:
+- The core Commerce engine remains "blind" to marketing rules.
+- Marketing logic is encapsulated in **Rules Strategies**.
+- Communication occurs via the `commerce:order:adjustments` filter, where the Marketing satellite injects negative-value adjustments into the order aggregate.
+
+## 3. High-Performance Rule Matching
+To support massive scale, the engine implements a tiered matching strategy:
+- **Index-Based Filtering**: Active promotions are pre-filtered by date and status at the database level.
+- **Complexity O(N)**: Rule matching scales linearly with the number of active campaigns, not the number of items in the catalog.
+- **Memory Priming**: In "Sport Mode," rule metadata is hydrated into heap memory, enabling instantaneous matching for system-wide promotions.
+
+## 4. Distributed Coupon Governance (Turbo Guard)
+In cluster deployments (AWS ECS / Kubernetes), coupon "Double-Spending" is a critical risk.
+- **Standard Protocol**: SQL-based atomic increments for usage tracking.
+- **Turbo Protocol**: Redis-backed semaphores. When a high-value coupon is entered, the system performs a sub-ms "check-and-decrement" in Redis before committing the transaction to SQL.
+
+## 5. Integration Scenarios
+- **Buy X Get Y (B2G1)**: Algorithmic analysis of the cart items to find the cheapest item for discount.
+- **Loyalty Synergy**: Bridges with the Membership satellite to offer exclusive discounts based on the user's `membership_level`.
+
+---
+*Gravito Framework: Powering Commerce through Precision Engineering.*

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { ServiceProvider, Container } from '@gravito/core';
+
+declare class MarketingServiceProvider extends ServiceProvider {
+    register(container: Container): void;
+    getMigrationsPath(): string;
+    boot(): Promise<void>;
+}
+
+export { MarketingServiceProvider };

package/dist/index.js

@@ -0,0 +1,379 @@
+// src/index.ts
+import { join } from "path";
+import { fileURLToPath } from "url";
+import { ServiceProvider } from "@gravito/core";
+
+// src/Application/Services/CouponService.ts
+import { DB } from "@gravito/atlas";
+var CouponService = class {
+  constructor(core) {
+    this.core = core;
+  }
+  /**
+   * 根據代碼查找折價券
+   */
+  async findByCode(code) {
+    this.core.logger.info(`[CouponService] Looking up coupon: ${code}`);
+    return DB.table("coupons").where("code", code).first();
+  }
+  /**
+   * 計算折價券調整金額
+   */
+  async getAdjustment(code, _order) {
+    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 < /* @__PURE__ */ 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
+    };
+  }
+};
+
+// src/Application/Services/PromotionEngine.ts
+import { DB as DB3 } from "@gravito/atlas";
+
+// src/Application/Rules/BuyXGetYRule.ts
+var BuyXGetYRule = class {
+  /**
+   * config: { target_sku: 'IPHONE', x: 2, y: 1 }
+   * 意即：買 2 個 IPHONE 送 1 個 (折抵 1 個的價格)
+   */
+  match(order, config) {
+    if (!order.items || !Array.isArray(order.items)) {
+      return null;
+    }
+    const targetItems = order.items.filter((item) => item.props.sku === config.target_sku);
+    if (targetItems.length === 0) {
+      return null;
+    }
+    const totalQty = targetItems.reduce((sum, item) => sum + item.props.quantity, 0);
+    const unitPrice = targetItems[0].props.unitPrice;
+    const sets = Math.floor(totalQty / config.x);
+    const freeQuantity = sets * config.y;
+    if (freeQuantity > 0) {
+      return {
+        label: `Promotion: Buy ${config.x} Get ${config.y} Free (${config.target_sku})`,
+        amount: -(unitPrice * freeQuantity),
+        sourceType: "promotion",
+        sourceId: "buy_x_get_y"
+      };
+    }
+    return null;
+  }
+};
+
+// src/Application/Rules/CartThresholdRule.ts
+var CartThresholdRule = class {
+  /**
+   * config: { min_amount: 2000, discount: 200 }
+   */
+  match(order, config) {
+    const subtotal = Number(order.subtotalAmount);
+    if (subtotal >= config.min_amount) {
+      return {
+        label: `Promotion: Spend ${config.min_amount} Get ${config.discount} Off`,
+        amount: -config.discount,
+        // 負數代表折扣
+        sourceType: "promotion",
+        sourceId: "cart_threshold"
+      };
+    }
+    return null;
+  }
+};
+
+// src/Application/Rules/CategoryDiscountRule.ts
+var CategoryDiscountRule = class {
+  /**
+   * config: { category_id: 'electronics', discount_percent: 20 }
+   */
+  match(order, config) {
+    if (!order.items || !Array.isArray(order.items)) {
+      return null;
+    }
+    const eligibleItems = order.items.filter((item) => {
+      const path = item.props.options?.categoryPath || "";
+      return path.includes(`/${config.category_id}/`);
+    });
+    if (eligibleItems.length === 0) {
+      return null;
+    }
+    const eligibleTotal = eligibleItems.reduce(
+      (sum, item) => sum + item.props.totalPrice,
+      0
+    );
+    const discount = eligibleTotal * (config.discount_percent / 100);
+    if (discount > 0) {
+      return {
+        label: `Category Sale: ${config.category_id.toUpperCase()} Items ${config.discount_percent}% Off`,
+        amount: -discount,
+        sourceType: "promotion",
+        sourceId: "category_discount"
+      };
+    }
+    return null;
+  }
+};
+
+// src/Application/Rules/FreeShippingRule.ts
+var FreeShippingRule = class {
+  /**
+   * config: { min_amount: 1000 }
+   * 意即：滿 1000 元即享免運
+   */
+  match(order, config) {
+    const subtotal = Number(order.subtotalAmount);
+    if (subtotal >= config.min_amount) {
+      return {
+        label: `Free Shipping (Orders over ${config.min_amount})`,
+        amount: -60,
+        // 抵銷基礎運費
+        sourceType: "promotion",
+        sourceId: "free_shipping"
+      };
+    }
+    return null;
+  }
+};
+
+// src/Application/Rules/MembershipLevelRule.ts
+import { DB as DB2 } from "@gravito/atlas";
+var MembershipLevelRule = class {
+  /**
+   * config: { target_level: 'gold', discount_percent: 10 }
+   */
+  async match(order, config) {
+    if (!order.memberId) {
+      return null;
+    }
+    const member = await DB2.table("members").where("id", order.memberId).first();
+    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;
+  }
+};
+
+// src/Application/Services/PromotionEngine.ts
+var PromotionEngine = class {
+  constructor(core) {
+    this.core = core;
+  }
+  ruleFor(type) {
+    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) {
+    this.core.logger.info("[PromotionEngine] Calculating promotions...");
+    const applied = [];
+    const promotions = await DB3.table("promotions").where("is_active", true).orderBy("priority", "desc").get();
+    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;
+  }
+};
+
+// src/Application/UseCases/AdminListCoupons.ts
+import { UseCase } from "@gravito/enterprise";
+
+// src/Domain/Entities/Coupon.ts
+import { Entity } from "@gravito/enterprise";
+var Coupon = class _Coupon extends Entity {
+  _props;
+  constructor(props, id) {
+    super(id || crypto.randomUUID());
+    this._props = props;
+  }
+  static create(props, id) {
+    return new _Coupon(
+      {
+        ...props,
+        usedCount: 0
+      },
+      id
+    );
+  }
+  get code() {
+    return this._props.code;
+  }
+  get status() {
+    return this._props.status;
+  }
+  unpack() {
+    return { ...this._props };
+  }
+};
+
+// src/Application/UseCases/AdminListCoupons.ts
+var AdminListCoupons = class extends UseCase {
+  async execute() {
+    return [
+      Coupon.create({
+        code: "WELCOME2025",
+        name: "\u65B0\u5E74\u6B61\u8FCE\u79AE",
+        type: "PERCENTAGE",
+        value: 10,
+        minPurchase: 0,
+        startsAt: /* @__PURE__ */ new Date("2025-01-01"),
+        expiresAt: /* @__PURE__ */ new Date("2025-12-31"),
+        usageLimit: 1e3,
+        status: "ACTIVE"
+      }),
+      Coupon.create({
+        code: "SAVE500",
+        name: "\u6EFF\u984D\u6298\u62B5",
+        type: "FIXED",
+        value: 500,
+        minPurchase: 5e3,
+        startsAt: /* @__PURE__ */ new Date("2025-01-01"),
+        expiresAt: /* @__PURE__ */ new Date("2025-06-30"),
+        status: "ACTIVE"
+      })
+    ];
+  }
+};
+
+// src/Interface/Http/Controllers/AdminMarketingController.ts
+var AdminMarketingController = class {
+  constructor(core) {
+    this.core = core;
+  }
+  async coupons(ctx) {
+    try {
+      const useCase = this.core.container.make(
+        "marketing.usecase.adminListCoupons"
+      );
+      const coupons = await useCase.execute();
+      return ctx.json(
+        coupons.map((c) => ({
+          id: c.id,
+          ...c.unpack()
+        }))
+      );
+    } catch (error) {
+      return ctx.json({ message: error.message }, 500);
+    }
+  }
+};
+
+// src/index.ts
+var __dirname = fileURLToPath(new URL(".", import.meta.url));
+var MarketingServiceProvider = class extends ServiceProvider {
+  register(container) {
+    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() {
+    return join(__dirname, "Infrastructure/Persistence/Migrations");
+  }
+  async boot() {
+    const core = this.core;
+    if (!core) {
+      return;
+    }
+    const adminCtrl = core.container.make("marketing.controller.admin");
+    core.router.prefix("/api/admin/v1/marketing").group((router) => {
+      router.get("/coupons", (ctx) => adminCtrl.coupons(ctx));
+    });
+    const promoEngine = core.container.make("marketing.promotion-engine");
+    const couponService = core.container.make("marketing.coupon-service");
+    core.hooks.addFilter(
+      "commerce:order:adjustments",
+      async (adjustments, { order, extras }) => {
+        core.logger.info(`\u{1F3AF} [Marketing] \u6B63\u5728\u70BA\u8A02\u55AE ${order.id} \u6383\u63CF\u4FC3\u92B7\u8207\u6298\u50F9\u5238...`);
+        const results = [...adjustments];
+        const promoAdjustments = await promoEngine.applyPromotions(order);
+        results.push(...promoAdjustments);
+        if (extras?.couponCode) {
+          try {
+            const couponAdj = await couponService.getAdjustment(extras.couponCode, order);
+            if (couponAdj) {
+              results.push(couponAdj);
+            }
+          } catch (e) {
+            core.logger.warn(`\u26A0\uFE0F [Marketing] \u6298\u50F9\u5238\u7121\u6548: ${e.message}`);
+          }
+        }
+        return results;
+      }
+    );
+    core.hooks.addAction("commerce:order-placed", async (payload) => {
+      core.logger.info(`\u{1F4DD} [Marketing] \u8A02\u55AE ${payload.orderId} \u5DF2\u5EFA\u7ACB\uFF0C\u6B63\u5728\u8655\u7406\u6298\u50F9\u5238\u6838\u92B7...`);
+    });
+    core.logger.info("\u{1F6F0}\uFE0F Satellite Marketing is operational");
+  }
+};
+export {
+  MarketingServiceProvider
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@gravito/satellite-marketing",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external @gravito/core --external stripe --external @gravito/atlas --external @gravito/enterprise",
+    "test": "bun test",
+    "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck"
+  },
+  "dependencies": {
+    "@gravito/core": "workspace:*",
+    "stripe": "^20.1.0",
+    "@gravito/atlas": "workspace:*",
+    "@gravito/enterprise": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gravito-framework/gravito.git",
+    "directory": "satellites/marketing"
+  }
+}

package/src/Application/Rules/BuyXGetYRule.ts

@@ -0,0 +1,40 @@
+import type { IPromotionRule, MarketingAdjustment } from '../../Domain/Contracts/IPromotionRule'
+
+export class BuyXGetYRule implements IPromotionRule {
+  /**
+   * config: { target_sku: 'IPHONE', x: 2, y: 1 }
+   * 意即：買 2 個 IPHONE 送 1 個 (折抵 1 個的價格)
+   */
+  match(order: any, config: any): MarketingAdjustment | null {
+    if (!order.items || !Array.isArray(order.items)) {
+      return null
+    }
+
+    // 尋找目標商品
+    const targetItems = order.items.filter((item: any) => item.props.sku === config.target_sku)
+
+    if (targetItems.length === 0) {
+      return null
+    }
+
+    // 累計總數量與單價快照
+    const totalQty = targetItems.reduce((sum: number, item: any) => sum + item.props.quantity, 0)
+    const unitPrice = targetItems[0].props.unitPrice
+
+    // 計算符合幾組 (Buy X Get Y)
+    // 這裡我們實作最經典的：買 X 個，其中 Y 個免費
+    const sets = Math.floor(totalQty / config.x)
+    const freeQuantity = sets * config.y
+
+    if (freeQuantity > 0) {
+      return {
+        label: `Promotion: Buy ${config.x} Get ${config.y} Free (${config.target_sku})`,
+        amount: -(unitPrice * freeQuantity),
+        sourceType: 'promotion',
+        sourceId: 'buy_x_get_y',
+      }
+    }
+
+    return null
+  }
+}

package/src/Application/Rules/CartThresholdRule.ts

@@ -0,0 +1,21 @@
+import type { IPromotionRule, MarketingAdjustment } from '../../Domain/Contracts/IPromotionRule'
+
+export class CartThresholdRule implements IPromotionRule {
+  /**
+   * config: { min_amount: 2000, discount: 200 }
+   */
+  match(order: any, config: any): MarketingAdjustment | null {
+    const subtotal = Number(order.subtotalAmount)
+
+    if (subtotal >= config.min_amount) {
+      return {
+        label: `Promotion: Spend ${config.min_amount} Get ${config.discount} Off`,
+        amount: -config.discount, // 負數代表折扣
+        sourceType: 'promotion',
+        sourceId: 'cart_threshold',
+      }
+    }
+
+    return null
+  }
+}

package/src/Application/Rules/CategoryDiscountRule.ts

@@ -0,0 +1,40 @@
+import type { IPromotionRule, MarketingAdjustment } from '../../Domain/Contracts/IPromotionRule'
+
+export class CategoryDiscountRule implements IPromotionRule {
+  /**
+   * config: { category_id: 'electronics', discount_percent: 20 }
+   */
+  match(order: any, config: any): MarketingAdjustment | null {
+    if (!order.items || !Array.isArray(order.items)) {
+      return null
+    }
+
+    // 遍歷所有品項，尋找屬於該分類 (或其子分類) 的商品
+    // 注意：這裡假設 Order Item 中已經快照了商品的 categoryPath (由 Catalog 提供)
+    const eligibleItems = order.items.filter((item: any) => {
+      const path = item.props.options?.categoryPath || ''
+      return path.includes(`/${config.category_id}/`)
+    })
+
+    if (eligibleItems.length === 0) {
+      return null
+    }
+
+    const eligibleTotal = eligibleItems.reduce(
+      (sum: number, item: any) => sum + item.props.totalPrice,
+      0
+    )
+    const discount = eligibleTotal * (config.discount_percent / 100)
+
+    if (discount > 0) {
+      return {
+        label: `Category Sale: ${config.category_id.toUpperCase()} Items ${config.discount_percent}% Off`,
+        amount: -discount,
+        sourceType: 'promotion',
+        sourceId: 'category_discount',
+      }
+    }
+
+    return null
+  }
+}