open-index/open-npm huggingface dataset:
npm package: @gravito/satellite-cart
Description: 這是 Gravito Galaxy 的高效購物車持久化模組。它支援多設備同步、訪客合併以及針對高併發場景的「三段式推進」存儲策略。
Latest version: 0.2.0

# @gravito/satellite-cart 🛒

這是 Gravito Galaxy 的高效購物車持久化模組。它支援多設備同步、訪客合併以及針對高併發場景的「三段式推進」存儲策略。

## 🌟 核心特性

- **跨設備持久化**: 支援會員與訪客身分識別，購物車不再隨瀏覽器關閉而消失。
- **自動合併邏輯**: 偵測到會員登入後，自動將訪客期間加購的品項合併至會員帳戶。
- **三段式存儲**:
  - **Standard**: SQL 存儲（預設）。
  - **Sport**: Session / 內存快取。
  - **Turbo**: Redis 叢集存儲（百萬併發適用）。
- **無縫 Hook 聯動**: 監聽身分衛星事件，實現零代碼侵入的購物車轉移。

## 🚀 快速上手

### 1. API 使用
- **GET `/api/cart`**: 獲取購物車。
  - 訪客請帶 Header: `X-Guest-ID: <UUID>`。
- **POST `/api/cart/items`**: 加購。
  - Body: `{ variantId: "uuid", quantity: 1 }`

## 🔗 Galaxy 聯動

本插件監聽以下事件：
- **Action**: `member:logged-in` -> 觸發 `MergeCart` UseCase。
npm package: @gravito/satellite-commerce
Description: 這是 Gravito Galaxy 的核心交易與訂單引擎。它專為高性能電商場景設計，具備金融級的原子性保證與「渦輪增壓」擴展能力。
Latest version: 0.2.0

# @gravito/satellite-commerce 🛰️

這是 Gravito Galaxy 的核心交易與訂單引擎。它專為高性能電商場景設計，具備金融級的原子性保證與「渦輪增壓」擴展能力。

## 🌟 核心特性

- **原子化下單**: 訂單、明細、庫存預扣在單一資料庫事務中完成。
- **樂觀鎖 (Optimistic Locking)**: 內建 `version` 校驗，無需 Redis 即可應對中併發搶購，徹底杜絕超賣。
- **價格快照 (Snapshotting)**: 訂單明細紀錄結帳當下的單價，防止商品調價引起的財務糾紛。
- **調整項系統 (Adjustments)**: 靈活處理運費、折扣、稅金，支援行銷插件動態注入。
- **Galaxy Hook 聯動**: 預留多個掛載點，輕鬆串接紅利、點數、郵件與物流系統。

## 🚀 快速上手

### 1. 安裝
```bash
# 在您的 Gravito 專案中
bun add @gravito/satellite-commerce
```

### 2. 註冊插件
```typescript
import { CommerceServiceProvider } from '@gravito/satellite-commerce'

await core.use(new CommerceServiceProvider())
```

### 3. API 接口
- **POST `/api/commerce/checkout`**: 下單結帳
  - Header `X-Idempotency-Key`: 確保請求冪等。
  - Body: `{ items: [{ variantId: 'uuid', quantity: 1 }] }`

## 🔗 Hook 清單 (Galaxy 擴充)

| Hook 名稱 | 類型 | 描述 | Payload / Return |
| :--- | :--- | :--- | :--- |
| `commerce:order:adjustments` | Filter | 行銷插件注入折扣或加價 | `(adjustments[], { order })` |
| `commerce:order-placed` | Action | 訂單建立後觸發 (紅利/發信) | `{ orderId: string }` |
| `rewards:assigned` | Action | 紅利分配完成後的後續動作 | `{ memberId, points }` |

## 🏎️ 渦輪增壓模式 (Turbo Mode)
本模組支援「秒開渦輪」。當環境變數 `COMMERCE_MODE=turbo` 時，可切換為 Redis 預扣與非同步隊列模式（需安裝 turbo-engine 擴展包）。

## 📚 設計文檔

### [DESIGN_DECISIONS.md](./DESIGN_DECISIONS.md)

詳細的架構設計決策，包括：
- **Flash-Sale 依賴集成** - 為什麼透過 DI 整合而非事件驅動
- **調整項系統** - 靈活費用管理與行銷插件擴展
- **樂觀鎖庫存** - 高併發無鎖設計
- **訂單快照** - 防止調價糾紛的財務追蹤機制
- **Galaxy Hook 整合** - 跨 Satellite 功能擴展
- **v2.0.0 演進路線** - 未來完全事件驅動的評估計畫

建議在修改商業邏輯前閱讀此文檔，了解設計權衡。
npm package: @gravito/satellite-marketing
Description: 這是 Gravito Galaxy 的行銷與促銷規則引擎。它設計用於在不侵入核心交易邏輯的前提下，動態注入折扣、折價券與贈品。
Latest version: 0.2.0

# @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` (用於核銷折價券次數)
npm package: @gravito/satellite-membership
Description: 這是 Gravito 生態系中的標準會員管理衛星模組（Satellite）。基於 **DDD (領域驅動設計)** 與 **Galaxy Architecture** 構建，專為高效能、高擴展性與 Bun 原生環境優化。
Latest version: 0.2.0

# 🛰️ Gravito Membership Satellite

這是 Gravito 生態系中的標準會員管理衛星模組（Satellite）。基於 **DDD (領域驅動設計)** 與 **Galaxy Architecture** 構建，專為高效能、高擴展性與 Bun 原生環境優化。

## ✨ 核心功能

- **身分驗證 (Auth)**: 整合 Sentinel 模組，支援 Session 登入與 **持久化 (Remember Me)**。
- **註冊流程**: 包含自動生成驗證權杖與電子郵件發送 Hook。
- **安全防護**:
  - **多設備登入限制 (Single Device Login)**: 可開關功能，自動註冊並踢除舊裝置。
  - **密碼安全**: 使用 Bun 原生加密，支援自動 Rehash。
  - **Passkeys (WebAuthn)**: 內建 Passkeys 登錄 + 登入 API，可配合 `@simplewebauthn/browser` 與瀏覽器原生驗證器。
- **美化郵件 (Beautiful Emails)**:
  - 使用 Prism 模板引擎。
  - 支援現代化 HTML 佈局。
  - 完整多語系支持 (i18n)。
- **動態 Metadata**: 會員實體支援無 Schema 的元數據擴展，適合電商、訂閱制等場景。

## 🚀 快速開始

... (內容省略) ...

## 🛠️ 擴充與自定義 (DX Guide)

想要自定義品牌、覆寫郵件樣式或增加業務邏輯？請參考我們的：
👉 [**Membership 擴充與自定義指南 (EXTENDING.md)**](./docs/EXTENDING.md)

想要使用 Passkeys？請參考：
👉 [**Passkeys Integration Guide (PASSKEYS.md)**](./docs/PASSKEYS.md)

## ⚙️ 配置選項

在 `core` 配置中調整以下開關：

```typescript
{
  membership: {
    auth: {
      // 是否限制帳號只能在單一裝置登入
      single_device: true, 
      // 是否啟用持久化登入 (Remember Me)
      remember_me: true
    },
    branding: {
      name: 'Your Project Name',
      primary_color: '#3b82f6' // Tailwind Blue 500
    }
  },
  app: {
    url: 'https://yourapp.com'
  }
}
```

## 🎨 自定義模板

本模組提供預設的郵件模板。如果您想更換設計，只需在您的專案中建立以下檔案，Prism 會優先使用您的檔案：

- `views/emails/welcome.html`
- `views/emails/reset_password.html`
- `views/emails/level_changed.html`

模板中可以使用 `{{ branding.name }}` 和 `{{ branding.color }}` 來保持一致性。

本模組不強制綁定郵件驅動，而是透過 Hook 觸發動作。若您啟用了 `OrbitSignal`，本模組會自動處理以下 Hook：

- `membership:send-verification`: 發送註冊驗證郵件。
- `membership:send-reset-password`: 發送密碼重設郵件。
- `membership:level-changed`: 當會員等級提升時發送慶祝郵件。

## 📦 隊列整合 (Queue Integration)

為了獲得最佳效能，建議掛載 `OrbitStream` 來啟用非同步發信。本模組已預設呼叫 `mail.queue()`。

### 1. 安裝隊列軌道
```typescript
import { OrbitStream } from '@gravito/stream'

await core.orbit(new OrbitStream({
  default: 'redis',
  connections: {
    redis: { driver: 'redis', host: 'localhost' }
  }
}))
```

### 2. 運作原理
- **有隊列時**: 郵件動作會被推入 `default` 隊列，API 請求會立即回傳。
- **無隊列時**: 系統會自動降級為同步發送（Sync Send），確保功能不中斷。

## 🛠️ API 使用範例

### 會員註冊
```typescript
const register = container.make('membership.register')
await register.execute({
  name: 'Carl',
  email: 'carl@example.com',
  passwordPlain: 'secret123'
})
```

### 多設備登入檢查 (Middleware)
您可以將此中間件應用於敏感路由：
```typescript
import { verifySingleDevice } from '@gravito/satellite-membership/middleware'

router.get('/profile', verifySingleDevice, (c) => { ... })
```

## 📄 授權
MIT License