YANGSHEEP 結帳強化 WP Registry grade A. No security issues foundWP RegistryNo security issues foundOpen the reportA

優化 WooCommerce 結帳頁面、我的帳號、訂單頁面的 WordPress 外掛。

版本資訊

當前版本：1.7.11 最後更新：2026-08-27 開發者：羊羊數位科技有限公司 網站：https://yangsheep.com.tw

功能特色

1. 結帳頁面優化

• 結帳頁面漸進式重新佈局 - 保留 WooCommerce 標準 Hook/模板，前端契約完整時才啟用 YS 版面
• 桌機版 Flex 佈局 - sidebar 20% + form 80%
• TWzipcode 整合 - 台灣地址選擇器自動帶入郵遞區號

2. 結帳欄位設置

• 關閉 Last Name - 啟用後只顯示「姓名」欄位（使用 First Name），適合台灣使用習慣
• 台灣化欄位 - 帳單欄位簡化為姓名、電話、電子郵件；運送欄位調整為台灣格式
• 收件人電話必填 - 收件人區塊的電話欄位預設為必填
• 手機號碼驗證 - 台灣手機格式驗證（09 開頭、10 位數字），前後端雙重驗證
• 訂單備註開關 - 用戶需勾選「我需要填寫訂單備註」才顯示備註欄位

3. 物流卡片選擇

• 以卡片式 proxy 操作 WooCommerce 原生物流 Radio；原生欄位仍是唯一提交來源
• AJAX 即時更新，地址變更時自動重新計算可用物流
• 虛擬商品自動隱藏物流選擇區塊與收件人欄位

4. 結帳側邊欄

• 獨立顯示結帳金額、運輸方式、購物車內容
• 桌機版固定顯示結帳金額與購物車概要

5. 第三方物流相容性

支援以下第三方物流外掛的超商取貨功能：

好用版 RY Tools for WooCommerce（綠界 ECPay）

• 支援 7-11、全家、萊爾富、OK 超商
• CVS 欄位（門市名稱、地址、電話）僅在選擇綠界超商物流時顯示
• 「超商門市」選擇按鈕自動置中加粗
• 內部欄位（LogisticsSubType、CVSStoreID）自動隱藏

好用版 PayNow Shipping（PayNow 超取）

• 自動辨識已知 C2C 7-11、全家、萊爾富方法；B2C、OK 或自訂方法由後台以完整 rate ID 指定
• 保留原生門市欄位作為送單資料源；增強成功後改以不可編輯的門市摘要顯示名稱、代號與地址
• 選店區統一為「超商門市」標題、狀態文字、白底虛線面板與全寬按鈕
• 內部欄位（Reserved NO、Ship Date）自動隱藏

6. 訂單頁面強化

前台物流狀態卡片

• 卡片式物流狀態顯示
• 進度條顯示（訂單成立 → 商品準備中 → 運送中 → 已到店/配送完成 → 已取貨）
• 一鍵更新貨態按鈕
• 物流單號複製功能

支援的物流系統

• YS PayNow 物流 - 超商取貨（7-11/全家/萊爾富）、黑貓宅配
• WPBR PayUni 物流 - 7-11 超取（大智通/交貨便）、黑貓宅配

後台手動配送資訊

• 支援新增多筆物流資訊
• 自動偵測物流類型，只對非自動串接物流顯示
• 隱藏條件：PayUni 物流、YS PayNow 物流
• 顯示條件：綠界、好用版 PayNow、其他自訂物流

7. 後台樣式設定

• 按鈕顏色（主色、Hover 色）
• 主要、標題、次要與輔助文字顏色
• 物流卡片顏色
• 側邊欄背景色
• 區塊圓角設定
• 一鍵恢復預設配色

8. 購物金與設定移轉

• YITH Points & Rewards 以安全代理介面直接輸入點數、全部使用、顯示上限，並鏡射 YITH 官方即時換算的折抵金額
• WPLoyalty 保留原生兌換視窗與活動規則，套用一致的結帳視覺
• 完整設定 JSON 匯入／匯出，包含所有功能、配色、物流與 WPLoyalty 顯示文字
• 嚴格 schema、值驗證、寫入鎖與失敗回滾，拒絕未知或不完整的設定檔

檔案結構

yangsheep-checkout-optimizer/
├── assets/
│   ├── css/
│   │   ├── yangsheep-checkout.css         # 結帳頁面樣式（media="not all"，增強後啟用）
│   │   ├── yangsheep-cvs-mode.css         # 超取模式隱藏地址欄位（永遠載入，不受增強 gate）
│   │   ├── yangsheep-cart.css             # 購物車折扣代碼欄位對齊
│   │   ├── yangsheep-sidebar.css          # 側邊欄樣式
│   │   ├── yangsheep-myaccount.css        # 我的帳號樣式
│   │   ├── yangsheep-order.css            # 訂單頁面樣式
│   │   ├── yangsheep-shipping-cards.css   # 物流卡片樣式
│   │   └── yangsheep-order-enhancer.css   # 訂單強化樣式
│   └── js/
│       ├── jquery.twzipcode.min.js        # TWzipcode 套件
│       ├── yangsheep-admin-settings.js    # 設定匯入／匯出
│       ├── yangsheep-checkout.js          # 結帳頁面 JS
│       ├── yangsheep-shipping-cards.js    # 物流卡片 JS
│       ├── yangsheep-wployalty.js          # WPLoyalty 整合 JS
│       ├── yangsheep-order-enhancer.js    # 訂單強化 JS
│       └── color-picker-init.js           # 後台顏色選擇器初始化
├── src/                                   # PSR-4 自動載入（命名空間：YangSheep\CheckoutOptimizer）
│   ├── Admin/
│   │   └── YSCheckoutSettings.php         # 後台設定頁面
│   ├── Checkout/
│   │   ├── YSCheckoutCustomizer.php       # 自訂器（Color Picker enqueue）
│   │   ├── YSCheckoutFields.php           # 結帳欄位設置
│   │   ├── YSCheckoutLayout.php           # 標準 Hook 區塊與漸進式版面目標
│   │   ├── YSCheckoutSidebar.php          # 側邊欄三盒（結帳金額/運輸方式/購物車內容，id fragment 更新）
│   │   └── YSShippingCards.php            # 物流卡片類別
│   ├── Compat/
│   │   ├── YSThirdPartyShippingCompat.php # 第三方物流相容性
│   │   ├── YSWPLoyaltyIntegration.php     # WPLoyalty 購物金整合
│   │   ├── YSYithCouponDisplay.php        # YITH 折扣標籤整合
│   │   └── YSYithPointsIntegration.php    # YITH Points 搬移與診斷
│   ├── Order/
│   │   └── YSOrderEnhancer.php            # 訂單頁面強化
│   └── Settings/
│       ├── YSSettingsManager.php          # 設定管理門面（Facade）
│       ├── YSSettingsRepository.php       # 設定 CRUD 操作
│       ├── YSSettingsTableMaker.php       # 設定資料表建立
│       ├── YSSettingsMigrator.php         # 設定資料遷移
│       └── YSSettingsTransfer.php         # 完整設定匯入／匯出、驗證與回滾
├── templates/
│   └── checkout/
│       └── shipping-cards.php             # 直接 include 的視覺 proxy partial
├── README.md                              # 本檔案
└── yangsheep-checkout-optimization.php    # 主外掛檔案（含 PSR-4 自動載入器）

核心類別說明

所有類別統一使用 YS 前綴，命名空間為 YangSheep\CheckoutOptimizer\{Module}。

YSCheckoutFields (Checkout\YSCheckoutFields)

結帳欄位設置類別，處理：

• WooCommerce 運送設定檢查
• First Name / Last Name 關閉選項
• 台灣化欄位設置
• 欄位排序與寬度
• 訂單備註設置
• 收件人電話驗證（woocommerce_checkout_process hook）

YSThirdPartyShippingCompat (Compat\YSThirdPartyShippingCompat)

第三方物流相容性處理：

• 綠界 CVS 欄位顯示/隱藏控制
• PayNow CVS 欄位顯示/隱藏控制
• 內部欄位（Reserved NO、Ship Date、LogisticsSubType、CVSStoreID）CSS 隱藏
• 手機號碼前端驗證（JS 即時驗證）
• 僅在啟用對應物流外掛時載入

YSOrderEnhancer (Order\YSOrderEnhancer)

訂單頁面強化：

• 前台物流狀態卡片渲染
• 後台手動配送 Meta Box
• 物流類型偵測（YS PayNow / PayUni / 其他）
• AJAX 貨態更新

YSCheckoutSettings (Admin\YSCheckoutSettings)

後台設定頁面，包含：

• 顏色設定（按鈕、物流卡片、側邊欄等）
• 功能開關（台灣化欄位、我的帳號視覺等）
• 遷移管理 UI
• MyAccount CSS 變數注入

YSSettingsManager (Settings\YSSettingsManager)

設定存取門面（Facade），統一所有設定的讀寫：

• YSSettingsManager::get( $key, $default ) - 讀取設定
• YSSettingsManager::set( $key, $value ) - 寫入設定
• 底層使用自訂資料表 wp_ys_checkout_settings

YSSettingsTransfer (Settings\YSSettingsTransfer)

完整設定移轉服務：

• 依 canonical key 清單輸出完整、版本化 JSON
• 嚴格拒絕未知 key、缺少 key、非法 CSS、HTML 與不支援的 schema
• 匯入寫入失敗時還原先前設定；與一般儲存、遷移及清理共用寫入鎖

手機號碼驗證機制

前端驗證（JS）

位置：src/Compat/YSThirdPartyShippingCompat.php

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

事件綁定：

• input 事件：輸入時即時驗證（不顯示錯誤）
• blur 事件：失焦時顯示錯誤訊息
• submit 事件：表單提交前驗證
• checkout_error 事件：WooCommerce 結帳錯誤時再次驗證

後端驗證（PHP）

位置：src/Checkout/YSCheckoutFields.php

// 驗證格式：必須是 09 開頭的 10 位數字
if ( ! preg_match( '/^09\d{8}$/', $phone_numeric ) ) {
    wc_add_notice( '錯誤訊息', 'error' );
}

驗證條件：

• 只在勾選「運送到不同地址」且有填寫 shipping_phone 時驗證

手動配送 Meta Box 顯示邏輯

技術注意事項

• 遵循 WooCommerce 模板覆寫規範
• 使用 woocommerce_update_order_review_fragments filter 確保 AJAX 更新
• 保留標準 Action Hooks 以相容第三方外掛
• 維持 shipping_method[...] input name 結構
• CSS Grid 排版，使用 grid-column 控制欄位寬度
• 第三方物流欄位由各物流外掛原生節點作為資料來源，YS 只在已辨識的節點上做漸進式排版與顯示同步

版本紀錄

格式基於 Keep a Changelog，版本號遵循 Semantic Versioning。

v1.7.11 (2026-08-27)

• 收件人電話位置被 WooCommerce 前端 locale 重排修正：WooCommerce 8.9+ 將 phone 納入 address-i18n.js 的 locale 欄位——頁面載入與切換國家時，前端會用 core locale 的 phone 條目（priority 100、label「聯絡電話」、class form-row-wide）蓋掉伺服器輸出並依 locale priority 重排 DOM，導致電話欄位掉到詳細地址之後、「訂購人電話／收件人電話」被統一改名「聯絡電話」（伺服器端 HTML 順序其實正確，是前端 JS 事後搬動）。新增 woocommerce_get_country_locale_default / _base filter 將 locale phone 條目對齊 YS 契約：priority 15（同 force_phone_fields）、label / class / placeholder 交還伺服器端欄位定義、required 保留原值（避免 address-i18n 把欄位視覺降為選填並拔掉前端必填驗證 class）。

v1.7.10 (2026-08-27)

• PayNow 官方物流（wc-paynow-shipping）相容：修正選「非 PayNow 物流」（宅配等）時收件人電話被 PayNow 前端 JS 連坐隱藏 — shipping_phone 掛有 paynow-shipping-field class，該外掛切換物流時會 hide 全部自家欄位；改以永遠載入的 !important 規則強制顯示，enhanced / native 模式皆生效。
• 站方自訂選店複製鈕（button.ys-cvs-btn）樣式接管：站點以自訂片段複製第二顆 #choose-cvs-btn 到收件欄位區時，native 模式修正為全寬按鈕（不再被欄位 Grid 擠成窄條斷行）；enhanced 模式已有 YS 超商門市面板、且 PayNow 點擊事件只綁第一顆按鈕，複製鈕屬重複死鈕 → 直接隱藏。
• 訂單備註切換器跟隨備註欄位：切換器改由 JS 固定插在 #order_comments_field 正上方，電子發票（速買配等）模組插入其他資訊區塊時維持「發票模組 → 切換器 → 備註欄位」順序，與第三方腳本執行先後無關；Grid 版面下切換器獨占整列。
• 備註顯示同步閘門放寬：由「僅 enhanced」放寬為「enhanced 或切換器實際可見」— CSS 優化外掛（WP Rocket RUCSS 等）把 media="not all" 增強樣式攤平時，native 模式也會顯示切換器，此時同樣接管備註欄位顯示，修正「勾選框看得到但勾了沒反應」；切換器隱藏時維持 Woo 原生行為（fail-open）。

v1.7.9 (2026-07-28)

• HPOS 宣告歸位：由結帳強化主外掛使用已註冊的主檔宣告相容性。
• Hub Client 2.0.5：vendor library 不再以自己的檔案路徑宣告 HPOS，避免 WooCommerce 持續寫入 Invalid plugin file 錯誤。

v1.7.8 (2026-07-25)

• 設定動作列整理：將「一鍵恢復預設配色」移入設定表單底部，與儲存按鈕位於同一動作列；恢復功能、確認流程與 AJAX 寫入契約不變。
• 獨立入口前移：結帳強化 頂層入口移至 WooCommerce 區段後、電商工具箱 上方，工具箱子入口與雙入口資料契約維持不變。
• Hub Client 2.0.4：新增晚期選單 normalizer；舊版 Client 先載入時仍會校正父選單名稱、圖示與位置，並固定將「系統資訊」「聯絡我們」排在工具箱最後。

v1.7.7 (2026-07-25)

• 父選單正名「電商工具箱」：Hub Client 升級 2.0.3，ys-toolbox 頂層選單中央統一註冊為「電商工具箱」（dashicons-store、位置 56，與開發準則 §4 及各外掛自建選單完全一致）；外掛端另備 label 校正，同站若有尚未更新的舊版 Hub Client（≤2.0.2 先註冊成「YS Plugin」）也會被統一回「電商工具箱」。
• 恢復獨立「結帳強化」入口：重新註冊舊版頂層端點 admin.php?page=yangsheep_checkout_optimization，同時保留 電商工具箱 → 結帳強化 的 admin.php?page=ys-checkout-optimizer 子入口；兩者共用相同設定頁、權限與資料來源。
• 雙入口導覽相容：設定頁完整載入色彩及匯入匯出資產，表單儲存後留在管理員原先開啟的入口；未知或偽造 page slug 會回到現行電商工具箱子入口。

v1.7.6 (2026-07-25)

• YITH 折抵金額鏡射：v1.7.5 代理介面漏掉 YITH 原生的「輸入點數 → 可折抵 NT$X」換算，現鏡射官方 .woocommerce-Price-amount 金額並經原生 keyup 觸發 YITH 即時換算（YS 不自行以比例推算）；換算中、無效數字與官方端點無回應各有獨立狀態，fragment 重建時清除舊 observer 與 timer。
• 折抵介面版面調整（使用者指定）：移除「折抵點數」文字 label（aria-label 保留供無障礙）；輸入框靠左，與「套用折抵」「全部使用」同列；「本次最多可使用 X 點」移至區塊右上角，與「購物金折抵」標題垂直置中對齊。窄幅（<480px）時輸入框獨占一列、上限文字靠左。後台預覽同步新版面。

v1.7.5 (2026-07-25)

• 購物金整合重整：WPLoyalty 與 YITH Points & Rewards 集中在「購物金整合」分頁，各自提供外掛狀態、啟用開關與正確的操作說明；共同預覽會直接反映結帳頁按鈕、欄位、邊框、背景與圓角設定。
• YITH 安全直接折抵介面：不再複製第三方表單。原生 YITH form 留在結帳 form 外作為唯一提交來源，YS 只建立無 form/name/id 的數字代理，支援直接輸入、Enter、全部使用、上限、錯誤提示，以及「輸入點數 → 可折抵金額」的 YITH 官方即時換算結果；YS 不自行猜測兌換比例，原生合約、樣式或增強任一失敗即保留原生介面。
• WPLoyalty 共存硬化：只接管一個可見且具有原生 reward link 的訊息來源，仍由 WPLoyalty 視窗選擇活動；停用整合時完全不搬移或隱藏原生內容，可與 YITH 同時顯示。
• 結帳設計 token 完整化：新增主要、標題、次要、輔助文字配色；購物金、物流卡、側邊欄與相容面板統一取用後台按鈕、欄位、區塊及圓角設定。所有 runtime CSS 值先經共用 validator，舊資料若不合法會回到安全預設值。
• 完整設定匯入／匯出：資料庫管理頁可下載及匯入版本化 JSON，涵蓋全部 canonical 設定與 WPLoyalty 顯示文字；採 exact-key schema、1 MB 上限、CSS／物流 rate id／placeholder 驗證、管理員 nonce、共享寫入鎖與補償回滾。
• 設定儲存安全：一般後台儲存改與匯入共用 validator；遷移會補齊自訂表缺少但仍存在於 wp_options 的 fallback 值，確認完整前禁止清除舊資料。

v1.7.4 (2026-07-24)

• 避免原生結帳首屏閃現：主結帳 body 先進入 ys-checkout-pending，以 head 內極小 critical CSS 暫時隱藏原生 form；YS 增強成功後立即顯示最終版面。主 JS／CSS／DOM 契約失敗時由 window.load、2 秒 timeout、CSS animation 與 `