YS PayNow Shipping for WooCommerce

整合 PayNow 物流服務至 WooCommerce，支援超商取貨與宅配。

版本資訊

當前版本：1.5.11 最後更新：2026-07-26 開發者：羊羊數位科技有限公司（YANGSHEEP DESIGN） 網站：https://yangsheep.com.tw 命名空間：yangsheep\paynow\shipping

功能特色

1. 超商取貨

• 7-11 交貨便（C2C） - 店到店
• 7-11 大智通（B2C） - 大宗寄倉
• 7-11 冷凍 - 冷凍店到店、冷凍大宗寄倉
• 全家店到店（C2C）
• 全家大宗寄倉（B2C）
• 全家冷凍 - 冷凍店到店、冷凍大宗寄倉
• 萊爾富 Hi-Life

2. 黑貓宅配

• 常溫宅配 - TCat Normal
• 冷藏宅配 - TCat Chilled
• 冷凍宅配 - TCat Frozen

3. 貨到付款支援

• PayNow 超取付款 - 超商取貨付款整合
• 自動偵測超取物流，限制僅顯示 PayNow 超取付款

4. 後台訂單管理

• 訂單 Meta Box - 顯示物流狀態、物流單號、門市資訊
• 一鍵建立託運單 - 支援 API 串接自動建立
• 批次列印標籤 - 訂單列表頁批次操作
• 貨態即時更新 - Cron 排程自動更新物流狀態

5. 前台功能

• 門市選擇器 - 超商地圖選擇門市
• CVS 欄位自動填入 - 門市名稱、代號、地址
• 我的帳號物流查詢 - 訂單詳情頁顯示物流狀態
• 手機號碼驗證 - 台灣手機格式驗證（09 開頭、10 位數字）

6. 結帳欄位處理

• 超取時自動隱藏帳單地址欄位
• 填入預設值通過 WooCommerce 驗證
• 支援 Block Checkout 區塊結帳
• 門市選擇後自動恢復已填欄位

檔案結構

ys-paynow-shipping/
├── assets/
│   ├── css/
│   │   └── ys-paynow-admin.css          # 後台樣式
│   └── js/
│       ├── ys-paynow-frontend.js        # 前台 JS（門市選擇、手機驗證）
│       └── ys-paynow-admin.js           # 後台 JS
├── src/
│   ├── admin/
│   │   ├── YSAdminPrint.php             # 標籤列印
│   │   ├── YSOrderEdit.php              # 訂單編輯頁
│   │   ├── YSOrderListTable.php         # 訂單列表頁
│   │   └── YSOrderMetaBox.php           # 物流 Meta Box
│   ├── api/
│   │   ├── YSShippingRequest.php        # API 請求（建立託運單）
│   │   └── YSShippingResponse.php       # API 回應（回傳處理）
│   ├── cron/
│   │   └── YSStatusUpdater.php          # 排程更新物流狀態
│   ├── frontend/
│   │   ├── YSMyAccount.php              # 我的帳號頁面
│   │   └── YSStoreSelector.php          # 門市選擇器
│   ├── gateways/
│   │   └── YSGatewayPaynowCOD.php       # PayNow 超取付款閘道
│   ├── providers/
│   │   ├── YSAbstractShipping.php       # 物流抽象類別
│   │   ├── YSShipping711.php            # 7-11 交貨便
│   │   ├── YSShipping711Bulk.php        # 7-11 大智通
│   │   ├── YSShipping711BulkFrozen.php  # 7-11 大智通冷凍
│   │   ├── YSShipping711Frozen.php      # 7-11 冷凍
│   │   ├── YSShippingFamily.php         # 全家店到店
│   │   ├── YSShippingFamilyBulk.php     # 全家大宗寄倉
│   │   ├── YSShippingFamilyBulkFrozen.php # 全家大宗冷凍
│   │   ├── YSShippingFamilyFrozen.php   # 全家冷凍
│   │   ├── YSShippingHilife.php         # 萊爾富
│   │   ├── YSShippingTcatChilled.php    # 黑貓冷藏
│   │   ├── YSShippingTcatFrozen.php     # 黑貓冷凍
│   │   └── YSShippingTcatNormal.php     # 黑貓常溫
│   ├── settings/
│   │   └── YSSettingsTab.php            # WooCommerce 設定頁籤
│   ├── utils/
│   │   ├── YSLogisticService.php        # 物流服務工具
│   │   ├── YSOrderMeta.php              # 訂單 Meta 常數
│   │   ├── YSOrderStatus.php            # 訂單狀態工具
│   │   └── YSShippingStatus.php         # 物流狀態對應
│   └── YSPaynowShipping.php             # 主要類別
├── vendor/                              # Composer 依賴
├── README.md                            # 本檔案
└── ys-paynow-shipping.php               # 主外掛檔案

物流方式與 Method ID

訂單 Meta 欄位

// 檔案：src/utils/YSOrderMeta.php

const StoreId            = '_ys_paynow_store_id';              // 門市代號
const StoreName          = '_ys_paynow_store_name';            // 門市名稱
const StoreAddr          = '_ys_paynow_store_addr';            // 門市地址
const StoreTel           = '_ys_paynow_store_tel';             // 門市電話
const STORE_DATA_JSON    = '_ys_paynow_store_data_json';       // 門市 JSON
const LogisticServiceId  = '_ys_paynow_logistic_service_id';   // 物流服務 ID
const LogisticService    = '_ys_paynow_logistic_service';      // 物流服務名稱
const LogisticNumber     = '_ys_paynow_logistic_number';       // 物流單號
const PaymentNo          = '_ys_paynow_payment_no';            // 託運單號
const ValidationNo       = '_ys_paynow_validation_no';         // 驗證碼
const Status             = '_ys_paynow_status';                // 訂單狀態
const DeliveryStatus     = '_ys_paynow_delivery_status';       // 物流狀態描述
const LogisticCode       = '_ys_paynow_logistic_code';         // 物流狀態碼
const DetailStatusDesc   = '_ys_paynow_detail_status_desc';    // 狀態詳細描述
const StatusUpdateAt     = '_ys_paynow_status_update_at';      // 最後更新時間
const DeliveryType       = '_ys_paynow_delivery_type';         // 宅配溫層
const DeliveryTime       = '_ys_paynow_delivery_time';         // 配送時段

核心類別說明

YSPaynowShipping

主要類別，負責：

• 初始化所有子系統
• 註冊物流方式到 WooCommerce
• 載入前後端資源

YSAbstractShipping

物流抽象類別，提供：

• 共用的物流設定欄位
• 運費計算邏輯
• 可用性判斷（重量、金額、地區限制）

YSStoreSelector

門市選擇器，處理：

• 超商地圖跳轉
• 門市資料回傳接收
• CVS 欄位動態控制
• 結帳欄位保存與恢復（sessionStorage）

YSShippingRequest

API 請求類別：

• 建立託運單 API 呼叫
• 標籤列印 API
• 錯誤處理與重試

YSShippingResponse

API 回應處理：

• 物流商回傳通知（Callback）
• 貨態更新儲存
• 訂單狀態自動變更

YSStatusUpdater

排程更新：

• WP-Cron 排程查詢物流狀態
• 批次更新未完成訂單
• 貨態變更通知

手機號碼驗證機制

前端驗證（JS）

位置：assets/js/ys-paynow-frontend.js

initMobilePhoneValidation: function() {
    // 綁定 input/blur/submit 事件
},

validateMobilePhone: function($input, showError) {
    // 驗證格式：必須是 09 開頭的 10 位數字
    var isValid = /^09\d{8}$/.test(numericValue);
    // ...
}

後端驗證（PHP）

位置：src/YSPaynowShipping.php

add_action( 'woocommerce_checkout_process', array( __CLASS__, 'validate_shipping_fields' ) );

public static function validate_shipping_fields() {
    // 驗證 shipping_phone 格式
    if ( ! preg_match( '/^09\d{8}$/', $phone ) ) {
        wc_add_notice( '錯誤訊息', 'error' );
    }
}

CVS 欄位自動隱藏

選擇超取物流時，自動處理：

1. 隱藏地址欄位（可在設定中開關）

   • shipping_postcode、shipping_state、shipping_city
   • shipping_address_1、shipping_address_2
   • billing_* 相關欄位

2. 填入預設值

   • country = TW
   • address_1 = N/A 或 超商取貨

3. 移除必填驗證

   • 動態設定 required = false
   • 移除 validate-required class

4. Block Checkout 支援

   • 透過 wp.data.dispatch('wc/store/cart') 操作
   • 備用 DOM 直接操作方案

與其他外掛的整合

YANGSHEEP 結帳強化外掛

• 物流狀態卡片顯示（前台訂單詳情）
• 貨態進度條
• 物流單號複製功能
• 手動配送 Meta Box 自動隱藏（YS PayNow 物流訂單不顯示）

相容性注意

• 保留標準 WooCommerce Action Hooks
• 使用標準 shipping_method[...] input name
• 支援 HPOS（High-Performance Order Storage）

設定選項

WooCommerce > 設定 > 運送 > YS PayNow

版本紀錄

v1.5.11 (2026-07-28)

• Hub Client 2.0.5：移除 vendor library 無效的 HPOS 宣告；PayNow Shipping 主外掛原有的 HPOS 相容宣告保持不變。

v1.5.10 (2026-07-25)

• 設定頁版型收斂 — 採用結帳強化的 1200px 設定骨架、品牌頁首、連續頁籤／內容卡片、統一欄位尺寸與表單動作列；PayNow 設定鍵、儲存流程與物流功能不變。
• Hub Client 2.0.4 — 舊版 Client 先載入時仍校正 電商工具箱 的名稱、商店圖示與位置，並固定將「系統資訊」「聯絡我們」排在最後。
• 發佈契約 — 新增可重跑 UI contract；測試、Composer 與內部文件透過 export-ignore 排除正式 ZIP。

v1.5.9 (2026-07-25)

• 修正：父選單正名「電商工具箱」 — Hub Client 升級 2.0.3，ys-toolbox 頂層選單中央統一註冊為「電商工具箱」（dashicons-store、位置 56，與開發準則 §4 一致）；外掛端補 label 校正，同站若有尚未更新的舊版 Hub Client（≤2.0.2 先以「YS Plugin」註冊同一 slug）也會統一改回「電商工具箱」。與其他工具箱成員外掛（結帳強化 v1.7.7+ 等）共存時無論載入順序，選單名稱、圖示與位置一致。

v1.3.0 (2026-03-12)

安全修正

• Webhook Token Fail-Close — Token 未設定時自動產生並拒絕請求（HTTP 403），不再跳過驗證；使用 hash_equals() 防時序攻擊
• API 回應 Sanitize — 取消物流單/更換超商失敗時，API 回應體寫入訂單備註前以 wp_strip_all_tags() 過濾，防止 Stored XSS
• 前端通知安全 — 後台 JS 通知訊息統一使用 jQuery .text() 而非 .html()，防止 DOM XSS

重構

• 命名空間全面小寫化 — YangSheep\PayNow\Shipping → yangsheep\paynow\shipping，確保 Linux 檔案系統相容性
• 目錄名稱小寫化 — src/ 下所有子目錄（Admin → admin、Api → api 等 8 個）統一為小寫
• Gateway 類別更名 — WCGatewayPaynowCOD → YSGatewayPaynowCOD，符合 YS 前綴命名規範
• PassCode 模式統一 — build_pass_code() 方法明確區分 'new'（建立）與 'cancel'（取消）模式
• Webhook URL 標準化 — 統一使用 WC()->api_request_url() 取代手動 get_site_url() 拼接
• 移除未使用常數 — YS_PAYNOW_SHIPPING_TEMPLATE_DIR（已無 templates 目錄）
• CSS/JS 文件標籤更新 — @package 統一為小寫命名空間

改進

• 列印狀態標記優化 — GET 方法（C2C 超商）改為確認 API 成功回傳有效 URL 後才標記已列印

清理

• 移除空目錄：languages/、templates/
• 更新跨外掛引用（yangsheep-checkout-optimizer 的 class_exists 檢查）

文件

• 新增 DEVELOPMENT.md 完整開發文件（架構說明、類別文檔、資料流程、Hooks 參考）
• 更新 README.md 檔案結構樹、Meta 欄位表與版本紀錄

v1.2.0 (2026-02-06)

修復

• Webhook 端點 URL 修正 - 回傳網址從 ys-paynow-shipping-callback 更正為 ys-paynow-response
• CRON 排程三項修正 - Status 判斷 'S'→'1'、欄位名 DeliveryStatus→Delivery_Status、回應解析修正
• 前台進度條回退 BUG - 宅配訂單按下「更新貨態」後進度線條從運送中退回商品準備中的問題，改為根據流程類型（宅配 4 步驟 / 超取 5 步驟）動態計算進度百分比
• 訂單列表 / 我的帳號物流狀態關鍵字 - get_status_class() 新增轉運、理貨、暫置等運送中狀態判斷

新增

• 黑貓物流狀態碼 - 新增 4060（理貨中）、4500（集貨轉運中）、5500（配送中）、5505（暫置營業所）、8500（配送完成）、8520（收退）
• 後台查詢同步 WC 訂單狀態 - 管理員查詢貨態時自動更新 WooCommerce 訂單狀態
• Webhook php://input 備援 - $_POST 為空時自動使用 php://input 讀取回傳內容

改進

• 前端顯示託運單號 - 前台訂單詳情頁優先顯示託運單號（PaymentNo），非物流單號（LogisticNumber），標籤動態切換
• CRON 排程頻率提高 - 從每日一次改為每 6 小時一次，加速物流狀態同步
• API 完整 LOG 紀錄 - 管理員查詢、前台用戶查詢、建立物流單、CRON 排程均記錄完整 API 回應

技術變更

• YSStatusUpdater.php - 自訂 every_six_hours cron interval，自動移除舊的 daily 排程
• YSShippingRequest.php - AJAX 回應改為 flow_type-aware 動態進度計算
• YSPaynowShipping.php - 新增 $display_no / $display_label 邏輯
• ys-paynow-frontend.js - 複製按鈕 toast 改為「單號已複製！」
• YSShippingStatus.php - 新增 6 個黑貓狀態碼對應

v1.1.0 (2026-01-12)

• 新增：手機號碼驗證（09 開頭、10 位數字）
• 新增：前端 JS 即時驗證 + 後端 PHP 驗證
• 優化：門市選擇後自動恢復已填欄位（sessionStorage）
• 優化：Block Checkout 支援

v1.0.9 (2026-01-10)

• 新增：全家冷凍大宗寄倉
• 新增：7-11 冷凍大宗寄倉
• 優化：貨態對應表更新

v1.0.8 (2026-01-08)

• 新增：我的帳號物流狀態顯示
• 新增：貨態進度條 UI
• 優化：排程更新效能

v1.0.5 (2026-01-05)

• 新增：黑貓宅配（常溫/冷藏/冷凍）
• 新增：訂單列表頁批次列印
• 修復：API 逾時處理

v1.0.0 (2026-01-01)

• 首發：7-11、全家、萊爾富超商取貨
• 首發：PayNow 超取付款閘道
• 首發：後台訂單管理功能

開發者

羊羊數位科技有限公司（YANGSHEEP DESIGN） https://yangsheep.com.tw