pos-system/docs/vi/architecture/multi-vertical-architecture.md

# 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

```mermaid
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.

```mermaid
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

```csharp
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

```csharp
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)

```csharp
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:

```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

```mermaid
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

```mermaid
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 |

## Tài Nguyên Liên Quan

- [Kế Hoạch Triển Khai](file:///Users/velikho/.gemini/antigravity/brain/fc592f5c-fd0a-4a19-87d0-d09926a1cdde/implementation_plan.md)
- [Domain-Driven Design Skill](file:///Users/velikho/Desktop/WORKING/Base/.agent/skills/domain-driven-design/SKILL.md)
- [CQRS Pattern Skill](file:///Users/velikho/Desktop/WORKING/Base/.agent/skills/cqrs-mediatr/SKILL.md)
- [Inter-Service Communication](file:///Users/velikho/Desktop/WORKING/Base/.agent/skills/inter-service-communication/SKILL.md)