pos-system/Multi-vertical.md

Multi-vertical Architecture Implementation Plan
Problem Statement / Vấn Đề
Hệ thống hiện tại có Merchant Service đang làm tốt vai trò quản trị/định danh, nhưng cần mở rộng để hỗ trợ đa ngành hàng (Multi-vertical) bao gồm:

Retail: Bán lẻ hàng hóa vật lý (Áo, Mũ, Điện thoại...)
F&B: Food & Beverage (Quán cafe, Nhà hàng, Quán ăn...)
Services: Dịch vụ (Spa, Salon, Phòng khám...)
Hybrid: Kết hợp nhiều ngành (Quán cafe bán kèm merchandise)
Nguyên tắc thiết kế:

Merchant Service chỉ quản lý "Ai" (Identity) và "Luật chơi" (Configuration), còn "Chơi thế nào" (Execution) phải đẩy ra các Service vệ tinh.

Architecture Overview / Tổng Quan Kiến Trúc
🔵 Vertical Engines - Logic Ngành
🔴 Orchestration Layer
🟡 Core Services - Configuration & Identity
Client
Retail Item
Service Item
F&B Item
Ref
Get Config
⚡ Traefik Gateway
💳 Smart POS / Web
🔐 IAM Service(User/Role)
🏪 Merchant Service(Shop DNA, Settings, Staff)
💰 Wallet Service(Payment)
📦 Catalog Service(Polymorphic Products)
📝 Order Service(The Brain - Strategy Pattern)
🏭 Inventory Service(Retail Logic)
📅 Booking Service(Spa/Service Logic)
🍳 F&B Engine(Table/Session/KDS)
User Review Required
IMPORTANT

Quyết định Scope: Plan này bao gồm 4 phases. User cần xác nhận muốn triển khai tất cả hay chỉ một số phases cụ thể.

WARNING

Breaking Changes trong Phase 1: Thay đổi database schema của Shop entity sẽ yêu cầu migration và có thể ảnh hưởng đến các service đang sử dụng Merchant Service API.

Phase 1: Foundation Refactoring
Mục tiêu
Chuẩn bị Merchant Service làm nền tảng cho multi-vertical, không triển khai logic nghiệp vụ ngành.

1.1 Database Changes
[MODIFY] Add JSONB columns to shops table
Migration SQL:

-- Migration: Add multi-vertical support columns
ALTER TABLE shops 
ADD COLUMN features_config JSONB DEFAULT '{}',
ADD COLUMN vertical_settings JSONB DEFAULT '{}',
ADD COLUMN business_category VARCHAR(50) DEFAULT 'Other';
-- Index for performance
CREATE INDEX idx_shops_business_category ON shops(business_category);
CREATE INDEX idx_shops_features_config ON shops USING GIN (features_config);
-- Comment documentation
COMMENT ON COLUMN shops.features_config IS 'Feature flags: HasInventory, HasBooking, HasTables, HasKitchen...';
COMMENT ON COLUMN shops.vertical_settings IS 'Business-specific settings as JSON document';
COMMENT ON COLUMN shops.business_category IS 'Primary business type: Retail, FoodBeverage, Services, Other';
1.2 Domain Model Changes
[MODIFY] 

Shop.cs
New Properties:

public class Shop : Entity, IAggregateRoot
{
    // ... existing properties ...
    
    // NEW: Business category enum
    public BusinessCategory Category { get; private set; }
    
    // NEW: Feature configuration (maps to JSONB)
    public ShopFeatures Features { get; private set; }
    
    // NEW: Dynamic settings (maps to JSONB) 
    public JsonDocument? Settings { get; private set; }
    
    // Factory method with category-based defaults
    public static Shop Create(Guid merchantId, string name, BusinessCategory category)
    {
        var shop = new Shop(merchantId, name, category);
        shop.Features = GetDefaultFeatures(category);
        return shop;
    }
    
    private static ShopFeatures GetDefaultFeatures(BusinessCategory category) => category switch
    {
        BusinessCategory.Retail => new ShopFeatures(HasInventory: true, HasShipping: true),
        BusinessCategory.FoodBeverage => new ShopFeatures(HasTables: true, HasKitchen: true, HasInventory: true),
        BusinessCategory.Services => new ShopFeatures(HasBooking: true),
        _ => new ShopFeatures(HasInventory: true, HasBooking: true) // Hybrid
    };
}
[NEW] BusinessCategory.cs
// Path: MerchantService.Domain/AggregatesModel/ShopAggregate/BusinessCategory.cs
public enum BusinessCategory
{
    Retail = 1,      // Bán lẻ
    FoodBeverage = 2, // F&B
    Services = 3,     // Dịch vụ (Spa, Salon)
    Other = 99        // Hybrid/Other
}
[NEW] ShopFeatures.cs (Value Object)
// Path: MerchantService.Domain/AggregatesModel/ShopAggregate/ShopFeatures.cs
public record ShopFeatures(
    bool HasInventory = false,
    bool HasBooking = false,
    bool HasTables = false,
    bool HasKitchen = false,
    bool HasShipping = false,
    bool HasDelivery = false
);
1.3 API Changes
[MODIFY] Shop DTOs
CreateShopRequest:

public record CreateShopRequest(
    string Name,
    string? Description,
+   BusinessCategory Category = BusinessCategory.Other,
+   ShopFeaturesDto? Features = null
);
ShopResponse:

public record ShopResponse(
    Guid Id,
    string Name,
    string? Description,
+   BusinessCategory Category,
+   ShopFeaturesDto Features,
    ...
);
[NEW] ShopFeaturesDto
public record ShopFeaturesDto(
    bool HasInventory = false,
    bool HasBooking = false,
    bool HasTables = false,
    bool HasKitchen = false,
    bool HasShipping = false,
    bool HasDelivery = false
);
Phase 2: Retail MVP
Mục tiêu
Xây dựng luồng bán hàng cơ bản cho ngành Retail.

2.1 Catalog Service (NEW)
Trách nhiệm: Quản lý sản phẩm đa hình (Polymorphic Products)

Database Schema
CREATE TABLE products (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    shop_id UUID NOT NULL REFERENCES shops(id),
    name VARCHAR(255) NOT NULL,
    description TEXT,
    price DECIMAL(18,2) NOT NULL,
    product_type VARCHAR(50) NOT NULL, -- Physical, Service, PreparedFood
    attributes JSONB DEFAULT '{}',      -- Type-specific attributes
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_products_shop ON products(shop_id);
CREATE INDEX idx_products_type ON products(product_type);
Core Entities
Product (Aggregate Root)
ProductType (Enum: Physical, Service, PreparedFood)
ProductVariant (Size, Color...)
ProductCategory
2.2 Inventory Service (NEW)
Trách nhiệm: Quản lý tồn kho cho Retail

Database Schema
CREATE TABLE inventory_items (
    id UUID PRIMARY KEY,
    product_id UUID NOT NULL,
    shop_id UUID NOT NULL,
    quantity INT NOT NULL DEFAULT 0,
    reserved_quantity INT NOT NULL DEFAULT 0,
    reorder_level INT DEFAULT 10,
    updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE TABLE inventory_transactions (
    id UUID PRIMARY KEY,
    inventory_item_id UUID NOT NULL,
    transaction_type VARCHAR(50) NOT NULL, -- IN, OUT, ADJUSTMENT
    quantity INT NOT NULL,
    reference_id UUID, -- Order ID, PO ID...
    notes TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW()
);
Core Features
Stock in/out operations
Stock reservation for orders
Low stock alerts
Inventory audit trail
2.3 Order Service (NEW) - The Brain
Trách nhiệm: Điều phối đơn hàng, sử dụng Strategy Pattern

Strategy Pattern Design
// Interface for line item processing
public interface ILineItemStrategy
{
    ProductType SupportedType { get; }
    Task ValidateAsync(OrderItem item, Guid shopId);
    Task ExecuteAsync(OrderItem item, Guid shopId);
}
// Strategy implementations
public class RetailStrategy : ILineItemStrategy
{
    public ProductType SupportedType => ProductType.Physical;
    
    public async Task ValidateAsync(OrderItem item, Guid shopId)
    {
        // Call Inventory Service: Check stock availability
    }
    
    public async Task ExecuteAsync(OrderItem item, Guid shopId)
    {
        // Call Inventory Service: Reserve/Deduct stock
    }
}
Order Flow
WalletService
InventoryService
MerchantService
OrderService
POS
WalletService
InventoryService
MerchantService
OrderService
POS
loop
[For each LineItem]
loop
[For each LineItem]
Create Order
Get Shop Features
ShopFeatures
Select Strategy by ProductType
Validate (Check Stock)
OK/Error
Process Payment
Payment OK
Execute (Deduct Stock)
Order Completed
Phase 3: F&B Vertical
Mục tiêu
Mở rộng hỗ trợ ngành F&B (Food & Beverage)

3.1 F&B Engine (NEW)
Trách nhiệm: Quản lý phiên ăn uống và bếp

Core Entities
Table - Sơ đồ bàn
Session - Phiên ăn (khách ngồi tại bàn)
KitchenTicket - Phiếu bếp
Recipe - Định lượng nguyên liệu
Database Schema
CREATE TABLE tables (
    id UUID PRIMARY KEY,
    shop_id UUID NOT NULL,
    table_number VARCHAR(50) NOT NULL,
    capacity INT DEFAULT 4,
    zone VARCHAR(100),
    status VARCHAR(50) DEFAULT 'Available'
);
CREATE TABLE sessions (
    id UUID PRIMARY KEY,
    table_id UUID NOT NULL,
    started_at TIMESTAMPTZ DEFAULT NOW(),
    closed_at TIMESTAMPTZ,
    guest_count INT DEFAULT 1,
    status VARCHAR(50) DEFAULT 'Active'
);
CREATE TABLE kitchen_tickets (
    id UUID PRIMARY KEY,
    session_id UUID NOT NULL,
    order_item_id UUID NOT NULL,
    station VARCHAR(50), -- Bar, Kitchen, Grill...
    priority INT DEFAULT 0,
    status VARCHAR(50) DEFAULT 'Pending',
    created_at TIMESTAMPTZ DEFAULT NOW()
);
3.2 F&B Strategy
public class FnbStrategy : ILineItemStrategy
{
    public ProductType SupportedType => ProductType.PreparedFood;
    
    public async Task ExecuteAsync(OrderItem item, Guid shopId)
    {
        // 1. Publish KitchenTicketCreated event
        // 2. F&B Engine receives and displays on KDS
        // 3. Optionally: Deduct ingredients from Inventory
    }
}
Phase 4: Services Vertical (Spa/Salon)
Mục tiêu
Mở rộng hỗ trợ ngành Dịch vụ (Spa, Salon, Clinic)

4.1 Booking Service (NEW)
Trách nhiệm: Quản lý "tồn kho thời gian"

Core Entities
StaffSchedule - Lịch làm việc nhân viên
Resource - Tài nguyên (Giường, Phòng)
Appointment - Cuộc hẹn
TimeSlot - Slot thời gian khả dụng
Database Schema
CREATE TABLE staff_schedules (
    id UUID PRIMARY KEY,
    staff_id UUID NOT NULL,
    shop_id UUID NOT NULL,
    day_of_week INT NOT NULL,
    start_time TIME NOT NULL,
    end_time TIME NOT NULL
);
CREATE TABLE resources (
    id UUID PRIMARY KEY,
    shop_id UUID NOT NULL,
    name VARCHAR(255) NOT NULL,
    resource_type VARCHAR(50) NOT NULL, -- Room, Bed, Equipment
    capacity INT DEFAULT 1
);
CREATE TABLE appointments (
    id UUID PRIMARY KEY,
    shop_id UUID NOT NULL,
    customer_id UUID,
    staff_id UUID,
    resource_id UUID,
    service_id UUID NOT NULL,
    start_time TIMESTAMPTZ NOT NULL,
    end_time TIMESTAMPTZ NOT NULL,
    status VARCHAR(50) DEFAULT 'Scheduled'
);
4.2 Booking Strategy
public class ServiceStrategy : ILineItemStrategy
{
    public ProductType SupportedType => ProductType.Service;
    
    public async Task ValidateAsync(OrderItem item, Guid shopId)
    {
        // Call Booking Service: Check slot availability
        // Check staff + resource availability intersection
    }
    
    public async Task ExecuteAsync(OrderItem item, Guid shopId)
    {
        // Call Booking Service: Create Appointment
    }
}
New Microservices Summary
Service	Trách nhiệm	Phase
Catalog Service	Quản lý sản phẩm đa hình	Phase 2
Inventory Service	Quản lý tồn kho Retail + F&B ingredients	Phase 2
Order Service	Orchestrator với Strategy Pattern	Phase 2
F&B Engine	Table management, KDS, Sessions	Phase 3
Booking Service	Appointment scheduling	Phase 4
File Changes Summary
Phase 1 (Merchant Service Updates)
Action	File
MODIFY	MerchantService.Domain/AggregatesModel/ShopAggregate/Shop.cs
NEW	MerchantService.Domain/AggregatesModel/ShopAggregate/BusinessCategory.cs
NEW	MerchantService.Domain/AggregatesModel/ShopAggregate/ShopFeatures.cs
MODIFY	MerchantService.Infrastructure/EntityConfigurations/ShopConfiguration.cs
NEW	Migration file for JSONB columns
MODIFY	API DTOs (CreateShopRequest, ShopResponse)
Phase 2-4 (New Services)
Action	Project
NEW	catalog-service-net/
NEW	inventory-service-net/
NEW	order-service-net/
NEW	fnb-engine-net/
NEW	booking-service-net/
Verification Plan
Documentation Review
 Technical Documentation reviewed by team
 Architecture diagrams validated
 API specifications approved
Phase 1 Verification
 Migration runs successfully on test database
 Existing Merchant Service APIs unchanged (backward compatible)
 New ShopFeatures returned in API responses
 Unit tests for new Value Objects pass
Phase 2+ Verification
 Integration tests between services pass
 End-to-end order flow works for Retail
 Strategy Pattern correctly routes line items
Notes
NOTE

Scope: User yêu cầu chỉ tạo documentation và planning, KHÔNG triển khai code trong phase này.

TIP

Phụ thuộc Skills: Khi triển khai code, tham khảo các skills:


domain-driven-design

repository-pattern

cqrs-mediatr

inter-service-communication