| name | woomp |
| description | Woomp WooCommerce 台灣在地化外掛開發指引。涵蓋 PayUni/綠界/藍新/立吉富金流、超商物流、電子發票整合架構與模組載入機制。開發、除錯或擴充 woomp 外掛任何模組時使用。 |
| user-invocable | false |
Woomp 開發指引 SKILL
架構概覽
Woomp 是一個單體式 WooCommerce 外掛，將多個子外掛（金流、物流、發票）整合於統一的設定介面下。每個子外掛可獨立啟用或停用。
技術棧
- PHP 8.0+ / WordPress 6.x / WooCommerce 5.3+
- jQuery + ES6 Modules（PayUni v3 前端）
- Composer：PSR-4 自動載入（
J7\Payuni\）、a7/autoload（舊版）
- PHPCS：WordPress Coding Standards（Tab 縮排、短陣列語法、PHP 8.0+ 相容）
- Playwright：E2E 測試（TypeScript）
核心依賴（composer.json）
| 套件 | 版本 | 用途 |
|---|
oberonlai/wp-metabox | ^1.0 | Metabox 建構器 |
a7/autoload | ^2.1 | 舊版 PayUni v1 自動載入器 |
dennykuo/invoice-porter | ^0.2.2 | 發票工具 |
guzzlehttp/guzzle | ^6.5.8 | HTTP 客戶端 |
yahnis-elsts/plugin-update-checker | ^5.3 | 基於 GitHub 的外掛更新機制 |
完整目錄結構
woomp/
├── woomp.php # 外掛入口點（版本 header：3.4.81）
├── init.php # 常數定義、WC 檢查、子外掛載入、工具函式
├── Compatibility.php # 相容性輔助工具
├── debug.php # 除錯工具
│
├── admin/ # === 後台功能 ===
│ ├── class-woomp-admin.php # 後台 Hook、資源載入、帳單/運送 meta
│ ├── class-woomp-product.php # 商品後台客製化
│ ├── class-woomp-order.php # 訂單管理、物流單號更新
│ ├── class-woomp-email.php # 自訂郵件動作
│ ├── class-woomp-payment-cod-clone.php # 貨到付款複製
│ ├── class-woomp-shipping-flat-rate.php # 自訂統一運費
│ ├── settings/
│ │ ├── class-woomp-setting.php # 主設定頁籤（好用版擴充）
│ │ ├── class-woomp-setting-gateway.php # 金流子頁籤
│ │ ├── class-woomp-setting-shipping.php # 物流子頁籤
│ │ └── class-woomp-setting-invoice.php # 發票子頁籤
│ ├── resources/
│ │ ├── shop_subscription/index.php # 訂閱資源
│ │ └── class-checkout.php # 結帳後台資源
│ ├── css/ # 後台樣式表
│ ├── js/ # 後台腳本
│ └── partials/ # 後台模板片段
│
├── public/ # === 前台功能 ===
│ ├── class-woomp-public.php # 前台資源載入、虛擬商品自動完成訂單
│ ├── class-woomp-checkout.php # 結帳頁客製化（欄位順序、驗證）
│ ├── class-woomp-order.php # 前台訂單顯示
│ ├── class-woomp-product.php # 前台商品顯示（可變商品 UI）
│ ├── css/ # 前台樣式表
│ │ └── themes/ # 佈景主題專屬覆寫
│ ├── js/ # 前台腳本
│ └── partials/ # 前台模板片段
│
├── includes/ # === 核心類別 + 子外掛模組 ===
│ ├── class-woomp.php # 主外掛類別（Loader Pattern）
│ ├── class-woomp-loader.php # Hook 管理器（add_action/add_filter 收集器）
│ ├── class-woomp-logger.php # 日誌工具
│ ├── class-woomp-i18n.php # 國際化
│ ├── class-woomp-activator.php # 啟用邏輯
│ ├── class-woomp-deactivator.php # 停用邏輯
│ │
│ ├── payuni/ # --- PayUni（統一金流）---
│ │ ├── payuni.php # PayUni 入口 & v1/v3 啟動
│ │ ├── assets/ # v1 前端資源（card.js、card.css）
│ │ ├── settings/ # PayUni 設定
│ │ ├── src/ # v1 原始碼
│ │ │ └── gateways/
│ │ │ ├── AbstractGateway.php # 基底閘道（繼承 WC_Payment_Gateway_CC）
│ │ │ ├── Credit.php # 信用卡 v1
│ │ │ ├── CreditV3.php # 信用卡 v3（UNi Embed）
│ │ │ ├── CreditInstallment.php # 分期付款
│ │ │ ├── CreditSubscription.php # 訂閱付款
│ │ │ ├── Atm.php # ATM 轉帳
│ │ │ ├── Cvs.php # 超商代碼繳費
│ │ │ ├── Request.php # API 請求處理
│ │ │ ├── Response.php # API 回應處理
│ │ │ ├── Refund.php # 退款處理
│ │ │ └── Subscription.php # 訂閱處理
│ │ └── v3/ # v3 PSR-4（命名空間 J7\Payuni\）
│ │ ├── Bootstrap.php # V3 Hook 註冊 & 交易通知處理
│ │ ├── Contracts/DTOs/ # 資料傳輸物件
│ │ │ ├── SdkDTO.php # SDK Token 回應
│ │ │ ├── SettingDTO.php # 閘道設定
│ │ │ ├── TradeReqDTO.php # 交易請求資料
│ │ │ └── TradeReqHashDTO.php # 加密交易請求
│ │ ├── Infrastructure/Http/ # HTTP 層
│ │ │ ├── HttpClient.php # API 客戶端
│ │ │ └── TradeHandler.php # 交易處理
│ │ ├── Shared/
│ │ │ ├── Enums/ # 列舉（EMode 等）
│ │ │ ├── Helpers/ # 輔助類別
│ │ │ └── Utils/ # 工具類別（OrderUtils 等）
│ │ └── Applications/assets/
│ │ ├── css/checkout.css # V3 結帳樣式
│ │ └── js/ # V3 ES6 模組
│ │ ├── checkout.js # 入口點
│ │ ├── env.module.js # jQuery 別名 & 環境偵測
│ │ ├── Elements.module.js # iframe 元素管理
│ │ ├── PayUniService.module.js # PayUni SDK 封裝
│ │ ├── FormState.module.js # 表單狀態管理
│ │ ├── ApiService.module.js # API 呼叫服務
│ │ ├── UIHelper.module.js # UI 輔助工具
│ │ ├── constants.module.js # 選擇器 & 常數
│ │ └── utils.module.js # 共用工具函式
│ │
│ ├── ry-woocommerce-tools/ # --- 綠界 / 藍新 / 速買配 ---
│ │ ├── class.ry-wt.main.php # 主類別（常駐載入）
│ │ ├── icon/ # 付款圖示
│ │ ├── style/ # 樣式
│ │ ├── templates/ # 模板
│ │ └── woocommerce/ # WC 模板覆寫
│ │
│ ├── paynow-payment/ # --- 立吉富金流（條件式載入）---
│ │ ├── includes/class-paynow-payment.php # 金流主類別
│ │ ├── admin/ public/ # 後台 & 前台
│ │ └── languages/ # 翻譯檔
│ │
│ ├── paynow-shipping/ # --- 立吉富物流（條件式載入）---
│ │ ├── includes/
│ │ │ ├── shippings/ # 物流方式類別
│ │ │ │ ├── abstract-paynow-shipping.php
│ │ │ │ ├── class-paynow-shipping-c2c-711.php # 7-11 超商取貨
│ │ │ │ ├── class-paynow-shipping-c2c-family.php # 全家超商取貨
│ │ │ │ ├── class-paynow-shipping-c2c-hilife.php # 萊爾富超商取貨
│ │ │ │ └── class-paynow-shipping-hd-tcat.php # 黑貓宅配
│ │ │ └── api/ # 物流 API
│ │ ├── assets/ templates/ languages/
│ │
│ ├── paynow-einvoice/ # --- 立吉富電子發票（條件式載入）---
│ ├── line-pay-for-woo/ # --- LINE Pay（常駐載入）---
│ ├── PChomePay-Cart-for-WooCommerce/ # --- 支付連（條件式載入）---
│ ├── woomp-ecpay-invoice/ # --- 綠界電子發票（常駐載入）---
│ │ ├── src/ # 發票原始碼
│ │ └── assets/ # 發票靜態資源
│ ├── woomp-ezpay-invoice/ # --- EZPAY 電子發票（常駐載入）---
│ │ ├── src/ # 發票原始碼
│ │ └── assets/ # 發票靜態資源
│ └── woomp-paynow-shipping/ # --- 立吉富物流 v2（條件式載入）---
│
├── woocommerce/checkout/ # WC 結帳模板覆寫
├── languages/ # 多國語系 .po/.mo 檔案
├── e2e/ # Playwright E2E 測試
│ ├── playwright.config.ts # Playwright 設定
│ ├── payuni-checkout.ts # 結帳流程測試
│ ├── payuni-installment.ts # 分期付款測試
│ ├── payuni-invoice-carrier.ts # 發票載具測試
│ └── payuni-tokenization.ts # 記憶卡號測試
├── composer.json # PHP 依賴 & PSR-4 自動載入
├── package.json # Node.js 建置工具
├── build.mjs # 建置腳本（ZIP 打包）
└── phpcs.xml # PHPCS 設定
模組載入機制
入口流程
woomp.php -> init.php -> includes/class-woomp.php -> Woomp::run()
-> （條件式子外掛載入）
-> includes/payuni/payuni.php
init.php 中的條件式載入
每個服務商根據 WordPress 選項載入：
| 選項鍵 | 模組 | 預設值 |
|---|
wc_woomp_enabled_payuni_gateway | PayUni 金流 | no |
wc_woomp_enabled_payuni_shipping | PayUni 物流 | no |
RY_WT::$option_prefix . 'enabled_ecpay_gateway' | 綠界金流 | no |
RY_WT::$option_prefix . 'enabled_ecpay_shipping' | 綠界物流 | no |
RY_WT::$option_prefix . 'enabled_newebpay_gateway' | 藍新金流 | no |
RY_WT::$option_prefix . 'enabled_newebpay_shipping' | 藍新物流 | no |
RY_WT::$option_prefix . 'enabled_smilepay_gateway' | 速買配金流 | no |
RY_WT::$option_prefix . 'enabled_smilepay_shipping' | 速買配物流 | no |
wc_woomp_setting_paynow_gateway | 立吉富金流 | no |
wc_woomp_setting_paynow_shipping | 立吉富物流 | no |
wc_settings_tab_active_paynow_einvoice | 立吉富電子發票 | no |
wc_woomp_enabled_ecpay_invoice | 綠界電子發票 | no |
wc_woomp_enabled_ezpay_invoice | EZPAY 電子發票 | no |
woocommerce_linepay_enabled | LINE Pay | no |
woocommerce_pchomepay_enabled | 支付連 | no |
常駐載入：ry-woocommerce-tools、line-pay-for-woo、woomp-ecpay-invoice、woomp-ezpay-invoice、PayUni v3 Bootstrap::register_hooks()。
金流閘道整合模式
AbstractGateway（PayUni v1）
namespace PAYUNI\Gateways;
abstract class AbstractGateway extends \WC_Payment_Gateway_CC {
public $id;
protected $mer_id;
protected $hash_key;
protected $hash_iv;
}
建立新的金流閘道
namespace PAYUNI\Gateways;
class MyNewGateway extends AbstractGateway {
public const ID = 'payuni-my-new';
public function __construct() {
$this->id = self::ID;
parent::__construct();
$this->method_title = '我的新閘道';
$this->supports = [ 'products', 'refunds' ];
$this->init_form_fields();
$this->init_settings();
$this->title = $this->get_option( 'title' );
\add_action(
"woocommerce_update_options_payment_gateways_{$this->id}",
[ $this, 'process_admin_options' ]
);
}
public function init_form_fields(): void {
$this->form_fields = [
'enabled' => [
'title' => __( '啟用/停用', 'woocommerce' ),
'type' => 'checkbox',
'label' => sprintf( __( '啟用 %s', 'woomp' ), $this->method_title ),
'default' => 'no',
],
'title' => [
'title' => __( '標題', 'woocommerce' ),
'type' => 'text',
'default' => $this->method_title,
],
];
}
public function process_payment( $order_id ) {
$order = wc_get_order( $order_id );
return [
'result' => 'success',
'redirect' => $this->get_return_url( $order ),
];
}
}
註冊金流閘道
金流閘道透過各子外掛初始化檔案中的 woocommerce_payment_gateways 過濾器註冊。
物流方式整合模式
class PayNow_Shipping_C2C_711 extends Abstract_PayNow_Shipping {
}
add_filter( 'woocommerce_shipping_methods', function( $methods ) {
$methods['paynow_shipping_c2c_711'] = 'PayNow_Shipping_C2C_711';
return $methods;
});
可用物流類型：
- C2C（店到店）：7-11、全家、萊爾富
- HD（宅配）：黑貓宅急便
電子發票整合模式
三家發票服務商，皆透過設定開關控制：
- 綠界（
woomp-ecpay-invoice/）：使用 wc_woomp_enabled_ecpay_invoice
- EZPAY（
woomp-ezpay-invoice/）：使用 wc_woomp_enabled_ezpay_invoice
- 立吉富（
paynow-einvoice/）：使用 wc_settings_tab_active_paynow_einvoice
發票載具類型包含：手機條碼、自然人憑證、統一編號（公司戶）。
PayUni v3 前端架構
ES6 模組系統
入口：checkout.js -> Elements.module.js -> PayUniService.module.js
checkout.js # jQuery ready + updated_checkout 事件綁定
├── env.module.js # 匯出 jQuery 為 $、環境偵測
├── Elements.module.js # 管理 PayUni SDK iframe 生命週期
│ ├── PayUniService.module.js # PayUni UNi Embed SDK 封裝
│ ├── FormState.module.js # 結帳表單狀態管理
│ ├── ApiService.module.js # AJAX API 呼叫
│ └── UIHelper.module.js # DOM 操作輔助工具
├── constants.module.js # CSS 選擇器、iframe 元素 ID
└── utils.module.js # 共用工具函式
腳本載入方式
wp_enqueue_script( 'uni-payment', $sdk_url, [], '3.0.0', true );
wp_enqueue_script( 'uni-payment-checkout', '.../checkout.js', [ 'uni-payment', 'jquery' ], WOOMP_VERSION, true );
add_filter( 'script_loader_tag', [ __CLASS__, 'modify_script_type' ], 10, 3 );
前端參數（wp_localize_script）
wp_localize_script( 'uni-payment-checkout', 'payuni_payment_v3_checkout_params', [
'ENV' => 'P' 或 'S', // 正式環境或沙箱
'SDK_TOKEN' => $sdk_token, // 一次性 SDK Token
'USE_INST' => $enable_installment, // 是否啟用分期
'ENABLE_3D_AUTH' => $enable_3d_auth, // 3D 驗證
'INST_OPTIONS' => $installment_options, // 分期期數選項
'ENABLE_TOKENIZATION' => $enable_tokenization, // 記憶卡號
'ERROR_MAPPER' => HttpClient::$error_mapper,
]);
PayUni v3 PSR-4 結構
J7\Payuni\
├── Bootstrap # Hook 註冊、腳本載入、交易通知處理
├── Contracts\DTOs\
│ ├── SdkDTO # SDK Token 回應對應
│ ├── SettingDTO # 閘道設定（單例模式）
│ ├── TradeReqDTO # 交易請求資料
│ └── TradeReqHashDTO # 加密交易請求
├── Infrastructure\Http\
│ ├── HttpClient # PayUni API HTTP 客戶端
│ └── TradeHandler # 交易處理 & 訂單狀態更新
└── Shared\
├── Enums\ # EMode（正式/沙箱）等
├── Helpers\ # 輔助類別
└── Utils\
└── OrderUtils # 訂單 meta 操作、結帳欄位擴充
記憶卡號（Tokenization）模式
PayUni v3 支援信用卡記憶卡號：
- 前端：PayUni SDK 透過 iframe 收集卡片資訊，回傳
CardHash
- 結帳：
Bootstrap::save_payuni_card_hash() 將 hash 暫存於訂單 meta
- 付款：
CreditV3 將 CardHash 連同 UseToken 旗標送至 PayUni API
- WooCommerce Token：透過
WC_Payment_Token 儲存，供回訪客戶使用
閘道宣告支援：$this->supports = [ 'products', 'refunds', 'tokenization' ];
設定頁面架構
設定位於 WooCommerce > 設定 > 好用版擴充（woomp_setting 頁籤）：
主頁籤（class-woomp-setting.php）
- 各服務商啟用/停用開關（PAYUNi、綠界、藍新、速買配、立吉富、LINE Pay、支付連）
- 結帳模式（預設 / 一頁式 / 兩頁式）
- 台灣地址下拉選單、欄位驗證、虛擬商品選項
- 可變商品 UI 設定
- 免運提示
子頁籤（透過 set_more_tabs()）
class-woomp-setting-gateway.php - 金流專屬設定class-woomp-setting-shipping.php - 物流專屬設定class-woomp-setting-invoice.php - 發票專屬設定
E2E 測試（Playwright）
設定（tests/e2e/playwright.config.ts）
- 基本 URL：
https://local-test.powerhouse.tw（本地測試環境）
- 瀏覽器：Chromium，非無頭模式
- Workers：1（序列執行，避免 PayUni 沙箱並發衝突）
- 逾時：每個測試 60 秒、每個動作 15 秒
測試檔案
| 檔案 | 測試範圍 |
|---|
payuni-checkout.ts | 基本結帳流程 |
payuni-installment.ts | 分期付款 |
payuni-invoice-carrier.ts | 發票載具選擇 |
payuni-tokenization.ts | 記憶卡號 |
執行測試
cd tests/e2e
npm install
npx playwright test
npx playwright test payuni-checkout.ts
npx playwright test --headed
WooCommerce 模板覆寫
woocommerce/checkout/ 中的自訂結帳模板在結帳模式設為 onepage 或 twopage 時啟用（由 wc_woomp_setting_mode 選項控制）。透過 wc_get_template 過濾器攔截模板路徑。
常用指令
composer install
composer dump-autoload
vendor/bin/phpcs
vendor/bin/phpcbf
npm run build
cd tests/e2e && npx playwright test
cd tests/e2e && npx playwright test --ui
關鍵模式總覽
| 模式 | 實作方式 | 位置 |
|---|
| Loader Pattern | Woomp_Loader 收集 Hook 後批次註冊 | includes/class-woomp-loader.php |
| 抽象閘道 | 所有 PayUni 金流閘道的基底類別 | includes/payuni/src/gateways/AbstractGateway.php |
| 設定驅動載入 | get_option() 控制模組啟用 | init.php |
| Metabox 建構器 | oberonlai/wp-metabox Composer 套件 | 各後台檔案 |
| 外掛更新檢查 | yahnis-elsts/plugin-update-checker | init.php（底部） |
| ES6 模組系統 | 原生模組搭配 type="module" | includes/payuni/v3/Applications/assets/js/ |
| DTO 模式 | 型別化資料物件用於 API 通訊 | includes/payuni/v3/Contracts/DTOs/ |
| 模板覆寫 | wc_get_template 過濾器用於結帳頁 | init.php + woocommerce/checkout/ |
Reference 導航
| 檔案 | 何時使用 |
|---|
| testing.md | 需要完整 PHPUnit testsuite / group 參數、E2E npm scripts 完整清單時 |
