Products API (產品服務)

📋 基本資訊

專案路徑: liongroup/liontech/lionglobal/b2c/productsapi
GitLab URL: https://gitlab.com/liongroup/liontech/lionglobal/b2c/productsapi
專案類型: 後端 API (.NET)
最後更新: 2026-02-07

📖 專案描述

Products API 是 GlobeConnect Product Hub (GPH) 的核心服務，負責管理和搜尋旅遊產品。支援多幣別定價、多語言在地化，並使用 Elasticsearch 提供高效能搜尋功能。

專案目標

建立 GlobeConnect Product Hub (GPH) - 統一平台，使所有全球站點能夠銷售和訂購其他站點提供的產品。

核心功能

AI 輔助產品採購 - 從供應商和提供商智慧採購
全球訂單交換 (GOX) - 跨站點訂單連接系統
AI 增強產品重新包裝 - 支援多語言和多幣別格式
全面控制面板 - 營運和分析儀表板

🏗️ 專案架構

Clean Architecture 分層

productsapi/
├── src/
│   ├── Domain/                          # 領域層 (無依賴實體)
│   │   └── Product/                     # 多產品領域
│   │       ├── Product.cs               # 基礎實體 (抽象)
│   │       ├── ProductPrice.cs          # 多幣別定價
│   │       ├── ProductTranslation.cs    # 多語言內容
│   │       ├── ProductType.cs           # 產品類型列舉
│   │       ├── Voucher/                 # 票券產品類型
│   │       │   ├── VoucherProduct.cs
│   │       │   └── VoucherCategory.cs
│   │       ├── PackageTour/             # 套裝行程產品
│   │       │   ├── PackageTour.cs
│   │       │   ├── Itinerary.cs         # 每日行程模板
│   │       │   ├── DepartedTour.cs      # 出發班次實例
│   │       │   ├── PriceTier.cs         # 分級定價
│   │       │   └── ProductImage.cs      # 產品圖片
│   │       └── Booking/                 # 訂位管理
│   │           ├── Booking.cs
│   │           └── Passenger.cs
│   │
│   ├── Application/                     # 應用層 (CQRS 處理器)
│   │   ├── Abstractions/                # 介面定義
│   │   ├── Products/                    # 多產品應用邏輯
│   │   │   ├── Bookings/                # 訂位管理
│   │   │   ├── Commands/                # 共享命令 (發布, 定價)
│   │   │   ├── EventHandlers/           # 領域事件處理器
│   │   │   ├── Images/                  # 圖片處理
│   │   │   ├── Import/                  # 匯入邏輯
│   │   │   ├── PackageTours/            # 套裝行程邏輯
│   │   │   ├── Prices/                  # 定價邏輯
│   │   │   ├── Queries/                 # 共享查詢
│   │   │   ├── Translations/            # 在地化邏輯
│   │   │   └── Vouchers/                # 票券邏輯
│   │   │
│   ├── Infrastructure/                  # 基礎設施層
│   │   ├── Database/
│   │   │   ├── ApplicationDbContext.cs  # 產品資料庫上下文
│   │   │   ├── StationOrderDbContext.cs # 訂單資料庫上下文
│   │   │   └── Configurations/          # EF Core 實體設定
│   │   ├── Elasticsearch/               # 搜尋實作
│   │   ├── Services/                    # 外部服務 (AWS 等)
│   │   ├── Migrations/                  # 資料庫遷移
│   │   └── BackgroundJobs/              # Hangfire 任務
│   │
│   ├── Web.Api/                         # 展示層 (Minimal API)
│   │   ├── Endpoints/                   # API 端點
│   │   ├── Middleware/                  # 自訂中介軟體
│   │   └── Program.cs                   # 應用程式進入點
│   │
│   ├── Gateway/                         # API Gateway (BFF)
│   │   ├── krakend.json                 # Gateway 設定
│   │   ├── config/                      # 部分設定
│   │   └── plugins/                     # Go 外掛
│   │
│   └── SharedKernel/                    # 共享值物件與基礎類別
│       ├── Entity.cs
│       └── Result.cs
│
├── tests/                               # 測試專案
│   ├── UnitTests/                       # 單元測試
│   ├── IntegrationTests/                # 整合測試
│   ├── ContractTests/                   # 契約測試
│   ├── ArchitectureTests/               # 架構測試
│   └── Benchmarks/                      # 效能基準測試
│
├── docs/                                # 完整文件
│   ├── README.md                        # 文件索引
│   ├── api/                             # API 文件
│   ├── 架構/                            # 架構設計
│   ├── 訂單/                            # 訂單管理
│   ├── 金流/                            # 金流系統
│   ├── 產品/                            # 產品匯入
│   ├── 訊息佇列/                        # Wolverine 訊息佇列
│   └── 維運/                            # 維運指南
│
├── docker-compose.yml                   # Docker Compose 設定
├── global.json                          # .NET SDK 版本
├── Directory.Build.props                # 全域 MSBuild 設定
└── Directory.Packages.props             # NuGet 版本管理

技術棧詳細

後端框架

.NET 10.0 - ASP.NET Core Minimal API
Entity Framework Core - ORM 框架

資料庫

PostgreSQL - 主資料庫 (產品資料 + 訂單資料)
Redis - 快取層
Elasticsearch 8.11 - 全文搜尋引擎

背景任務

Hangfire - 背景任務處理 (產品匯入、同步)

訊息佇列

Wolverine - 訊息處理框架 (取代 MediatR)

API Gateway

KrakenD - Backend-for-Frontend (BFF) 模式

其他工具

AWS S3 - 圖片儲存
Seq - 結構化日誌

🔌 API 文件

功能模組

產品管理 - Vouchers 與 Package Tours 的 CRUD 操作
搜尋 - 使用 Elasticsearch 的進階搜尋、篩選、排序、分頁
在地化 - 多語言支援 (en-US, zh-TW, ja-JP)
多幣別 - 動態價格轉換與儲存
匯入 - 從外部供應商非同步匯入產品
Webhooks - 產品變更事件驅動更新
稽核日誌 - 追蹤關鍵資源變更
API Gateway (BFF) - 使用 KrakenD 進行資料聚合

主要端點

產品相關

GET /products - 搜尋產品
GET /products/{id} - 取得產品詳情
POST /products - 建立產品
PUT /products/{id} - 更新產品
DELETE /products/{id} - 刪除產品

訂單相關

POST /bookings - 建立訂位
GET /bookings/{id} - 查詢訂位狀態

匯入相關

POST /products/import - 啟動匯入任務
GET /products/import/{jobId} - 查詢匯入狀態

出發班次

GET /tours/{id}/departures - 取得可用出發日期

Webhook

POST /webhooks/products/update - 接收產品更新事件

💾 資料模型

資料庫架構 (Multi-Site)

本系統採用多站點架構，使用兩個獨立的資料庫上下文：

1. ApplicationDbContext (產品資料庫 - `productsdb`)

集中管理，所有站點共享

• Products              - 產品基礎表 (TPH 繼承)
• VoucherProducts       - 票券產品
• PackageTours          - 套裝行程產品
• ProductPrices         - 多幣別定價
• Suppliers             - 供應商設定
• DepartedTours         - 出發班次實例
• Bookings              - 訂位記錄
• FulfillmentProviders  - 履行提供商設定

2. StationOrderDbContext (訂單資料庫 - `stationorderdb`)

站點本地，支援本地履行與跨站轉發

• Orders                - 訂單主表
• OrderItems            - 訂單明細
• OrderContacts         - 聯絡資訊
• Payments              - 付款記錄
• TourOrderDetails      - 行程訂單詳情
• VoucherOrderDetails   - 票券訂單詳情
• Travelers             - 旅客資訊
• OrderStatusHistory    - 訂單狀態歷史

設計理念

產品集中管理 → 所有站點共享同一產品目錄
訂單本地化 → 每個站點有自己的訂單資料庫，支援：
- 本地訂單履行
- 跨站點訂單轉發 (透過 B2B API)
- 站點專屬資料隱私

🔗 相關專案

專案	關係	說明
globalhub	前端消費者	展示產品並建立訂單
globalhubapi	兄弟服務	商品匯入與管理
productbackend	管理後台	產品內容管理系統 (CMS)

資料流關係

ProductBackend (CMS)
    ↓ (管理產品)
ProductsAPI
    ↓ (提供 API)
GlobalHub (前端)
    ↓ (下單)
ProductsAPI (訂單服務)

🚀 開發指南

環境需求

.NET 10.0 SDK
Docker Desktop - 用於 Elasticsearch、Redis、PostgreSQL

本地執行

啟動基礎設施服務
```
docker-compose up -d
```
這會啟動：
- PostgreSQL (port 5432) - 資料庫
- Redis (port 6380) - 快取
- Elasticsearch (port 9201) - 搜尋引擎
- Seq (port 8081) - 日誌系統
- Product API (port 5050) - 主 API

執行 API

dotnet run --project src/Web.Api/Web.Api.csproj

存取 Swagger UI
```
http://localhost:5000/swagger
```
存取 API Gateway
```
http://localhost:8080/health
```

執行測試

# 所有測試
dotnet test

# 單元測試
dotnet test tests/UnitTests

# 整合測試
dotnet test tests/IntegrationTests

# 架構測試
dotnet test tests/ArchitectureTests

執行效能基準測試

dotnet run --project tests/Benchmarks/Benchmarks.csproj -c Release

🏛️ 架構模式

Clean Architecture

Domain - 業務邏輯核心，無依賴
Application - 用例實作，依賴 Domain
Infrastructure - 外部依賴實作
Presentation - API 端點

CQRS

使用明確的處理器 (Explicit Handlers) 實作命令查詢職責分離模式。

Event-Driven

使用領域事件處理副作用：

稽核日誌
Webhooks
搜尋索引更新

📊 Use Case 流程圖

1. 核心產品檢索 (搜尋、篩選、在地化)

sequenceDiagram
    participant Client
    participant API
    participant Elasticsearch
    participant DB

    Client->>API: GET /products?search=bali&currency=JPY&locale=zh-TW
    API->>Elasticsearch: Search(term="bali")
    Elasticsearch-->>API: Product IDs
    API->>DB: GetDetails(IDs)
    DB-->>API: Product Data
    API->>API: Apply Currency Conversion (JPY)
    API->>API: Apply Localization (zh-TW)
    API-->>Client: Filtered & Localized Product List

2. 供應商匯入工作流程

sequenceDiagram
    participant Admin
    participant API
    participant Worker
    participant Supplier
    participant S3
    participant DB
    participant Elasticsearch

    Admin->>API: POST /import/{productId}
    API->>Worker: Enqueue Import Job
    API-->>Admin: 202 Accepted (JobId)

    Worker->>Supplier: Get Product Details
    Supplier-->>Worker: Product Data + Image URLs
    loop For Each Image
        Worker->>Supplier: Download Image
        Worker->>S3: Upload Optimized Image
    end
    Worker->>DB: Save Product (PackageTour)
    Worker->>Elasticsearch: Index Product

3. 訂位流程 (套裝行程)

sequenceDiagram
    participant User
    participant API
    participant DB

    User->>API: GET /tours/{id}/departures
    API->>DB: Query Departures
    DB-->>API: Available Dates & Seats
    API-->>User: Departures List

    User->>API: POST /bookings
    API->>DB: Begin Transaction
    API->>DB: Check Availability & Lock Seat
    alt Capacity OK
        API->>DB: Create Booking Record
        API->>DB: Commit Transaction
        API-->>User: 201 Created (BookingRef)
    else Full
        API->>DB: Rollback
        API-->>User: 409 Conflict
    end

🔄 訊息佇列 (Wolverine)

遷移歷程

之前: MediatR
現在: Wolverine
原因: 更好的效能、內建持久化、靈活的訊息路由

處理器類型

Command Handlers - 處理命令
Event Handlers - 處理領域事件
Message Handlers - 處理外部訊息

🌐 多語言支援

支援的語言：

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

資料模型包含 ProductTranslation 表，儲存不同語言版本的內容。

💰 多幣別支援

支援的幣別：

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

貨幣服務

參考文件：docs/產品/貨幣服務使用說明.md

📚 完整文件索引

API 相關

🔐 安全性

輸入驗證 - FluentValidation
SQL Injection 防護 - EF Core 參數化
API 金鑰驗證 - Webhook 簽章驗證
HTTPS - 強制 HTTPS

📊 CI/CD

GitLab CI 支援：

自動建置
單元測試
整合測試
Docker 映像推送
自動部署

🧪 測試策略

UnitTests - 領域邏輯測試
IntegrationTests - 資料庫、外部服務整合測試
ContractTests - API 契約測試
ArchitectureTests - 架構規則驗證
Benchmarks - 效能基準測試

📈 效能優化

Elasticsearch - 快速全文搜尋
Redis - 快取層減少資料庫負載
非同步處理 - Hangfire 背景任務
Result Pattern - 避免例外的效能成本

📋 基本資訊​

📖 專案描述​

專案目標​

核心功能​

🏗️ 專案架構​

Clean Architecture 分層​

技術棧詳細​

🔌 API 文件​

功能模組​

主要端點​

💾 資料模型​

資料庫架構 (Multi-Site)​

1. ApplicationDbContext (產品資料庫 - productsdb)​

2. StationOrderDbContext (訂單資料庫 - stationorderdb)​

設計理念​

🔗 相關專案​

資料流關係​

🚀 開發指南​

環境需求​

本地執行​

執行測試​

執行效能基準測試​

🏛️ 架構模式​

Clean Architecture​

CQRS​

Event-Driven​

📊 Use Case 流程圖​

1. 核心產品檢索 (搜尋、篩選、在地化)​

2. 供應商匯入工作流程​

3. 訂位流程 (套裝行程)​

🔄 訊息佇列 (Wolverine)​

遷移歷程​

處理器類型​

相關文件​

🌐 多語言支援​

💰 多幣別支援​

貨幣服務​

📚 完整文件索引​

API 相關​

🔐 安全性​

📊 CI/CD​

🧪 測試策略​

📈 效能優化​