Skip to main content

GlobalHub (中央 B2C 前台)

📋 基本資訊​

📖 專案描述​

GlobalHub 是 Lion Travel 中央層 (Central) 的 B2C 旅遊產品展示前端，提供多語言、多幣別的產品瀏覽與訂購功能。

架構定位​

中央層 (Central)
├─ GlobalHub (本專案) ← 中央 B2C 前台
└─ GlobalHub API ← 中央匯入與分發服務

區域層 (Regions: TW, US, JP)
├─ ProductsAPI ← 區域產品服務
├─ ProductBackend ← 區域 CMS 管理
└─ 區域 B2C 前台

職責:

  • 展示來自 GlobalHub API 的產品資料
  • 提供中央站點的產品瀏覽與訂購
  • 面向全球使用者（多語言、多幣別）

🏗️ 專案架構​

目錄結構​

globalhub/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── layout.tsx         # 根佈局
│   │   ├── page.tsx           # 首頁
│   │   ├── globals.css        # 全域樣式
│   │   └── favicon.ico        # 網站圖示
│   └── test/                   # 測試檔案
│       ├── setup.ts           # 測試環境設定
│       └── example.test.ts    # 範例測試
├── public/                     # 靜態資源
│   ├── globe.svg
│   ├── next.svg
│   ├── vercel.svg
│   ├── window.svg
│   └── file.svg
├── next.config.ts              # Next.js 設定
├── package.json                # 專案依賴
├── tsconfig.json               # TypeScript 設定
├── vitest.config.ts            # Vitest 測試設定
├── eslint.config.mjs           # ESLint 設定
├── postcss.config.mjs          # PostCSS 設定
├── Dockerfile                  # Docker 容器化設定
├── .gitlab-ci.yml              # GitLab CI/CD 設定
└── README.md                   # 專案說明

技術棧詳細​

核心框架

  • Next.js 16.1.1 - React 框架，支援 Server-Side Rendering (SSR) 與 Static Site Generation (SSG)
  • React 19.2.3 - UI 函式庫

開發工具

  • TypeScript 5 - 型別安全
  • Tailwind CSS 4 - 實用優先的 CSS 框架
  • Vitest 4.0.16 - 單元測試框架
  • Testing Library - React 元件測試
  • ESLint 9 - 程式碼品質檢查

CI/CD

  • Docker - 容器化部署
  • GitLab CI - 自動化建置與部署

🔌 API 整合​

GlobalHub 作為中央層前端，主要整合以下後端服務：

主要整合​

服務層級用途
GlobalHub API中央產品資料展示

預期端點​

  • 產品列表查詢
  • 產品詳情查看
  • 購物車管理
  • 訂單建立

🚀 開發指南​

環境需求​

  • Node.js: v22 (根據 Dockerfile)
  • npm: 隨 Node.js 安裝

本地開發​

  1. 安裝依賴

    npm ci

  2. 啟動開發伺服器

    npm run dev

    開啟瀏覽器訪問 http://localhost:3000

  3. 執行測試

    npm test

  4. 測試覆蓋率

    npm run test:coverage

  5. 程式碼檢查

    npm run lint

建置生產版本​

npm run build
npm start

Docker 部署​

建置映像檔

docker build -t globalhub:latest .

執行容器

docker run -d -p 3000:3000 --name globalhub globalhub:latest

健康檢查

  • 容器內建健康檢查：每 30 秒檢查 http://localhost:3000/
  • 失敗重試 3 次後標記為不健康

📦 Docker 配置​

Multi-stage Build​

Dockerfile 採用兩階段建置：

  1. Builder Stage (node:22-alpine)

    • 安裝依賴
    • 建置應用程式

  2. Runner Stage (node:22-alpine)

    • 僅複製建置產物
    • 建立 non-root 使用者 (nextjs)
    • 執行生產伺服器

環境變數​

  • NODE_ENV=production
  • PORT=3000
  • HOSTNAME=0.0.0.0

安全性​

  • 使用 non-root 使用者 (uid: 1001, gid: 1001)
  • 最小化映像檔大小 (Alpine Linux)

🧪 測試​

  • 測試框架: Vitest
  • 元件測試: @testing-library/react
  • 瀏覽器環境: jsdom

測試檔案位於 src/test/ 目錄。

🔗 相關專案​

中央層專案​

專案關係說明
globalhubapi後端 API (中央)中央匯入與分發服務

區域層專案​

專案關係說明
productsapi產品服務 (區域)區域產品搜尋、訂單管理
productbackend後台管理 (區域)區域產品內容管理系統

📊 CI/CD 流程​

GitLab CI 自動化流程（.gitlab-ci.yml）：

  1. Build - 建置 Docker 映像檔
  2. Test - 執行單元測試與覆蓋率檢查
  3. Deploy - 部署到目標環境

📝 重要文件​

檔案說明
next.config.tsNext.js 配置（輸出模式、最佳化等）
tsconfig.jsonTypeScript 編譯器設定
vitest.config.ts測試設定與覆蓋率門檻
.gitlab-ci.ymlCI/CD 流程定義
Dockerfile容器化建置指令

🎨 設計模式​

  • App Router - Next.js 14+ 的新路由系統
  • Server Components - 預設使用 React Server Components
  • File-based Routing - 基於檔案系統的路由

📈 效能優化​

  • Static Generation - 靜態生成提升載入速度
  • Standalone Output - 最小化部署大小
  • Image Optimization - Next.js 自動圖片最佳化
  • Code Splitting - 自動程式碼分割

🔐 品質保證​

  • TypeScript - 型別安全
  • ESLint - 程式碼風格與潛在問題檢查
  • Vitest - 單元測試覆蓋率
  • GitLab CI - 自動化測試與建置

🌐 多語言支援​

前端應用預期支援多語言（需整合 i18n 函式庫），與 GlobalHub API 的多語言資料配合使用。

💰 多幣別支援​

透過整合 GlobalHub API 的多幣別價格功能，提供動態價格顯示。

🌍 與區域站點的關係​

  • GlobalHub = 中央站點前台
  • 區域 B2C 前台 = 各區域獨立的消費者網站 (TW/US/JP)
  • 數據來源: 中央站點的數據來自 GlobalHub API（已從 SERP 匯入）
  • 獨立性: 中央站點與區域站點各自獨立運營

📚 相關文件​