# Tài Liệu Kiến Trúc

**Dịch vụ**: mkt-facebook-service-net  
**Cập nhật lần cuối**: 2026-01-18

## Tổng Quan

Dịch vụ Marketing Facebook cung cấp giải pháp toàn diện cho doanh nghiệp tương tác với khách hàng trên Facebook Messenger thông qua chatbots tự động và hội thoại AI.

## Kiến Trúc Hệ Thống

### Kiến Trúc Tổng Quát

```mermaid
graph TB
    subgraph "Facebook Messenger Platform"
        EndUser[Người dùng cuối]
        MessengerApp[Messenger App]
    end
    
    subgraph "GoodGo Platform"
        direction TB
        
        subgraph "mkt-facebook-service-net"
            Webhook[Webhooks Controller]
            API[REST API]
            
            subgraph "Application Layer"
                Commands[Commands]
                Queries[Queries]
                Handlers[MediatR Handlers]
            end
            
            subgraph "Domain Layer"
                Conversation[Conversation Aggregate]
                Customer[Customer Aggregate]
                ChatbotFlow[ChatbotFlow Aggregate]
                AIChatbot[AIChatbotConfig Aggregate]
            end
            
            subgraph "Infrastructure Layer"
                FBClient[FacebookMessengerClient]
                AIClient[OpenAI Client]
                Repos[Repositories]
                DbContext[EF Core DbContext]
            end
        end
        
        subgraph "Data & Messaging"
            PostgreSQL[(PostgreSQL)]
            Redis[(Redis)]
            RabbitMQ[RabbitMQ]
        end
    end
    
    subgraph "External Services"
        FacebookAPI[Facebook Graph API]
        OpenAI[OpenAI / Azure OpenAI]
    end
    
    EndUser -->|Gửi Message| MessengerApp
    MessengerApp -->|Webhook Event| Webhook
    Webhook -->|Dispatch Command| Commands
    Commands --> Handlers
    Handlers --> Domain Layer
    Handlers --> Repos
    Repos --> DbContext
    DbContext --> PostgreSQL
    Handlers -->|Cache| Redis
    Handlers -->|Publish Events| RabbitMQ
    
    API -->|Commands/Queries| Handlers
    
    FBClient -->|HTTP| FacebookAPI
    AIClient -->|HTTP| OpenAI
    
    Handlers -->|Gửi Message| FBClient
    Handlers -->|AI Completion| AIClient
    
    style EndUser fill:#2C3E50,color:#ECF0F1,stroke:#34495E,stroke-width:2px
    style MessengerApp fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
    style Webhook fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:3px
    style API fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:3px
    style Commands fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style Queries fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style Handlers fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style Conversation fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
    style Customer fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
    style ChatbotFlow fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
    style AIChatbot fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
    style FBClient fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style AIClient fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style Repos fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style DbContext fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style PostgreSQL fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
    style Redis fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
    style RabbitMQ fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px
    style FacebookAPI fill:#7F8C8D,color:#ECF0F1,stroke:#5D6D7E,stroke-width:2px
    style OpenAI fill:#7F8C8D,color:#ECF0F1,stroke:#5D6D7E,stroke-width:2px
```

## Mô Hình Domain

### Các Aggregate

#### 1. Conversation Aggregate

```mermaid
classDiagram
    class Conversation {
        +Guid Id
        +Guid CustomerId
        +string PageId
        +ConversationStatus Status
        +Channel Channel
        +DateTime LastMessageAt
        +DateTime CreatedAt
        -List~Message~ _messages
        +IReadOnlyCollection~Message~ Messages
        
        +AddMessage(Message) void
        +MarkAsRead() void
        +Assign(string agentId) void
        +Close() void
    }
    
    class Message {
        +Guid Id
        +string SenderId
        +string Content
        +MessageType Type
        +MessageDirection Direction
        +DateTime SentAt
        +Dictionary Metadata
    }
    
    class ConversationStatus {
        <<enumeration>>
        Active
        Closed
        Archived
    }
    
    class MessageDirection {
        <<enumeration>>
        Incoming
        Outgoing
    }
    
    Conversation "1" *-- "many" Message
    Conversation --> ConversationStatus
    Message --> MessageDirection
    
    style Conversation fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style Message fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
    style ConversationStatus fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
    style MessageDirection fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
```

Aggregate Conversation quản lý vòng đời của một cuộc hội thoại khách hàng, bao gồm tất cả tin nhắn trao đổi.

**Quy Tắc Nghiệp Vụ**:
- Chỉ có thể thêm messages vào conversations Active
- Một conversation phải có ít nhất 1 message
- Messages không thể bị xóa, chỉ có thể archive conversation

#### 2. Customer Aggregate

```mermaid
classDiagram
    class Customer {
        +Guid Id
        +string FacebookUserId
        +string Name
        +string Email
        +string Phone
        +string ProfilePicUrl
        +string Locale
        +string Timezone
        +List~string~ Tags
        +Dictionary~string,string~ CustomFields
        +DateTime FirstSeenAt
        +DateTime LastInteractionAt
        
        +UpdateProfile(CustomerProfile) void
        +AddTag(string tag) void
        +RemoveTag(string tag) void
        +SetCustomField(string key, string value) void
    }
    
    style Customer fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
```

Aggregate Customer đại diện cho một Facebook user tương tác với chatbot.

**Quy Tắc Nghiệp Vụ**:
- `FacebookUserId` là unique identifier
- Tags phải là valid strings (không rỗng)
- Custom fields giới hạn 50 fields per customer
- Profile được sync từ Facebook Messenger Platform

#### 3. ChatbotFlow Aggregate (Automation)

```mermaid
classDiagram
    class ChatbotFlow {
        +Guid Id
        +string Name
        +Guid ShopId
        +FlowTriggerType TriggerType
        +string TriggerValue
        +bool IsActive
        -List~FlowNode~ _nodes
        +IReadOnlyCollection~FlowNode~ Nodes
        
        +AddNode(FlowNode) void
        +ConnectNodes(Guid from, Guid to) void
        +Activate() void
        +Deactivate() void
    }
    
    class FlowNode {
        +Guid Id
        +NodeType Type
        +string Content
        +Dictionary Config
        +List~Guid~ NextNodeIds
    }
    
    class NodeType {
        <<enumeration>>
        Start
        Message
        Question
        Condition
        Action
        End
    }
    
    ChatbotFlow "1" *-- "many" FlowNode
    FlowNode --> NodeType
    
    style ChatbotFlow fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style FlowNode fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:2px
    style NodeType fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
```

Aggregate ChatbotFlow định nghĩa quy tắc tự động và luồng hội thoại.

**Quy Tắc Nghiệp Vụ**:
- Mỗi flow phải có đúng 1 Start node
- Mỗi flow phải có ít nhất 1 End node
- Không được có circular references (vòng lặp vô hạn)
- `TriggerValue` phải unique trong cùng ShopId

#### 4. AIChatbotConfig Aggregate

```mermaid
classDiagram
    class AIChatbotConfig {
        +Guid Id
        +Guid ShopId
        +AIProvider Provider
        +string Model
        +string SystemPrompt
        +float Temperature
        +int MaxTokens
        +bool IsEnabled
        +DateTime CreatedAt
        +DateTime UpdatedAt
        
        +UpdateConfig(ConfigUpdate) void
        +Enable() void
        +Disable() void
    }
    
    class AIProvider {
        <<enumeration>>
        OpenAI
        AzureOpenAI
    }
    
    AIChatbotConfig --> AIProvider
    
    style AIChatbotConfig fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px
    style AIProvider fill:#E67E22,color:#ECF0F1,stroke:#D35400,stroke-width:2px
```

Aggregate AIChatbotConfig cấu hình hành vi chatbot AI.

**Quy Tắc Nghiệp Vụ**:
- Temperature phải trong khoảng [0.0, 2.0]
- MaxTokens phải > 0 và <= 4096
- SystemPrompt không được rỗng
- Chỉ có 1 active config per ShopId

## Luồng Xử Lý Tin Nhắn

```mermaid
sequenceDiagram
    participant User as Người dùng
    participant FB as Facebook Messenger
    participant Webhook as Webhooks Controller
    participant Handler as ProcessIncomingMessage Handler
    participant Domain as Domain Layer
    participant Strategy as Response Strategy
    participant AI as OpenAI Client
    participant FBClient as Facebook Client
    participant DB as PostgreSQL
    
    User->>FB: Gửi tin nhắn
    FB->>Webhook: POST /webhooks/facebook
    Webhook->>Webhook: Verify signature
    Webhook-->>FB: 200 OK (ngay lập tức)
    
    Webhook->>Handler: Dispatch ProcessIncomingMessageCommand
    
    Handler->>DB: Get or Create Customer
    Handler->>DB: Get or Create Conversation
    Handler->>Domain: conversation.AddMessage(incoming)
    Handler->>DB: Save changes
    
    Handler->>Strategy: DetermineStrategy(conversation)
    
    alt AI Chatbot Enabled
        Strategy-->>Handler: Use AI
        Handler->>AI: GetChatCompletion(context)
        AI-->>Handler: AI Response
    else Automation Flow
        Strategy-->>Handler: Use Automation
        Handler->>DB: Find matching FlowNode
        Handler->>Handler: Execute flow logic
    end
    
    Handler->>FBClient: SendMessage(response)
    FBClient->>FB: POST /messages
    FB-->>FBClient: Success
    
    Handler->>Domain: conversation.AddMessage(outgoing)
    Handler->>DB: Save changes
```

**Các Bước Chính**:

1. **Nhận Webhook**: Facebook gửi event đến service
2. **Xác thực Chữ ký**: Verify Facebook request signature
3. **Quản lý Khách hàng & Hội thoại**: Get hoặc tạo mới
4. **Lựa chọn Chiến lược**: Automation vs AI
5. **Tạo Phản hồi**: Dựa trên strategy
6. **Gửi Tin nhắn**: Qua Facebook Messenger API
7. **Lưu trữ**: Save message history

## Mẫu Tích Hợp

### Tích Hợp Facebook Messenger Platform

Dịch vụ tích hợp với Facebook Messenger Platform qua:
- **Webhooks**: Nhận messages, postbacks, read receipts
- **Send API**: Gửi messages, quick replies, templates
- **User Profile API**: Lấy thông tin user

### Tích Hợp OpenAI

AI chatbot sử dụng OpenAI Chat Completions API với:
- **Streaming**: Tạo phản hồi real-time
- **Context Management**: Hội thoại nhiều lượt
- **Retry Logic**: Polly resilience policies
- **Cost Tracking**: Theo dõi sử dụng tokens

## Mô Hình Dữ Liệu

### Lược Đồ Cơ Sở Dữ Liệu

```mermaid
erDiagram
    CONVERSATIONS ||--o{ MESSAGES : contains
    CUSTOMERS ||--o{ CONVERSATIONS : has
    CHATBOT_FLOWS ||--o{ FLOW_NODES : contains
    AI_CHATBOT_CONFIGS ||--|| SHOPS : belongs_to
    
    CONVERSATIONS {
        uuid id PK
        uuid customer_id FK
        string page_id
        string status
        string channel
        timestamp last_message_at
        timestamp created_at
    }
    
    MESSAGES {
        uuid id PK
        uuid conversation_id FK
        string sender_id
        text content
        string message_type
        string direction
        jsonb metadata
        timestamp sent_at
    }
    
    CUSTOMERS {
        uuid id PK
        string facebook_user_id UK
        string name
        string email
        string profile_pic_url
        string locale
        string timezone
        text[] tags
        jsonb custom_fields
        timestamp first_seen_at
        timestamp last_interaction_at
    }
    
    CHATBOT_FLOWS {
        uuid id PK
        uuid shop_id FK
        string name
        string trigger_type
        string trigger_value UK
        boolean is_active
        timestamp created_at
    }
    
    FLOW_NODES {
        uuid id PK
        uuid flow_id FK
        string node_type
        text content
        jsonb config
        uuid[] next_node_ids
        int order_index
    }
    
    AI_CHATBOT_CONFIGS {
        uuid id PK
        uuid shop_id FK UK
        string provider
        string model
        text system_prompt
        float temperature
        int max_tokens
        boolean is_enabled
        timestamp updated_at
    }
```

### Chỉ Mục

**Tối Ưu Hiệu Năng**:
- `idx_conversations_customer_id` - Fast lookup by customer
- `idx_conversations_page_id_status` - Filter active conversations by page
- `idx_messages_conversation_id_sent_at` - Sort messages chronologically
- `idx_customers_facebook_user_id` - Unique lookup
- `idx_chatbot_flows_shop_id_trigger` - Match triggers
- `idx_ai_configs_shop_id` - One config per shop

## Bảo Mật

### Xác Thực Facebook Webhook

Tất cả webhooks phải:
1. Có header `X-Hub-Signature-256`
2. Signature được verify bằng App Secret
3. Signature không hợp lệ bị reject với 403

### Xác Thực API

REST API endpoints yêu cầu:
- JWT Bearer token từ IAM service
- Authorization theo role (Admin, Agent, Viewer)

### Quyền Riêng Tư Dữ Liệu

- **GDPR Compliance**: Customer data export và deletion
- **Data Encryption**: At rest (PostgreSQL) và in transit (HTTPS)
- **PII Protection**: Customer info không log ra files

## Cân Nhắc Khả Năng Mở Rộng

### Mở Rộng Ngang

Service hỗ trợ mở rộng ngang với:
- **Stateless API**: Không có server-side sessions
- **Redis Cache**: Cache chia sẻ giữa các instances
- **RabbitMQ**: Message queue phân tán
- **Load Balancer**: Traefik phân phối traffic

### Giới Hạn Tỷ Lệ

Giới hạn Facebook Messenger API:
- **100 tin nhắn/giây** mỗi app
- **Burst tolerance**: Queue messages khi tăng đột biến
- **Retry with exponential backoff**: Cho responses 429

## Giám Sát

### Chỉ Số Chính

| Chỉ số | Mô Tả | Mục Tiêu |
|--------|-------|----------|
| **Webhook Latency** | Thời gian trả 200 cho Facebook | < 500ms |
| **Message Processing Time** | Thời gian tạo & gửi response | < 2s |
| **AI Response Time** | OpenAI API latency | < 5s |
| **Message Success Rate** | % messages gửi thành công | > 99% |
| **Conversation Active Count** | Số conversations đang active | - |
| **AI Cost per Conversation** | Chi phí OpenAI trung bình | Monitor |

### Kiểm Tra Sức Khỏe

- **Database**: PostgreSQL connection pooling
- **Redis**: Cache availability
- **RabbitMQ**: Message broker connection
- **Facebook API**: API availability check
- **OpenAI API**: Provider availability

## Quyết Định Thiết Kế

### Tại Sao CQRS?

Tách biệt operations đọc và ghi để:
- **Queries Tối Ưu**: Dùng Dapper cho reads nhanh
- **Commands Phức Tạp**: Dùng EF Core với Domain Model
- **Khả Năng Mở Rộng**: Scale reads và writes độc lập

### Tại Sao DDD?

Logic nghiệp vụ phức tạp yêu cầu:
- **Rich Domain Model**: Conversation, Customer aggregates
- **Encapsulation**: Business rules trong domain
- **Domain Events**: Tách biệt side effects

## Tài Nguyên

- [Tài Liệu API](./API.md)
- [Hướng Dẫn Setup Facebook](./FACEBOOK_SETUP.md)
- [Hướng Dẫn AI Chatbot](./AI_CHATBOT.md)
- [Domain-Driven Design Skill](../../../.agent/skills/domain-driven-design/SKILL.md)
- [CQRS MediatR Skill](../../../.agent/skills/cqrs-mediatr/SKILL.md)
