Files

Ho Ngoc Hai 76d75c753b Migrate

2026-05-23 18:37:02 +07:00

6.5 KiB

Raw Blame History

Kiến Trúc Đa Ngành Hàng (Multi-vertical Architecture)

Tổng Quan

Tài liệu này mô tả kiến trúc hỗ trợ hoạt động kinh doanh đa ngành hàng trong nền tảng GoodGo. Thiết kế cho phép một Merchant vận hành trên nhiều ngành dọc (Retail, F&B, Services) mà không tạo ra "spaghetti code."

Nguyên Tắc Thiết Kế

Merchant Service quản lý "AI" (Định danh) và "LUẬT" (Cấu hình), còn "CÁCH" (Thực thi) được ủy quyền cho các service vệ tinh.

Các Tầng Kiến Trúc

graph TB
    subgraph Clients ["📱 Tầng Client"]
        POS["Smart POS"]
        WEB["Web Dashboard"]
        APP["Mobile App"]
    end

    subgraph Gateway ["⚡ API Gateway"]
        TRAEFIK["Traefik"]
    end

    subgraph Core ["🟡 Tầng Lõi - Định Danh & Cấu Hình"]
        IAM["🔐 IAM Service"]
        MERCHANT["🏪 Merchant Service"]
        WALLET["💰 Wallet Service"]
    end

    subgraph Orchestration ["🔴 Tầng Điều Phối"]
        CATALOG["📦 Catalog Service"]
        ORDER["📝 Order Service"]
    end

    subgraph Verticals ["🔵 Engines Ngành Dọc"]
        INVENTORY["🏭 Inventory"]
        BOOKING["📅 Booking"]
        FNB["🍳 F&B Engine"]
    end

    Clients --> Gateway
    Gateway --> Core
    Gateway --> Orchestration
    ORDER --> Verticals

Trách Nhiệm Các Tầng

1. Tầng Lõi (Cấu Hình & Định Danh)

Service	Trách Nhiệm
IAM Service	Xác thực người dùng, vai trò, quyền
Merchant Service	Định danh shop, cờ tính năng, thiết lập nghiệp vụ
Wallet Service	Xử lý thanh toán, quản lý số dư

2. Tầng Điều Phối

Service	Trách Nhiệm
Catalog Service	Quản lý sản phẩm đa hình
Order Service	Xử lý đơn hàng với Strategy Pattern

3. Engines Ngành Dọc

Service	Ngành	Logic Chính
Inventory Service	Retail, F&B	Quản lý tồn kho, công thức
Booking Service	Dịch vụ	Đặt lịch hẹn
F&B Engine	Food & Beverage	Bàn, phiên, hiển thị bếp

Strategy Pattern Cho Xử Lý Đơn Hàng

Order Service đóng vai trò "bộ não" định tuyến từng dòng hàng đến engine ngành dọc phù hợp dựa trên loại sản phẩm.

flowchart LR
    ORDER["Order Service"]
    
    subgraph Strategies ["Các Strategy Dòng Hàng"]
        RETAIL["RetailStrategy"]
        SERVICE["ServiceStrategy"]
        FNB["FnbStrategy"]
    end
    
    ORDER --> |"ProductType.Physical"| RETAIL
    ORDER --> |"ProductType.Service"| SERVICE
    ORDER --> |"ProductType.PreparedFood"| FNB
    
    RETAIL --> INVENTORY["Inventory Service"]
    SERVICE --> BOOKING["Booking Service"]
    FNB --> KITCHEN["F&B Engine"]

Strategy Interface

public interface ILineItemStrategy
{
    ProductType SupportedType { get; }
    Task ValidateAsync(OrderItem item, Guid shopId);
    Task ExecuteAsync(OrderItem item, Guid shopId);
}

Hỗ Trợ Đơn Hàng Hybrid

Một đơn hàng có thể chứa nhiều loại sản phẩm:

☕ Cà phê (PreparedFood → F&B Engine)
👕 Áo merchandise (Physical → Inventory Service)
💆 Voucher spa (Service → Booking Service)

Mỗi dòng hàng được xử lý bởi strategy tương ứng.

Mô Hình Cấu Hình Merchant Service

Enum BusinessCategory

public enum BusinessCategory
{
    Retail = 1,       // Hàng hóa vật lý
    FoodBeverage = 2, // Nhà hàng, quán cafe
    Services = 3,     // Spa, salon, phòng khám
    Other = 99        // Hybrid
}

ShopFeatures (Cờ Tính Năng)

public record ShopFeatures(
    bool HasInventory = false,  // Bật Inventory Service
    bool HasBooking = false,    // Bật Booking Service
    bool HasTables = false,     // Bật quản lý bàn
    bool HasKitchen = false,    // Bật KDS
    bool HasShipping = false,   // Bật vận chuyển
    bool HasDelivery = false    // Bật giao hàng
);

Cài Đặt Động (JSONB)

Tham số nghiệp vụ cụ thể lưu dạng JSON:

{
  "fnb": {
    "serviceChargePercent": 5,
    "defaultTableCapacity": 4
  },
  "booking": {
    "slotDurationMinutes": 30,
    "advanceBookingDays": 14
  },
  "retail": {
    "lowStockThreshold": 10
  }
}

Ví Dụ Luồng Dữ Liệu

Luồng Đơn Hàng Retail

sequenceDiagram
    participant POS
    participant Order as Order Service
    participant Merchant as Merchant Service
    participant Inventory as Inventory Service
    participant Wallet as Wallet Service

    POS->>Order: Tạo đơn (Hàng vật lý)
    Order->>Merchant: Lấy ShopFeatures
    Merchant-->>Order: {HasInventory: true}
    Order->>Inventory: Kiểm tra tồn kho
    Inventory-->>Order: Còn hàng
    Order->>Wallet: Xử lý thanh toán
    Wallet-->>Order: Thanh toán thành công
    Order->>Inventory: Trừ tồn kho
    Order-->>POS: Đơn hàng hoàn tất

Luồng Đơn Hàng F&B

sequenceDiagram
    participant POS
    participant Order as Order Service
    participant FnB as F&B Engine
    participant Inventory as Inventory Service

    POS->>Order: Tạo đơn (Bàn 5, Cà phê)
    Order->>FnB: Thêm vào phiên đang hoạt động
    FnB->>FnB: Tạo KitchenTicket
    FnB-->>Order: Ticket đã tạo
    Note over FnB: Hiển thị trên KDS
    FnB->>Inventory: Trừ nguyên liệu (tùy chọn)
    Order-->>POS: Đơn hàng đã xác nhận

Lợi Ích Của Kiến Trúc Này

Lợi Ích	Mô Tả
Trách Nhiệm Đơn Lẻ	Mỗi service xử lý một domain
Khả Năng Mở Rộng	Thêm ngành mới không cần sửa core
Khả Năng Test	Các strategy có thể test độc lập
Hỗ Trợ Hybrid	Đơn hàng hỗn hợp xử lý tự nhiên
Điều Khiển Bằng Cấu Hình	Thay đổi hành vi qua cờ tính năng

6.5 KiB Raw Blame History