
商務
Shopify
商品 / 變體 / 價格 / 庫存
訂單 / 會員 / 結帳
TanStack Start
內容
Sanity
商品文案 / 品牌故事 / SEO
圖庫 / 條款 / FAQ
[ 01 / 08 ]·background
專案背景
從去年開始,我就曾建立了一個完全客製化的前後端電商專案,不過為了與維護成本取得平衡,我著手重新設計系統架構並進行責任劃分。面對即將擴展的海外市場,若繼續採用全自建模式,多國語系、多幣別、跨境稅務與在地支付等客製邏輯將使維護負擔成倍成長。因此,此重構的核心目標在於明確邊界——將獨特的使用者體驗留給品牌前端自主掌握,將複雜且標準化的商務基礎設施交由成熟平台代勞。
[ 02 / 08 ]·decision
專案目標
為了兼顧前端設計的高自由度與極致效能,同時保有後端服務的彈性,我選擇以 Headless 架構整合 Shopify。Shopify 的國際信任度高,利於未來擴展海外市場;針對台灣在地化需求,則能透過綠界官方 Plugin 快速串接金流。此外,Shopify 提供完整的 API 支援,可完美搭配現代前端框架獨立開發。
要達成什麼?
01
保留既有品牌前端
版面、動效與內容呈現自己掌握
02
台灣要能出貨
金流、物流、發票、會員、售後
03
商務交給專業系統
商品變體、價格、庫存、訂單
04
能擴展海外市場
付款、稅務、物流與在地內容,用設定開通
哪個方案做得到?
市面上能達成商務需求的做法有三種。把上面 01–04 當成同一把尺,逐一量過去。
方案
01
02
03
04
判斷
Shopify theme
商務都到位,但前端被 theme 綁住
延續自建
自由度換來持續累加的維護責任
Headless Shopify
採用四個條件都達成
[ 03 / 08 ]·architecture
架構分工
Shopify
商務
- 商品・變體・庫存
- 購物車
- 訂單・結帳
- 會員
- 金流・物流
- 多幣別・稅務
- 商品翻譯
Storefront API Customer Account API
TanStack Start
前端
- 品牌視覺頁面結構、動線完全自訂,不受主題限制
- 效能SSR、快取、圖片策略自己決定
- SEO多語系網址、301 規則自己掌握
Sanity API
Sanity
內容
- 商品文案
- 品牌故事
- 規格與相容性
- FAQ
- 圖庫
- 條款
- SEO 文案
- TanStack Start
- React
- TypeScript
- Tailwind CSS
- Railway
- Shopify Storefront API
- Shopify Customer Account API
- GraphQL
- Sanity
[ 04 / 08 ]·commerce
交易安全
headless 前端 · TanStack Start
瀏覽商品購物車登入按鈕訂單管理Storefront API
產品與變體資料
Storefront API
變體 id 與數量 購物車本體存在 Shopify
Customer Account API
登入請求
Customer Account API
訂單、退貨、取消
Shopify 託管頁
結帳付款checkoutUrl 導轉
託管結帳頁 金額由 Shopify 重算
託管登入頁
OTP 驗證 憑證不經本站
Shopify 後端
Shopify
商品 · 庫存 · 購物車 · 結帳 · 顧客 · 訂單
| 環節 | 誰負責 | 怎麼保護 |
|---|---|---|
| 瀏覽、選規格、購物車 | 本站 | 前端只送商品變體 id 與數量 |
| 結帳付款 | Shopify 託管頁 | 售價、折扣與可售狀態由 Shopify 重新計算 |
| 登入 | Shopify 託管頁 | 憑證不經本站,本站不存密碼 |
| 訂單查詢、退貨、取消 | 本站 | 透過 Customer Account API 讀取後渲染 |
| 私有 token | 伺服器端 | 發布前掃 client bundle,外洩就擋下 |
前端只送變體 ID 與數量,金額由 Shopify 在結帳時重算;信用卡與密碼只在託管頁輸入。私有 Token 留於伺服器端。
[ 05 / 08 ]·discovery
海外市場
headless 前端
/zh-tw · /en-tw · 同一份程式碼
Shopify
商品 · 訂單 · 會員 · 結帳 · 兩個市場共用
台灣市場
海外市場
金流
綠界 ECPay
Shopify 官方 App
PayPal · Shop Pay
Shopify 內建
物流
自行指定物流商
訂單填單號與查詢網址
國際快遞
分區運費規則 · 同一套訂單管理
語系 · 偵測國家
/zh-tw
TWD
/en-tw
依偵測國家切換幣別
開海外市場,換幣別只是其中一件事。顧客還要能用自己的語言找到商品、確認規格相不相容、看懂運送與退換規則,最後用當地能用的付款方式結帳。新增市場時,前端和 Shopify 商務核心也能直接沿用,再加上市場設定、付款、稅務、物流與在地內容。
[ 06 / 08 ]·execution
遷移上線
0108/20平台轉換
- 那天要解決的問題
- 換到 Shopify 之後,原本的網站外觀還留得住嗎?
- 當天做完的
- 新站架起來,商品、規格與價格從 Shopify 讀進網站
0208/21資料來源
- 那天要解決的問題
- 同一個商品,Shopify 有一份、Sanity 也有一份,以誰為準?
- 當天做完的
- 價格庫存看 Shopify、介紹圖文看 Sanity,兩邊用同一組商品代號對起來
0308/22結帳功能
- 那天要解決的問題
- 從看商品到付完錢、登入會員,中間會不會斷掉?
- 當天做完的
- 商品頁、購物車、結帳、會員登入整條走通
0408/23中英網站
- 那天要解決的問題
- 中英文各自要有固定網址,Google 才找得到
- 當天做完的
- 中英文網址分開、翻譯內容接上、基本 SEO 設定完成
0508/24正式上線
- 那天要解決的問題
- 換成正式網域與正式金流之後,舊資料跟登入還能用嗎?
- 當天做完的
- 網域切到新站,金流、登入與既有商品資料都接上
0608/25售後處理
- 那天要解決的問題
- 下單後想退貨或取消,是不是還要 email 來回問?
- 當天做完的
- 站內就能申請退貨、取消還沒出貨的訂單,退換規則同步顯示
[ 07 / 08 ]·spec
規格驅動開發
決策・寫 spec
資料來源、限制、替代方案、驗收條件
拆任務・實作
從定案的 spec 拆出工作並執行
驗收
手動測試:功能、安全、資料都對才發布
01專案建立選定 headless + Shopify,寫遷移 spec
人決策・寫 spec
選定 headless + Shopify,寫遷移 spec
AI拆任務・實作
- 提替代方案給比較
- 快速建立好專案骨架
人驗收
確認骨架符合 spec
02前端遷移指定要保留的畫面與路由
人決策・寫 spec
指定要保留的畫面與路由
AI拆任務・實作
- 把先前設計好的前端畫面遷移到新專案
- 前端 UI/UX 優化
人驗收
逐頁比對舊站
03商品資料定資料邊界:Shopify 管商務、Sanity 管內容
人決策・寫 spec
定資料邊界:Shopify 管商務、Sanity 管內容
AI拆任務・實作
- 批次把產品資料從舊後端匯入 Shopify
- 找出 SKU 重複的產品
- 檢查所有產品頁文案
人驗收
抽查商品頁與價格庫存
04API 串接寫 spec:每條 API 的資料來源、限制、驗收條件
人決策・寫 spec
寫 spec:每條 API 的資料來源、限制、驗收條件
AI拆任務・實作
- 檢查 spec 是否符合 Shopify API 規範
- 依 spec 寫 API 串接邏輯
人驗收
手動跑完整交易流程
05交易安全定邊界:金額與憑證不經本站
人決策・寫 spec
定邊界:金額與憑證不經本站
AI拆任務・實作
審查前後端溝通方式,確保私密資料不會留在瀏覽器
人驗收
發布前確認 bundle 掃描全過
使用 spec-driven 的快速開發方式與 AI Agent 協作,每個階段動工前先寫清楚資料來源、限制、替代方案與驗收條件;實作途中發現前提不成立,就回去改規格,並留下一份接手得了的交接狀態,並且在發佈每項更新前做好手動測試,確認功能可行且安全、資料正確才發佈。
[ 08 / 08 ]·outcome
結果
管理端
ADMIN ONLY
系統
不直接對外
對外開放
OPEN ACCESS
Shopify 託管
Shopify Admin
商品 · 訂單 · 會員 · 金流與市場設定
Shopify 商務核心
Storefront API · Customer Account API
Shopify 託管頁
結帳 · 登入(Shopify CDN)
Storefront API Customer Account API
結帳 · 登入時 跳轉再返回
自部署 · TanStack Start
GitHub
程式碼 repo · push 觸發建置
Railway
建置 · 執行 server · 環境變數與私有 token
www.hs-magic.com
商品頁 · 購物車 · 會員中心 · 訂單與售後
Content API(讀)
Sanity 託管
Sanity Studio
內容編輯 · 圖片與文案
Sanity Content Lake
Content API · 以 shopifyHandle 對照商品
由網站讀取後呈現
在AI Agent 的協助下,一個禮拜內就完成了後端架構的轉換,且也完全複製了原本的前端設計。商品、訂單、會員與結帳交給 Shopify,內容由 Sanity 維護,三者用 shopifyHandle 對照;商品、購物車、結帳、會員、訂單查詢與售後接成同一條流程。