ellohello.com 文件中心

外觀

ELO 專案交接指南 ​

本文件為原始碼交接給接手團隊使用的總體說明。內容涵蓋 Theme 架構、使用過的 Plugin、客製化記錄，以及重要 Hook 與 Meta key 索引。 functions.php 的逐行說明請參照同目錄下的 functions.php.txt。

1. 專案概述 ​

  • 平台：WordPress + WooCommerce
  • 父主題：sober（第三方主題）
  • 子主題：ctkpro-childtheme（位於 wp-content/themes/ctkpro-childtheme/，本 repo 主要客製成果）
  • 金流：藍新金流（NewebPay）
  • 點數系統：SUMO Reward Points
  • 語系：繁體中文（台灣）

2. Theme 架構 ​

2.1 父子主題關係 ​

sober（父主題，第三方）
  └─ ctkpro-childtheme（子主題，本 repo）
       Template: sober
       Version : 1.0.0

子主題依賴父主題 sober，缺一不可。子主題的 style.css 已透過 Template: sober 宣告依賴關係，並由 functions.php 主動 require_once 父主題 functions.php 確保父主題函式可用。

2.2 子主題目錄結構 ​

wp-content/themes/ctkpro-childtheme/
├── style.css                 # 子主題宣告（Template: sober, Version: 1.0.0）
├── style.min.css             # 預留（目前為空檔）
├── functions.php             # 主要客製邏輯（共 142 行，詳見 functions.php.txt）
├── screenshot.png            # 主題縮圖
├── css/
│   ├── theme-update.css      # SCSS 編譯後的覆寫樣式
│   └── theme-update.css.map
├── sass/                     # SCSS 原始碼（接手後需自備編譯流程）
│   ├── theme-update.scss     # 入口檔，依序載入下列分層
│   ├── base/
│   │   ├── index.scss
│   │   ├── _color.scss       # 色票
│   │   ├── _reset.scss       # 重設樣式
│   │   └── _typography.scss  # 字型／文字樣式
│   ├── components/
│   │   ├── index.scss
│   │   ├── _auth-popup.scss  # 登入／註冊彈窗
│   │   └── _bought-together.scss  # 加價購區塊（FBT 已棄用，但樣式保留）
│   ├── layout/
│   │   ├── index.scss
│   │   ├── _header.scss      # 含手機 header 會員 icon
│   │   ├── _footer.scss
│   │   ├── _content.scss
│   │   └── _elements.scss
│   └── pages/
│       ├── index.scss
│       ├── _home.scss
│       └── _checkout.scss    # 結帳頁與購物金表格 RWD
├── js/
│   ├── main.js               # 前端 JS 原始碼（79 行）
│   ├── main.min.js           # 上線使用的壓縮版
│   └── main.min.js.map
└── template-parts/
    └── header-v4.php         # 覆寫父主題 header v4（為了塞購物金顯示）

2.3 SCSS 分層原則 ​

採典型的 7-1 簡化分層（base / components / layout / pages）：

  • base/：基礎重設、字型、色票（變數）。最先載入。
  • components/：可重用 UI 元件樣式。
  • layout/：版型結構（header、footer、content）。
  • pages/：個別頁面客製（首頁、結帳頁）。

每個資料夾皆有 index.scss 統整 partial 匯入，最終由 theme-update.scss 進入點輸出至 css/theme-update.css。

接手後若需修改樣式，請務必修改 SCSS 後重新編譯，不要直接改 theme-update.css（會在下次編譯時被覆蓋）。

2.4 前端 JS 重點（js/main.js） ​

main.js 包含三項客製功能，編譯後輸出至 main.min.js：

  1. 移除所有 <img> 的 title 屬性（避免 hover 出現重複 alt/title 的提示）。
  2. 結帳時隱藏多餘運送選項（hideRedundantShipping）：
    • 偵測到「超商取貨免運」啟用時，隱藏付費的「超商取貨」選項。
    • 偵測到「宅配到府免運」啟用時，隱藏付費的「宅配到府」選項。
    • 若使用者原本選的是付費版，自動切換到免運版。
    • 透過 updated_checkout 事件 + setTimeout 300ms 兩層保險觸發。
  3. 預購／團購商品隱藏超取選項（setupGiftBox）：
    • 掃描購物車內商品名稱是否包含「預購」或「團購」。
    • 若有，則隱藏 #shipping_method_0_newebpay_cvscom（藍新超商取貨），並自動切換到 #shipping_method_0_flat_rate1。

2.5 覆寫的 template-parts ​

  • template-parts/header-v4.php
    • 對應父主題 sober 的 header v4 樣板。
    • 主要變更：在 header 右側 icon 區塊插入「購物金顯示」（透過 [rs_my_reward_points] shortcode 取得 SUMO Reward Points 點數，再以 SVG icon + 數字顯示）。
    • 父主題其他樣板（footer、sidebar、404 等）皆未覆寫。

3. 使用的 Plugin 清單 ​

3.1 Repo 內追蹤的 Plugin（皆有客製化） ​

Plugin路徑用途
藍新金流 NewebPaywp-content/plugins/newebpay/信用卡、ATM、超商代碼、超商取貨等金流
SUMO Reward Pointswp-content/plugins/rewardsystem/會員購物金（紅利點數）系統

3.2 Repo 內未追蹤的 Plugin ​

其餘 Plugin（akismet、WooCommerce 主程式、第三方擴充等）依 .gitignore 排除。完整啟用清單請以正式站 wp-admin/plugins.php 為準，並在交接時取得授權檔（如有付費 Plugin）。

3.3 已棄用的 Plugin（歷史記錄） ​

Plugin棄用日期commit備註
Frequently Bought Together for WooCommerce（WebToffee）2025-02-126a46107加價購功能曾大幅客製（修改 plugin 原生 PHP 與 partial 樣板共 ~3,400 行），後棄用並從 repo 刪除。請勿重新安裝舊版 plugin — 若未來重新引入需求，應評估其他方案或重新評估客製範圍。

4. Plugin 客製化記錄（重點） ​

⚠️ 升級這些 Plugin 前，請先比對 commit diff，否則客製內容會被 plugin 更新覆蓋。

4.1 藍新金流 NewebPay（v1.0.4） ​

  • 檔案：wp-content/plugins/newebpay/class-newebpay.php
  • commit：17f898e [plugins] 藍新金流 1.0.4 錯誤排除（2025-03-07）
  • 客製內容：第 1673 行，將
    php
    $cart_items = WC()->cart->get_cart();
    改為
    php
    $cart_items = function_exists('WC') && WC()->cart ? WC()->cart->get_cart() : []; // 防止 get_cart() 出錯
  • 原因：在某些非結帳情境（如後台、API 呼叫）WC()->cart 為 null，呼叫 get_cart() 會 fatal error。

4.2 SUMO Reward Points（rewardsystem） ​

  • 檔案：wp-content/plugins/rewardsystem/includes/frontend/class-fp-rewardsystem-frontend-assets.php
  • commit：64e76be [plugins] SUMO Reward Points Checkout 預計可獲得點數欄位調整（2025-01-14）
  • 客製內容：整支 928 行檔案皆為我方覆寫版本。主要調整 cart / checkout / order detail 三個頁面顯示「預計可獲得點數」的 hook 位置與欄位文案。

5. 重要 Hook 與 Meta key 索引 ​

提供給接手團隊在進行除錯、擴充或排查問題時快速搜尋。

5.1 Action / Filter Hooks（PHP 端） ​

Hook優先序Callback / 說明來源
after_setup_theme預設 10ctkpro_theme_enqueue_styles — 前台載入父主題 functions.phpfunctions.php
wp_enqueue_scripts預設 10ctkpro_enqueue_styles_scripts — enqueue parent style、子主題覆寫 css、main.min.jsfunctions.php
body_class預設 10add_slug_body_class — body class 加入 {post_type}-{post_name}functions.php
after_switch_theme預設 10ctkpro_reset_theme_mods — 切換主題時複製 theme_mods_soberfunctions.php
customize_register11ctkpro_customize_register — 載入父主題 customizer.php 並複製 modsfunctions.php
manage_woocommerce_page_wc-orders_columns20add_wc_order_list_shipping_column — 訂單列表插入「運送方式」欄位functions.php
manage_woocommerce_page_wc-orders_custom_column20display_wc_order_list_shipping_column_content — 顯示「超取需出貨」functions.php
woocommerce_order_status_changed10ctk_store_complete — pending → processing 時自動完成超商付款訂單functions.php

5.2 前端 JS 事件 ​

事件Callback說明
updated_checkouthideRedundantShipping結帳更新時隱藏多餘的付費運送選項
updated_checkoutsetupGiftBox結帳更新時依購物車內容隱藏超取選項（預購／團購）

5.3 Post Meta Keys ​

Meta key來源用途
_newebpayStoreName藍新金流 plugin訂單綁定的超商門市名稱。functions.php 兩處依此判斷：(1) 訂單列表「超取需出貨」標示；(2) ctk_store_complete 判斷是否為超商取貨。

5.4 WP Options / Theme Mods ​

Option key用途
theme_mods_sober父主題 sober 客製器設定（切換子主題時會被複製）
theme_mods_{stylesheet}子主題 customizer 設定（由父主題 mods 複製而來）
rs_message_before_after_cart_tableSUMO 點數提示訊息位置
rs_reward_point_troubleshoot_before_cartSUMO 訊息錯位修正開關
rs_select_type_for_cart購物車「可獲得點數」顯示位置
rs_select_type_for_checkout結帳頁「可獲得點數」顯示位置
rs_show_hide_message_for_guest訪客點數提示開關（cart）
rs_show_hide_message_for_guest_checkout_page訪客點數提示開關（checkout）

5.5 WooCommerce 訂單狀態流轉關鍵點 ​

pending → processing 時 ctk_store_complete 會：

  1. 讀取訂單前 3 筆已核准的留言（$wpdb->comments，原生 SQL）。
  2. 依留言內容判斷付款方式：
    • 包含「信用卡」「TAIWANPAY」「超商代碼繳費」 → 略過（維持 processing）。
    • 含 _newebpayStoreName（超商取貨已先付） → 自動更新為 completed。

6. 重要注意事項 ​

  1. 子主題依賴父主題 sober：缺少父主題會導致前台無法載入。
  2. functions.php 第 117 行有原生 SQL：直接查詢 $wpdb->comments，升級 WP / WC 時若資料表結構變更需留意。
  3. 編譯流程：SCSS 與 JS 目前需手動編譯。專案內未提供 build script（如 package.json），接手團隊需自備工具鏈。
  4. 付款留言判斷：ctk_store_complete 依「訂單留言文字」判斷付款方式，若藍新 plugin 升級改變留言格式（如「信用卡」改為「Credit Card」），此邏輯會失效。

© 2026 cloudwp