7-ELEVEN WDS 電子地圖整合模組使用指南

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

概覽

7-ELEVEN 超商取貨電子地圖（WDS）整合模組為 Nuxt 應用程式提供完整的 7-ELEVEN 門市選擇功能，支援桌機版與手機版電子地圖、自動處理回調資料格式轉換。模組設計簡潔易用，提供自動註冊 composable 和 server route，並提供完整的 TypeScript 型別支援。

功能特色

• 整合 7-ELEVEN WDS 電子地圖門市選擇
• 支援桌機版與手機版電子地圖
• 自動處理回調資料格式轉換

安裝與設定

1. 安裝套件

在 apps/web 安裝

yarn add @astralweb/nova-e-map-wds

2. 註冊模組

在 nuxt.config.ts 中註冊模組

// apps/web/nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@astralweb/nova-e-map-wds',
  ],
});

3. 模組配置選項（可選）

// apps/web/nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@astralweb/nova-e-map-wds',
  ],
  emapWds: {
    // 回調後重導向路徑（預設：'/checkout'）
    redirectPath: '/checkout',
    // Cookie 有效期（秒）（預設：60）
    cookieMaxAge: 60,
  },

  // 多語系支援（專案級別設定）
  runtimeConfig: {
    public: {
      multiLocales: true,
    },
  },
});

使用方式

基本使用

<script setup lang="ts">
import type { EMapWDSConfig } from '@astralweb/nova-e-map-wds/types';

// 從 Magento storeConfig 取得設定
const config: EMapWDSConfig = {
  eshopId: 'your_shop_id',
  eshopParId: 'your_parent_id',
  eshopPwd: 'your_password',
  emapEndpoint: 'https://emap.pcsc.com.tw/ecmap/default.aspx',
  emapMobileEndpoint: 'https://emap.pcsc.com.tw/ecmap/default.aspx',
  storeCategory: '1',
};

const {
  selectedStore,
  hasSelectedStore,
  openEMap,
  setSelectedStore,
  clearSelectedStore,
  readCallbackCookie,
} = useEMapWDS({ config });

// 開啟電子地圖選擇門市（會跳轉頁面）
const handleSelectStore = () => {
  openEMap();
};

// 處理回調資料（通常在 checkout 頁面的 onMounted 中處理）
// 回調資料會存在 Cookie 中，有效期 60 秒
onMounted(() => {
  const callbackData = readCallbackCookie();
  if (callbackData) {
    setSelectedStore(callbackData);
  }
});
</script>

<template>
  <div>
    <button @click="handleSelectStore">選擇門市</button>

    <div v-if="hasSelectedStore">
      <p>門市代碼：{{ selectedStore?.storeId }}</p>
      <p>門市名稱：{{ selectedStore?.storeName }}</p>
      <p>門市地址：{{ selectedStore?.storeAddress }}</p>
      <button @click="clearSelectedStore">清除選擇</button>
    </div>
  </div>
</template>

從 Magento storeConfig 取得設定

import { mapStoreConfigToEMapWDSConfig } from '@astralweb/nova-e-map-wds/types';

// 假設 storeConfig 來自 Magento GraphQL
const storeConfig = {
  seven_eleven_shipping_e_shop_id: 'shop_id',
  seven_eleven_shipping_e_shop_pid: 'parent_id',
  seven_eleven_shipping_e_shop_pwd: 'password',
  seven_eleven_shipping_emap_endpoint: 'https://emap.pcsc.com.tw/ecmap/default.aspx',
  seven_eleven_shipping_emap_mobile_endpoint: 'https://emap.pcsc.com.tw/ecmap/default.aspx',
  seven_eleven_shipping_store_category: '1',
};

const emapConfig = mapStoreConfigToEMapWDSConfig(storeConfig);

使用工具函數驗證回調資料

import {
  isWDSData,
  convertWDSToUnified,
  parseWDSCallback,
} from '@astralweb/nova-e-map-wds/utils';

// 檢查是否為 WDS 資料格式
if (isWDSData(callbackData)) {
  const unified = convertWDSToUnified(callbackData);
  console.log(unified.storeId);
}

// 或使用 parseWDSCallback 一次完成驗證和轉換
const result = parseWDSCallback(callbackData);
if (result) {
  console.log(result.storeId);
}

型別定義

EMapWDSConfig

interface EMapWDSConfig {
  eshopId: string; // 統一超商商店 ID
  eshopParId: string; // 統一超商 Parent ID
  eshopPwd: string; // 統一超商密碼
  emapEndpoint: string; // 桌機版電子地圖 URL
  emapMobileEndpoint: string; // 手機版電子地圖 URL
  storeCategory: string; // 門市類型
}

WDSEMapData（原始回調格式）

interface WDSEMapData {
  storeid: string; // 門市代碼
  storename: string; // 門市名稱
  storeaddress: string; // 門市地址
  outside: string; // 外部區域
  ship: string; // 配送方式
  TempVar: string; // 時間戳記
}

UnifiedEMapData（統一格式）

interface UnifiedEMapData {
  storeId: string; // 門市代碼
  storeName: string; // 門市名稱
  storeAddress: string; // 門市地址
  shippingMethod: 'sevenelevenstoredelivery';
}

API 參考

useEMapWDS(options)

選項

| 參數 | 型別 | 預設值 | 說明 | | -------------- | --------------- | ------------- | ---------------- | | config | EMapWDSConfig | 必填 | WDS 電子地圖設定 | | callbackPath | string | '/emap/wds' | 回調 URL 路徑 |

回傳值

| 屬性 | 型別 | 說明 | | -------------------- | ----------------------------------------- | --------------------- | | selectedStore | Ref<UnifiedEMapData \| null> | 已選擇的門市資料 | | hasSelectedStore | ComputedRef<boolean> | 是否已選擇門市 | | openEMap | (isMobile?: boolean) => void | 開啟電子地圖選擇器 | | setSelectedStore | (data: UnifiedEMapData \| null) => void | 設定已選擇的門市 | | clearSelectedStore | () => void | 清除已選擇的門市 | | readCallbackCookie | () => UnifiedEMapData \| null | 讀取並清除回調 Cookie | | getFormData | () => FormData | 產生 WDS API FormData | | getEndpoint | (isMobile?: boolean) => string | 取得電子地圖 URL |

Server Route

模組會自動註冊 /emap/wds POST 路由來處理 WDS 回調（符合 7-ELEVEN WDS 實際回調方式）。

回調流程

1. 用戶在 WDS 電子地圖選擇門市
2. WDS 系統 POST 資料到 /emap/wds
3. Server 將門市資料存入 Cookie（有效期 60 秒）
4. 重導向回 /checkout
5. 前端使用 readCallbackCookie() 讀取門市資料

Cookie 格式

• Cookie 名稱：eMap
• 有效期：60 秒（可透過 cookieMaxAge 配置）
• 內容：JSON 格式的 UnifiedEMapData

多語系支援

模組使用專案級別的 runtimeConfig.public.multiLocales 設定（與 line-pay 等其他模組共用）。

當 multiLocales: true 時，模組會：

1. 讀取 i18n_redirected cookie 取得當前語系
2. 自動在重導向路徑前加上語系前綴（如 /zh-Hant-TW/checkout）

// apps/web/nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      multiLocales: true, // 設定後所有模組共用
    },
  },
});

Magento GraphQL 欄位

需要在 Magento storeConfig 查詢中加入以下欄位：

query {
  storeConfig {
    seven_eleven_shipping_e_shop_id
    seven_eleven_shipping_e_shop_pid
    seven_eleven_shipping_e_shop_pwd
    seven_eleven_shipping_emap_endpoint
    seven_eleven_shipping_emap_mobile_endpoint
    seven_eleven_shipping_store_category
  }
}

授權聲明

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