Recently Viewed Product 模組使用指南

⚠️ 內部使用套件 - 此套件僅供 Astral Web 內部使用，未經授權不得用於其他用途。

概覽

Recently Viewed Product 是一個 Nuxt 3 模組，提供完整的最近瀏覽商品追蹤與管理功能。模組採用 Nuxt Module 架構設計，支援本地儲存與伺服器同步、訪客與會員資料自動合併，並提供靈活的配置選項。

安裝與設定

1. 安裝套件

在 apps/web 和 apps/server 安裝

yarn add @astralweb/nova-recently-viewed-product

2. Middleware 擴充

// apps/server/extendApiMethods/index.ts

export {
  recentlyViewedProducts,
  addRecentlyViewedProducts,
} from '@astralweb/nova-recently-viewed-product/api';

3. 註冊模組

// apps/web/nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    '@astralweb/nova-recently-viewed-product',
  ],
})

架構設計

三層架構

1. API Layer (useRecentlyViewedApi)

   • 處理與 GraphQL 後端的通信
   • 提供 syncToServer 和 fetchFromServer 方法

2. Storage Layer (useRecentlyViewedStorage)

   • 管理本地儲存與核心業務邏輯
   • 處理訪客/會員資料合併
   • 提供完整的 CRUD 操作

3. List Layer (useRecentlyViewedList)

   • 高階封裝，適用於產品詳情頁
   • 自動處理初始化、登入狀態變化、SKU 更新
   • 提供開箱即用的體驗

使用方式

適合產品詳情頁，自動處理所有邏輯。

<template>
  <ProductSlider :products-sku="recentlyViewedSkus" />
</template>

<script setup lang="ts">
const { recentlyViewedSkus } = useRecentlyViewedList({
  currentSku: computed(() => product.value?.sku ?? ''),
  isLoggedIn: computed(() => !!user.value),
  enableServerSync: true,
});
</script>

自動處理：

• ✅ 組件掛載時初始化
• ✅ SKU 變化時更新列表
• ✅ 登入狀態變化時合併資料
• ✅ 本地緩存優化

API 參考

useRecentlyViewedList

const { recentlyViewedSkus } = useRecentlyViewedList({
  currentSku: Ref<string> | ComputedRef<string>,
  isLoggedIn: ComputedRef<boolean>,
  maxItems?: number,              // 預設：20
  guestStorageKey?: string,       // 預設：'recently-viewed-guest'
  customerStorageKey?: string,    // 預設：'recently-viewed-customer'
  enableServerSync?: boolean,     // 預設：true
  autoInit?: boolean,             // 預設：true
});

返回值：

• recentlyViewedSkus: Ref<string[]> - 最近瀏覽商品的 SKU 列表

useRecentlyViewedStorage

核心 composable，提供完整的儲存管理功能。

const {
  addRecentlyViewed,
  getRecentlyViewedSkus,
  getSkusFromLocalStorage,
  clearAllRecentlyViewed,
  mergeGuestToCustomer,
  isLoggedIn,
} = useRecentlyViewedStorage(config, isLoggedIn);

配置選項：

interface RecentlyViewedConfig {
  maxItems?: number;              // 最多儲存數量（預設：20）
  guestStorageKey?: string;       // 訪客 localStorage key
  customerStorageKey?: string;    // 會員 localStorage key
  enableServerSync?: boolean;     // 啟用伺服器同步（預設：true）
}

方法：

• addRecentlyViewed(sku: string): Promise<void> - 添加商品到最近瀏覽
• getRecentlyViewedSkus(excludeSku?: string): Promise<string[]> - 獲取 SKU 列表（伺服器優先）
• getSkusFromLocalStorage(excludeSku?: string): string[] - 從本地儲存獲取 SKU 列表
• clearAllRecentlyViewed(): void - 清除所有記錄
• mergeGuestToCustomer(): Promise<void> - 合併訪客資料到會員帳戶

useRecentlyViewedApi

API 層 composable，處理與後端的通信。

const {
  syncToServer,
  fetchFromServer,
} = useRecentlyViewedApi();

方法：

• syncToServer(input: AddRecentlyViewedInputItem[]): Promise<void> - 同步資料到伺服器
• fetchFromServer(): Promise<AddRecentlyViewedInputItem[]> - 從伺服器獲取資料

工作原理

訪客模式

• 資料保存在 localStorage（key: recently-viewed-guest）
• 不進行伺服器同步
• 本地去重與數量限制

登入模式

• 主要資料來源：伺服器
• 本地緩存：加速 UI 更新
• 新增時：同步到伺服器 → 更新本地緩存

登入時資料合併

1. 讀取訪客 localStorage 資料
2. 同步到伺服器（合併到會員帳戶）
3. 清除訪客資料
4. 從伺服器獲取最新資料

授權

此套件僅供 Astral Web 內部使用，未經授權不得用於其他用途。