ProductBackend (區域 CMS 管理系統)

📋 基本資訊

專案路徑: liongroup/liontech/lionglobal/b2c/productbackend
GitLab URL: https://gitlab.com/liongroup/liontech/lionglobal/b2c/productbackend
專案類型: 前端管理後台 (Next.js)
定位: 區域層 (TW/US/JP) - 產品內容管理系統
最後更新: 2026-02-07

📖 專案描述

ProductBackend 是區域站點 (TW/US/JP) 的產品後台管理系統，提供產品內容管理 (CMS)、首頁編輯、AI 聊天輔助等功能。

架構定位

中央層 (Central)
├─ SERP API → GlobalHub API → GlobalHub
    │
    ▼ 同步產品
區域層 (Regions: TW, US, JP)
├─ ProductsAPI (接收同步的產品)
├─ ProductBackend (本專案) ← 區域 CMS 管理
└─ 區域 B2C 前台

職責:

管理來自 GlobalHub API 同步的產品
區域化產品內容編輯（語言、幣別、定價）
區域特色促銷與活動設定
首頁與 CMS 內容編輯

🏗️ 專案架構

目錄結構

productbackend/
├── app/                            # Next.js App Router
│   ├── layout.tsx                  # 根佈局
│   ├── page.tsx                    # 首頁 (Dashboard)
│   ├── globals.css                 # 全域樣式
│   ├── favicon.ico                 # 網站圖示
│   ├── homepage/                   # 首頁編輯模組
│   │   ├── page.tsx               # CMS 首頁編輯器
│   │   └── actions.ts             # Server Actions
│   ├── products/                   # 產品管理模組
│   │   ├── page.tsx               # 產品列表
│   │   ├── new/                   # 新增產品
│   │   └── [id]/                  # 產品詳情/編輯
│   ├── globals/                    # 全域設定
│   │   └── page.tsx               # 全域設定頁
│   ├── chat/                       # AI 聊天模組
│   │   └── page.tsx               # 聊天介面
│   └── api/                        # API Routes
│       └── cms/                    # CMS API 端點
│
├── components/                     # React 元件
│   ├── ui/                         # shadcn/ui 元件庫
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── input.tsx
│   │   ├── table.tsx
│   │   ├── tabs.tsx
│   │   ├── dialog.tsx
│   │   ├── dropdown-menu.tsx
│   │   ├── select.tsx
│   │   ├── label.tsx
│   │   ├── textarea.tsx
│   │   ├── switch.tsx
│   │   ├── checkbox.tsx
│   │   ├── badge.tsx
│   │   ├── avatar.tsx
│   │   ├── tooltip.tsx
│   │   ├── chart.tsx
│   │   ├── separator.tsx
│   │   ├── collapsible.tsx
│   │   ├── skeleton.tsx
│   │   ├── sheet.tsx
│   │   ├── sidebar.tsx
│   │   ├── logo.tsx
│   │   └── grid-pattern.tsx
│   ├── products/                   # 產品管理元件
│   │   ├── products-table.tsx     # 產品列表表格
│   │   ├── product-form.tsx       # 產品表單
│   │   ├── product-status-badge.tsx # 狀態標籤
│   │   ├── media-uploader.tsx     # 媒體上傳器
│   │   ├── itinerary-editor.tsx   # 行程編輯器
│   │   ├── package-editor.tsx     # 套餐編輯器
│   │   ├── pricing-editor.tsx     # 費用編輯器
│   │   ├── traveler-fields-editor.tsx # 旅客欄位編輯器
│   │   ├── localized-input.tsx    # 多語言輸入
│   │   └── locale-tabs.tsx        # 語言切換標籤
│   ├── homepage/                   # 首頁編輯元件
│   │   ├── editable-field.tsx     # 可編輯欄位
│   │   └── widget-editor.tsx      # Widget 編輯器
│   ├── globals/                    # 全域設定元件
│   │   └── global-settings-editor.tsx
│   ├── chat/                       # 聊天元件
│   │   ├── chat-main.tsx
│   │   ├── chat-sidebar.tsx
│   │   ├── chat-message.tsx
│   │   └── chat-input-box.tsx
│   └── theme-toggle.tsx            # 主題切換
│
├── lib/                            # 函式庫
│   ├── utils.ts                    # 工具函式 (cn, clsx, tailwind-merge)
│   ├── cms.ts                      # CMS API 客戶端
│   ├── products-api.ts             # Products API 客戶端
│   └── sections.ts                 # CMS Section 定義
│
├── store/                          # Zustand 狀態管理
│   ├── dashboard-store.ts          # Dashboard 狀態
│   └── chat-store.ts               # 聊天狀態
│
├── hooks/                          # Custom Hooks
│   └── use-mobile.ts               # 偵測行動裝置
│
├── mock-data/                      # 模擬資料
│   ├── products.ts                 # 產品資料
│   ├── chats.ts                    # 聊天資料
│   ├── deals.ts                    # 交易資料
│   └── stats.ts                    # 統計資料
│
├── public/                         # 靜態資源
│   └── ln.png                      # Logo
│
├── next.config.ts                  # Next.js 設定
├── package.json                    # 專案依賴
├── tsconfig.json                   # TypeScript 設定
├── components.json                 # shadcn/ui 設定
├── eslint.config.mjs               # ESLint 設定
├── postcss.config.mjs              # PostCSS 設定
├── Dockerfile                      # Docker 容器化
├── .gitlab-ci.yml                  # GitLab CI/CD
├── .env.example                    # 環境變數範例
├── .env.staging                    # Staging 環境變數
├── .env.production                 # Production 環境變數
└── README.md                       # 專案說明

技術棧詳細

核心框架

Next.js 16.0.10 - React 框架 (App Router)
React 19.2.3 - UI 函式庫
TypeScript 5 - 型別安全

UI 元件庫

shadcn/ui - 可自訂的高品質元件
Radix UI - 無障礙的 Headless UI 元件
Lucide React - 圖示庫

樣式

Tailwind CSS 4 - 實用優先的 CSS 框架
next-themes - 深色/淺色模式切換
class-variance-authority - 變體樣式管理
clsx + tailwind-merge - 條件式類別名稱合併

表格與圖表

@tanstack/react-table - 強大的表格元件
recharts - 圖表繪製

狀態管理

Zustand - 輕量級狀態管理

其他工具

date-fns - 日期處理
vaul - Drawer 元件

🎯 核心功能

1. 產品管理模組

頁面路由

路由	說明
`/products`	產品列表 - 搜尋、篩選、分頁
`/products/new`	新增產品表單
`/products/[id]`	產品詳情頁
`/products/[id]/edit`	編輯產品表單

核心元件

元件	檔案	功能
ProductsTable	`components/products/products-table.tsx`	產品列表表格，含搜尋、篩選、分頁
ProductForm	`components/products/product-form.tsx`	新增/編輯產品主表單（6個分頁）
ProductStatusBadge	`components/products/product-status-badge.tsx`	產品狀態標籤（草稿/已上架/已下架）
MediaUploader	`components/products/media-uploader.tsx`	照片/影片上傳管理
ItineraryEditor	`components/products/itinerary-editor.tsx`	行程表編輯器（多日行程+活動）
PackageEditor	`components/products/package-editor.tsx`	套餐編輯器（支援多幣別）
PricingEditor	`components/products/pricing-editor.tsx`	費用項目編輯器（支援多幣別）
TravelerFieldsEditor	`components/products/traveler-fields-editor.tsx`	旅客資料欄位設定
LocalizedInput	`components/products/localized-input.tsx`	多語言輸入欄位
LocaleTabs	`components/products/locale-tabs.tsx`	語言切換標籤

資料模型 (mock-data/products.ts)

幣別金額 (支援多幣別)

interface CurrencyAmount {
  currency: string;  // TWD, USD, JPY, EUR...
  amount: number;
}

費用項目

interface PriceItem {
  id: string;
  name: string;
  amounts: CurrencyAmount[];  // 多幣別金額
  isIncluded: boolean;
  description?: string;
}

套餐

interface Package {
  id: string;
  name: LocalizedString;
  description?: LocalizedString;
  basePrice: number;
  currency: string;
  maxCapacity?: number;
  currentBookings: number;
  isActive: boolean;
  highlights: LocalizedString[];
}

產品

interface Product {
  id: string;
  name: LocalizedString;
  summary: LocalizedString;
  dateDescription: string;
  media: MediaItem[];
  description: DescriptionBlock[];
  htmlDescription: string;
  itinerary: ItineraryDay[];
  purchaseNotes: LocalizedString;
  pricing: PriceItem[];
  notices: LocalizedString[];
  redemption: LocalizedString;
  validity: ValidityPeriod;
  packages: Package[];
  travelerFields: TravelerField[];
  status: ProductStatus;  // draft | published | archived
  createdAt: string;
  updatedAt: string;
}

支援幣別

費用項目和套餐編輯器支援以下幣別：

代碼	名稱
TWD	新台幣
USD	美元
JPY	日圓
EUR	歐元
CNY	人民幣
HKD	港幣
SGD	新加坡幣
KRW	韓元
AUD	澳幣
GBP	英鎊
THB	泰銖
MYR	馬幣

2. 首頁編輯模組

整合 ApostropheCMS 的首頁內容編輯功能。

頁面路由

路由	說明
`/homepage`	CMS 首頁內容編輯器

核心元件

元件	檔案	功能
EditableField	`components/homepage/editable-field.tsx`	可編輯欄位元件
WidgetEditor	`components/homepage/widget-editor.tsx`	Widget 編輯器

CMS API (lib/cms.ts)

函式	說明
`getCmsToken()`	取得 CMS 登入 Token
`getCmsPages()`	取得頁面資料
`updateCmsPage()`	更新頁面欄位

可編輯欄位

支援編輯的欄位類型：

label, placeholder, title, cardTitle
subtitle, slideTitle, url, link
content, cardContent, explainLabel, pretitle
price, currency, description
buttonText, buttonLabel, alt, caption

3. AI 聊天模組

提供 AI 輔助的產品管理與諮詢功能。

頁面路由

路由	說明
`/chat`	AI 聊天介面

核心元件

元件	檔案	功能
ChatMain	`components/chat/chat-main.tsx`	主聊天區域
ChatSidebar	`components/chat/chat-sidebar.tsx`	聊天列表側邊欄
ChatMessage	`components/chat/chat-message.tsx`	訊息顯示
ChatInputBox	`components/chat/chat-input-box.tsx`	輸入框

4. 全域設定

統一管理系統全域設定。

頁面路由

路由	說明
`/globals`	全域設定頁

🔌 API 整合

環境配置

環境	API URL	說明
開發	`http://localhost:5050/api/v1`	本地開發預設
測試	`https://productapi.107.liondev.work/api/v1`	Staging 環境
正式	`https://productapi.liontravel.com/api/v1`	Production 環境

設定檔

本地開發 - 建立 .env.local：

PRODUCTS_API_URL=http://localhost:5050/api/v1

Staging - .env.staging Production - .env.production

API 客戶端

Products API (lib/products-api.ts)

產品 CRUD 操作
產品搜尋
訂單管理

CMS API (lib/cms.ts)

ApostropheCMS 整合
頁面內容管理

🚀 開發指南

環境需求

Node.js 20+
npm 或 pnpm

本地開發

安裝依賴
```
npm install
```

設定環境變數

cp .env.example .env.local
# 編輯 .env.local 設定 PRODUCTS_API_URL

啟動開發伺服器
```
npm run dev
```
開啟 http://localhost:3000
程式碼檢查
```
npm run lint
```

建置生產版本

npm run build
npm start

Docker 部署

本地建置

docker build -t productbackend .

指定環境建置

docker build --build-arg PRODUCTS_API_URL=https://productapi.107.liondev.work/api/v1 -t productbackend:staging .

執行容器

docker run -p 3000:3000 productbackend:staging

📊 CI/CD 流程

GitLab CI 會根據分支自動選擇環境：

分支	環境	Image Tag
`main`	production	`:latest`, `:sha`
其他	staging	`:branch-name`, `:sha`

🎨 UI/UX 設計

shadcn/ui 元件

使用 shadcn/ui 元件庫提供：

一致性 - 統一的設計語言
可訪問性 - 符合 WCAG 標準
可自訂 - 完全控制樣式
深色模式 - 內建主題切換

主要元件

Button - 按鈕（多種變體）
Input - 輸入框
Table - 表格（整合 @tanstack/react-table）
Dialog - 對話框
Dropdown - 下拉選單
Tabs - 標籤頁
Badge - 標籤
Card - 卡片容器
Chart - 圖表（整合 recharts）

響應式設計

Mobile-first - 優先考慮行動裝置
Breakpoints - Tailwind 標準斷點
Sidebar - 可收合的側邊欄

🔗 相關專案

專案	關係	說明
productsapi	後端 API	提供產品資料與訂單管理
globalhub	前台展示	B2C 客戶端
globalhubapi	匯入服務	產品資料匯入

資料流

ProductBackend (CMS)
    ↓ (管理產品內容)
ProductsAPI
    ↓ (提供資料)
GlobalHub (前台)

🧪 開發工具

VS Code 擴充

推薦安裝：

Tailwind CSS IntelliSense - Tailwind 自動完成
ESLint - 程式碼檢查
Prettier - 程式碼格式化

狀態管理

使用 Zustand 管理：

Dashboard 狀態
聊天狀態
使用者偏好設定

工具函式

lib/utils.ts 提供：

cn() - Tailwind 類別合併工具

📝 重要文件

檔案	說明
`next.config.ts`	Next.js 配置
`tsconfig.json`	TypeScript 編譯設定
`components.json`	shadcn/ui 元件設定
`eslint.config.mjs`	ESLint 規則
`.env.example`	環境變數範例
`Dockerfile`	Docker 容器化設定
`.gitlab-ci.yml`	CI/CD 流程

🌐 多語言支援

透過 LocalizedInput 與 LocaleTabs 元件支援：

en-US - 英文
zh-TW - 繁體中文
ja-JP - 日文

🔐 安全性

環境變數 - 敏感資料不進版控
API 驗證 - 整合後端 API 驗證機制
輸入驗證 - 表單驗證

📈 效能優化

Next.js Image - 自動圖片最佳化
Code Splitting - 自動程式碼分割
Server Components - 減少客戶端 JavaScript
Static Generation - 靜態頁面生成

🎯 未來規劃

整合更多 CMS 功能
增強 AI 聊天能力
多站點管理
更豐富的數據視覺化

📋 基本資訊​

📖 專案描述​

架構定位​

🏗️ 專案架構​

目錄結構​

技術棧詳細​

🎯 核心功能​

1. 產品管理模組​

頁面路由​

核心元件​

資料模型 (mock-data/products.ts)​

支援幣別​

2. 首頁編輯模組​

頁面路由​

核心元件​

CMS API (lib/cms.ts)​

可編輯欄位​

3. AI 聊天模組​

頁面路由​

核心元件​

4. 全域設定​

頁面路由​

🔌 API 整合​

環境配置​

設定檔​

API 客戶端​

🚀 開發指南​

環境需求​

本地開發​

建置生產版本​

Docker 部署​

📊 CI/CD 流程​

🎨 UI/UX 設計​

shadcn/ui 元件​

主要元件​

響應式設計​

🔗 相關專案​

資料流​

🧪 開發工具​

VS Code 擴充​

狀態管理​

工具函式​

📝 重要文件​

🌐 多語言支援​

🔐 安全性​

📈 效能優化​

🎯 未來規劃​

📋 基本資訊

📖 專案描述

架構定位

🏗️ 專案架構

目錄結構

技術棧詳細

🎯 核心功能

1. 產品管理模組

頁面路由

核心元件

資料模型 (mock-data/products.ts)

支援幣別

2. 首頁編輯模組

頁面路由

核心元件

CMS API (lib/cms.ts)

可編輯欄位

3. AI 聊天模組

頁面路由

核心元件

4. 全域設定

頁面路由

🔌 API 整合

環境配置

設定檔

API 客戶端

🚀 開發指南

環境需求

本地開發

建置生產版本

Docker 部署

📊 CI/CD 流程

🎨 UI/UX 設計

shadcn/ui 元件

主要元件

響應式設計

🔗 相關專案

資料流

🧪 開發工具

VS Code 擴充

狀態管理

工具函式

📝 重要文件

🌐 多語言支援

🔐 安全性

📈 效能優化

🎯 未來規劃